Setup

Name

Setup -- Preparing a PC for eCos Development

Overview

In a typical development environment, the PC boots into the RedBoot monitor from a floppy disk. eCos applications are configured for RAM startup and then downloaded and run on the board via the debugger i386-elf-gdb. Preparing for development therefore involves writing a suitable RedBoot image onto a floppy disk.

The following RedBoot configurations are supported:

ConfigurationDescriptionUseFile
FLOPPYRedBoot booted from a floppy disk and running in the bottom 640k of RAMredboot_FLOPPY.ecmredboot_FLOPPY.bin
GRUBRedBoot loaded by the GRUB bootloader into memory above 0x00100000redboot_GRUB.ecmredboot_GRUB.bin
ROMRedBoot booted directly from ROM (experimental and unsupported)redboot_ROM.ecmredboot_ROM.bin
FLOPPY_SMPRedBoot booted from a floppy disk and running in the bottom 640k of RAM. This version supports dual processor systems.redboot_FLOPPY_SMP.ecmredboot_FLOPPY_SMP.bin
GRUB_SMPRedBoot loaded by the GRUB bootloader into memory above 0x00100000. This version supports dual processor systems.redboot_GRUB_SMP.ecmredboot_GRUB_SMP.bin

For serial communications, all versions run with 8 bits, no parity, and 1 stop bit at 38400 baud. RedBoot also supports ethernet communication and flash management.

Initial Installation

Floppy Installation

RedBoot takes the form of a self-booting image that must be written onto a formatted floppy disk. The process will erase any file system or data that already exists on that disk, so proceed with caution.

For Red Hat Linux users, writing the RedBoot image to floppy disk this can be achieved using the following command:

$ dd conv=sync if=install/bin/redboot.bin of=/dev/fd0H1440

For Windows users with recent versions of Cygwin, the raw floppy device should be accessible as /dev/fd0. Users with older versions of Cygwin may need to mount the floppy drive explicitly using the command:

$ mount -f -b //./a: /dev/fd0

To actually install the boot image on the floppy under Cygwin, use the command:

$ dd conv=sync if=install/bin/redboot.bin of=/dev/fd0

Insert this floppy in the A: drive of the PC to be used as a target and ensure that the BIOS is configured to boot from A: by default. On reset, the PC will boot from the floppy and the target will be ready for GDB debug sessions via either serial line, or the ethernet interface if it is installed.

NOTE: Unreliable floppy media may cause the write to silently fail. This can be determined if the RedBoot image does not correctly boot. In such cases, the floppy should be (unconditionally) reformatted using the fdformat command on Linux, or format a: /u on DOS/Windows.

VMWare Installation

The PC platform HAL may also be run under VMWare (Player, Server, etc). This can provide an initial development environment using simulated i386 PC hardware. The setup is similar to a floppy installation. However no IDE devices should be included in the guest definition due to issues with VMWare. The AMD Lance ethernet device is also recommended as the mechanism to communicate to the simulated PC hardware. The remainder of this sub-section describes how to set up a suitable virtual machine under VMWare that will be bootstrapped by RedBoot and allow for debugging of i386 PC applications either over the network or using serial communications.

First create a RedBoot floppy bootstrap image with the AMD Lance ethernet device included:

% ecosconfig new pc_vmWare redboot
% ecosconfig import $ECOS_REPOSITORY/hal/i386/pc/VERSION/misc/redboot_FLOPPY.ecm
% ecosconfig tree
% make

Create a VMWare virtual machine definition with no SCSI or IDE interfaces, 1MB memory, a single serial interface to a file, NAT Network adaptor and a floppy. Copy the redboot.bin you created above into place on the VMWare host and point the floppy image to this file. Example .vmx and .vmxf files for this configuration may be found in the misc subdirectory of the PC hal ($ECOS_REPOSITORY/packages/hal/i386/pc/). You may use other types of Network connections or serial ports as required.

To configure the Network connection to be an AMD Lance ethernet, you must edit the .vmx if you created your own VM definition and set ethernet0.virtualDev to vlance.

Note: The example .vmx file is intended for a Windows VMWare host so the setting serial0.fileName also must be adjusted accordingly.

If you intend to develop on a different host from the VMWare host, you may also wish to set up a NAT port forward from the VMWare host to the PC running RedBoot. An example Linux nat.conf NAT configuration file may also be found in the misc directory. For Windows, the Virtual Network Editor is recommended.

When the VM is powered on in this configuration, you will be able to download and debug executables through either the network connection or through the virtualised serial port using RedBoot.

GRUB Installation

If RedBoot is built with the GRUB startup type, it is configured to be loaded by the GRUB bootloader.

GRUB is an open source boot loader that supports many different operating systems. It is available from http://www.gnu.org/software/grub. The latest version of GRUB should be downloaded from there and installed. GRUB is now the default bootloader for most Linux distributions and therefore is already installed in many systems.

To install GRUB on a floppy disk from Linux you need to execute the following commands, with a fresh floppy diskette in the main drive:

$ mformat a:
$ mount /mnt/floppy
$ grub-install --root-directory=/mnt/floppy '(fd0)'
Probing devices to guess BIOS drives. This may take a long time.
Installation finished. No error reported.
This is the contents of the device map /mnt/floppy/boot/grub/device.map.
Check if this is correct or not. If any of the lines is incorrect,
fix it and re-run the script `grub-install'.

(fd0)	/dev/fd0
$ cp $ECOS_REPOSITORY/packages/hal/i386/pc/current/misc/redboot_menu.lst /mnt/floppy/boot/grub/menu.lst
$ umount /mnt/floppy

The file redboot_menu.lst is a GRUB menu configuration file. It contains a menu item to load RedBoot from the floppy diskette. Alternatively you can use the command-line interface of GRUB to input commands yourself.

To install RedBoot on the diskette, execute the following command:

$ mcopy redboot_GRUB.img a:/boot/redboot

Insert this floppy in the A: drive of the PC to be used as a target and ensure that the BIOS is configured to boot from A: by default. On reset, the PC will boot from the floppy into GRUB which will display its Boot Menu. If left for 30 seconds it will boot into RedBoot automatically. However, typing a return on the keyboard will cause it to boot RedBoot immediately.

To install GRUB on a hard disk, refer to the GRUB documentation. Be warned, however, that if you get this wrong it may compromise any existing bootloader that exists on the hard disk and may make any other operating systems unbootable. Practice on floppy disks or sacrificial hard disks first. On machines already running a GRUB-booted Linux you can just add your own menu items to the /boot/grub/menu.lst file that already exists.

Rebuilding RedBoot

Should it prove necessary to rebuild a RedBoot binary, this is achieved most conveniently at the command line. The steps needed to rebuild the the FLOPPY version of RedBoot for the PC are:

$ mkdir redboot_pc_floppy
$ cd redboot_pc_floppy
$ ecosconfig new TARGET redboot
$ ecosconfig import $ECOS_REPOSITORY/hal/i386/pc/VERSION/misc/redboot_FLOPPY.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make
    

When following the above instructions, the user should adopt one of i386 PC target names detailed in the following section to build RedBoot with support for a specific ethernet adapter. At the end of the build the install/bin subdirectory should contain the file redboot.bin.

The steps needed to rebuild the the GRUB version of RedBoot for the PC are:

$ mkdir redboot_pc_grub
$ cd redboot_pc_grub
$ ecosconfig new pc redboot
$ ecosconfig import $ECOS_REPOSITORY/hal/i386/pc/VERSION/misc/redboot_GRUB.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make
    

At the end of the build the install/bin subdirectory should contain the file redboot.img..

2017-02-09
Documentation license for this page: eCosPro License