7 files changed, 329 insertions, 47 deletions
diff --git a/user/bsps/aarch64/xilinx-zynqmp.rst b/user/bsps/aarch64/xilinx-zynqmp.rst
index ca232de..78bff12 100644
--- a/user/bsps/aarch64/xilinx-zynqmp.rst
+++ b/user/bsps/aarch64/xilinx-zynqmp.rst
@@ -44,6 +44,173 @@ When booting via u-boot, RTEMS must be packaged into a u-boot image or booted
 as a raw binary since u-boot does not currently support ELF64 which is required
 for AArch64 ELF binaries.
 
+Example: Booting a RTEMS image on the ZCU102 ZynqMP board
+---------------------------------------------------------
+
+This example will walk through the steps needed for booting RTEMS from a SD card
+on the
+`ZCU102 ZynqMP board. <https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html>`_
+The reference for setting up a SD card and obtaining pre-built boot images is
+`here. <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841858/Board+bring+up+using+pre-built+images>`_
+
+Hardware Setup
+^^^^^^^^^^^^^^
+
+Set the dip switch SW6 according to the table below. This will allow the board
+to boot from the SD card. Connect a Micro-USB cable to the USB UART interface
+J83. This is a quad USB UART interface which will show up on the development
+host computer as four different serial or tty devices. Use the first channel
+for the console UART. It should be set to 115k baud.
+
++---------------------------+
+| Dip Switch JW6            |
++------+------+------+------+
+|  ON  |  OFF |  OFF |  OFF |
++------+------+------+------+
+
+Prepare a SD card with a bootable partition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The goal is to have a bootable SD card with a partition that is formatted with
+the FAT file system. The file system will contain the boot artifacts including
+BOOT.bin and the u-boot image. The RTEMS image will be placed on this volume. To
+create the bootable SD card, follow the directions
+`here. <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18842385/How+to+format+SD+card+for+SD+boot>`_
+
+Once you have the card formatted correctly, you need to place the files from
+`this archive <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2202763266/2021.2+Release#Downloads>`_
+on the FAT partition. The following file was used for this example:
+`xilinx-vck190-v2021.2-final.bsp <https://www.xilinx.com/member/forms/download/xef.html?filename=xilinx-vck190-v2021.2-final.bsp>`_
+
+In order to download these files, you need to have a Xilinx account login. As an
+alternative, you can download a bootable image for Ubuntu 20.04 and write it to
+an SD card using a utility such as `Balena Etcher <https://www.balena.io/etcher>`_
+or dd. The Ubuntu image is available `here. <https://ubuntu.com/download/xilinx>`_
+Download the image for the Zynq Ultrascale+ MPSoC Development boards, uncompress
+it and write it to the SD card. This image creates multiple partitions, but we
+only need to use the FAT partition with the boot artifacts on it.
+
+Verify that the board can boot from the SD card
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is worth booting the board from the SD card before trying to boot RTEMS.
+Insert the card and power on the board. You should see the messages on the first
+console indicating the various boot loader stages and eventually the Linux
+kernel. The goal is to interrupt u-boot when given the chance to access the
+u-boot command prompt.
+
+Build RTEMS with examples
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Build the RTEMS `xilinx-zynqmp-lp64-zu3eg` BSP. Use the ticker.exe sample which
+can be found in the directory:
+
+.. code-block:: shell
+
+  build/aarch64/xilinx-zynqmp-lp64-zu3eg/testsuites/samples
+
+Prepare the RTEMS image
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Prepare your RTEMS image to boot from u-boot with the following commands:
+
+.. code-block:: shell
+
+  $ aarch64-rtems6-objcopy -Obinary ticker.exe ticker.bin
+  $ gzip -9 ticker.bin
+  $ mkimage -A arm64 -O rtems -T kernel -a 0x10000000 -e 0x10000000 -n RTEMS -d ticker.bin.gz rtems.img
+
+Boot the RTEMS image
+^^^^^^^^^^^^^^^^^^^^
+Copy the prepared RTEMS image to the SD card and insert the SD crd in the ZCU102
+board. Power on the board. When you see the prompt on the console to interupt
+u-boot, hit a key to bring up the u-boot command prompt. On the u-boot command
+prompt you can boot your RTEMS image:
+
+.. code-block:: shell
+
+  Zynq-MP> fatload mmc 0:1 0x1000 rtems.img
+  Zynq-MP> bootm 0x1000
+
+This is the entire boot sequence:
+
+.. code-block:: shell
+
+  Pre-FSBL boot Started
+  Xilinx Zynq MP First Stage Boot Loader
+  Release 2020.2   Nov 18 2020  -  11:46:01
+  NOTICE:  ATF running on XCZU9EG/silicon v1/RTL5.1 at 0xfffea000
+  NOTICE:  BL31: v2.2(release):xilinx_rebase_v2.2_2020.1-10-ge6eea88b1
+  NOTICE:  BL31: Built : 12:28:45, Nov 17 2020
+
+  U-Boot 2020.01 (Jun 15 2021 - 14:24:32 +0000)
+
+  Model: ZynqMP ZCU102 Rev1.0
+  Board: Xilinx ZynqMP
+  DRAM:  4 GiB
+  PMUFW:  v1.1
+  EL Level:       EL2
+  Chip ID:        zu9eg
+  NAND:  0 MiB
+  MMC:   mmc@ff170000: 0
+  In:    serial@ff000000
+  Out:   serial@ff000000
+  Err:   serial@ff000000
+  Bootmode: SD_MODE1
+  Reset reason:   SOFT
+  Net:
+  ZYNQ GEM: ff0e0000, mdio bus ff0e0000, phyaddr 12, interface rgmii-id
+
+  Warning: ethernet@ff0e0000 (eth0) using random MAC address - 82:32:1d:80:d9:c9
+  eth0: ethernet@ff0e0000
+  Hit any key to stop autoboot:  0
+
+  ZynqMP> fatload mmc 0:1 0x1000 rtems.img
+  46669 bytes read in 27 ms (1.6 MiB/s)
+  ZynqMP> bootm 0x1000
+  ## Booting kernel from Legacy Image at 00001000 ...
+     Image Name:   RTEMS
+     Image Type:   AArch64 RTEMS Kernel Image (gzip compressed)
+     Data Size:    46605 Bytes = 45.5 KiB
+     Load Address: 10000000
+     Entry Point:  10000000
+     Verifying Checksum ... OK
+     Uncompressing Kernel Image
+  ## Transferring control to RTEMS (at address 10000000) ...
+
+  *** BEGIN OF TEST CLOCK TICK ***
+  *** TEST VERSION: 6.0.0.f381e9bab29278e4434b1a93e70d17a7562dc64c
+  *** TEST STATE: EXPECTED_PASS
+  *** TEST BUILD: RTEMS_POSIX_API RTEMS_SMP
+  *** TEST TOOLS: 10.3.1 20210409 (RTEMS 6, RSB ad54d1dd3cf8249d9d39deb1dd28b2f294df062d, Newlib eb03ac1)
+  TA1  - rtems_clock_get_tod - 09:00:00   12/31/1988
+  TA2  - rtems_clock_get_tod - 09:00:00   12/31/1988
+  TA3  - rtems_clock_get_tod - 09:00:00   12/31/1988
+  TA1  - rtems_clock_get_tod - 09:00:05   12/31/1988
+  TA2  - rtems_clock_get_tod - 09:00:10   12/31/1988
+  TA1  - rtems_clock_get_tod - 09:00:10   12/31/1988
+  TA1  - rtems_clock_get_tod - 09:00:15   12/31/1988
+  TA3  - rtems_clock_get_tod - 09:00:15   12/31/1988
+  TA2  - rtems_clock_get_tod - 09:00:20   12/31/1988
+  TA1  - rtems_clock_get_tod - 09:00:20   12/31/1988
+  TA1  - rtems_clock_get_tod - 09:00:25   12/31/1988
+  TA2  - rtems_clock_get_tod - 09:00:30   12/31/1988
+  TA1  - rtems_clock_get_tod - 09:00:30   12/31/1988
+  TA3  - rtems_clock_get_tod - 09:00:30   12/31/1988
+
+  *** END OF TEST CLOCK TICK ***
+
+  [ RTEMS shutdown ]
+
+
+Follow up
+^^^^^^^^^
+
+This is just one possible way to boot the RTEMS image. For a development
+environment you may wish to configure u-boot to boot the RTEMS image from a TFTP
+server. For a production environment, you may wish to download, configure, and
+build u-boot, or develop a BOOT.BIN image with the RTEMS application.
+
 Clock Driver
 ------------
 
