diff options
Diffstat (limited to 'user/bsps/arm')
| -rw-r--r-- | user/bsps/arm/altera-cyclone-v.rst | 4 | ||||
| -rw-r--r-- | user/bsps/arm/beagle.rst | 176 | ||||
| -rw-r--r-- | user/bsps/arm/csb337.rst (renamed from user/bsps/arm/bsp-csb337.rst) | 0 | ||||
| -rw-r--r-- | user/bsps/arm/fvp.rst | 39 | ||||
| -rw-r--r-- | user/bsps/arm/gdbarmsim.rst | 8 | ||||
| -rw-r--r-- | user/bsps/arm/imx.rst | 72 | ||||
| -rw-r--r-- | user/bsps/arm/imxrt.rst | 310 | ||||
| -rw-r--r-- | user/bsps/arm/lpc24xx.rst | 2 | ||||
| -rw-r--r-- | user/bsps/arm/raspberrypi.rst | 61 | ||||
| -rw-r--r-- | user/bsps/arm/realview-pbx-a9.rst | 16 | ||||
| -rw-r--r-- | user/bsps/arm/stm32f4.rst (renamed from user/bsps/arm/bsp-stm32f4.rst) | 0 | ||||
| -rw-r--r-- | user/bsps/arm/stm32h7.rst | 587 | ||||
| -rw-r--r-- | user/bsps/arm/xen.rst | 4 | ||||
| -rw-r--r-- | user/bsps/arm/xilinx-zynq.rst | 142 | ||||
| -rw-r--r-- | user/bsps/arm/xilinx-zynqmp-rpu.rst | 95 | ||||
| -rw-r--r-- | user/bsps/arm/xilinx-zynqmp.rst | 2 |
16 files changed, 1468 insertions, 50 deletions
diff --git a/user/bsps/arm/altera-cyclone-v.rst b/user/bsps/arm/altera-cyclone-v.rst index 14c026c..12e563e 100644 --- a/user/bsps/arm/altera-cyclone-v.rst +++ b/user/bsps/arm/altera-cyclone-v.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2017, 2019 embedded brains GmbH +.. Copyright (C) 2017, 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2017, 2019 Sebastian Huber altera-cyclone-v (Intel Cyclone V) @@ -27,7 +27,7 @@ image. Use the following commands: .. code-block:: none - arm-rtems5-objcopy -O binary app.exe app.bin + arm-rtems@rtems-ver-major@-objcopy -O binary app.exe app.bin gzip -9 -f -c app.bin > app.bin.gz mkimage -A arm -O linux -T kernel -a 0x00300000 -e 0x00300000 -n RTEMS -d app.bin.gz app.img diff --git a/user/bsps/arm/beagle.rst b/user/bsps/arm/beagle.rst index fe2dc6f..55f75c0 100644 --- a/user/bsps/arm/beagle.rst +++ b/user/bsps/arm/beagle.rst @@ -2,6 +2,12 @@ .. Copyright (C) 2019 Vijay Kumar Banerjee +.. _BSP_arm_beagle: +.. _BSP_arm_beagleboardorig: +.. _BSP_arm_beagleboardxm: +.. _BSP_arm_beagleboneblack: +.. _BSP_arm_beaglebonewhite: + beagle ====== @@ -26,7 +32,7 @@ To boot via uboot, the ELF must be converted to a U-Boot image like below: .. code-block:: none - arm-rtems5-objcopy hello.exe -O binary app.bin + arm-rtems@rtems-ver-major@-objcopy hello.exe -O binary app.bin gzip -9 app.bin mkimage -A arm -O linux -T kernel -a 0x80000000 -e 0x80000000 -n RTEMS -d app.bin.gz rtems-app.img @@ -61,23 +67,39 @@ Add the following to a file named uEnv.txt: I2C Driver ---------- -The Beagle has the `i2c-0` device registered at initialization. For registering -`i2c-1` and `i2c-2` ``bbb_register_i2c_1()`` and -``bbb_register_i2c_2()`` wrapper functions are respectively used. +The Beagle i2c initialization is based on the device tree. To initialize a i2c +device, the user has to enable the respective node in the device tree using +overlays. -For registering an I2C device with a custom path (say `/dev/i2c-3`) the -function ``am335x_i2c_bus_register()`` has to be used. +For registering an I2C device with a custom path (say `/dev/i2c-eeprom`) an +overlay has to be provided. The overlay must add an additional attribute +`rtems,path` with the custom path as value to the respective i2c node. -The function prototype is given below: +For example, + +.. code-block:: none + + /dts-v1/; + + / { + compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx"; -.. code-block:: C + fragment@0 { + target = <0xffffffff>; - int am335x_i2c_bus_register( - const char *bus_path, - uintptr_t register_base, - uint32_t input_clock, - rtems_vector_number irq - ); + __overlay__ { + compatible = "rtems,bsp-i2c", "ti,omap4-i2c"; + status = "okay"; + rtems,path = "/dev/i2c-eeprom"; + }; + }; + + __fixups__ { + i2c0 = "/fragment@0:target:0"; + }; + }; + +The above example registers a custom path `/dev/i2c-eeprom` for i2c0. SPI Driver ---------- @@ -88,10 +110,134 @@ For registering with a custom path, the ``bsp_register_spi()`` can be used. The function prototype is given below: -.. code-block:: C +.. code-block:: c rtems_status_code bsp_register_spi( const char *bus_path, uintptr_t register_base, rtems_vector_number irq ); + +Debugging using libdebugger +--------------------------- + +RTEMS's ``libdebugger`` requires the ARM debug resources be enabled for it to +work. The TI SOC used on the ``beagleboneblack`` board provides no access for +software to the ARM defined debug enable signal ``DBGEN``. The signal is +negated on power up locking software out of the ARM debug hardware. The signal +can only be accessed via the JTAG interface. + +The ``beagleboneblack`` BSP provides a low level solution to enable the +``DBGEN`` signal via the JTAG interface if the board has the following +hardware modification installed. The modification requires the addition of two +small wire links soldered to the pads of the JTAG connect on the underside of +the board. A small length of fine wire, a fine tip soldering iron, some good +quality solder and a pair of fine tip pliers are required. If you are new to +soldering I suggest you find something to practice on first. + +The modification details and software driver can be found in the BSP in the +file ``bsps/arm/beagle/start/bspdebug.c``. The driver is automatically run +and the ``DBGEN`` is asserted via JTAG when ``libdebugger`` is started. + +The modification is: + +1. Locate P2 on the bottom side of the board. It is the JTAG connector + pads. If you look at the underside of the board with the SD card holder to + the right the pads are top center left. There are 20 pads in two + columns. The pads are numbered 1 at the top left then 2 top right, 3 is + second top on the left, 4 is second top to the right, then the pin number + increments as you move left then right down the pads. + +2. Connect P2 to P5. + +3. Connect P7 to P13. + +The resulting wiring is: + +.. code-block:: none + + 1 === /--=== 2 + 3 === | === 4 + 5 ===--/ === 6 + 7 ===--\ === 8 + 9 === | === 10 + 11 === | === 12 + 13 ===--/ === 14 + 15 === === 16 + 17 === === 18 + 19 === === 20 + +.. figure:: ../../../images/user/bbb-p2-debug-mod.jpg + :width: 50% + :align: center + :alt: BeagleBone Black JTAG Hardware Modification + + BeagleBone Black JTAG Hardware Modification + +If ``libdebugger`` fails to detect the registers open the ``bspdebug.c`` +source and change ``has_tdo`` to ``1``, save then rebuild and install the +BSP. This will turn on an internal feeback to check the JTAG logic. Discard +the edit once the hardware is working. + +Debugging Beagle Bone Black using a JTAG debugger and gdb +--------------------------------------------------------- + +Debugging a Beagle Bone Black (or variants) is also possible using a hardware +JTAG debugger. The JTAG is available via P2. The footprint is for an ARM 20 pin +cTI connector. That connector should be used, if it is necessary to have access +to commercially available adapters. + +For hand-made cables and adapters a standard 1.27mm pitch header and a 0.635mm +ribbon cable can be much cheaper. But note that even if it looks compatible, +it's not the same pin out as a ARM Cortex 20 pin connector! + +A lot of JTAG adapters that are working together with OpenOCD will work. There +are also commercially available systems (like Segger J-Link) that work well with +the Beagle. Note that the JTAG debugger has to be compatible with ARM Cortex A8. +Cortex M only debuggers (like the Segger J-Link Edu Mini) won't work. + +If the debugger offers a gdb server (like OpenOCD or Segger J-Link) the +following gdb start script can be used: + +.. code-block:: none + + define reset + echo -- Reset target and wait for U-Boot to start kernel.\n + monitor reset + # RTEMS U-Boot starts at this address. + tbreak *0x80000000 + # Linux starts here. + tbreak *0x82000000 + continue + + echo -- Disable watchdog.\n + set *(uint32_t*)0x44e35048=0xAAAA + while (*(uint32_t*)0x44e35034 != 0) + end + set *(uint32_t*)0x44e35048=0x5555 + while (*(uint32_t*)0x44e35034 != 0) + end + + echo -- Overwrite kernel with application to debug.\n + load + end + + target remote :2331 + +Note that you might have to replace the ``monitor reset`` by some other command +that resets the target using your specific debugger. You also have to replace +the ``target remote :2331`` to match the port of your gdb server. + +The script expects that the Beagle Bone Black starts some application from an SD +card or from eMMC. It defines a ``reset`` command that does the following: + + * reset the target + * let U-Boot run, initialize the base system, load an FDT and an application + * break at the application entry point + * disable the watchdog + * overwrite the application that has been loaded by U-Boot with the application + provided as an command line argument to gdb + +This method has the advantage that the application is executed in nearly the +same environment like it would be executed if loaded by U-Boot directly (except +for the watchdog). diff --git a/user/bsps/arm/bsp-csb337.rst b/user/bsps/arm/csb337.rst index 6f7d927..6f7d927 100644 --- a/user/bsps/arm/bsp-csb337.rst +++ b/user/bsps/arm/csb337.rst diff --git a/user/bsps/arm/fvp.rst b/user/bsps/arm/fvp.rst new file mode 100644 index 0000000..b938e30 --- /dev/null +++ b/user/bsps/arm/fvp.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 embedded brains GmbH & Co. KG + +fvp (Fixed Virtual Platform) +============================ + +The BSP for the +`Arm Fixed Virtual Platforms <https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms>`_ +offers one variant. You need a license from Arm to run the simulator. The +`fvp_cortex_r52` variant supports a simulation of the Cortex-R52 processor. +The BSP supports the SMP configuration. + +Run an Executable +----------------- + +To run an executable on a single Cortex-R52 processor use: + +.. code-block:: none + + FVP_BaseR_Cortex-R52x1 -C bp.vis.disable_visualisation=1 -a build/arm/fvp_cortex_r52/testsuites/samples/ticker.exe + +To run an executable on a four Cortex-R52 processors use: + +.. code-block:: none + + FVP_BaseR_Cortex-R52x4 -C bp.vis.disable_visualisation=1 -a build/arm/fvp_cortex_r52/testsuites/samples/ticker.exe + +Clock Driver +------------ + +The clock driver uses the `ARMv7-AR Generic Timer`. + +Console Driver +-------------- + +The console driver uses the +`semihosting <https://developer.arm.com/documentation/dui0471/g/Semihosting/Semihosting-operations?lang=en>`_ +``SYS_READC`` and ``SYS_WRITEC`` system calls. diff --git a/user/bsps/arm/gdbarmsim.rst b/user/bsps/arm/gdbarmsim.rst deleted file mode 100644 index 26ea90c..0000000 --- a/user/bsps/arm/gdbarmsim.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2019 TBD - -gdbarmsim -========= - -TODO. diff --git a/user/bsps/arm/imx.rst b/user/bsps/arm/imx.rst index bc93ae3..47ad503 100644 --- a/user/bsps/arm/imx.rst +++ b/user/bsps/arm/imx.rst @@ -1,20 +1,23 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2017, 2019 embedded brains GmbH +.. Copyright (C) 2017, 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2017, 2019 Sebastian Huber imx (NXP i.MX) ============== This BSP offers only one variant, the `imx7`. This variant supports the i.MX -7Dual processor. The basic hardware initialization is not performed by the -BSP. A boot loader with device tree support must be used to start the BSP, -e.g. U-Boot. +7Dual processor and the i.MX 6UL/ULL processor family (with slightly different +clock settings). The basic hardware initialization is not performed by the BSP. +A boot loader with device tree support must be used to start the BSP, e.g. +U-Boot or barebox. Build Configuration Options --------------------------- -The following options are available at the configure command line. +The following options can be used in the BSP section of the waf +configuration INI file. The waf defaults can be used to inspect the +values. ``BSP_PRESS_KEY_FOR_RESET`` If defined to a non-zero value, then print a message and wait until pressed @@ -40,9 +43,30 @@ The following options are available at the configure command line. ``IMX_CCM_UART_HZ`` The UART clock frequency in Hz (default is 24000000). +``IMX_CCM_ECSPI_HZ`` + The ECSPI clock frequency in Hz (default is 67500000). + ``IMX_CCM_AHB_HZ`` The AHB clock frequency in Hz (default is 135000000). +``IMX_CCM_SDHCI_HZ`` + The SDHCI clock frequency in Hz (default is 196363000). + +Clock settings for different boards +----------------------------------- + +The default clock settings are targeted for an i.MX 7Dual evaluation board using +U-Boot. Some other boards with different boot loaders need different settings: + + * Phytec phyCORE-i.MX 6ULL (system on module) with MCIMX6Y2CVM08AB and a + barebox bootloader (version ``2019.01.0-bsp-yocto-i.mx6ul-pd19.1.0``): + + * IMX_CCM_IPG_HZ=66000000 + * IMX_CCM_UART_HZ=80000000 + * IMX_CCM_AHB_HZ=66000000 + * IMX_CCM_SDHCI_HZ=198000000 + * IMX_CCM_ECSPI_HZ=60000000 + Boot via U-Boot --------------- @@ -51,7 +75,7 @@ image. Use the following commands: .. code-block:: none - arm-rtems5-objcopy -O binary app.exe app.bin + arm-rtems@rtems-ver-major@-objcopy -O binary app.exe app.bin gzip -9 -f -c app.bin > app.bin.gz mkimage -A arm -O linux -T kernel -a 0x80200000 -e 0x80200000 -n RTEMS -d app.bin.gz app.img @@ -65,6 +89,14 @@ The ``loadfdt`` command may be not defined in your U-Boot environment. Just replace it with the appropriate commands to load the device tree at ``${fdt_addr}``. +Boot via barebox +---------------- + +The same command like for U-Boot can be used to generate an application image. +In a default configuration barebox expects an fdt image called `oftree` and a +kernel image called `zImage` in the root folder of the bootable medium (e.g. an +SD card). + Clock Driver ------------ @@ -133,6 +165,34 @@ system controls: A value of zero for the time or count disables the interrupt coalescing in the corresponding direction. +On the Phytec phyCORE-i.MX 6ULL modules the PHY needs an initialization for the +clock. A special PHY driver handles that (``ksz8091rnb``). Add it to your libbsd +config like that: + +.. code-block:: c + + #define RTEMS_BSD_CONFIG_BSP_CONFIG + #define RTEMS_BSD_CONFIG_INIT + SYSINIT_DRIVER_REFERENCE(ksz8091rnb, miibus); + #include <machine/rtems-bsd-config.h> + +On chips with two Ethernet controllers, the MDIO lines are shared between the +two controllers for a number of chips variants. This is currently supported with +some restrictions on the initialization order. For this configuration to work, +you have to make sure that the pins are assigned to the Ethernet controller that +is initialized first. The initialization order in `libbsd` depends on the order +of the Ethernet controllers in the device tree. So if (for example) `fec2` is +defined in the device tree sources before `fec1`, make sure that the MDIO lines +are routed to `fec2` and that the Ethernet PHYs are a sub-node of `fec2` in the +device tree. + +Note that the clock for the second Ethernet controller is not necessarily +enabled in the `CCM`. On the i.MX6UL/ULL, the clock will be enabled by the +startup code if the node that is compatible with `fsl,imx6ul-anatop` can be +found in the device tree. If you have trouble with the second Ethernet +controller make sure that the `ENET2_125M_EN` bit in the `CCM_ANALOG_PLL_ENET` +register is set as expected. + MMC/SDCard Driver ----------------- diff --git a/user/bsps/arm/imxrt.rst b/user/bsps/arm/imxrt.rst new file mode 100644 index 0000000..30b1437 --- /dev/null +++ b/user/bsps/arm/imxrt.rst @@ -0,0 +1,310 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG +.. Copyright (C) 2020 Christian Mauderer + +imxrt (NXP i.MXRT) +================== + +This BSP offers multiple variants. The `imxrt1052` supports the i.MXRT 1052 +processor on a IMXRT1050-EVKB (tested with rev A1). Some possibilities to adapt +it to a custom board are described below. + +NOTE: The IMXRT1050-EVKB has an backlight controller that must not be enabled +without load. Make sure to either attach a load, disable it by software or +disable it by removing the 0-Ohm resistor on it's input. + +The `imxrt1166-cm7-saltshaker` supports an application specific board. Adapting +it to another i.MXRT1166 based board works similar like for the `imxrt1052` BSP. + +Build Configuration Options +--------------------------- + +Please see the documentation of the `IMXRT_*` and `BSP_*` configuration options +for that. You can generate a default set of options with:: + + ./waf bspdefaults --rtems-bsps=arm/imxrt1052 > config.ini + +Adapting to a different board +----------------------------- + +This is only a short overview for the most important steps to adapt the BSP to +another board. Details for most steps follow further below. + +#. The device tree has to be adapted to fit the target hardware. +#. A matching clock configuration is necessary (simplest method is to generate + it with the NXP PinMux tool) +#. The `dcd_data` has to be adapted. That is used for example to initialize + SDRAM. +#. `imxrt_flexspi_config` has to be adapted to match the Flash connected to + FlexSPI (if that is used). +#. `BOARD_InitDEBUG_UARTPins` should be adapted to match the used system + console. + +Boot Process of IMXRT1050-EVKB +------------------------------ + +There are two possible boot processes supported: + +1) The ROM code loads a configuration from HyperFlash (connected to FlexSPI), + does some initialization (based on device configuration data (DCD)) and then + starts the application. This is the default case. `linkcmds.flexspi` is used + for this case. + +2) Some custom bootloader does the basic initialization, loads the application + to SDRAM and starts it from there. Select the `linkcmds.sdram` for this. + +For programming the HyperFlash in case 1, you can use the on board debugger +integrated into the IMXRT1050-EVKB. You can generate a flash image out of a +compiled RTEMS application with for example:: + + arm-rtems@rtems-ver-major@-objcopy -O binary build/arm/imxrt1052/testsuites/samples/hello.exe hello.bin + +Then just copy the generated binary to the mass storage provided by the +debugger. Wait a bit till the mass storage vanishes and re-appears. After that, +reset the board and the newly programmed application will start. + +NOTE: It seems that there is a bug on at least some of the on board debuggers. +They can't write more than 1MB to the HyperFlash. If your application is bigger +than that (like quite some of the applications in libbsd), you should use an +external debugger or find some alternative programming method. + +For debugging: Create a special application with a `while(true)` loop at end of +`bsp_start_hook_1`. Load that application into flash. Then remove the loop +again, build your BSP for SDRAM and use a debugger to load the application into +SDRAM after the BSP started from flash did the basic initialization. + +Flash Image +----------- + +For booting from a HyperFlash (or other storage connected to FlexSPI), the ROM +code of the i.MXRT first reads some special flash header information from a +fixed location of the connected flash device. This consists of the Image vector +table (IVT), Boot data and Device configuration data (DCD). + +In RTEMS, these flash headers are generated using some C-structures. If you use +a board other than the IMXRT1050-EVKB, those structures have to be adapted. To +do that re-define the following variables in your application (you only need the +ones that need different values): + +.. code-block:: c + + #include <bsp/flash-headers.h> + const uint8_t imxrt_dcd_data[] = + { /* Your DCD data here */ }; + const ivt imxrt_image_vector_table = + { /* Your IVT here */ }; + const BOOT_DATA_T imxrt_boot_data = + { /* Your boot data here */ }; + const flexspi_nor_config_t imxrt_flexspi_config = + { /* Your FlexSPI config here */ }; + +You can find the default definitions in `bsps/arm/imxrt/start/flash-*.c`. Take a +look at the `i.MX RT1050 Processor Reference Manual, Rev. 4, 12/2019` chapter +`9.7 Program image` or `i.MX RT1166 Processor Reference Manual, Rev. 0, 05/2021` +chapter `10.7 Program image` for details about the contents. + +FDT +--- + +The BSP uses a FDT based initialization. The FDT is linked into the application. +You can find the default FDT used in the BSPs in `bsps/arm/imxrt/dts`. The FDT +is split up into two parts. The controller specific part is put into an `dtsi` +file. The board specific one is in the dts file. Both are installed together +with normal headers into +`${PREFIX}/arm-rtems@rtems-ver-major@/${BSP}/lib/include`. You can use that to +create your own device tree based on that. Basically use something like:: + + /dts-v1/; + + #include <imxrt/imxrt1050-pinfunc.h> + #include <imxrt/imxrt1050.dtsi> + + &lpuart1 { + pinctrl-0 = <&pinctrl_lpuart1>; + status = "okay"; + }; + + &chosen { + stdout-path = &lpuart1; + }; + + /* put your further devices here */ + + &iomuxc { + pinctrl_lpuart1: lpuart1grp { + fsl,pins = < + IMXRT_PAD_GPIO_AD_B0_12__LPUART1_TX 0x8 + IMXRT_PAD_GPIO_AD_B0_13__LPUART1_RX 0x13000 + >; + }; + + /* put your further pinctrl groups here */ + }; + +You can then convert your FDT into a C file with (replace `YOUR.dts` and similar +with your FDT source names): + +.. code-block:: none + + sh> arm-rtems@rtems-ver-major@-cpp -P -x assembler-with-cpp \ + -I ${PREFIX}/arm-rtems@rtems-ver-major@/imxrt1052/lib/include \ + -include "YOUR.dts" /dev/null | \ + dtc -O dtb -o "YOUR.dtb" -b 0 -p 64 + sh> rtems-bin2c -A 8 -C -N imxrt_dtb "YOUR.dtb" "YOUR.c" + +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. + +Clock Driver +------------ + +The clock driver uses the generic `ARMv7-M Clock`. + +IOMUX +----- + +The i.MXRT IOMUXC is initialized based on the FDT. For that, the `pinctrl-0` +fields of all devices with a status of `ok` or `okay` will be parsed. + +Console Driver +-------------- + +LPUART drivers are registered based on the FDT. The special `rtems,path` +attribute defines where the device file for the console is created. + +The `stdout-path` in the `chosen` node determines which LPUART is used for the +console. + +I2C Driver +---------- + +I2C drivers are registered based on the FDT. The special `rtems,path` attribute +defines where the device file for the I2C bus is created. + +Limitations: + +* Only basic I2C is implemented. This is mostly a driver limitation and not a + hardware one. + +SPI Driver +---------- + +SPI drivers are registered based on the FDT. The special `rtems,path` attribute +defines where the device file for the SPI bus is created. + +Note that the SPI-pins on the evaluation board are shared with the SD card. +Populate R278, R279, R280, R281 on the IMXRT1050-EVKB (Rev A) to use the SPI +pins on the Arduino connector. + +By default, the native chip selects are used. If you want to use GPIOs as chip +select instead, you can use the `cs-gpios` and `num-cs` attributes just like on +a Linux SPI controller. A maximum of `IMXRT_LPSPI_MAX_CS` pins can be used. + +The hardware doesn't support selecting no native chip select during a transfer. +Therefore one native chip select has to be reserved as a dummy if you want to be +able to use GPIOs. The pin function for this chip select must not be configured +on any pin. Dummy will be the first of the first four chip selects that is not a +native one. Example configuration:: + + &lpspi4 { + status = "okay"; + pinctrl-0 = <&my_pinctrl_lpspi4>; + cs-gpios = <0>, <0>, <&gpio1 1 0>, <0>, <&gpio11 5 1>; + num-cs = <5>; + } + +In this case, CS2 will be the dummy chip select and no pin must be configured +with that function. CS0, CS1 and CS3 are just native chip selects and should be +used via pin functions. GPIO1.1 is used as a high active CS and GPIO11.5 a low +active one. + +Limitations: + +* Only a basic SPI driver is implemented. This is mostly a driver limitation and + not a hardware one. +* GPIO CS pins on i.MXRT10xx are not tested. The chip has a lot of errate so + they might not work. +* Switching from one mode (CPOL/CPHA) to another one can lead to single wrong + edges on the CLK line if GPIO CS pins are involved. Make sure to stuff a dummy + transfer with `SPI_NO_CS` set if you use multiple modes together with a GPIO + CS. + +Network Interface Driver +------------------------ + +The network interface driver is provided by the `libbsd`. It is initialized +according to the device tree. + +Note on the hardware: The i.MXRT1050 EVKB maybe has a wrong termination of the +RXP, RXN, TXP and TXN lines. The resistors R126 through R129 maybe shouldn't be +populated because the used KSZ8081RNB already has an internal termination. +Ethernet does work on short distance anyway. But keep it in mind in case you +have problems. Source: +https://community.nxp.com/t5/i-MX-RT/Error-in-IMXRT1050-EVKB-and-1060-schematic-ethernet/m-p/835540#M1587 + +NXP SDK files +------------- + +A lot of peripherals are currently not yet supported by RTEMS drivers. The NXP +SDK offers drivers for these. For convenience, the BSP compiles the drivers from +the SDK. But please note that they are not tested and maybe won't work out of +the box. Everything that works with interrupts most likely needs some special +treatment. + +The SDK files are imported to RTEMS from the NXP mcux-sdk git repository that +you can find here: https://github.com/nxp-mcuxpresso/mcux-sdk/ + +The directory structure has been preserved and all files are in a +`bsps/arm/imxrt/mcux-sdk` directory. All patches to the files are marked with +`#ifdef __rtems__` markers. + +The suggested method to import new or updated files is to apply all RTEMS +patches to the mcux-sdk repository, rebase them to the latest mcux-sdk release +and re-import the files. The new base revision should be mentioned in the commit +description to make future updates simpler. + +A import helper script (that might or might not work on newer releases of the +mcux-sdk) can be found here: +https://raw.githubusercontent.com/c-mauderer/nxp-mcux-sdk/d21c3e61eb8602b2cf8f45fed0afa50c6aee932f/export_to_RTEMS.py + +Clocks and SDRAM +---------------- + +The clock configuration support is quite rudimentary. The same is true for +SDRAM. It mostly relies on the DCD and on a static clock configuration that is +taken from the NXP SDK example projects. + +If you need to adapt the DCD or clock config to support a different hardware, +you should generate these files using the NXP MCUXpresso Configuration Tools. +You can add the generated files to your application to overwrite the default +RTEMS ones or you can add them to RTEMS in a new BSP variant. + +As a special case, the imxrt1052 BSP will adapt it's PLL setting based on the +chip variant. The commercial variant of the i.MXRT1052 will use a core clock of +600MHz for the ARM core. The industrial variants only uses 528MHz. For other +chip or BSP variants, you should adapt the files generated with the MCUXpresso +Configuration Tools. + +Caveats +------- + +* The MPU settings are currently quite permissive. + +* There is no power management support. + +* On the i.MXRT1166, sleeping of the Cortex M7 can't be disabled even for + debugging purposes. That makes it hard for a debugger to access the + controller. To make debugging a bit easier, it's possible to overwrite the + idle thread with the following one in the application: + + .. code-block:: c + + void * _CPU_Thread_Idle_body(uintptr_t ignored) + { + (void)ignored; + while (true) { + /* void */ + } + } diff --git a/user/bsps/arm/lpc24xx.rst b/user/bsps/arm/lpc24xx.rst index ecf1d84..f287dc8 100644 --- a/user/bsps/arm/lpc24xx.rst +++ b/user/bsps/arm/lpc24xx.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2017, 2019 embedded brains GmbH +.. Copyright (C) 2017, 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2017, 2019 Sebastian Huber lpc24xx (NXP LPC17XX/LPC24XX/LPC40XX) diff --git a/user/bsps/arm/raspberrypi.rst b/user/bsps/arm/raspberrypi.rst index 72889a5..8f40e92 100644 --- a/user/bsps/arm/raspberrypi.rst +++ b/user/bsps/arm/raspberrypi.rst @@ -5,13 +5,14 @@ raspberrypi =========== -This BSP supports `Raspberry Pi 1` and `Raspberry Pi 2` currently. -The support for `Raspberry Pi 3` is work under progress. +The 'raspberrypi' BSP supports the single core models (Zero, Zero W, A+, B+), +and the 'raspberrypi2' BSP supports the Raspberry Pi 2, Raspberry Pi 3 A+, and Raspberry Pi 3. +The Raspberry Pi 4 is not supported currently. The default bootloader on the Raspberry Pi which is used to boot Raspbian or other OS can be also used to boot RTEMS. U-boot can also be used. Setup SD card ----------------- +------------- The Raspberry Pis have an unconventional booting mechanism. The GPU boots first, initializes itself, runs the bootloader and starts the CPU. @@ -19,11 +20,13 @@ The bootloader looks for a kernel image, by default the kernel images must have a name of the form ``kernel*.img`` but this can be changed by adding `kernel=<img_name>` to ``config.txt``. -You must provide the required files for the GPU to proceed. These files -can be downloaded from -`the Raspberry Pi Firmware Repository <https://github.com/raspberrypi/firmware/tree/master/boot>`_. -You can remove the ``kernel*.img`` files if you want too, but don't touch -the other files. +You must provide the required firmware files on the SD card for the GPU to +proceed, and thereby to boot RTEMS. The BSP currently boots up with an older +version of the official firmware. These files can be downloaded from `the +Raspberry Pi Firmware Repository +<https://github.com/raspberrypi/firmware/tree/1.20200601/boot>`_. You can +remove the ``kernel*.img`` files if you want to, but don't touch the other +files. Copy these files in to a SD card with FAT filesystem. @@ -38,7 +41,7 @@ To create the kernel image: .. code-block:: none - $ arm-rtems5-objcopy -Obinary hello.exe kernel.img + $ xsarm-rtems@rtems-ver-major@-objcopy -Obinary hello.exe kernel.img Copy the kernel image to the SD card. @@ -46,10 +49,46 @@ Make sure you have these lines below, in your ``config.txt``. .. code-block:: none - enable-uart=1 + dtoverlay=disable-bt kernel_address=0x200000 kernel=kernel.img +SPI Driver +---------- + +SPI drivers are registered by the ``rpi_spi_init(bool bidirectional_mode)`` function. + +.. code-block:: none + + #include <assert.h> + #include <bsp.h> + + void spi_init(void) + { + int rv; + + rv = rpi_spi_init(false); + assert(rv == 0); + } + +I2C Driver +---------- + +I2C drivers are registered by the ``rpi_setup_i2c_bus()`` function. + +.. code-block:: none + + #include <assert.h> + #include <bsp.h> + + void i2c_init(void) + { + int rv; + + rv = rpi_setup_i2c_bus(); + assert(rv == 0); + } + Testing using QEMU ------------------ @@ -93,7 +132,7 @@ In a new terminal, run GDB using .. code-block:: none - $ arm-rtems5-gdb hello.exe + $ arm-rtems@rtems-ver-major@-gdb hello.exe This will open GDB and will load the symbol table from hello.exe. Issue the following commands in the GDB prompt. diff --git a/user/bsps/arm/realview-pbx-a9.rst b/user/bsps/arm/realview-pbx-a9.rst index 96710a0..bbe0269 100644 --- a/user/bsps/arm/realview-pbx-a9.rst +++ b/user/bsps/arm/realview-pbx-a9.rst @@ -1,8 +1,20 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 TBD +.. Copyright (C) 2020 embedded brains GmbH & Co. KG realview-pbx-a9 =============== -TODO. +The ``arm/realview_pbx_a9_qemu`` BSP is intended to be used with Qemu. The +Qemu ``realview-pbx-a9`` machine can be used to run SMP tests using for example +the Qemu ``-smp 4`` command line option. + +The command line to execute an ELF file :file:`app.exe` on this Qemu machine +is: + +.. code-block:: none + + export QEMU_AUDIO_DRV="none" + qemu-system-arm -net none -nographic -M realview-pbx-a9 -m 256M -kernel app.exe + +You do not need to specify a device tree blob. diff --git a/user/bsps/arm/bsp-stm32f4.rst b/user/bsps/arm/stm32f4.rst index 23e764e..23e764e 100644 --- a/user/bsps/arm/bsp-stm32f4.rst +++ b/user/bsps/arm/stm32f4.rst diff --git a/user/bsps/arm/stm32h7.rst b/user/bsps/arm/stm32h7.rst new file mode 100644 index 0000000..cdf4d43 --- /dev/null +++ b/user/bsps/arm/stm32h7.rst @@ -0,0 +1,587 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. Copyright (C) 2022 Karel Gardas <karel@functional.vision> + +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 on specified core with using specified BSP variant. + +.. table:: + + +----------------------------------------------------------------------------------+-----------+------------------------+ + | Board name | Core name | BSP variant name | + +==================================================================================+===========+========================+ + |`STM32H743I-EVAL 2 <https://www.st.com/en/evaluation-tools/stm32h743i-eval.html>`_| M7 | arm/stm32h7 | + +----------------------------------------------------------------------------------+-----------+------------------------+ + |`STM32H743ZI-Nucleo <https://www.st.com/en/evaluation-tools/nucleo-h743zi.html>`_ | M7 | arm/nucleo-h743zi | + +----------------------------------------------------------------------------------+-----------+------------------------+ + |`STM32H7B3I-DK <https://www.st.com/en/evaluation-tools/stm32h7b3i-dk.html>`_ | M7 | arm/stm32h7b3i-dk | + +----------------------------------------------------------------------------------+-----------+------------------------+ + |`STM32H757I-EVAL <https://www.st.com/en/evaluation-tools/stm32h757i-eval.html>`_ | M7 | arm/stm32h757i-eval | + | +-----------+------------------------+ + | | M4 | arm/stm32h757i-eval-m4 | + +----------------------------------------------------------------------------------+-----------+------------------------+ + |`STM32H747I-DISCO <https://www.st.com/en/evaluation-tools/stm32h747i-disco.html>`_| M7 | arm/stm32h747i-disco | + | +-----------+------------------------+ + | | M4 | arm/stm32h747i-disco-m4| + +----------------------------------------------------------------------------------+-----------+------------------------+ + + +Clock Driver +------------ + +The clock driver uses the `ARMv7-M Systick` module. The HSE (external +oscillator) value can also be different for different evaluation or custom +boards, so it is recommended to check the default values of the BSP. + +Console Driver +-------------- + +The console driver supports the on-chip UART and USART modules. Even +the MCU supports about 10 U(S)ARTs, only those supported by the chosen +board are enabled by default configuration. The board needs to support +some kind of connector-based connection to the U(S)ART in order for the +feature to be considered supported here. +.. +.. Leaving previous notes here as a comment. They may still be useful +.. and incorporated into the later version of the document. +.. +.. Different board variations use different GPIO pins and blocks for the default +.. communication UART and it is recommended to check whether the default +.. configuration provided is valid in the BSP. + +.. To specify that the BSP should be built for the STM32H743ZI-Nucleo board, +.. users can supply ``STM32H743ZI_NUCLEO = True`` to ``config.ini`` when +.. building the BSP. + +.. Alternatively, users can supply the configuration structs defined in ``hal.h`` +.. in the application for other boards. For the console driver, the +.. ``stm32h7_usartX_config`` structs are used to configure the GPIO pins and other +.. parameters. The default implementations can be found in +.. ``bsps/arm/stm32ht/console`` in the RTEMS sources. + +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``. + +SD/MMC Driver +------------- + +The SDMMC driver ``st_sdmmc`` is provided by the ``libbsd``. + +The default initialization is done for the STM32H743I-EVAL 2 board. + +To use different pins, you can create a ``HAL_SD_MspInit()`` function in your +application that overwrites the default one defined in ``RTEMS``. If you don't +have direction lines like on the evaluation board, you can just skip +initializing these pins. + +If you want to use a different number of data lines, another polarity for the +data direction pins, a different voltage or similar, you have to redefine +``st_sdmmc_get_config()`` (normally provided by ``libbsd``) in your application. + +Known limitations: + +* Currently 1.8V signaling is not implemented. Therefore higher speeds like used + for UHS cards are not available. All cards fall back to High Speed transfers. +* The driver uses the IDMA only. MDMA is currently not implemented. For SDMMC1 + that means that the memory buffers can only come from AXI SRAM, QSPI memory, + Flash or the FMC (SDRAM, ...). The internal SRAM1, SRAM2, SRAM3 and SRAM4 are + not supported. SDMMC2 should not have that limitation. See ST AN5200 "Getting + started with STM32H7 Series SDMMC host controller" for more details. + + +How to run RTEMS on the board +----------------------------- +Following few paragraphs save a purpose of simple HOWTO or a quick +starting guide for the users not versed in STM32 toolchain and their +boards workflow. + +Board hardware setup +^^^^^^^^^^^^^^^^^^^^ +Connect board with the host computer using micro-USB cable connected +to micro-USB connector on the board marked with 'ST-LINK V3E' in case of evaluation +and discovery boards or with 'USB PWR' in case of Nucleo board. + +STM32CubeIDE installation +^^^^^^^^^^^^^^^^^^^^^^^^^ +Download and install STM32CubeIDE from +https://www.st.com/en/development-tools/stm32cubeide.html. Install the +software into the user directory. On Linux install with 'sudo' command +to install as a root since as part of the installation USB permissions +rules for ST-Link GDB server are also installed. The reason for +installing into the user directory is that the IDE is based on +Eclipse, which provides +its own update method and this will not work well in case of read-only +access to the installation directory. In case of any troubles consult +installation manual provided by ST here https://www.st.com/resource/en/user_manual/um2563-stm32cubeide-installation-guide-stmicroelectronics.pdf. +Although we will not used full fledged IDE here, the package provides ST-Link GDB Server which will be used for uploading RTEMS binaries to the board +memory. + +STM32CubeProgrammer installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Download and install STM32CubeProgrammer from +https://www.st.com/en/development-tools/stm32cubeprog.html. We will +use this software for board setup required for RTEMS and later when +something goes wrong to delete content of the MCU flash memory. The +software is also internally used by the ST-Link GDB Server from +STM32CubeIDE so it is crucial to have it installed. + +Board ST-Link firmware upgrade +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Download ST-Link board firmware upgrade package from +https://www.st.com/en/development-tools/stsw-link007.html. The +software is distributed in a form of Java jar file for Linux and Mac +OSX and in a form of Windows binary for MS Windows. Unpack it +somewhere and run it with + +.. code-block:: shell + + $ unzip en.stsw-link007-v3-9-3_v3.9.3.zip + $ cd stsw-link007/AllPlatforms + $ java -jar STLinkUpgrade.jar + +Click on *Open in update mode* button and then if *Version* and *Update +to Firmware* version information are different in shown version number/code, click on *Upgrade* +button and wait till upgrade finishes. + +.. note: On Linux you will need to have libusb library installed in + order to make upgrade process working. On Ubuntu 20.04 LTS you can do + that with following command. + +.. code-block:: shell + + $ sudo apt install libusb-1.0-0 + + +Dual core board setup for RTEMS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Current RTEMS BSP supports +running MCU in a single-core mode only on either M7 core or M4 +core. That means that to not leave other core interfering with the +system we either need to upload short infinite loop code to it or we +may switch off the core completely. The second option is what is +described here. The board by default switches on and starts both +cores. Based on chosen BSP variant you may like to switch off other +core with using STMCubeProgrammer tool. +Go to the directory where you have installed STMCubeProgrammer +software and run it with + +.. code-block:: shell + + $ cd bin + $ ./STM32CubeProgrammer + + +.. important:: It is absolutely necessary you will do that from inside the bin + directory where STM32CubeProgrammer binary resides. If you don't, then + programmer UI will crash on attempt to connect to the board. Probable + reason is a bug in the programmer which is not able to correctly locate + its C dynamic library responsible for connecting to the ST-Link board + interface. Version 2.9.0 of the programmer is described here. Other + versions may behave a bit differently. + +When you start the programmer application, the UI window of the programmer will +appear. +Click on green *Connect* button in the right upper corner of +the UI. This will connect programmer to the board. +Then click on *OB* +icon in the left upper corner. Actually this is hidden menu item which you +can un-hide by clicking on menu icon (three horizontal stripes) in the +upper left corner. +When you click on *OB* or *Option bytes* in un-hidden state, then +click on *User Configuration* in the options list and when the user +configuration list opens +unselect preselected *BCM4* item inside it to switch off M4 core or +unselect preselected *BCM7* item to switch off M7 core from +starting up. The action needs to be saved by clicking on *Apply* button +below the option table. + +.. warning:: Be careful! Wrong setup in STM32H7 configuration may result in + *bricked* board. + +Do not forget to disconnect the programmer application from the board by clicking on green *Disconnect* button +in the upper right corner and then close the programmer UI. + +.. important:: If you keep programmer connected then you will not be able + to connect ST-Link GDB server to the board and upload RTEMS binary to + it. + + +STM32CubeIDE ST-Link GDB Server setup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In order to use STM provided ST-Link GDB server externally, that is +not from inside the IDE, we need to configure it. Please go to the +directory where you have installed STM32CubeIDE software. Look for +file containing *ST-LINK* string inside its name. Following shell +command sequence shows example about how to find it. + +.. code-block:: shell + + $ cd $HOME/sfw/stm32cubeide_1.8.0 + $ find . -name 'ST-LINK*' + ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin/ST-LINK_gdbserver.sh + ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin/ST-LINK_gdbserver + ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin/ST-LINK_gdbserver.sh + ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin/ST-LINK_gdbserver + +Notice that in this particular installation case we already have two +versions of GDB server installed. This is due to fact that version +1.8.0 of the IDE was later upgraded to 1.9.0 version. Anyway, we will choose +to use the latest one, or if there is only one, then the only one +installed. Please go to its *bin* directory. E.g. + +.. code-block:: shell + + $ cd plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin + +Now, you will need to edit provided *config.txt* file inside the +directory. Use your favorite editor. Open the file and scroll +down to its end. You will see following comment: + +.. code-block:: none + + ############################################################### + # -cp <path> : Path to STM32CubeProgrammer + # Modify to correct path + # for STM32_Programmer_CLI executable + ############################################################### + -cp + +and here you will need to place path where your STM32CubeProgrammer is +installed directly behind the *-cp* parameter. E.g. + +.. code-block:: none + + ############################################################### + # -cp <path> : Path to STM32CubeProgrammer + # Modify to correct path + # for STM32_Programmer_CLI executable + ############################################################### + -cp /home/karel/sfw/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.linux64_2.0.200.202202231230/tools/bin + +Once you are done with it, you can save the file and close the +editor. Let's verify that GDB server is configured and running well by starting +it inside the shell. Please go inside the directory where +ST-LINK_gdbserver.sh is located and run it by: + +.. code-block:: shell + + $ ./ST-LINK_gdbserver.sh + +If everything is all right and if you have board still connected to +the host computer then you should see output like following: + +.. code-block:: shell + + $ ./ST-LINK_gdbserver.sh + + STMicroelectronics ST-LINK GDB server. Version 6.1.0 + Copyright (c) 2022, STMicroelectronics. All rights reserved. + + Starting server with the following options: + Persistent Mode : Enabled + LogFile Name : debug.log + Logging Level : 31 + Listen Port Number : 61234 + Status Refresh Delay : 15s + Verbose Mode : Disabled + SWD Debug : Enabled + + COM frequency = 24000 kHz + Target connection mode: Default + Reading ROM table for AP 0 @0xe00fefd0 + Hardware watchpoint supported by the target + ST-LINK Firmware version : V3J9M3 + Device ID: 0x450 + PC: 0x8028fa4 + ST-LINK device status: HALT_MODE + ST-LINK detects target voltage = 3.28 V + ST-LINK device status: HALT_MODE + ST-LINK device initialization OK + Stm32Device, pollAndNotify running... + SwvSrv state change: 0 -> 1 + Waiting for connection on port 61235... + Waiting for debugger connection... + Waiting for connection on port 61234... + +In output above you can see ST-Link GDB server waiting for debugger +connection. If this is the case in your case, then you can finish GDB server by hitting +*Ctrl-C* key combination. + +RTEMS BSP samples build and run +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We will use STM32H747I-DISCO board as an example hereafter. If you use +different board please adjust configuration steps in BSP configuration +accordingly. You should use BSP variant name specified for your +particular board in the table above. + +Generate default configuration for the board: + +.. code-block:: shell + + $ ./waf bspdefaults --rtems-bsps=arm/stm32h747i-disco > stm32h747i-disco.ini + Regenerate build specification cache (needs a couple of seconds)... + +To run basic hello world or ticker samples you do not need to modify +default BSP configuration here as the compilation of basic RTEMS demo samples is +enabled by default. Let's continue with configuration of +the RTEMS source by running following command. Please change the RTEMS +tools installation prefix to suite your installation. + +.. code-block:: shell + + $ ./waf configure --rtems-bsps=arm/stm32h747i-disco --rtems-config=./stm32h747i-disco.ini --rtems-tools=$HOME/workspace/rtems-tools + Setting top to : /home/rtems/workspace/rtems + Setting out to : /home/rtems/workspace/rtems/build + Configure board support package (BSP) : arm/stm32h747i-disco + Checking for program 'arm-rtems6-gcc' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-gcc + Checking for program 'arm-rtems6-g++' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-g++ + Checking for program 'arm-rtems6-ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for program 'arm-rtems6-ld' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ld + Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for program 'g++, c++' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-g++ + Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for program 'gas, gcc' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-gcc + Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for program 'gcc, cc' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-gcc + Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for asm flags '-MMD' : yes + Checking for c flags '-MMD' : yes + Checking for cxx flags '-MMD' : yes + 'configure' finished successfully (0.454s) + +Build the BSP including samples using *build* command: + +.. code-block:: shell + + $ ./waf build + +the command outputs a lot of information about files being compiled +and ends with output like: + +.. code-block:: shell + + Waf: Leaving directory `/home/rtems/workspace/rtems/build/arm/stm32h747i-disco' + 'build_arm/stm32h747i-disco' finished successfully (12.086s) + +As your RTEMS BSP including samples is compiled, we will proceed with +running the hello world sample on the board now. +Open 3 shell windows for the test on the host computer. Also make sure +board is connected to the computer and is running. It does not matter +if manufacturer's demo is running there or if you navigated to some +demo part and left it there. ST-Link GDB server always takes over the +board when connected to it. + +Start GDB server in the first window by switching to GDB server +directory and running the shell script. This is from testing machine +installation, the path to GDB server will probably look different in your +installation case. + +.. code-block:: shell + + $ cd sfw/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin + $ ./ST-LINK_gdbserver.sh + + STMicroelectronics ST-LINK GDB server. Version 6.1.0 + Copyright (c) 2022, STMicroelectronics. All rights reserved. + + Starting server with the following options: + Persistent Mode : Enabled + LogFile Name : debug.log + Logging Level : 31 + Listen Port Number : 61234 + Status Refresh Delay : 15s + Verbose Mode : Disabled + SWD Debug : Enabled + + COM frequency = 24000 kHz + Target connection mode: Default + Reading ROM table for AP 0 @0xe00fefd0 + Hardware watchpoint supported by the target + ST-LINK Firmware version : V3J9M3 + Device ID: 0x450 + PC: 0x8028fa4 + ST-LINK device status: HALT_MODE + ST-LINK detects target voltage = 3.28 V + ST-LINK device status: HALT_MODE + ST-LINK device initialization OK + Stm32Device, pollAndNotify running... + SwvSrv state change: 0 -> 1 + Waiting for connection on port 61235... + Waiting for debugger connection... + Waiting for connection on port 61234... + +In second shell window you will need to run your terminal program and +connect to the board virtual serial port. Following steps describes +how to do that on the Ubuntu 20.04. The recommended way here is to use minicom. Let's install it +first by: + +.. code-block:: shell + + $ sudo apt install minicom + +And run it with root privileges to be able to reach USB serial port +provided by board: + +.. code-block:: shell + + $ sudo minicom -s + +The minicom is invoked with configuration menu open. Go into the +*Serial port setup* and hit *a* key to select *Serial Device* +setup. Change */dev/modem* from there into */dev/ttyACM0* and hit +*Enter* key. Hit *f* key to change hardware flow control from *Yes* to +*No*. When you are done with it, you can hit *Enter* key to finish +this part of configuration and then scrolls in menu to *Exit* and hit +*Enter* key on it. The minicom will switch to terminal mode with just +provided configuration. + +In the third shell window navigate into the BSP build directory and start +RTEMS GDB with the hello.exe sample. + +.. code-block:: shell + + $ arm-rtems6-gdb build/arm/stm32h747i-disco/testsuites/samples/hello.exe + GNU gdb (GDB) 10.1.90.20210409-git + Copyright (C) 2021 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + Type "show copying" and "show warranty" for details. + This GDB was configured as "--host=x86_64-linux-gnu --target=arm-rtems6". + Type "show configuration" for configuration details. + For bug reporting instructions, please see: + <https://www.gnu.org/software/gdb/bugs/>. + Find the GDB manual and other documentation resources online at: + <http://www.gnu.org/software/gdb/documentation/>. + + For help, type "help". + Type "apropos word" to search for commands related to "word"... + Reading symbols from build/arm/stm32h747i-disco/testsuites/samples/hello.exe... + (gdb) + +Now, you need to connect GDB with the ST's GDB server by: + +.. code-block:: shell + + (gdb) target extended-remote :61234 + Remote debugging using :61234 + 0x08028fa4 in ?? () + (gdb) + +and finally you will need to load hello.exe binary into the board +memory by: + +.. code-block:: shell + + (gdb) load + Loading section .start, size 0x458 lma 0x24000000 + Loading section .text, size 0xfca8 lma 0x24000480 + Loading section .init, size 0xc lma 0x24010128 + Loading section .fini, size 0xfecc lma 0x24010134 + Loading section .rodata, size 0x1aab lma 0x24020000 + Loading section .ARM.exidx, size 0x8 lma 0x24021aac + Loading section .eh_frame, size 0x4 lma 0x24021ab4 + Loading section .init_array, size 0x4 lma 0x24021ab8 + Loading section .fini_array, size 0x4 lma 0x24021abc + Loading section .rtemsroset, size 0x540 lma 0x24021ac0 + Loading section .data, size 0x6a4 lma 0x24022000 + Start address 0x24000400, load size 140923 + Transfer rate: 684 KB/sec, 2562 bytes/write. + (gdb) + +If everything went fine, then you can run the RTEMS binary by using +*cont* GDB command. + +.. note:: Memory address values in the load output in the gdb shows + that we have loaded our application into the AXI + SRAM. Memory addresses will be different when loading into + different part of MCU memory. + +.. code-block:: shell + + (gdb) cont + Continuing. + +Note that this command should never finish. To see the actual output +from RTEMS switch to +the second shell window with minicom (or other terminal emulation +program) running and you should see hello output +there: + +.. code-block:: none + + *** BEGIN OF TEST HELLO WORLD *** + *** TEST VERSION: 6.0.0.50ce036cfbd9807a54af47eb60eadb6a33a9e82d + *** TEST STATE: EXPECTED_PASS + *** TEST BUILD: + *** TEST TOOLS: 10.3.1 20220224 (RTEMS 6, RSB 49e3dac17765fa82ce2f754da839638ee352f95c, Newlib 64b2081) + Hello World + + *** END OF TEST HELLO WORLD *** + + + [ RTEMS shutdown ] + RTEMS version: 6.0.0.50ce036cfbd9807a54af47eb60eadb6a33a9e82d + RTEMS tools: 10.3.1 20220224 (RTEMS 6, RSB 49e3dac17765fa82ce2f754da839638ee352f95c, Newlib 64b2081) + executing thread ID: 0x08a010001 + +Since default RTEMS BSP configuration resets the board after run +immediately you can also see output from the immediately started ST +demo: + +.. code-block:: none + + STM32H747I-DISCO_MB1248: Out Of the Box Demonstration V1.0.1 (Build Aug 22 2019 at 11:56:22) + STM32H747I-DISCO_MB1248: ST Menu Launcher V1.1.0 + CPU running at 400MHz, Peripherals at 100MHz/100Mz + +which is not a problem here at all. Later we can reconfigure BSP to +not reset board to prevent demo output here. + +How to load binary file into the QSPI NOR +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Connect the board to your host computer using micro-USB +cable. Start STM32CubeProgrammer and connect it to the board by +clicking on *Connect* button which is located in the right upper +corner of the programmer application UI. For accessing QSPI connected +memory you will need to configure programmer's external loader which +needs to match your target board. Click on *EL* icon (or *External +loaders*) in the left sidebar menu. Either go thorough the list of +external loaders or just search for your board by typing board +name (or part of the name) into the search bar located on top of the table view. When +you find your board, select it by selecting rectangle in the *Select* +table column. That's what is needed to make programmer ready to +program your board memory. +For uploading file to the board, you need to continue with clicking on +*Erase & programming* menu item in the left sidebar menu. It's second item +from the top. Now, let's select +your file to upload by clicking on *Browse* button and selecting the +file name from your host computer filesystem. The most important thing here is +to specify start address of flashing process. You need to do that by +typing start address into the *Start address* field. + +.. note:: Usually external memory connected to QSPI has 0x90000000 starting + address. + +When all is set you can click on *Start Programming* button. + +.. important:: Cube programmer is very picky about files it shows in the file list. The only recognized suffixes are: elf, bin, hex and + similar. Also do not try to fool programmer by renaming let's say text + file to bin file. It'll detect file type as ascii text and will not + show it in the list of files to flash. So bin file type is really for + media types like avi, jpeg, mpeg or for binary dumps from elf + files. If you need to save text file, convert it to hex file first. diff --git a/user/bsps/arm/xen.rst b/user/bsps/arm/xen.rst index c7085ce..d7538f0 100644 --- a/user/bsps/arm/xen.rst +++ b/user/bsps/arm/xen.rst @@ -42,13 +42,13 @@ The ``ticker.exe`` file can be found in the BSP build tree at: .. code-block:: none - arm-rtems5/c/xen_virtual/testsuites/samples/ticker.exe + arm-rtems@rtems-ver-major@/c/xen_virtual/testsuites/samples/ticker.exe The ``ticker.exe`` elf file must be translated to a binary format. .. code-block:: none - arm-rtems5-objcopy -O binary ticker.exe ticker.bin + arm-rtems@rtems-ver-major@-objcopy -O binary ticker.exe ticker.bin Then place the ``ticker.bin`` file on the dom0 filesystem. diff --git a/user/bsps/arm/xilinx-zynq.rst b/user/bsps/arm/xilinx-zynq.rst index 909b23e..0ac4487 100644 --- a/user/bsps/arm/xilinx-zynq.rst +++ b/user/bsps/arm/xilinx-zynq.rst @@ -1,8 +1,146 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 TBD +.. Copyright (C) 2015, 2020 Chris Johns (chrisj@rtems.org) xilinx-zynq =========== -TODO. +This BSP supports the Xilinx Zynq range of devices. This family of +devices contain the same ARM hard IP and the different parts have +different sizes of programable logic. + +The BSP defaults may need to be adjusted using ``configure`` BSP +options to match the size of memory your board may have. + +Bootloader +---------- + +The bootloader initialises the Zynq device. The Xilinx tool provide an +interface to configure the hardware. This is includes the buses, +clocks, memory and UART board rate. The output of this is called +``ps7_init`` and it a C file. The Xilinx SDK builds a first stage boot +loader (FSBL) using this file. + +The U-Boot boot loader has it's own FSBL called ``MLO`` to initialise +the hardware. + +Clocks +------ + +An application can provide a function called: + +.. code-block:: none + + uint32_t a9mpcore_clock_periphclk(void); + +to return the peripheral clock. Normally this is half the CPU +clock. This function is declared ``weak`` so you can override the +default behaviour by providing it in your application. + +Console +------- + +The console driver for the UARTs will always be initialized to a +baud rate of 115200 with 8 bit characters, 1 stop bit and no parity +bits during start up. +Previous configurations programmed into the hardware by the Xilinx +tools or a bootloader will be overwritten. + +The settings for the console driver can be changed by the user +application through the termios API afterwards. + +Network +------- + +The Cadence network interface driver of LibBSD works on the Xilinx Zynq +platform. The hardware checksum support works on real hardware but does not +seem to be supported on Qemu therefore the default state is to disable +``IFCAP_TXCSUM`` and ``IFCAP_RXCSUM`` and this can be enabled from the shell +with: + +.. code-block:: none + + ifconfig cgem0 rxcsum txcsum + +or with an ``ioctl()`` call to the network interface driver with ``SIOCSIFCAP`` +and the mask ``IFCAP_TXCSUM`` and ``IFCAP_RXCSUM`` set. + +Debugging with xilinx_zynq_a9_qemu +---------------------------------- + +To debug an application add the QEMU options ``-s``. If you need to +debug an initialisation issue also add ``-S``. For example to debug a +networking application you could use: + +.. code-block:: none + + qemu-system-arm -M xilinx-zynq-a9 -m 256M -no-reboot -serial \ + null -serial mon:stdio -nographic \ + -net nic,model=cadence_gem -net vde,id=vde0,sock=/tmp/vde1 \ + -kernel myapp.exe \ + -s -S + +Start GDB with the same executable QEMU is running and connect to the +QEMU GDB server: + +.. code-block:: none + + (gdb) target remote :1234 + +If your application is crashing set a breakpoint on the fatal error +handler: + +.. code-block:: none + + (gdb) b bsp_fatal_extension + +Enter continue to run the application. Running QEMU loads the +executable and initialises the CPU. If the ``-S`` option is provided +the CPU is held in reset. Without the option the CPU runs starting +RTEMS. Either way you are connecting to set up target and all you need +to do is continue: + +.. code-block:: none + + (gdb) c + +If you have a crash and the breakpoint on ``bsp_fatal_extension`` is +hit, load the following a GDB script: + +.. code-block:: none + + define arm-crash + set $code = $arg0 + set $r0 = ((const rtems_exception_frame *) $code)->register_r0 + set $r1 = ((const rtems_exception_frame *) $code)->register_r1 + set $r2 = ((const rtems_exception_frame *) $code)->register_r2 + set $r3 = ((const rtems_exception_frame *) $code)->register_r3 + set $r4 = ((const rtems_exception_frame *) $code)->register_r4 + set $r5 = ((const rtems_exception_frame *) $code)->register_r5 + set $r6 = ((const rtems_exception_frame *) $code)->register_r6 + set $r7 = ((const rtems_exception_frame *) $code)->register_r7 + set $r8 = ((const rtems_exception_frame *) $code)->register_r8 + set $r9 = ((const rtems_exception_frame *) $code)->register_r9 + set $r10 = ((const rtems_exception_frame *) $code)->register_r10 + set $r11 = ((const rtems_exception_frame *) $code)->register_r11 + set $r12 = ((const rtems_exception_frame *) $code)->register_r12 + set $sp = ((const rtems_exception_frame *) $code)->register_sp + set $lr = ((const rtems_exception_frame *) $code)->register_lr + set $pc = ((const rtems_exception_frame *) $code)->register_pc + set $cpsr = ((const rtems_exception_frame *) $code)->register_cpsr + end + +Enter the command: + +.. code-block:: none + + (gdb) arm-crash code + + +Enter ``bt`` to see the stack back trace. + +The script moves the context back to the crash location. You should be +able to view variables and inspect the stack. + +The fatal error handler runs inside an exception context that is not +the one than generated the exception. diff --git a/user/bsps/arm/xilinx-zynqmp-rpu.rst b/user/bsps/arm/xilinx-zynqmp-rpu.rst new file mode 100644 index 0000000..0dfb77e --- /dev/null +++ b/user/bsps/arm/xilinx-zynqmp-rpu.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2024 On-Line Applications Research Corporation (OAR) + +.. _BSP_arm_xilinx_zynqmp_rpu: + +Xilinx ZynqMP RPU +================= + +This BSP supports the Cortex-R5 processor on the Xilinx Zynq UltraScale+ MPSoC +platform. Basic hardware initialization is performed by the Cortex-R5 FSBL and +the BSP. This BSP supports the GICv2 interrupt controller available to the +Cortex-R5 subsystem. Since the Cortex-R5 subsystem only varies in speed, this +BSP should be functional across all chip variants as well as on Xilinx's QEMU +branch. SMP operation is not currently supported. + +Clock Driver +------------ + +The clock driver uses one of the available triple timer counters (TTCs) as the +timer interrupt source. + +Console Driver +-------------- + +The console driver supports the default Qemu emulated ARM PL011 PrimeCell UART +as well as the physical ARM PL011 PrimeCell UART in the ZynqMP hardware. + +Boot on ZynqMP Hardware +----------------------- + +On the ZynqMP RPU, RTEMS can be started by Cortes-R5 u-boot, Cortex-A53 u-boot, +via JTAG, or directly as part of BOOT.bin. For quick turnaround during testing, +it is recommended to use Cortex-A53 u-boot to avoid repeated BOOT.bin +generation since the provided Cortex-R5 u-boot is highly limited and has no +network or MMC/SD access. + +Note that if the RPU image is started by the Cortex-A53 u-boot, the program +sections located at ZYNQMP_RPU_RAM_INT_0_ORIGIN and ZYNQMP_RPU_RAM_INT_1_ORIGIN +must be manually relocated from DDR to TCM since the TCMs are not directly +available to the Cortex-A53 cores at their Cortex-R5 internal addresses. This +can be accomplished by disabling dcache in u-boot and using u-boot's "cp" +command. Once this is done, the program can be started at 0x0 by using u-boot's +"cpu" command to first disable core 4 and then release it in split mode. + +Hardware Boot Image Generation +------------------------------ + +When generating BOOT.bin from components, the BIF file should include at least +entries for the Cortex-R5 FSBL ([bootloader,destination_cpu=r5-0]) and the +Cortex-R5 application ([destination_cpu=r5-0]). The Cortex-R5 application should +be either a u-boot or RTEMS ELF binary. The Cortex-R5 u-boot binary can be +obtained by building it from Xilinx's u-boot repository. The Cortex-R5 FSBL can +be obtained setting up an appropriate platform project in Xilinx's current +development system. + +Boot on QEMU +------------ +The executable image is booted by Qemu in ELF format. + +Running Executables on QEMU +--------------------------- + +Xilinx's qemu-devicetrees repository must be used in conjunction with the Xilinx +QEMU available via RSB. Executables generated by this BSP can be run using the +following command: + +.. code-block:: shell + + qemu-system-aarch64 -no-reboot -nographic -M arm-generic-fdt -serial null \ + -serial mon:stdio -device loader,file=example.exe,cpu-num=4 \ + -device loader,addr=0xff5e023c,data=0x80088fde,data-len=4 \ + -device loader,addr=0xff9a0000,data=0x80000218,data-len=4 \ + -hw-dtb /xlnx-qemu-devtrees-path/LATEST/SINGLE_ARCH/board-zynqmp-zcu102.dtb \ + -m 4096 -display none + +Debugging Executables on QEMU +----------------------------- + +Debugging the RPU cores under QEMU presents unique challenges due to requiring +the AArch64 QEMU to emulate the entire processing subsystem. Debugging requires +a multi-arch GDB which can be created by adding "--enable-targets=all" to the +normal GDB configure line and then building as normal. + +To attach to the RPU core once QEMU is started with "-s -S", The following steps +are required: + +.. code-block:: shell + + aarch64-rtems6-gdb + (gdb) tar ext :1234 + (gdb) add-inferior + (gdb) inferior 2 + (gdb) file example.exe + (gdb) attach 2 diff --git a/user/bsps/arm/xilinx-zynqmp.rst b/user/bsps/arm/xilinx-zynqmp.rst index 9a605bb..fa60470 100644 --- a/user/bsps/arm/xilinx-zynqmp.rst +++ b/user/bsps/arm/xilinx-zynqmp.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG xilinx-zynqmp ============= |