--- 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 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
