8.2. arm (ARM)

8.2.1. altera-cyclone-v (Intel Cyclone V)

This BSP offers only one variant, the altcycv_devkit. This variant supports the Intel Cyclone V system on chip. 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.

The BSP is known to run on these boards:

8.2.1.1. Boot via U-Boot

The application executable file (ELF file) must be converted to an U-Boot image. Use the following commands:

arm-rtems5-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

Use the following U-Boot commands to boot an application via TFTP download:

tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset

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}.

8.2.1.2. Clock Driver

The clock driver uses the Cortex-A9 MPCore Global Timer.

8.2.1.3. Console Driver

The console driver supports up to two on-chip NS16550 UARTs. The console driver does not configure the pins.

8.2.1.4. I2C Driver

There is a legacy I2C driver. It should be converted to the I2C driver framework.

8.2.1.5. Network Interface Driver

The network interface driver is provided by the libbsd. It is initialized according to the device tree. It supports checksum offload.

8.2.1.6. MMC/SDCard Driver

The MMC/SDCard driver is provided by the libbsd. It is initialized according to the device tree. Pin re-configuration according to the serial clock frequency is not supported. DMA transfers are supported.

8.2.1.7. USB Host Driver

The USB host driver is provided by the libbsd. It is initialized according to the device tree. The driver works in polled mode.

8.2.1.8. Caveats

The clock and pin configuration support is quite rudimentary and mostly relies on the boot loader.

8.2.2. atsam

TODO.

8.2.3. beagle

This BSP supports four variants, beagleboardorig, beagleboardxm, beaglebonewhite and beagleboneblack. 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.

TODO(These drivers are present but not documented yet):

  • Clock driver.

  • Network Interface Driver.

  • SDcard driver.

  • GPIO Driver.

  • Console driver.

  • PWM Driver.

  • RTC driver.

8.2.3.1. Boot via U-Boot

To boot via uboot, the ELF must be converted to a U-Boot image like below:

arm-rtems5-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

8.2.3.2. Getting the Device Tree Blob

The Device Tree Blob (DTB) is needed to load the device tree while starting up the kernel. We build the dtb from the FreeBSD source matching the commit hash from the libbsd HEAD of freebsd-org. For example if the HEAD is at “19a6ceb89dbacf74697d493e48c388767126d418” Then the right Device Tree Source (DTS) file is: https://github.com/freebsd/freebsd/blob/19a6ceb89dbacf74697d493e48c388767126d418/sys/gnu/dts/arm/am335x-boneblack.dts

Please refer to the Device Tree to know more about building and applying the Device Trees.

8.2.3.3. Writing the uEnv.txt file

The uEnv.txt file is needed to set any environment variable before the kernel is loaded. Each line is a u-boot command that the uboot will execute during start up.

Add the following to a file named uEnv.txt:

setenv bootdelay 5
uenvcmd=run boot
boot=fatload mmc 0 0x80800000 rtems-app.img ; fatload mmc 0 0x88000000 am335x-boneblack.dtb ; bootm 0x80800000 - 0x88000000

8.2.3.4. I2C Driver

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-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.

For example,

/ {
   compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx";

   fragment@0 {
      target = <0xffffffff>;

      __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.

8.2.3.5. SPI Driver

The SPI device /dev/spi-0 can be registered with bbb_register_spi_0()

For registering with a custom path, the bsp_register_spi() can be used.

The function prototype is given below:

rtems_status_code bsp_register_spi(
   const char         *bus_path,
   uintptr_t           register_base,
   rtems_vector_number irq
);

8.2.3.6. 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:

 1 ===  /--=== 2
 3 ===  |  === 4
 5 ===--/  === 6
 7 ===--\  === 8
 9 ===  |  === 10
11 ===  |  === 12
13 ===--/  === 14
15 ===     === 16
17 ===     === 18
19 ===     === 20
BeagleBone Black JTAG Hardware Modification

Fig. 8.1 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.

8.2.3.7. 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:

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).

8.2.4. stm32h7

This BSP supports the STM32H7 Series. The BSP is known to run on these boards:

8.2.4.1. Clock Driver

The clock driver uses the ARMv7-M Systick module.

8.2.4.2. Console Driver

The console driver supports the on-chip UART and USART modules.

8.2.4.3. Network Interface Driver

The network interface driver if_stmac is provided by the libbsd.

8.2.4.4. USB Host Driver

The USB host driver dwc_otg is provided by the libbsd.

8.2.5. csb336

TODO.

8.2.6. csb337

TODO.

8.2.7. edb7312

TODO.

8.2.8. gumstix

TODO.

8.2.9. imx (NXP i.MX)

This BSP offers only one variant, the imx7. This variant supports the i.MX 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.

8.2.9.1. Build Configuration Options

The following options are available at the configure command line.

BSP_PRESS_KEY_FOR_RESET

If defined to a non-zero value, then print a message and wait until pressed before resetting board when application terminates.

BSP_RESET_BOARD_AT_EXIT

If defined to a non-zero value, then reset the board when the application terminates.

BSP_PRINT_EXCEPTION_CONTEXT

If defined to a non-zero value, then print the exception context when an unexpected exception occurs.

BSP_FDT_BLOB_SIZE_MAX

The maximum size of the device tree blob in bytes (default is 262144).

CONSOLE_USE_INTERRUPTS

Use interrupt driven mode for console devices (enabled by default).

IMX_CCM_IPG_HZ

The IPG clock frequency in Hz (default is 67500000).

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).

