[PATCH rtems-docs] microblaze: Document BSPs and update CPU supplement

[Alex White]

---
 cpu-supplement/xilinx_microblaze.rst |  52 +++++++++-
 user/bsps/bsps-microblaze.rst        | 149 ++++++++++++++++++++++++++-
 2 files changed, 197 insertions(+), 4 deletions(-)

diff --git a/cpu-supplement/xilinx_microblaze.rst b/cpu-supplement/xilinx_microblaze.rst
index 2a92b61..350aeff 100644
--- a/cpu-supplement/xilinx_microblaze.rst
+++ b/cpu-supplement/xilinx_microblaze.rst
@@ -1,10 +1,58 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
-.. Copyright (C) 1988, 2002 On-Line Applications Research Corporation (OAR)
+.. Copyright (C) 2022 On-Line Applications Research Corporation (OAR)
 
 Xilinx MicroBlaze Specific Information
 **************************************
 
+This chapter discusses the dependencies of the *MicroBlaze architecture*
+(https://en.wikipedia.org/wiki/MicroBlaze).
+
+**Architecture Documents**
+
+For information on the MicroBlaze architecture, refer to
+*UG984 MicroBlaze Processor Reference Guide*
+(https://www.xilinx.com/support/documentation/sw_manuals/xilinx2021_2/ug984-vivado-microblaze-ref.pdf).
+
+CPU Model Dependent Features
+============================
+
+There are no CPU model dependent features in this port.
+
+Calling Conventions
+===================
+
+Please refer to "Chapter 4: MicroBlaze Application Binary Interface" of
+*UG984 MicroBlaze Processor Reference Guide*
+(https://www.xilinx.com/support/documentation/sw_manuals/xilinx2021_2/ug984-vivado-microblaze-ref.pdf).
+
+Interrupt Processing
+====================
+
+Hardware exceptions, interrupts, and user exceptions are all supported. When a
+hardware exception or user exception occurs, a fatal error will be generated.
+When an interrupt occurs, the interrupt source is determined by reading the
+AXI Interrupt Controller's Interrupt Status Register and masking it with the
+Interrupt Enable Register.
+
+Interrupt Levels
+----------------
+
+There are exactly two interrupt levels on MicroBlaze with respect to RTEMS.
+Level zero corresponds to interrupts disabled. Level one corresponds to
+interrupts enabled. This is the inverse of how most other architectures handle
+interrupt enable status.
+
+Interrupt Stack
+---------------
+
+The memory region for the interrupt stack is defined by the BSP.
+
+Default Fatal Error Processing
+==============================
+
+The default fatal error is BSP-specific.
+
 Symmetric Multiprocessing
 =========================
 
@@ -13,4 +61,4 @@ SMP is not supported.
 Thread-Local Storage
 ====================
 
-Thread-local storage is not implemented.
+Thread-local storage is supported.
diff --git a/user/bsps/bsps-microblaze.rst b/user/bsps/bsps-microblaze.rst
index dbb574f..e20df53 100644
--- a/user/bsps/bsps-microblaze.rst
+++ b/user/bsps/bsps-microblaze.rst
@@ -1,8 +1,153 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
 .. Copyright (C) 2018 embedded brains GmbH
+.. Copyright (C) 2022 On-Line Applications Research Corporation (OAR)
 
-microblaze (Microblaze)
+microblaze (MicroBlaze)
 ***********************
 
-There are no Microblaze BSPs yet.
+KCU105 QEMU
+===========
+
+The basic hardware initialization is performed by the BSP. This BSP supports the
+QEMU emulated Xilinx AXI Interrupt Controller v4.1.
+
+Boot via ELF
+------------
+
+The executable image is booted by QEMU in ELF format.
+
+Clock Driver
+------------
+
+The clock driver supports the QEMU emulated Xilinx AXI Timer v2.0. It is
+implemented as a simple downcounter.
+
+Console Driver
+--------------
+
+The console driver supports the QEMU emulated Xilinx AXI UART Lite v2.0. It is
+initialized to a baud rate of 115200.
+
+Network Driver
+--------------
+
+Support for networking is provided by the libbsd library. Network interface
+configuration is extracted from the device tree binary which, by default, is
+in `<bsp/microblaze-dtb.h> <https://git.rtems.org/rtems/tree/bsps/microblaze/microblaze_fpga/include/bsp/microblaze-dtb.h>`_.
+The device tree source for the default device tree is at `dts/system.dts <https://git.rtems.org/rtems/tree/bsps/microblaze/microblaze_fpga/dts/system.dts>`_.
+
+To replace the default device tree with your own, assuming ``my_device_tree.dts``
+is the name of your device tree source file, first you must convert your device
+tree to .dtb format.
+
+.. code-block:: none
+
+  $ dtc -I dts -O dtb my_device_tree.dts > my_device_tree.dtb
+
+The device tree blob, ``my_device_tree.dtb``, can now be converted to a C file.
+The name ``system_dtb`` is significant as it is the name expected by the BSP.
+
+.. code-block:: none
+
+  $ rtems-bin2c -C -A 8 -N system_dtb my_device_tree.dtb my_dtb
+
+The ``BSP_MICROBLAZE_FPGA_DTB_HEADER_PATH`` BSP configuration option can then be
+set to the path of the resulting source file, ``my_dtb.c``, to include it in the
+BSP build.
+
+.. code-block:: none
+
+  BSP_MICROBLAZE_FPGA_DTB_HEADER_PATH = /path/to/my_dtb.c
+
+
+Running Executables
+-------------------
+
+A .dtb (device tree blob) file should be provided to QEMU via the ``-hw-dtb``
+option. In the example command below, the device tree blob comes from the Xilinx
+Petalinux KCU105 MicroBlaze BSP (https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html).
+
+Executables generated by this BSP can be run using the following command:
+
+.. code-block:: none
+
+  $ qemu-system-microblazeel -no-reboot -nographic -M microblaze-fdt-plnx -m 256 \
+   -serial mon:stdio -display none -hw-dtb system.dtb -kernel example.exe
+
+Debugging with QEMU
+-------------------
+
+To debug an application, add the option ``-s`` to make QEMU listen for GDB
+connections on port 1234. Add the ``-S`` option to also stop execution until
+a connection is made.
+
+For example, to debug the hello sample and break at ``Init``, first start QEMU.
+
+.. code-block:: none
+
+  $ qemu-system-microblazeel -no-reboot -nographic -M microblaze-fdt-plnx -m 256 \
+   -serial mon:stdio -display none -hw-dtb system.dtb -kernel \
+   build/microblaze/kcu105_qemu/testsuites/samples/hello.exe -s -S
+
+Then start GDB and connect to QEMU.
+
+.. code-block:: none
+
+  $ microblaze-rtems6-gdb build/microblaze/kcu105_qemu/testsuites/samples/hello.exe
+  (gdb) target remote localhost:1234
+  (gdb) break Init
+  (gdb) continue
+
+KCU105
+======
+
+The basic hardware initialization is performed by the BSP. This BSP supports the
+Xilinx AXI Interrupt Controller v4.1.
+
+This BSP was tested using the Xilinx Kintex UltraScale FPGA KCU105 board
+configured with the default Petalinux KCU105 MicroBlaze BSP. The defaults may
+need to be adjusted using BSP configuration options to match the memory layout
+and configuration of your board.
+
+Clock Driver
+------------
+
+The clock driver supports the Xilinx AXI Timer v2.0. It is implemented as a
+simple downcounter.
+
+Console Driver
+--------------
+
+The console driver supports the Xilinx AXI UART Lite v2.0.
+
+Debugging
+---------
+
+The following debugging procedure was used for debugging RTEMS applications
+running on the Xilinx KCU105 board using GDB.
+
+First send an FPGA bitstream to the board using OpenOCD.
+
+.. code-block:: none
+
+  $ openocd -f board/kcu105.cfg -c "init; pld load 0 system.bit; exit"
+
+After the board has been programmed, start the Vivado ``hw_server`` application
+to serve as the debug server. Leave it running in the background for the rest of
+the process.
+
+.. code-block:: none
+
+  $ tools/Xilinx/Vivado/2020.2/bin/hw_server
+
+With the debug server running, connect to the debug server with GDB, load the
+application, and debug as usual. By default the GDB server listens on port 3002.
+
+.. code-block:: none
+
+  $ microblaze-rtems6-gdb example.exe
+  (gdb) target extended-remote localhost:3002
+  (gdb) load
+  (gdb) break Init
+  (gdb) continue
-- 
2.32.0