i386 PC Hardware Setup

# HG changeset patch # User nickg # Date 1038757977 0 # Node ID cb9bc921600ab0384abef47918da3a7a222be395 # Parent 41489edbdf761c720542da4705e11b7a1b66940d * ecos-tutorial.sgml: Expanded "i386 PC Hardware Setup" section to include information about FLOPPY and GRUB booting, and to add a section about debugging standalone applications. diff --git a/doc/sgml/tutorials/ChangeLog b/doc/sgml/tutorials/ChangeLog --- a/doc/sgml/tutorials/ChangeLog +++ b/doc/sgml/tutorials/ChangeLog @@ -1,3 +1,9 @@ +2002-12-01 Nick Garnett + + * ecos-tutorial.sgml: Expanded "i386 PC Hardware Setup" section to + include information about FLOPPY and GRUB booting, and to add a + section about debugging standalone applications. + 2002-10-15 Iztok Zupet * ecos-tutorial.sgml: pictures (gif==>png) diff --git a/doc/sgml/tutorials/ecos-tutorial.sgml b/doc/sgml/tutorials/ecos-tutorial.sgml --- a/doc/sgml/tutorials/ecos-tutorial.sgml +++ b/doc/sgml/tutorials/ecos-tutorial.sgml @@ -5253,6 +5253,12 @@ V850 CPU variant must be changed in the i386 PC Hardware Setup + +eCos application on the PC can be run in three ways: via RedBoot, +loaded directly from a floppy disk, or loaded by the GRUB bootloader. + + +RedBoot Support For information about setting up the PC to run with RedBoot, consult the RedBoot User"s Guide. If using serial debugging, the serial line runs at 38400 baud 8-N-1 and should be connected @@ -5263,6 +5269,146 @@ on the target PC and connected to the de When RedBoot is configured appropriately to have an IP address set, then GDB will be able to debug directly over TCP/IP to the target PC. + + +Floppy Disk Support + +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 + + +For NT Cygwin users, this can be done by first ensuring that the raw +floppy device is mounted as /dev/fd0. To check if this +is the case, type the command mount at the Cygwin bash +prompt. If the floppy drive is already mounted, it will be listed as something +similar to the following line: + \\.\a: /dev/fd0 user binmode +If this line is not listed, then mount the floppy drive using the command: + +$ mount -f -b //./a: /dev/fd0 +To actually install the boot image on the floppy, use the 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 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. If this fails, try a +different disk. + + + +GRUB Bootloader Support + +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. +In Red Hat Linux version 7.2 and later it is the default bootloader +for Linux and therefore is already installed. + + +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/current/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 running Red Hat Linux +version 7.2 and later, you can just add your own menu items to the +/boot/grub/menu.lst file that already exists. + + + +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. + + i386/Linux Synthetic Target Setup