8.2.9.2. 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

8.2.9.3. Boot via U-Boot

The application executable file (ELF file) must be converted to an U-Boot image. Use the following commands:

arm-rtems5-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

Use the following U-Boot commands to boot an application via TFTP download:

tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset

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}.

8.2.9.4. 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).

8.2.9.5. Clock Driver

The clock driver uses the ARMv7-AR Generic Timer.

8.2.9.6. Console Driver

The console driver supports up to seven on-chip UARTs. They are initialized according to the device tree. The console driver does not configure the pins.

8.2.9.7. I2C Driver

I2C drivers are registered by the i2c_bus_register_imx() function. The I2C driver does not configure the pins.

#include <assert.h>
#include <bsp.h>

void i2c_init(void)
{
  int rv;

  rv = i2c_bus_register_imx("/dev/i2c-0", "i2c0");
  assert(rv == 0);
}

8.2.9.8. SPI Driver

SPI drivers are registered by the spi_bus_register_imx() function. The SPI driver configures the pins according to the pinctrl-0 device tree property. SPI transfers with a continuous chip select are limited by the FIFO size of 64 bytes. The driver has no DMA support.

#include <assert.h>
#include <bsp.h>

void spi_init(void)
{
  int rv;

  rv =  spi_bus_register_imx("/dev/spi-0", "spi0");
  assert(rv == 0);
}

8.2.9.9. Network Interface Driver

The network interface driver is provided by the libbsd. It is initialized according to the device tree. It supports checksum offload and interrupt coalescing. IPv6 transmit checksum offload is not implemented. The interrupt coalescing uses the MII/GMII clocks and can be controlled by the following system controls:

  • dev.ffec.<unit>.int_coal.rx_time

  • dev.ffec.<unit>.int_coal.rx_count

  • dev.ffec.<unit>.int_coal.tx_time

  • dev.ffec.<unit>.int_coal.tx_count

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:

#define RTEMS_BSD_CONFIG_BSP_CONFIG
#define RTEMS_BSD_CONFIG_INIT
SYSINIT_DRIVER_REFERENCE(ksz8091rnb, miibus);
#include <machine/rtems-bsd-config.h>

8.2.9.10. MMC/SDCard Driver

The MMC/SDCard driver (uSDHC module) is provided by the libbsd. It is initialized according to the device tree. Pin re-configuration according to the serial clock frequency is not supported. Data transfers are extremely slow. This is probably due to the missing DMA support.

8.2.9.11. Caveats

The clock and pin configuration support is quite rudimentary and mostly relies on the boot loader. For a pin group configuration see imx_iomux_configure_pins(). There is no power management support.

8.2.10. imxrt (NXP i.MXRT)

This BSP offers only one variant, the imxrt1052. This variant supports the i.MXRT 1052 processor on a IMXRT1050-EVKB (tested with rev A1). You can also configure it to work with custom boards.

8.2.10.1. 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 bsp_defaults --rtems-bsps=arm/imxrt1052 > config.ini

8.2.10.2. Boot Process

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-rtems6-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.

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.

8.2.10.3. 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):

#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 for details about the contents.

8.2.10.4. FDT

The BSP uses a FDT based initialization. The FDT is linked into the application. You can find the default FDT used in the BSP in bsps/arm/imxrt/dts/imxrt1050-evkb.dts. The FDT is split up into two parts. The core part is put into an dtsi file and is installed together with normal headers into ${PREFIX}/arm-rtems6/imxrt1052/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):

