Overview

In a typical development environment, the board boots from the SD/eMMC and runs the RedBoot ROM monitor from SDRAM. eCos applications are configured for RAM startup and then downloaded and run on the board via the debugger arm-eabi-gdb. Preparing the board therefore usually involves programming a suitable RedBoot image into an SD card.

Initial Installation

A Raspberry Pi boots initially to the GPU which then reads and executes a second-level GPU bootstrap image from the SD card. This then reads an ARM executable image from the card into SDRAM and executes it. For eCos development we want RedBoot to be the ARM image loaded from the SD card.

The SD card used to boot RedBoot is prepared in exactly the same way as a card is prepared to boot Raspian or any other operating system for the RPi. A complete disk image must be written to the card, typically from a host system running either Windows or Linux. You will need a 2GB, or larger, SD card for this purpose.

A prebuilt bootable SD card image is supplied as part of the eCosPro release. This image is universal and will boot RedBoot on all Raspberry Pi variants. The eCosPro_RedBoot_RPi_2Mb.img image is located within your eCosPro installation in the eCosPro/ecos-VERSION/loaders/rpi directory. This RedBoot uses 2Mb/s as its default serial speed.

A few non-FTDI based USB to serial converters have been found to be incapable of reliably handling the high-speed 2Mb/s default baud rate used by the standard RedBoot image. For these systems an alternative eCosPro_RedBoot_RPi_115k.img image has been provided in the same location. This defaults to a baud rate of 115200, but is otherwise identical. This may also be useful if you encounter any communications issues with slow host machines, or with specific operations such as x/ymodem transfers. Alternatively you could dynamically change the communications speed used by RedBoot with its baudrate command.

RedBoot Startup

Once the RedBoot image has been flashed, insert the SD card into your RPi board's SD socket. If the board has an Ethernet socket insert an Ethernet cable. Connect an RS232 TTL transceiver to the Raspberry Pi's UART pins. On the host run a terminal emulator and connect to the transceiver's serial port, setting it to 2Mb/s (2000000 baud), 8 data bits, no parity, one stop bit (8N1).

Note

Suitable low cost USB RS232 TTL transceivers include the FTDI Raspberry Pi Cable: TTL-232R-RPI or FTDI LC234X module. The FTDI cable can be connected directly to the Raspberry Pi, whereas connecting the module will reqire set of additional jumper cables. These FTDI products are fully supported by drivers on both Windows and Linux hosts. Whatever transceiver is used, it will need connecting to the Raspberry Pi's GND, GPIO14 TXD (transceiver RXD) and GPIO15 RXD (transceiver TXD) pins on the GPIO header. For the 40 way expansion header on standard RPi's these are pins 6, 8 and 10 respectively. We do NOT recommend connecting any other signals that the transceiver might provide, in particular 3V3 or 5V lines.

	Note
	There are a wide range of freely available terminal emulation programs to choose from - we can recommend Minicom on Linux and PuTTY on Windows.

When the above connections have been made, apply power to the board and similar output to the following should be seen on the terminal:

+USB LOG: HCD register DWC ports 1
USB LOG: hub 01 attach on port 1
USB LOG: hub attach 03
USB LOG: hub 03 attach on port 1
USB LOG: hub attach 04
USB LOG: hub 04 attach on port 1
USB LOG: device attach 05 [ff:00] [0424:7800]
... waiting for BOOTP information
Ethernet eth0: MAC address b8:27:eb:30:d0:7b
IP: 10.0.2.2/255.0.0.0, Gateway: 10.0.0.3
Default server: 0.0.0.0
DNS server IP: 10.0.0.5, DNS domain name: <null>

Mount /dev/mmcsd0/1 on /boot type fatfs:sync=write

RedBoot(tm) bootstrap and debug environment [ROM]
eCosCentric certified release, version v4_2_0 - built 17:03:10, Jun 12 2018

Copyright (C) 2000-2009 Free Software Foundation, Inc.
Copyright (C) 2003-2018 eCosCentric Limited
The RedBoot bootloader is a component of the eCos real-time operating system.
This is free software, covered by the eCosPro Non-Commercial Public License
and eCos Public License. You are welcome to change it and/or distribute copies
of it under certain conditions. Under the license terms, RedBoot's source code
and full license terms must have been made available to you.
Redboot comes with ABSOLUTELY NO WARRANTY.

Platform: Raspberry Pi B3 (BCM2837 - Cortex-A53)
RAM: 0x00000000-0x3e000000 [0x0004eeb0-0x3de00000 available]
  Arena: base 0x3de00000, size 0x200000, 95% free, maxfree 0x1eaf3c
== Executing boot script in 1.000 seconds - enter ^C to abort
RedBoot> fs exec /boot/redboot.txt
RedBoot> jtag 22 23 24 25 26 27
PIN FUNC
 22 ARM_TRST
 23 ARM_RTCK
 24 ARM_TDO
 25 ARM_TCK
 26 ARM_TDI
 27 ARM_TMS
RedBoot> fs exec
RedBoot>

Before loading RedBoot, the GPU configures the board according to the contents of the config.txt file in the boot partition. eCosPro currently makes minimal use of the settings in this file, the default config.txt for eCosPro just sets the GPU reserved memory to its minimum of 16MiB. No other configuration settings have been tested, so change them at your peril. Full details of the file contents can be found in the Raspberry Pi Foundation documentation.

	Note
	If a RPi board supports Ethernet and you do not connect an Ethernet cable, or the network does not provide a dhcp server, then you will experience a delay before the full RedBoot banner and prompt are displayed.

