7.2. arm (ARM)

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

• Cyclone V SoC Development Kit

• Enclustra Mars MA3 SoC Module

• Terasic DE10-Standard Development Kit

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

7.2.1.2. Clock Driver

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

7.2.1.3. Console Driver

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

7.2.1.4. I2C Driver

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

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

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

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

7.2.1.8. Caveats

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

7.2.2. atsam

TODO.

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

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

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

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

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

For registering an I2C device with a custom path (say /dev/i2c-3) the function am335x_i2c_bus_register() has to be used.

The function prototype is given below:

int am335x_i2c_bus_register(
const char         *bus_path,
uintptr_t           register_base,
uint32_t            input_clock,
rtems_vector_number irq
);

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

7.2.4. csb336

TODO.

7.2.5. edb7312

TODO.

7.2.6. gumstix

TODO.

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

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

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

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

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

7.2.7.5. Clock Driver

The clock driver uses the ARMv7-AR Generic Timer.

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

7.2.7.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);
}

7.2.7.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);
}

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

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

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

7.2.8. lm3s69xx

TODO.

7.2.9. lpc176x

TODO.

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

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

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

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

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

7.2.10.5. Clock Driver

The clock driver uses the ARMv7-AR Generic Timer.

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

7.2.10.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);
}

7.2.10.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);
}

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

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

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

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

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

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

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

7.2.12. realview-pbx-a9

TODO.

7.2.13. rtl22xx

TODO.

7.2.14. smdk2410

TODO.

7.2.15. tms570

TODO.

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

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

7.2.16.2. Additional Information

• Virtuosity distribution

7.2.17. xilinx-zynq

TODO.

7.2.18. xilinx-zynqmp

This BSP supports the Xilinx Zynq UltraScale+ MPSoC platform.