Name

Setup — Preparing the Raspberry Pi for eCos Development

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.

Installation from Windows to an SD card

The following steps describe how to create a bootable RedBoot SD card for your Raspberry Pi. The best Windows-based tool for this purpose is the freely available Etcher SD card image burning utility. This is also the recommended utility for writing Raspian and other RPi Linux images.

Visit etcher.io to download and install the Etcher SD Burner utility.

  1. Insert the SD card to be programmed into the PC's card reader.
  2. Start the Etcher utility and click Select image, then browse to and select the RedBoot Raspberry Pi image from within the loaders/rpi directory.
  3. Click Select drive and select your SD card drive. Note that Etcher may have already pre-selected the SD drive. You can click on Change if this is not the correct drive.
  4. Click Flash! to write the image to the SD card. You'll see a progress bar that tells you how much is left to do. Once complete, the utility will automatically unmount the SD card so it's safe to immediately remove it from the computer.

Installation from Linux to an SD card

Installation on Linux should be done using the dd command.

  1. Locate a Linux PC with an SD card reader and insert the SD card to be programmed into the reader.
  2. Identify the device name that Linux has assigned to the SD card. This can be done either by monitoring the system log, or by using lsblk before and after inserting the card. In this example we will use /dev/sdX as a placeholder.
  3. Execute the following command in a shell:

    $ dd status=progress if=/path/to/eCosPro_RedBoot_RPi_2Mb.img of=/dev/sdX

    Depending on permissions and user group membership, it may be necessary to prefix this command with sudo or run it in a root shell.

  4. Execute the sync command. This may not be strictly necessary, but it will ensure that all data is safely written to the card.
  5. The card is now ready and may be removed.

Installation from Windows to Compute Module eMMC

Installation to the compute module eMMC requires the installation of a driver and a boot utility tool.

  1. Download and run the Windows Installer to install the drivers and boot tool.
  2. Follow the instructions on the Raspberry Pi website for installing the driver. Make sure the J4 jumper is in the EN position.
  3. Run the RPiBoot.exe tool. The compute module will then appear as a USB mass storage disk drive under Windows.
  4. You can now use the Etcher tool to write the RedBoot image to the drive as described above for an SD card.
  5. Once complete, the USB cable can be detached. Power off the CMIO board and move J4 back to its original position. On re-applying power, RedBoot will start.

Installation from Linux to Compute Module eMMC

To program an image from Linux it is necessary to download and compile the rpiboot utility program.

  1. The utility program is in a github repository, so ensure that git is installed. The program also needs libusb-1, so ensure that this is also installed.
  2. Clone the git repository into a convenient directory.

    $ git clone --depth=1 https://github.com/raspberrypi/usbboot
    Cloning into 'usbboot'...
    remote: Counting objects: 21, done.
    remote: Compressing objects: 100% (19/19), done.
    remote: Total 21 (delta 1), reused 14 (delta 0), pack-reused 0
    Unpacking objects: 100% (21/21), done.
    $
  3. Build the tool:

    $ cd usbboot
    $ make
    cc -Wall -Wextra -g -o rpiboot main.c -lusb-1.0
    $
  4. Move J4 on the compute module IO board to the EN position. Connect a USB cable between the USB SLAVE port and the host and power up the board.
  5. Run the rpiboot just built from the build directory:

    $ sudo ./rpiboot
    Waiting for BCM2835/6/7
    Sending bootcode.bin
    Successful read 4 bytes
    Waiting for BCM2835/6/7
    Second stage boot server
    File read: start.elf
    Second stage boot server done
    $
  6. The CM board will now be visible to Linux as a new USB mass storage device. Identify the device name that Linux has assigned to the SD card. This can be done either by monitoring the system log, or by using lsblk before and after inserting the card. In this example we will use /dev/sdx as a placeholder.
  7. Execute the following command in a shell:

    $ dd status=progress if=/path/to/eCosPro_RedBoot_RPi_2Mb.img of=/dev/sdx

    Depending on permissions and user group membership, it may be necessary to prefix this command with sudo or run it in a root shell.

  8. Execute the sync command. This may not be strictly necessary, but it will ensure that all data is safely written to the eMMC.
  9. Remove power from the compute module, move J4 back to its original position and detach the USB cable from the USB SLAVE port.
  10. Restore power to the compute module and RedBoot should boot.

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

Resizing from Windows

In Windows you need to run the Windows Disk Management tool to remove the second partition and create the new partition sized as required:

  1. To start the tool you can click on the Start Menu and type "disk management", click on the "Create and format hard disk partitions control panel" entry that appears.
  2. Remove the second partition (1.23GB FAT32) by right clicking on second partition and selecting "Delete Volume...". Click "Yes" to confirm.
  3. Create a new volume of the required size (typically the remaining space on the SD) by right clicking on the "Unallocated" space and selecting "New Simple Volume...".
  4. In the New Simple Volume Wizard's initial dialog click "Next >" to move to the "Specify Volume Size" dialog, then choose the disk size required (default is the remaining space on the SD) and click "Next >" again.
  5. In the "Assign Drive Letter or Path" dialog choose the drive letter of your choice, typically the default provided and click "Next >".
  6. In the final "Format Partition" dialog, choose the file system type - this should be the default "FAT32", then select the allocation size - choose "Default" or 4096 and then enter the "Volume label" of your choice. Leaving the "Perform a quick format" checkbox ticked, click "Next >". Review the settings and then click "Finish".

