Overview

The PC platform HAL package is loaded automatically when eCos is configured for a pc target. It should never be necessary to load this package explicitly. Unloading the package should only happen as a side effect of switching target hardware.

Startup

The PC platform HAL package accommodates four separate startup types:

Floppy Startup Installation

If an application is built with a startup type of FLOPPY, then it is configured to be a self-booting image that must be written onto a formatted floppy disk. This will erase any existing file system or data that is already on the disk, so proceed with caution.

To write an application to floppy disk, it must first be converted to a pure binary format. This is done with the following command:

$ i386-elf-objcopy -O binary app.elf app.bin

Here app.elf is the final linked application executable, in ELF format (it may not have a .elf extension). The file app.bin is the resulting pure binary file. This must be written to the floppy disk with the following command:

$ dd conv=sync if=app.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 eCos application will load itself and execute immediately.

	NOTE
	Unreliable floppy media may cause the write to silently fail. This can be determined if the application 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. If this fails, try a different disk.

GRUB Bootloader Support (version 0.97)

If an application 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 Linux and therefore is already installed in many installations.

To install GRUB on a floppy disk from Linux you need to execute the following commands:

$ 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/VERSION/misc/menu.lst /mnt/floppy/boot/grub
$ umount /mnt/floppy

The file menu.lst is an example GRUB menu configuration file. It contains menu items to load some of the standard eCos tests from floppy or from partition zero of the first hard disk. You should, of course, customize this file to load your own application. Alternatively you can use the command-line interface of GRUB to input commands yourself.

Applications can be installed, or updated simply by copying them to the floppy disk at the location expected by the menu.lst file. For booting from floppy disks it is recommended that the executable be stripped of all debug and symbol table information before copying. This reduces the size of the file and can make booting faster.

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.

	NOTE
	Certain distributions of Linux, including Red Hat Linux, supply a version of GRUB which references a configuration file named grub.conf rather than menu.lst.

GRUB 2 Bootloader Support (version 1.98)

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

GRUB 2 is an open source boot loader that supports many different operating systems. GRUB 2 is the sucessor to the legacy GRUB boot loader. It has been rewritten and requires a new configuration file that is different from the legacy GRUB loader. It is available from http://www.gnu.org/software/grub. The latest version of GRUB should be downloaded from there and installed. Cygwin users will need to install the GRand Unified Bootloader package on their system.

To install GRUB 2 on a disk drive from Cygwin you will first need to format your disk. Begin by launching a windows Command Prompt with ADMINISTRATOR priviledges. This example assumes that your destination drive is E and the filesystem type is FAT32.

$ format e: /fs:fat32 /q

The type of the file system is FAT32.
WARNING, ALL DATA ON NON-REMOVABLE DISK
DRIVE E: WILL BE LOST!
Proceed with Format (Y/N)? y
QuickFormatting 512M
Initializing the File Allocation Table (FAT)...
Volume label (11 characters, ENTER for none)?
Format complete.

When your drive is finished formatting, Cygwin will automatically mount the drive under /cygdrive/e. Next, launch a bash shell. Cygwin users should run their shell as ADMINISTRATOR otherwise the grub-install program will fail. To install GRUB we need to know the device name for your disk. A second disk drive is usually called /dev/sdb. The C: drive is usually called /dev/sda. Determine your device name by reading the /proc/partitions file. This example uses /dev/sdb as input to the GRUB install program.

$ cat /proc/partitions
major minor  #blocks  name
    8     0 156290904 sda
    8     1    102400 sda1
    8     2 156185600 sda2
    8    16 156290904 sdb
    8    17    524288 sdb1

$ grub-install --root-directory=/cygdrive/e /dev/sdb
Installation finished. No error reported.

$ cp $ECOS_REPOSITORY/packages/hal/i386/pc/current/misc/grub.cfg /cygdrive/e/boot/grub

$ cp redboot.elf /cygdrive/e/boot

After installing GRUB 2, we need to a copy a configuration file for grub to use. The file grub.cfg is an example configuration file that loads redboot.elf. You should, of course, customize this file to load your own application. Alternatively you can use the command-line interface of GRUB to input commands yourself. Applications can be installed or updated simply by copying them to the location expected by the grub.cfg file. In this example the /boot directory is used.

When installing 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 a spare disk or sacrificial hard disks first.

Debugging FLOPPY and GRUB Applications

When RedBoot loads an application it also provides debugging services in the form of GDB remote protocol stubs. When an application is loaded stand-alone from a floppy disk, or by GRUB, these services are not present. To allow these application to be debugged, it is possible to include GDB stubs into the application.

To do this, set the "Support for GDB stubs" (CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS) configuration option. Following this any application built will allow GDB to connect to the debug serial port (by default serial device 0, also known as COM1) whenever the application takes an exception, or if a Control-C is typed to the debug port. Ethernet debugging is not supported.

The option "Enable initial breakpoint" (CYGDBG_HAL_DEBUG_GDB_INITIAL_BREAK) causes the HAL to take a breakpoint immediately before calling cyg_start(). This gives the developer a chance to set any breakpoints or inspect the system state before it proceeds. The configuration sets this option by default if GDB stubs are included, and this is not a RedBoot build. To make the application execute immediately either disable this option, or disable CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS.

RedBoot and Virtual Vectors

If the application is intended to act as a monitor, providing services for other applications, then the configuration option CYGSEM_HAL_ROM_MONITOR should be set. Typically this option is set only when building RedBoot.

If the application is supposed to make use of services provided by a monitor, via the eCos virtual vector mechanism, then the configuration option CYGSEM_HAL_USE_ROM_MONITOR should be set. By default this option is enabled when building for a RAM startup, disabled otherwise. It can be manually disabled for a RAM startup, making the application self-contained, as a testing step before switching to FLOPPY or GRUB startup.

If the application does not rely on a monitor for diagnostic services then the serial port will be claimed for HAL diagnostics.

Ethernet Drivers

eCos is designed to support typical embedded development and production boards. These usually have a fixed set of hardware devices which are either on-chip or are soldered to the board. The PC target is unusual in that is does not have a fixed ethernet device, instead a variety PCI ethernet cards may be installed in the PCI card slots.

eCos supports different ethernet cards by defining a separate target configuration for each supported device. An instance of eCos or RedBoot configured to use one device will not work with a different ethernet device installed. The following table lists the targets and driver packages for the supported devices.

Entries in the cards column are examples only. There are for example many cards that contain the RealTek RTL8139 or a compatible device. Also be aware that manufacturers may change the device on a particular card to a totally different one without changing the model number.

System Clock

By default, the system clock interrupts once every 10ms, corresponding to a 100Hz clock. This can be changed by the configuration option CYGNUM_HAL_RTC_DENOMINATOR which corresponds to the clock frequency. Other clock-related settings are recalculated automatically if the denominator is changed.

Compiler Flags

The platform HAL defines the default compiler and linker flags for all packages, although it is possible to override these on a per-package basis. Most of the flags used are the same as for other architectures supported by eCos. There are no i386 specific flags that need to be specified for a PC platform.