Mercurial > flash_v2

comparison doc/sgml/tutorials/ecos-tutorial.sgml @ 442:cb9bc921600a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* 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.
author nickg
date Sun, 01 Dec 2002 15:52:57 +0000
parents f59de13184c2
children
comparison
equal deleted inserted replaced
441:41489edbdf76 442:cb9bc921600a
5251 or rebuilding the stubs for a V850/SB1 target, then the 5251 or rebuilding the stubs for a V850/SB1 target, then the
5252 V850 CPU variant must be changed in the CEB-V850 HAL to the SB1.</PARA> 5252 V850 CPU variant must be changed in the CEB-V850 HAL to the SB1.</PARA>
5253 </SECT1> 5253 </SECT1>
5254 <SECT1 id="setup-i386-pc"> 5254 <SECT1 id="setup-i386-pc">
5255 <TITLE>i386 PC Hardware Setup</TITLE> 5255 <TITLE>i386 PC Hardware Setup</TITLE>
5256 <para>
5257 eCos application on the PC can be run in three ways: via RedBoot,
5258 loaded directly from a floppy disk, or loaded by the GRUB bootloader.
5259 </para>
5260 <sect2>
5261 <title>RedBoot Support</title>
5256 <PARA>For information about setting up the PC to run with RedBoot, 5262 <PARA>For information about setting up the PC to run with RedBoot,
5257 consult the RedBoot User&quot;s Guide. If using serial debugging, 5263 consult the RedBoot User&quot;s Guide. If using serial debugging,
5258 the serial line runs at 38400 baud 8-N-1 and should be connected 5264 the serial line runs at 38400 baud 8-N-1 and should be connected
5259 to the debug host using a null modem cable. If ethernet debugging 5265 to the debug host using a null modem cable. If ethernet debugging
5260 is required, an i82559 compatible network interface card, such as 5266 is required, an i82559 compatible network interface card, such as
5261 an Intel EtherExpress Pro 10/100, should be installed 5267 an Intel EtherExpress Pro 10/100, should be installed
5262 on the target PC and connected to the development PC running GDB. 5268 on the target PC and connected to the development PC running GDB.
5263 When RedBoot is configured appropriately to have an IP address set, 5269 When RedBoot is configured appropriately to have an IP address set,
5264 then GDB will be able to debug directly over TCP/IP to the 5270 then GDB will be able to debug directly over TCP/IP to the
5265 target PC.</PARA> 5271 target PC.</PARA>
5272 </sect2>
5273 <sect2>
5274 <title>Floppy Disk Support</title>
5275 <para>
5276 If an application is built with a startup type of FLOPPY, then it is
5277 configured to be a self-booting image that must be written onto a
5278 formatted floppy disk. This will erase any existing file system or
5279 data that is already on the disk, so proceed
5280 with caution.
5281 </para>
5282 <para>
5283 To write an application to floppy disk, it must first be converted to
5284 a pure binary format. This is done with the following command:
5285 </para>
5286 <screen width=72>
5287 $ <userinput>i386-elf-objcopy -O binary app.elf app.bin</userinput>
5288 </screen>
5289 <para>
5290 Here <filename>app.elf</filename> is the final linked application
5291 executable, in ELF format (it may not have a <filename>.elf</filename>
5292 extension). The file <filename>app.bin</filename> is the resulting
5293 pure binary file. This must be written to the floppy disk with the
5294 following command:
5295 <screen width=72>
5296 $ <userinput>dd conv=sync if=app.bin of=/dev/fd0</userinput>
5297 </screen>
5298 </para>
5299 <para>For NT Cygwin users, this can be done by first ensuring that the raw
5300 floppy device is mounted as <filename>/dev/fd0</filename>. To check if this
5301 is the case, type the command <command>mount</command> at the Cygwin bash
5302 prompt. If the floppy drive is already mounted, it will be listed as something
5303 similar to the following line:</para>
5304 <screen> \\.\a: /dev/fd0 user binmode</screen>
5305 <para>If this line is not listed, then mount the floppy drive using the command:
5306 </para>
5307 <screen>$ <userinput>mount -f -b //./a: /dev/fd0</userinput></screen>
5308 <para>To actually install the boot image on the floppy, use the command:</para>
5309 <screen>
5310 $ <userinput>dd conv=sync if=app.bin of=/dev/fd0</userinput>
5311 </screen>
5312 <para>Insert this floppy in the A: drive of the PC to be used as a target
5313 and ensure that the BIOS is configured to boot from A: by default. On reset,
5314 the PC will boot from the floppy and the eCos application will load
5315 itself and execute immediately.</para>
5316 <note><title>NOTE</title>
5317 <para>Unreliable floppy media may cause the write to silently fail. This
5318 can be determined if the RedBoot image does not correctly
5319 boot. In such cases, the floppy should be (unconditionally) reformatted
5320 using the <command>fdformat</command> command on Linux, or
5321 <command>format a: /u</command> on DOS/Windows. If this fails, try a
5322 different disk.</para>
5323 </note>
5324 </sect2>
5325 <sect2>
5326 <title>GRUB Bootloader Support</title>
5327 <para>
5328 If an application is built with the GRUB startup type, it is
5329 configured to be loaded by the GRUB bootloader.
5330 </para>
5331 <para>
5332 GRUB is an open source boot loader that supports many different
5333 operating systems. It is available from
5334 <ulink
5335 url="http://www.gnu.org/software/grub">http://www.gnu.org/software/grub</ulink>.
5336 The latest version of GRUB should be downloaded from there and installed.
5337 In Red Hat Linux version 7.2 and later it is the default bootloader
5338 for Linux and therefore is already installed.
5339 </para>
5340 <para>
5341 To install GRUB on a floppy disk from Linux you need to execute the
5342 following commands:
5343 </para>
5344 <screen>
5345 $ <userinput>mformat a:</userinput>
5346 $ <userinput>mount /mnt/floppy</userinput>
5347 $ <userinput>grub-install --root-directory=/mnt/floppy '(fd0)'</userinput>
5348 Probing devices to guess BIOS drives. This may take a long time.
5349 Installation finished. No error reported.
5350 This is the contents of the device map /mnt/floppy/boot/grub/device.map.
5351 Check if this is correct or not. If any of the lines is incorrect,
5352 fix it and re-run the script `grub-install'.
5353
5354 (fd0) /dev/fd0
5355 $ <userinput>cp $ECOS_REPOSITORY/packages/hal/i386/pc/current/misc/menu.lst /mnt/floppy/boot/grub</userinput>
5356 $ <userinput>umount /mnt/floppy</userinput>
5357 </screen>
5358 <para>
5359 The file <filename>menu.lst</filename> is an example GRUB menu
5360 configuration file. It contains menu items to load some of the
5361 standard eCos tests from floppy or from partition zero of the first
5362 hard disk. You should, of course, customize this file to load your own
5363 application. Alternatively you can use the command-line interface of
5364 GRUB to input commands yourself.
5365 </para>
5366 <para>
5367 Applications can be installed, or updated simply by copying them to
5368 the floppy disk at the location expected by the
5369 <filename>menu.lst</filename> file. For booting from floppy disks it
5370 is recommended that the executable be stripped of all debug and symbol
5371 table information before copying. This reduces the size of the file
5372 and can make booting faster.
5373 </para>
5374 <para>
5375 To install GRUB on a hard disk, refer to the GRUB documentation. Be
5376 warned, however, that if you get this wrong it may compromise any
5377 existing bootloader that exists on the hard disk and may make any
5378 other operating systems unbootable. Practice on floppy disks or
5379 sacrificial hard disks first. On machines running Red Hat Linux
5380 version 7.2 and later, you can just add your own menu items to the
5381 <filename>/boot/grub/menu.lst</filename> file that already exists.
5382 </para>
5383 </sect2>
5384 <sect2>
5385 <title>Debugging FLOPPY and GRUB Applications</title>
5386 <para>
5387 When RedBoot loads an application it also provides debugging services
5388 in the form of GDB remote protocol stubs. When an application is
5389 loaded stand-alone from a floppy disk, or by GRUB, these services are
5390 not present. To allow these application to be debugged, it is possible
5391 to include GDB stubs into the application.
5392 </para>
5393 <para>
5394 To do this, set the &quot;Support for GDB stubs&quot;
5395 (<literal>CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS</literal>) configuration
5396 option. Following this any application built will allow GDB to connect
5397 to the debug serial port (by default serial device 0, also known as
5398 COM1) whenever the application takes an exception, or if a Control-C
5399 is typed to the debug port. Ethernet debugging is not supported.
5400 </para>
5401 <para>
5402 The option &quot;Enable initial breakpoint&quot;
5403 (<literal>CYGDBG_HAL_DEBUG_GDB_INITIAL_BREAK</literal>) causes the HAL
5404 to take a breakpoint immediately before calling cyg_start(). This
5405 gives the developer a chance to set any breakpoints or inspect the
5406 system state before it proceeds. The configuration sets this option by
5407 default if GDB stubs are included, and this is not a RedBoot build. To
5408 make the application execute immediately either disable this option,
5409 or disable <literal>CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS</literal>.
5410 </para>
5411 </sect2>
5266 </SECT1> 5412 </SECT1>
5267 <SECT1 id="setup-synth-i386linux"> 5413 <SECT1 id="setup-synth-i386linux">
5268 <TITLE><!-- <conditionaltext> --><!-- <index></index> -->i386/Linux Synthetic Target Setup</TITLE> 5414 <TITLE><!-- <conditionaltext> --><!-- <index></index> -->i386/Linux Synthetic Target Setup</TITLE>
5269 <PARA>When building for the synthetic Linux target, the resulting 5415 <PARA>When building for the synthetic Linux target, the resulting
5270 binaries are native Linux applications with the HAL providing suitable 5416 binaries are native Linux applications with the HAL providing suitable