Your SD card should now contain two partitions. The first is the original boot partition containing RedBoot (or your own application, named as kernel*.img) and the second is a new partition expanded to incorporate the remaining SD card capacity.

Resizing from Linux

There are a variety of Linux tools in different distributions for resizing a partition, many are GUI based and similar to the Windows tool. The following example uses just command line tools and should work on all Linux distributions.

  1. Depending on permissions, it may be best to perform the following actions as root. Either start a root shell, or prefix all commands with sudo.
  2. Insert the SD card into the card reader and identify the device name assigned to it. This can be done either by monitoring the system log, or by using lsblk before and after inserting the card. In this example we will use /dev/sdX as a placeholder.
  3. Run fdisk on the device and type p to print the partition table:

    # fdisk /dev/sdX
    
    Welcome to fdisk (util-linux 2.28).
    Changes will remain in memory only, until you decide to write them.
    Be careful before using the write command.
    
    
    Command (m for help): p
    Disk /dev/sdX: 14.9 GiB, 15931539456 bytes, 31116288 sectors
    Units: sectors of 1 * 512 = 512 bytes
    Sector size (logical/physical): 512 bytes / 512 bytes
    I/O size (minimum/optimal): 512 bytes / 512 bytes
    Disklabel type: dos
    Disk identifier: 0xec05ec05
    
    Device     Boot  Start     End Sectors  Size Id Type
    /dev/sdX1         8192  137215  129024   63M  c W95 FAT32 (LBA)
    /dev/sdX2       137216 2715647 2578432  1.2G  c W95 FAT32 (LBA)
    
    Command (m for help):

    Check that things like the disk identifier and the partition parameters match the above to ensure you have the right device.

  4. Use the d command to delete partition 2:

    Command (m for help): d
    Partition number (1,2, default 2): 2
    
    Partition 2 has been deleted.
    
    Command (m for help):
  5. Ensuring you set the first sector to 137216, since there is 3MB of free space before the first partition which should NOT be used, use the n command to create a new partition. Check that the new partition fills the remaining card space with the p command.

    Command (m for help): n
    Partition type
       p   primary (1 primary, 0 extended, 3 free)
       e   extended (container for logical partitions)
    Select (default p): p
    Partition number (2-4, default 2): 2
    First sector (2048-31116287, default 2048): 137216
    Last sector, +sectors or +size{K,M,G,T,P} (137216-31116287, default 31116287):
    
    Created a new partition 2 of type 'Linux' and of size 14.8 GiB.
    
    Command (m for help): p
    Disk /dev/sdX: 14.9 GiB, 15931539456 bytes, 31116288 sectors
    Units: sectors of 1 * 512 = 512 bytes
    Sector size (logical/physical): 512 bytes / 512 bytes
    I/O size (minimum/optimal): 512 bytes / 512 bytes
    Disklabel type: dos
    Disk identifier: 0xec05ec05
    
    Device     Boot  Start      End  Sectors  Size Id Type
    /dev/sdX1         8192   137215   129024   63M  c W95 FAT32 (LBA)
    /dev/sdX2       137216 31116287 30979072 14.8G 83 Linux
    
    Command (m for help):
  6. Fdisk has set the new partition's type to Linux, use the t command to change the type to FAT32:

    Command (m for help): t
    Partition number (1,2, default 2): 2
    Partition type (type L to list all types): c
    
    Changed type of partition 'Linux' to 'W95 FAT32 (LBA)'.
    
    Command (m for help):
  7. Finally use the w command to write the partition table back and exit fdisk.
  8. The new partition now needs to be formatted with a FAT32 filesystem. This can be done using the mkfs.fat command:

    # mkfs.fat -v -F 32 /dev/sdX2
    mkfs.fat 3.0.26 (2014-03-07)
    /dev/sdX2 has 64 heads and 32 sectors per track,
    hidden sectors 0x21800;
    logical sector size is 512,
    using 0xf8 media descriptor, with 30979072 sectors;
    drive number 0x80;
    filesystem has 2 32-bit FATs and 16 sectors per cluster.
    FAT size is 15112 sectors, and provides 1934301 clusters.
    There are 32 reserved sectors.
    Volume ID is e2a0eca8, no volume label.
    #
  9. Execute the sync command. This may not be strictly necessary, but it will ensure that all data is safely written to the card.
  10. The card is now ready and may be removed.

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:

ConfigurationDescriptionUseFile
ROM_2MbRedBoot loaded from SD card to SDRAM, Standard version with default baud rate of 2Mb/sredboot_ROM_2Mb.ecmredboot_ROM_2Mb.bin
ROM_115kRedBoot loaded from SD card to SDRAM, alternative version with default baud rate of 115200redboot_ROM_115k.ecmredboot_ROM_115k.bin
JTAGRedBoot loaded via a JTAG debugger, for RedBoot developers onlyredboot_JTAG.ecmredboot_JTAG.bin

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.