Name

Setup — Preparing for eCos Development

Overview

In a typical development environment, the VM boots into the RedBoot ROM monitor. eCos applications are configured for RAM startup and then downloaded and run on the board via the debugger arm-eabi-gdb. Preparing the VM therefore usually involves arranging for a suitable RedBoot image to be executed on startup.

This process for doing this differs considerably between hypervisors, which are described separately in the following sections.

Xvisor Installation

This section describes how to install RedBoot into an Xvisor guest VM and start it running. The reader should be familiar with Xvisor, how to install it onto a target platform and how, in general, a guest VM is created.

To create an eCos VM under Xvisor, it is necessary to instantiate a virtual machine, populate it with the executable of RedBoot, and then set it running. To do this a number of files are copied to the etc directory of a RedBoot installation which are used set up a VM to run eCos. These files are as follows:

evm.dts
This is a Linux device tree source file. It needs to be compiled into a device tree binary file using the dtc device tree compiler. This file is specific to use on Rockchip-based boards such as the Pine Rockpro64 or M2000.
boot.xscript
This is a sample Xvisor boot script that instantiates a Linux guest together with a eCos VM running RedBoot. It may be used as it is, or used as a template for your own script.
nor_flash.list
A list of addresses and file names used to populate the virtual flash in a VM. This defines the software that will run from reset in the VM. In this case the sole entry installs a binary of RedBoot at the start of flash.
install
A shell script that automates the installation of a RedBoot executable into a Xvisor disk image. It creates the necessary sub-directory in the disk image, compiles and installs the device tree, RedBoot binary and flash list. It does not copy the boot.xscript file, which may be copied separately if required. Following this, a make should be run in the Xvisor build directory to rebuild the disk image. The image may then be transferred to the target system bootstrap medium.

See the next section, Rebuilding RedBoot, for an example of using the install script to install RedBoot into an Xvisor VM.

Once the files are installed, Xvisor may be started and the eCos VM will be executed. Depending on the default setting for the initial serial connection, and whether the boot.xscript file has been copied, you may see a startup banner from RedBoot similar to the following:

XVisor# vserial bind evm1/uart0
[evm1/uart0] +No network interfaces found

RedBoot(tm) bootstrap and debug environment [ROM]
Non-certified release, version UNKNOWN - built 14:58:47, Jan 30 2020

Copyright (C) 2000-2009 Free Software Foundation, Inc.
Copyright (C) 2003-2019 eCosCentric Limited
The RedBoot bootloader is a component of the eCos real-time operating system.
Want to know more? Visit www.ecoscentric.com for everything eCos & RedBoot related.
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: Virtual ARM (CORTEX-A)
RAM: 0x40000000-0x42000000 [0x40030000-0x42000000 available]
RedBoot>
      

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 steps needed to rebuild the ROM version of RedBoot are:

$ mkdir redboot_virtual_rom
$ cd redboot_virtual_rom
$ ecosconfig new virtual_xvisor redboot
$ ecosconfig import $ECOS_REPOSITORY/hal/arm/cortexa/virrual/VERSION/misc/redboot_ROM.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make
        

At the end of the build the install/bin subdirectory should contain the file redboot.bin. This image can now be installed into an Xvisor boot disk image using the install script. Assuming the root directory for the release is in $RELEASE the following commands will do this.

$ cd install
$ ./etc/install $RELEASE/xvisor-fs

Install RedBoot in disk image

Done
$
        

If required, boot.xscript may also be copied into $RELEASE/xvisor-fs.

It is now necessary to do a rebuild in the $RELEASE directory:

$ cd $RELEASE
$ make -s
Image Name:   Xvisor Ramdisk
Created:      Fri Jun 12 15:50:27 2020
Image Type:   AArch64 Linux RAMDisk Image (gzip compressed)
Data Size:    29360128 Bytes = 28672.00 KiB = 28.00 MiB
Load Address: 00000000
Entry Point:  00000000
Image Name:
Created:      Fri Jun 12 15:50:28 2020
Image Type:   ARM Linux Script (uncompressed)
Data Size:    259 Bytes = 0.25 KiB = 0.00 MiB
Load Address: 00000000
Entry Point:  00000000
Contents:
   Image 0: 251 Bytes = 0.25 KiB = 0.00 MiB
tune2fs 1.43.8 (1-Jan-2018)
Creating journal inode: done
This filesystem will be automatically checked every 20 mounts or
0 days, whichever comes first.  Use tune2fs -c or -i to override.
$
        

The Xvisor executable, host device tree and initial ram disk are now available in the $RELEASE/boot-fs directory and can be installed on to a eMMC or SD card, or may be copied to a TFTP server to boot the target. Details of how this can be done can be found on the rockpro64-build repository's Wiki page here:

https://github.com/ecoscentric/rockpro64-build/wiki/Building .

QEMU Installation