Resizing the Second SD Partition

The standard eCosPro disk image is sized to fit into a 2GB SD card with two partitions. The first partition is located 4MB from the beginning of the SD card and contains RedBoot and other system files necessary to boot the Raspberry Pi. The second partition follows the first and contains an initially empty VFAT filesystem of 1.23GB in size. If you have a larger card, and wish to utilise all the available storage capacity from eCos, you will need to expand the second partition to incorporate the unused capacity. As an embedded system eCosPro does not have the ability to repartition the disk itself. This needs to be done from a host system running either Windows or Linux.

Installing user applications onto an SD card

If you wish to install a ROM startup application onto an SD to be automatically booted instead of RedBoot, then you can do this by replacing the appropriate kernel image file in the SD card boot partition.

First prepare an SD card as per the Initial Installation section above. The card should then be remounted and your application copied over, replacing the relevant kernel image file(s) within the boot partition. Applications are compiled and linked to ELF format, and need to be converted to binary before copying to the the SD card. This can be done as follows using objcopy:

$ arm-eabi-objcopy -O binary app.elf kernel.img

If you have built the application for the BCM2835 (Pi1/Pi0) based boards, replace kernel.img, and for the BCM2836 (Pi2) or BCM2837 (Pi3) based boards, replace kernel7.img. Replacing the wrong file may result in the board failing to boot. For widest compatibility you can replace both kernel.img and kernel7.img with suitably built versions of your application.

Rebuilding RedBoot

Typical users should never need to rebuild RedBoot. If you do intend to modify RedBoot then please note that rebuilding it is currently only supported from the Linux command line.

The following RedBoot configurations are supported:

The JTAG configuration is only required if you wish to build a version of RedBoot to load and debug over JTAG, before ultimately creating a final ROM version to be booted from SD.

Note that the use of the term ROM for the initial RedBoot configuration is a historical accident. RedBoot actually runs from SDRAM after being loaded there from the SD card by the GPU bootstrap. The use of ROM for this configuration is intended to indicate that it initializes the microprocessor and board peripherals, as opposed to a RAM configuration which assumes that this has already been done.

The ROM_115k configuration is provided as an alternative to the ROM_2Mb configuration, for compatibility with low performance USB to serial converters. It simply lowers the default baud rate to 115200 and is otherwise identical.

The final stage of the RedBoot build process will create a bootable RedBoot SD image. This is handled within the eCosPro/ecos-VERSION/packages/hal/arm/cortexa/pi/current/host/buildimg.sh script. In order for the script to complete successfully, the user must either have sudo privileges to mount and cp, or the user must be able to mount /tmp/sd_pi on /tmp/sd. For the latter case, the following entry in /etc/fstab is advised:

/tmp/sd_pi   /tmp/sd   vfat   user,noauto,rw,loop,offset=4194304  0   0

The steps needed to rebuild the ROM version of RedBoot are:

$ mkdir redboot_rpi2_rom
$ cd redboot_rpi2_rom
$ ecosconfig new raspberry_pi2 redboot
$ ecosconfig import $ECOS_REPOSITORY/hal/arm/cortexa/pi/VERSION/misc/redboot_ROM_2Mb.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make

At the end of the build the install/bin subdirectory should contain the file sd_pi.img. This file is the SD card image and is suitable at this point for booting Pi2 and Pi3 boards, including the CM3, since it only contains a kernel7.img file. To make it also capable of booting a Pi1 or Pi0 board repeat the above command sequence with the following changes:

$ mkdir redboot_rpi1b_rom
$ cd redboot_rpi1b_rom
$ ecosconfig new raspberry_pi1b redboot
$ ecosconfig import $ECOS_REPOSITORY/hal/arm/cortexa/pi/VERSION/misc/redboot_ROM_2Mb.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make

At the end of this build the install/bin subdirectory will contain a new sd_pi.img file. This should be a copy of the previous image with the addition of kernel.img. This image should then be written to an SD card as per the above Linux hosted setup instructions. e.g:

sudo dd status=progress if=install/bin/sd_pi.img of=/dev/sdX

The SD created should now be able to boot all RPi variants.

To build a RedBoot that uses a different default UART baud rate to the standard 2Mb/s, then edit the ecos.ecc file after each ecosconfig import stage as described above. Set user_value for both cdl_option CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL_BAUD and cdl_option CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL_BAUD to your desired baud rate. For example:

cdl_option CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL_BAUD {
    # Flavor: data
    # No user value, uncomment the following line to provide one.
    user_value 115200
    # value_source default
    # Default value: 2000000
    # Legal values: 9600 19200 38400 57600 115200 230400 460800 500000 576000 921600 1000000 1152000 1500000 2000000 2500000 3000000
};

You will then need to use this baud rate when connecting to the new RedBoot via a terminal or gdb debug session. The highest attainable reliable baud rate can depend upon the specific model Raspberry Pi, transceiver and/or host PC/OS used. The default 2MB/s has been found to work reliably across the Pi family members, using FTDI transceivers, connected to either Linux or Windows hosts. Use of other transceivers may require you to reduce the baud rate.