diff --git a/user/bsps/arm/bsp-stm32h7.rst b/user/bsps/arm/bsp-stm32h7.rst
deleted file mode 100644
index bc2b471..0000000
--- a/user/bsps/arm/bsp-stm32h7.rst
+++ /dev/null
@@ -1,32 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2020 embedded brains GmbH
-
-stm32h7
-=======
-
-This BSP supports the
-`STM32H7 Series <https://www.st.com/en/microcontrollers-microprocessors/stm32h7-series.html>`_.
-The BSP is known to run on these boards:
-
-* `STM32H743I-EVAL 2 <https://www.st.com/en/evaluation-tools/stm32h743i-eval.html>`_
-
-Clock Driver
-------------
-
-The clock driver uses the `ARMv7-M Systick` module.
-
-Console Driver
---------------
-
-The console driver supports the on-chip UART and USART modules.
-
-Network Interface Driver
-------------------------
-
-The network interface driver ``if_stmac`` is provided by the ``libbsd``.
-
-USB Host Driver
----------------
-
-The USB host driver ``dwc_otg`` is provided by the ``libbsd``.
diff --git a/user/bsps/arm/imxrt.rst b/user/bsps/arm/imxrt.rst
index f8d9731..6dacfd9 100644
--- a/user/bsps/arm/imxrt.rst
+++ b/user/bsps/arm/imxrt.rst
@@ -128,9 +128,11 @@ with your FDT source names)::
                      -I ${PREFIX}/arm-rtems6/imxrt1052/lib/include \
                      -include "YOUR.dts" /dev/null | \
             dtc -O dtb -o "YOUR.dtb" -b 0 -p 64
