source: rtems/c/src/lib/libbsp/i386/pc386/HOWTO @ 441b90e

4.115
Last change on this file since 441b90e was 4338045, checked in by Chris Johns <chrisj@…>, on May 8, 2003 at 2:27:21 PM

Updated the GRUB version info and how to build GRUB from source.
Added how to boot over the network with a PXE Netboot BIOS.

  • Property mode set to 100644
File size: 14.6 KB
Line 
1+-----------------------------------------------------------------------------+
2| RTEMS 4.6.0 PC386 BSP HOWTO - 2003/05/08                                    |
3|                                                                             |
4+-----------------------------------------------------------------------------+
5| (C) Copyright 1998 -                                                        |
6| - NavIST Group - Real-Time Distributed Systems and Industrial Automation    |
7|                                                                             |
8| http://pandora.ist.utl.pt                                                   |
9|                                                                             |
10| Instituto Superior Tecnico * Lisboa * PORTUGAL                              |
11+-----------------------------------------------------------------------------+
12| Disclaimer:                                                                 |
13|                                                                             |
14| This file is provided "AS IS" without warranty of any kind, either          |
15| expressed or implied.                                                       |
16+-----------------------------------------------------------------------------+
17| History:                                                                    |
18|  12 June 2000 - Updated to 4.5 (Joel)                                       |
19|   8 May  2003 - PXE GRUB (Chris Johns)                                      |
20+-----------------------------------------------------------------------------+
21
22CVS Revision: $Id$
23
24
251. Introduction
26---------------
27
28    This tries to explain how to setup the RTEMS host environment so
29that RTEMS applications can be built for and run in a bare PC 386 or
30above.
31
32    It covers essentially the aspects of loading images, since
33information concerning other issues such as building the development
34tools and the RTEMS distribution can be found in the 'RTEMS 4.6.0
35On-Line Library' under 'Getting Started with RTEMS for C/C++ Users'.
36
37    Please note that everything in the following text using the
38notation '<...>' is just an alias to something and should always be
39substituted by the real thing!
40
41
422. Building the GNU C/C++ Cross Compiler Toolset
43------------------------------------------------
44
45    Obtaining, building and installing the tools for building the
46PC386 BSP of RTEMS is covered in detail in the 'RTEMS 4.6.0 On-Line
47Library' -> 'Getting Started with RTEMS for C/C++ Users'.  You can
48either use pre-built toolset executables or build your own from
49the instructions given there.
50
51    This BSP is designed to work only with ELF toolset configurations.
52This is format used by the i386-rtems target.
53
54
554. Building RTEMS
56-----------------
57    Obtaining, building and installing the tools for building the
58PC386 BSP is covered in detail in the 'RTEMS 4.6.0 On-Line Library' ->
59'Getting Started with RTEMS for C/C++ Users' -> 'Building RTEMS'.
60
61    When running configure, use the following values for the listed
62options with an i386-rtems toolset:
63
64          --target=i386-rtems
65          --enable-rtemsbsp=pc386
66
67 
685. RTEMS Tests
69--------------
70
71    If you've completed the last step successfully, you'll find the
72RTEMS sample and test files that can be loaded with GRUB in the
73'<build_point>/pc386/tests' directory, RTEMS sample and test files in
74a format suitable for use with NetBoot in the
75'<build_point>/pc386/BootImgs' directory.
76
77
786. Loading RTEMS PC386 applications
79-----------------------------------
80
816.1. Unarchiving
82----------------
83
84    Files which have been "tarred, gzipped" (i.e. .tar.gz or .tgz
85extension) may be unarchived with a command similar to one of the
86following:
87
88      zcat <file>.tgz | tar xvof -
89
90    OR
91
92      gunzip -c <file>.tgz | tar xvof -
93
94    OR
95
96      tar xzvf <file>.tgz
97
98    NOTE: gunzip -c is equivalent to zcat. On commercial (non-Linux)
99Unices, since the GNU utilities are not the standard 'tar' will be
100gtar (GNU tar) and 'zcat' will be 'gzcat'.
101
102    Given that the necessary utility programs are installed, any of
103the above commands will extract the contents of <file>.tar.gz into the
104current directory. To view the contents of an archive without
105restoring any files, use a command similar to the following:
106
107      zcat <file>.tgz | tar tvf -
108
109
1106.2 Using GRUB to load RTEMS PC386 applications from Floppy
111-----------------------------------------------------------
112
113    Using GRUB (GRand Unified Bootloader) is the simplest way to load
114and run your PC386 BSP samples, tests and programs. You will need to build GRUB
115so you need a working GCC and friends. The online documentation for GRUB lists
116what you need:
117
118    - http://www.gnu.org/manual/grub/html_node/index.html
119
120    You can get the latest release of GRUB from its homepage:
121
122    - http://www.gnu.org/software/grub/
123
124    Once you obtain the .tar.gz archive from:
125
126    - ftp://alpha.gnu.org/gnu/grub/
127
128Download the lastest version (grub-0.93.tar.gz), change to a temporary
129directory (you won't need the grub files after this and can just go ahead and
130delete the whole directory structure that was generated) and unarchive
131'grub-0.93.tar.gz' following the instructions given above in [2. Unarchiving].
132
133      $ cd /tmp
134      $ mkdir grub
135      $ cd grub
136      $ cat grub-0.93.tar.gz | gzip -d | tar xf -
137
138after this is done create a build directory and decend into it:
139
140      $ mkdir build
141      $ cd build
142
143then configure GRUB with the standard options:
144
145      $ ../grub-0.93/configure
146
147and if successful run make:
148
149      $ make
150
151    Once complete you should have the 'stage1' and 'stage2' files. They will be
152in the directories with the same name.
153
154    You should have two (2) formatted diskettes available. One of
155these will only be used temporarily to create the other one, and we'll
156refer to it as 'RAW GRUB' diskette (you can label it accordingly if
157you wish). The other diskette, which we will refer to as 'GRUB FS'
158should be high-level formatted with one of GRUB's supported file
159systems, which are: DOS FAT, BSD FFS, and Linux ext2fs.
160
161    A DOS FAT diskette can, obviously, be created under DOS with the
162'FORMAT' command. Under Linux, the following commands are available to
163add file systems to low-level formatted diskettes:
164
165    1. To add a DOS FAT file system to a low-level formatted diskette:
166
167      a) If you have mtools installed:
168
169           'mformat a:'.
170
171      b) Assuming that you are formatting the diskette in the first
172         floppy disk drive ('/dev/fd0' under Linux):
173
174           'mkdosfs /dev/fd0' or
175
176           'mkfs.msdos /dev/fd0'.
177
178    2. To add a Linux ext2fs file system to a low-level formatted
179       diskette, assuming that you are formatting the diskette in the
180       first floppy disk drive ('/dev/fd0' under Linux):
181
182         'mke2fs /dev/fd0' or
183
184         'mkfs.ext2 /dev/fd0'.
185
186   Next we will install using 'rawrite' or 'dd' to the 'GRUB RAW'
187diskette.
188
189   NOTE: This will destroy any data currently on the diskette.
190
191   Execute your OS's equivalent of (this should work for recent
192FreeBSD versions and Linux just fine):
193
194     dd if=stage1/stage1 of=/dev/fd0 bs=512 count=1
195     dd if=stage2/stage2 of=/dev/fd0 bs=512 seek=1
196
197   Under DOS/Windows/NT, courtesy of Eric Hanchrow (erich@microsoft.com):
198
199     * Use the copy /b command to binary concatenate the stage1 and
200       stage2 files together via:
201
202         copy /b stage1\stage1 stage2\stage2 grub.raw
203
204     * Use rawrite.exe (which is available in many places on the net and
205       in some Linux distributions) to write grub.raw to a diskette.
206
207(CCJ: I am not sure about the Windows location etc)
208
209   Next stage: copy the 'stage1' and 'stage2' files to the 'GRUB FS'
210diskette (if you are using Linux you can mount the diskette in an
211appropriate mount point and then 'cp' the files to it, if it is either
212a DOS FAT or an EXT2FS diskette, or in the case of a DOS FAT diskette
213you can use 'mcopy' from 'mtools'.)
214
215   After this is done boot a PC using the 'GRUB RAW' diskette. After
216this is done, you will get GRUB's command line interface. Exchange
217'GRUB RAW' with the 'GRUB FS' diskette in the drive and issue the
218following command from GRUB's prompt:
219
220     install=(fd0)/stage1 (fd0) (fd0)/stage2 0x8000 (fd0)/grubmenu
221
222   This command will make the 'GRUB FS' diskette bootable. After this
223is done, you won't require the 'GRUB RAW' diskette anymore and you can
224delete the 'stage1' file from the 'GRUB FS' diskette.
225
226   Next copy all the files you wish to load to the diskette. The GRUB
227loadable test and sample files in the RTEMS distribution have '.exe'
228extension and can be found under the build point in the 'pc386/tests'
229directory. You can compress this files with gzip to save space if you
230wish. GRUB loads 'gzipped' files transparently.
231
232   Finally you have to create a GRUB menu configuration file. We will
233call this file 'grubmenu'. You can call it anything as long as you use
234the correct name in the 'install' command where we used 'grubmenu'.
235
236   The 'grubmenu' file, as far as we are interested has the following
237syntax:
238
239     title=  Hello World Test
240     kernel= (fd0)/hello.exe.gz
241
242   You can add as many of this entries as you want to the 'grubmenu'
243file. There should be one for each program you wish to load. The
244'title=' line provides a description for the program that will appear
245after boot in the GRUB menu for the user to choose and the 'kernel='
246line describes where the file can be found by GRUB (you should leave
247the '(fd0)/' part and just substitute the rest if you've copied the
248files to the root directory of the diskette.
249
250   Just boot the PC with the 'GRUB FS' diskette and you will be able
251to choose which program you want to load from GRUB's menu.
252
253   The GRUB documentation is available in HTML format in the 'docs'
254directory of the GRUB tree starting with the 'index.html' file.
255
256
2576.3 Using GRUB to load RTEMS PC386 applications via PXE NetBoot
258----------------------------------------------------------------
259
260PXE is the Intel Preboot Execution Environment. A number of PC
261manufactures provide a PXE option in the BIOS. This is usually a
262Net Boot option in a BIOS configuration screen. The simplist way to
263load an RTEMS application via PXE is to use GRUB as a first stage
264loader.
265
266You will need to determine your network card, and have a working
267network with a DHCP (or BOOTP), and TFTP server.
268
269You may to find a TFTP server that does not support option
270negotiations. A google search shows a number of PC's have a buggy
271PXE loader. Supressing option negotiations seems to make them
272work.
273
274You will need to build GRUB for your network card. Follow the
275procedure in item 6.2 up to the configure point. At this point
276run the following configure command:
277
278    $ ../grub-0.93/configure --enable-diskless --enable-eepro100
279
280for an Etherexpress Pro 100 network card, then run make:
281
282    $ make
283
284    Once complete you should have the 'stage2/pxegrub' file. Copy
285this to your TFTP server's download directory. Configure your
286DHCP server to provide an IP address and download the image. For
287the ISC server found on operating systems such as Linux something
288like the following should do:
289
290  #
291  # PC loading RTEMS via PXE and GRUB
292  #
293
294  group
295  {
296    filename "/tftpboot/pxeboot";
297    host rtems-pc { hardware ethernet 00:08:c7:73:41:65; }
298  }
299
300If all works your PC should boot and load GRUB over the network:
301
302    GRUB  version 0.93  (639K lower / 64512K upper memory)
303
304  Address: 10.10.10.10
305  NetMask: 255.255.255.0
306  Server: 10.10.10.1
307  Gateway: 10.10.10.1
308
309   [ Minimal BASH-like line editing is supported.  For the first word, TAB
310     lists possible command completions.  Anywhere else TAB lists the possible
311     completions of a device/filename. ]
312
313  grub>
314
315Copy your RTEMS executable to the TFTP server directory then enter
316the following GRUB commands:
317
318  grub> root (nd)
319    Filesystem type is tftp, using whole disk
320
321  grub> kernel ticker.exe
322     [Multiboot-elf, <0x100000:0x1e5a4:0x2b08>, shtab=0x122140, entry=0x10000c]
323
324  grub> boot
325
326The GRUB documents how to get GRUB to load a configuration file.
327
328
3296.4 Using NetBoot to load RTEMS PC386 applications
330---------------------------------------------------
331
332    To load the '*.bt' files you can
333
334    Alternatively, if you have a PC connected to a network with a
335BOOTP server and a TFTP server (this can very well be you're Linux
336RTEMS host system), you can use Gero Kuhlmann's NetBoot loader, to
337load RTEMS to a diskless PC across a network. You can get it from:
338
339   ftp://sunsite.unc.edu/pub/Linux/system/boot/ethernet/netboot-0.7.3.tar.gz
340
341or in any of Sunsite's mirrors. It is also available from NetBoot's
342homepage:
343
344      http://www.han.de/~gero/netboot
345
346    After unarchiving 'netboot-0.7.3.tar.gz' you should change to the
347base directory of this and run:
348
349      ./configure --disable-mknbi-dos --disable-mknbi-linux --disable-mknbi-mgl
350
351    Afterwards, you should follow the instructions contained in the
352'INSTALL' file also contained in the base directory, on how to setup the
353server(s) and to build a boot ROM for the client PC network card, or a
354boot diskette, and the PC client should be able to load the '*.bt' files
355from the server.
356
357    The important sections to check in the 'INSTALL FILE' are the last two:
358
359    - Setup of the server (only the BOOTP and TFTP parts - ignore NFS).
360      ===================
361
362    - Setup of the client including building the bootrom
363      ==================================================
364
365all the rest can be safely ignored if you don't care to examine it.
366
367 
3687. Technical Information
369------------------------
370
371    NOTE: All the following paths are relative to the base directory
372of the RTEMS distribution.
373
374    As of the writing of this HOWTO, PC386 images can be loaded either
375in low memory 0x10000 (64KB) until 0x97C00 (607K) using NetBoot or in
376high memory from 0x100000 (1024KB) until the top of the available
377memory using either NetBoot or GRUB.
378
379    If you want to change the default loading address from 1024KB to
380something else, just change the value of the variable RELOCADDR in the
381'make/custom/pc386.cfg' file to the new value you want (make sure you
382follow the instructions indicated before the definition of RELOCADDR).
383
384    Remember that GRUB restricts the loading addresses to values above
3850x100000 (1024KB), only NetBoot can load images in low memory.
386
387    After you make any changes to RELOCADDR and if you are using
388NetLoader, you'll have to recompile the
389'c/src/lib/libbsp/i386/pc386/start/start16.s' file. The easiest way to
390achieve this is just to 'make clean' and the 'make all' again. The
391quickest way is to change to
392'<build_point>/c/src/lib/libbsp/i386/pc386/start' and 'make
393RTEMS_BSP=pc386 clean all'.
394
395    When programming interrupt handlers take into account that the PIC
396is reprogrammed and so you should use the interface functions provided
397in '<build_point>/pc386/lib/include/irq.h> to guarantee that everything
398works ok.
Note: See TracBrowser for help on using the repository browser.