sh> arm-rtems6-cpp -P -x assembler-with-cpp \
                   -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"

Make sure that your new c file is compiled and linked into the application.

8.2.10.5. Clock Driver

The clock driver uses the generic ARMv7-M Clock.

8.2.10.6. 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.

8.2.10.7. 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.

8.2.10.8. 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.

8.2.10.9. 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.

Limitations:

  • Only a basic SPI driver is implemented. This is mostly a driver limitation and not a hardware one.

8.2.10.10. 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

8.2.10.11. 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.

8.2.10.12. Caveats

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.

The MPU settings are currently quite permissive.

There is no power management support.

8.2.11. lm3s69xx

TODO.

8.2.12. lpc176x

TODO.

8.2.13. lpc24xx (NXP LPC17XX/LPC24XX/LPC40XX)

This BSP offers only several variants. The following variants support the Embedded Artits LPC4088 Developer’s Kit and earlier board generations:

  • lpc17xx_ea_ram

  • lpc17xx_ea_rom_int

  • lpc24xx_ea

  • lpc40xx_ea_ram

  • lpc40xx_ea_rom_int

They can be used as a base line for customization. The basic hardware initialization is performed by the BSP. It can be customized via configuration options and configuration tables. See also <bsp/start-config.h>.

8.2.13.1. Clock Driver

The clock driver of the Cortex-M variants uses the ARMv7-M Systick. The older ARM7TDMI variants use the TMR0 timer module.

8.2.13.2. Console Driver

The console driver supports up to four on-chip UARTs. Initialization can be customized via the lpc24xx_uart_probe_1(), lpc24xx_uart_probe_2() and lpc24xx_uart_probe_3() functions.

8.2.13.3. I2C Bus Driver

I2C bus drivers are registered by the lpc24xx_register_i2c_0(), lpc24xx_register_i2c_1() and lpc24xx_register_i2c_2() functions. The I2C driver does not configure the pins. See also <bsp/i2c.h>.

8.2.13.4. SPI Bus Driver

SPI bus drivers are registered by the lpc24xx_register_ssp_0(), lpc24xx_register_ssp_1() and lpc24xx_register_ssp_2() functions. The SSP driver does not configure the pins. See also <bsp/ssp.h>.

8.2.13.5. Network Interface Driver

Only a legacy network driver is support. For a libbsd base driver the platform support is missing, see if_lpe.c.

8.2.13.6. USB Driver

The USB host driver (OHCI) is provided by the libbsd.

8.2.13.7. Framebuffer Driver

For a custom framebuffer driver see <bsp/lcd.h>.

8.2.13.8. RTC Driver

There is a standard RTC driver available using the on-chip RTC module.

8.2.14. raspberrypi

This BSP supports Raspberry Pi 1 and Raspberry Pi 2 currently. The support for Raspberry Pi 3 is work under progress. 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.

8.2.14.1. Setup SD card

The Raspberry Pis have an unconventional booting mechanism. The GPU boots first, initializes itself, runs the bootloader and starts the CPU. 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. You can remove the kernel*.img files if you want too, but don’t touch the other files.

Copy these files in to a SD card with FAT filesystem.

8.2.14.2. Kernel image

The following steps show how to run hello.exe on a Raspberry Pi 2. The same instructions can be applied to Raspberry Pi 1 also. Other executables can be processed in a similar way.

To create the kernel image:

$ arm-rtems5-objcopy -Obinary hello.exe kernel.img

Copy the kernel image to the SD card.

Make sure you have these lines below, in your config.txt.

enable_uart=1
kernel_address=0x200000
kernel=kernel.img

8.2.14.3. Testing using QEMU

QEMU can be built using RSB. Navigate to <SOURCE_BUILDER_DIR>/rtems and run this command.

$ ../source-builder/sb-set-builder --prefix=<TOOLCHAIN_DIR> devel/qemu4.bset

Note: Replace <SOURCE_BUILDER_DIR> and <TOOLCHAIN_DIR> with the correct path of the directories. For example, if you used quick-start section as your reference, these two will be $HOME/quick-start/src/rsb and $HOME/quick-start/rtems/5 respectively,

QEMU along with GDB can be used for debugging, but it only supports Raspberry Pi 2 and the emulation is also incomplete. So some of the features might not work as expected.

Make sure your version of QEMU is newer than v2.6, because older ones don’t support Raspberry Pis.