-  sh> rtems-bin2c -C -N imxrt_dtb "YOUR.dtb" "YOUR.c"
+  sh> rtems-bin2c -A 8 -C -N imxrt_dtb "YOUR.dtb" "YOUR.c"
 
-Make sure that your new C file is compiled and linked into the application.
+You'll get a C file which defines the `imxrt_dtb` array. Make sure that your new
+C file is compiled and linked into the application. It will overwrite the
+existing definition of the `imxrt_dtb` in RTEMS.
 
 PLL Settings
 ------------
diff --git a/user/bsps/bsps-arm.rst b/user/bsps/bsps-arm.rst
index f8a1d60..7f1e9d4 100644
--- a/user/bsps/bsps-arm.rst
+++ b/user/bsps/bsps-arm.rst
@@ -9,7 +9,6 @@ arm (ARM)
 .. include:: arm/altera-cyclone-v.rst
 .. include:: arm/atsam.rst
 .. include:: arm/beagle.rst
-.. include:: arm/bsp-stm32h7.rst
 .. include:: arm/csb336.rst
 .. include:: arm/csb337.rst
 .. include:: arm/edb7312.rst
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
diff --git a/user/hosts/posix.rst b/user/hosts/posix.rst
index 818eb25..9769e07 100644
--- a/user/hosts/posix.rst
+++ b/user/hosts/posix.rst
@@ -74,7 +74,7 @@ provide a manual override:
 CentOS
 ~~~~~~
 
-The following packages are required on a minimal CentOS 6.3 or Cent)S 7
+The following packages are required on a minimal CentOS 6.3 or CentOS 7
 64-bit installation:
 
 .. code-block:: none
@@ -137,23 +137,23 @@ prefix under your home directory as recommended and end up on the SD card.
 Ubuntu
 ~~~~~~
 
-The latest version is Ubuntu 18.04.1 LTS 64-bit. This section also includes
+The latest version is Ubuntu 20.04.3 LTS 64-bit. This section also includes
 Xubuntu. A minimal installation was used and the following packages installed:
 
 .. code-block:: none
 
-  $ sudo apt-get build-dep build-essential gcc-defaults g++ gdb git \
-  unzip pax bison flex texinfo unzip python3-dev libpython-dev \
-  libncurses5-dev zlib1g-dev
+  $ sudo apt-get build-dep build-essential gcc-defaults g++ gdb unzip \
+  pax bison flex texinfo python3-dev libpython2-dev libncurses5-dev \
+  zlib1g-dev
 
-Note that in previous versions of Ubuntu, the package libpython-dev was
+Note that in previous versions of Ubuntu, the package libpython2-dev was
 python2.7-dev. The name of packages changes over time. You need the
 package with Python development libraries for C/C++ programs. The following
 is needed for recent versions:
 
 .. code-block:: none
 
-  $ sudo apt-get install python-dev
+  $ sudo apt-get install python git
 
 It is likely necessary that you will have to enable the Ubuntu Source
 Repositories.  Users have suggested the following web pages which have
diff --git a/user/overview/index.rst b/user/overview/index.rst
index 550724a..16389d9 100644
--- a/user/overview/index.rst
+++ b/user/overview/index.rst
@@ -355,6 +355,7 @@ sophisticated real-time applications are significantly reduced.
 
 .. [#] Thread-local storage requires some support by the tool chain and the
        RTEMS architecture support, e.g. context-switch code.  It is supported
-       at least on ARM, PowerPC, RISC-V, SPARC and m68k.  Check the
-       `RTEMS CPU Architecture Supplement <https://docs.rtems.org/branches/master/cpu-supplement.pdf>`_
-       if it is supported.
+       at least on ARM, AArch64, PowerPC, RISC-V, SPARC, MicroBlaze, Nios II,
+       and m68k.  Check the `RTEMS CPU Architecture Supplement
+       <https://docs.rtems.org/branches/master/cpu-supplement.pdf>`_ if it is
+       supported.