This section describes how to run eCos under QEMU. The reader should be familiar with QEMU, how to install it onto their host and how to invoke it. The examples in this section describe running QEMU under Linux.

eCos applications can be run under QEMU either directly or by first loading RedBoot and then using that to load and execute the application. In both cases it is necessary to configure QEMU to emulate a virtual machine that matches the target for which eCos has been compiled. A typical QEMU invocation is shown below.

qemu-system-arm -M virt -m 32 -nographic -s -kernel app \
          -netdev user,id=mynet,net=10.4.0.0/24,hostfwd=tcp::9000-:9000 \
          -device virtio-net-device,netdev=mynet -device virtio-serial-device \
          -chardev socket,id=vio,host=0.0.0.0,port=4322,server,telnet,nowait \
          -device virtserialport,chardev=vio
        

This will run an eCos application in an Aarch32 virtual machine with the main serial port routed to standard IO. Breaking that command line down into its components:

-M virt -m 32 -nographic -s
        

The -M option selects a generic ARMv7 virtual machine emulation. The -m option sets the main RAM size to 32MB. The -nographic suppresses use of a graphical interface, confining QEMU to a command line interface. The -s option enables the GDB server.

-kernel app
        

This specifies the application to load. The application may be either an ELF executable or a binary file. Only applications built using the ROM startup type should be used here. This application executable should be RedBoot if it is intended to run RAM startup application via GDB.

-netdev user,id=mynet,net=10.4.0.0/24,hostfwd=tcp::9000-:9000
-device virtio-net-device,netdev=mynet
        

These options set up the networking interface. In this case we are using QEMU's user networking support, which avoids the need to set up additional interfaces on the host and does not need privileged access. This option runs the virtual machine in a private subnet, in this case 10.4.0.0/24, which should be chosen so as not to clash with the existing network. The hostfwd option maps the host's TCP port 9000 to the virtual machine's port 9000; which is RedBoot's telnet/GDB port. Additional port mappings may be added if necessary.

-device virtio-serial-device
-chardev socket,id=vio,host=0.0.0.0,port=4322,server,telnet,nowait
-device virtserialport,chardev=vio
        

These options map the virtual machine's second serial port on to a telnet server on local port 4322.

The above command line uses standard IO for the main console. An alternative would be to attach the console to a Telnet socket. The following additional options will do this:

>
-serial tcp:0.0.0.0:4321,server,telnet,nowait
        

Use of telnet here provides support for the RedBoot command line interface. However, if the intention is to use GDB to load and run applications via the console, then the telnet option should be omitted since the telnet protocol does not interact well with the GDB protocol. The same consideration applies to the arguments for the second serial line given earlier.

For simplicity, a shell script, ecos_qemu, is available in the etc directory of the RedBoot install directory which runs an eCos application using the options above. It is recommended that this script and the executable to be run are copied out to a working directory. This script may be edited to adjust the arguments if a different configuration is needed. Running RedBoot using the script under Linux, will look something like this:

$ ./ecos_qemu redboot.elf
APP       redboot.elf
QEMU-ARGS
QEMU      qemu-system-arm
CMD       -M virt -m 32 -nographic -s -kernel redboot.elf -netdev user,id=mynet,net=10.4.0.0/24,
hostfwd=tcp::9000-:9000 -device virtio-net-device,netdev=mynet -device virtio-serial-device
-chardev socket,id=vio,host=0.0.0.0,port=4322,server,telnet,nowait -device virtserialport,
chardev=vio

Ctrl-A X to exit
Ctrl-A C for qemu monitor

+Ethernet eth0: MAC address 52:54:00:12:34:56
IP: 10.4.0.15/255.255.255.0, Gateway: 10.4.0.2
Default server: 10.4.0.2
DNS server IP: 10.4.0.3, DNS domain name: <null%gt;

RedBoot(tm) bootstrap and debug environment [ROM]
Non-certified release, version UNKNOWN - built 14:28:56, May 26 2020

Copyright (C) 2000-2009 Free Software Foundation, Inc.
Copyright (C) 2003-2019 eCosCentric Limited
The RedBoot bootloader is a component of the eCos real-time operating system.
Want to know more? Visit www.ecoscentric.com for everything eCos & RedBoot related.
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: Virtual ARM (CORTEX-A)
RAM: 0x40000000-0x42000000 [0x40458000-0x42000000 available]
RedBoot>
        

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 steps needed to rebuild the ROM version of RedBoot are:

$ mkdir redboot_qemu_rom
$ cd redboot_qemu_rom
$ ecosconfig new virtual_qemu redboot
$ ecosconfig import $ECOS_REPOSITORY/hal/arm/cortexa/virrual/VERSION/misc/redboot_ROM.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make

At the end of the build the install/bin subdirectory should contain the files redboot.elf and redboot.bin. Either of these files can now be used to start RedBoot.