summaryrefslogtreecommitdiffstats
path: root/user
diff options
context:
space:
mode:
Diffstat (limited to 'user')
-rw-r--r--user/bsps/aarch64/xilinx-zynqmp.rst167
-rw-r--r--user/bsps/arm/bsp-stm32h7.rst32
-rw-r--r--user/bsps/arm/imxrt.rst6
-rw-r--r--user/bsps/bsps-arm.rst1
-rw-r--r--user/bsps/bsps-microblaze.rst149
-rw-r--r--user/hosts/posix.rst14
-rw-r--r--user/overview/index.rst7
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.