$ qemu-system-arm -M raspi2 -m 1G -kernel hello.exe -serial mon:stdio -nographic -S -s

This starts QEMU and creates a socket at port localhost:1234 for GDB to connect.

The Device Tree Blob (DTB) is needed to load the device tree while starting up the kernel. The BSP uses information from this file to initialize the drivers.

Make sure you pass in the correct DTB file. There are currently two version of DTB for the Raspberry Pi 2 bcm2709-rpi-2-b.dtb and bcm2710-rpi-2-b.dtb. The bcm2709-rpi-2-b.dtb is for Raspberry Pi 2 Model B and bcm2710-rpi-2-b.dtb is for Raspberry Pi 2 Model B v1.2

We need to pass in the DTB file to GDB before running the example.

In a new terminal, run GDB using

$ arm-rtems5-gdb hello.exe

This will open GDB and will load the symbol table from hello.exe. Issue the following commands in the GDB prompt.

(gdb) tar remote:1234
(gdb) load
(gdb) restore bcm2709-rpi-2-b.dtb binary 0x2ef00000
(gdb) set $r2 = 0x2ef00000

This will connect GDB to QEMU and will load the DTB file and the application.

(gdb) continue

The continue command will run the executable.

Note: Add set scheduler-locking on in GDB if you have any issues running the examples.

8.2.15. realview-pbx-a9

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 app.exe on this Qemu machine is:

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.

8.2.16. rtl22xx

TODO.

8.2.17. smdk2410

TODO.

8.2.18. stm32f4

TODO.

8.2.19. stm32h7

This BSP supports the STM32H7 Series.

The BSP is known to run on these boards:

8.2.19.1. 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.

8.2.19.2. Console Driver

The console driver supports the on-chip UART and USART modules. 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.

8.2.19.3. Network Interface Driver

The network interface driver if_stmac is provided by the libbsd.

8.2.19.4. USB Host Driver

The USB host driver dwc_otg is provided by the libbsd.

8.2.19.5. 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 is not supported. SDMMC2 should not have that limitation. See ST AN5200 “Getting started with STM32H7 Series SDMMC host controller” for more details.

8.2.20. tms570

TODO.

8.2.21. xen (Xen on ARM)

This BSP enables RTEMS to run as a guest virtual machine in AArch32 mode on the Xen hypervisor for ARMv8 platforms.

Drivers:

  • Clock: ARMv7-AR Generic Timer

  • Console: Virtual PL011 device

  • Interrupt: GICv2

BSP variants:

  • xen_virtual: completely virtualized guest with no dependence on underlying hardware

The xen_virtual BSP variant relies on standard Xen features, so it should be able to run on any ARMv8 platform.

Xen allows for the passthrough of hardware peripherals to guest virtual machines. BSPs could be added in the future targeting specific hardware platforms and include the appropriate drivers.

This BSP was tested with Xen running on the Xilinx Zynq UltraScale+ MPSoC using the Virtuosity distribution maintained by DornerWorks.

8.2.21.1. Execution

This procedure describes how to run the ticker sample application that should already be built with the BSP.

The ticker.exe file can be found in the BSP build tree at:

arm-rtems5/c/xen_virtual/testsuites/samples/ticker.exe

The ticker.exe elf file must be translated to a binary format.

arm-rtems5-objcopy -O binary ticker.exe ticker.bin

Then place the ticker.bin file on the dom0 filesystem.

From the dom0 console, create a configuration file ticker.cfg with the following contents.

name = "ticker"1G
kernel = "ticker.bin"
memory = 8
vcpus = 1
gic_version = "v2"
vuart = "sbsa_uart"

Create the virtual machine and attach to the virtual vpl011 console.

xl create ticker.cfg && xl console -t vuart ticker

To return back to the dom0 console, press both Ctrl and ] on your keyboard.

8.2.21.2. Additional Information

8.2.22. xilinx-zynq

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.

8.2.22.1. 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.

8.2.22.2. Clocks

An application can provide a function called:

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.

8.2.22.3. 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.

8.2.22.4. 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:

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:

(gdb) target remote :1234

If your application is crashing set a breakpoint on the fatal error handler:

(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:

(gdb) c

If you have a crash and the breakpoint on bsp_fatal_extension is hit, load the following a GDB script:

 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:

(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.

8.2.23. xilinx-zynqmp

This BSP supports the Xilinx Zynq UltraScale+ MPSoC platform.