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

4.104.114.84.95
Last change on this file since c0438add was fd808ba, checked in by Joel Sherrill <joel.sherrill@…>, on 08/21/98 at 12:48:44

Fixed discrepancies noted by John Oleynick <johno@…>.

  • Property mode set to 100644
File size: 11.6 KB
Line 
1
2+-----------------------------------------------------------------------------+
3| RTEMS 4.0.0 PC386 BSP HOWTO - 1998/04/21                                    |
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
18
191. Introduction
20---------------
21
22    This tries to explain how to setup the RTEMS host environment so
23that RTEMS applications can be built for and run in a bare PC 386 or
24above.
25
26    It covers essentially the aspects of loading images, since
27information concerning other issues such as building the development
28tools and the RTEMS distribution can be found in the 'RTEMS 4.0.0
29On-Line Library' under 'Getting Started with RTEMS for C/C++ Users'.
30
31    Please note that everything in the following text using the
32notation '<...>' is just an alias to something and should always be
33substituted by the real thing!
34
35
362. Building the GNU C/C++ Cross Compiler Toolset
37------------------------------------------------
38
39    Obtaining, building and installing the tools for building the
40PC386 BSP of RTEMS is covered in detail in the 'RTEMS 4.0.0 On-Line
41Library' -> 'Getting Started with RTEMS for C/C++ Users' -> 'Building
42the GNU C/C++ Cross Compiler Toolset'.
43
44    When running the 'bit' script you should specift the argumetn as
45either:
46
47   +  'i386-elf' to indicate an 'i386-rtemself' toolset, or
48   +  'i386' to indicate an 'i386-rtems' toolset.
49
50
514. Building RTEMS
52-----------------
53    Obtaining, building and installing the tools for building the
54PC386 BSP is covered in detail in the 'RTEMS 4.0.0 On-Line Library' ->
55'Getting Started with RTEMS for C/C++ Users' -> 'Building RTEMS'.
56
57    When running configure, use the following values for the listed
58options:
59
60      + with an i386-rtemself toolset
61          --target=i386-rtemself
62          --enable-rtemsbsp=pc386
63
64      + with an i386-rtems toolset
65          --target=i386-rtems
66          --enable-rtemsbsp=pc386
67
68 
695. RTEMS Tests
70--------------
71
72    If you've completed the last step successfully, you'll find the
73RTEMS sample and test files that can be loaded with GRUB in the
74'<build_point>/pc386/tests' directory, RTEMS sample and test files in
75a format suitable for use with NetBoot in the
76'<build_point>/pc386/BootImgs' directory.
77
78
796. Loading RTEMS PC386 applications
80-----------------------------------
81
826.1. Unarchiving
83----------------
84
85    Files which have been "tarred, gzipped" (i.e. .tar.gz or .tgz
86extension) may be unarchived with a command similar to one of the
87following:
88
89      zcat <file>.tgz | tar xvof -
90
91    OR
92
93      gunzip -c <file>.tgz | tar xvof -
94
95    OR
96
97      tar xzvf <file>.tgz
98
99    NOTE: gunzip -c is equivalent to zcat. On commercial (non-Linux)
100Unices, since the GNU utilities are not the standard 'tar' will be
101gtar (GNU tar) and 'zcat' will be 'gzcat'.
102
103    Given that the necessary utility programs are installed, any of
104the above commands will extract the contents of <file>.tar.gz into the
105current directory. To view the contents of an archive without
106restoring any files, use a command similar to the following:
107
108      zcat <file>.tgz | tar tvf -
109
110
1116.2 Using GRUB to load RTEMS PC386 applications
112-----------------------------------------------
113
114    Using GRUB (GRand Unified Bootloader) is the simplest way to load
115and run your PC386 BSP samples, tests and programs.
116
117    You can get the latest release of GRUB from its homepage:
118
119    - http://www.uruk.org/grub/
120
121or alternatively by ftp from:
122
123    - ftp://ftp.uruk.org/public/grub/
124
125    Once you obtain the .tar.gz archive 'grub-0.4.tar.gz', change to a
126temporary directory (you won't need the grub files after this and can
127just go ahead and delete the whole directory structure that was
128generated) and unarchive 'grub-0.4.tar.gz' following the instructions
129given above in [2. Unarchiving].
130
131    After this is done change the directory to:
132
133      grub-0.4/bin_std
134
135and there you'll find the two files you'll need from this archive:
136'stage1' and 'stage2'.
137
138    You should have two (2) formatted diskettes available. One of
139these will only be used temporarily to create the other one, and we'll
140refer to it as 'RAW GRUB' diskette (you can label it accordingly if
141you wish). The other diskette, which we will refer to as 'GRUB FS'
142should be high-level formatted with one of GRUB's supported file
143systems, which are: DOS FAT, BSD FFS, and Linux ext2fs.
144
145    A DOS FAT diskette can, obviously, be created under DOS with the
146'FORMAT' command. Under Linux, the following commands are available to
147add file systems to low-level formatted diskettes:
148
149    1. To add a DOS FAT file system to a low-level formatted diskette:
150
151      a) If you have mtools installed:
152
153           'mformat a:'.
154
155      b) Assuming that you are formatting the diskette in the first
156         floppy disk drive ('/dev/fd0' under Linux):
157
158           'mkdosfs /dev/fd0' or
159
160           'mkfs.msdos /dev/fd0'.
161
162    2. To add a Linux ext2fs file system to a low-level formatted
163       diskette, assuming that you are formatting the diskette in the
164       first floppy disk drive ('/dev/fd0' under Linux):
165
166         'mke2fs /dev/fd0' or
167
168         'mkfs.ext2 /dev/fd0'.
169
170   Next we will install using 'rawrite' or 'dd' to the 'GRUB RAW'
171diskette.
172
173   NOTE: This will destroy any data currently on the diskette.
174
175   Execute your OS's equivalent of (this should work for recent
176FreeBSD versions and Linux just fine):
177
178     dd if=stage1 of=/dev/fd0 bs=512 count=1
179     dd if=stage2 of=/dev/fd0 bs=512 seek=1
180
181   Under DOS/Windows/NT, courtesy of Eric Hanchrow (erich@microsoft.com):
182
183     * Use the copy /b command to binary concatenate the stage1 and
184       stage2 files together via:
185
186         copy /b stage1 stage2 grub.raw
187
188     * Use rawrite.exe (which is available in many places on the net and
189       in some Linux distributions) to write grub.raw to a diskette.
190
191   Next stage: copy the 'stage1' and 'stage2' files to the 'GRUB FS'
192diskette (if you are using Linux you can mount the diskette in an
193appropriate mount point and then 'cp' the files to it, if it is either
194a DOS FAT or an EXT2FS diskette, or in the case of a DOS FAT diskette
195you can use 'mcopy' from 'mtools'.)
196
197   After this is done boot a PC using the 'GRUB RAW' diskette. After
198this is done, you will get GRUB's command line interface. Exchange
199'GRUB RAW' with the 'GRUB FS' diskette in the drive and issue the
200following command from GRUB's prompt:
201
202     install=(fd0)/stage1 (fd0) (fd0)/stage2 0x8000 (fd0)/grubmenu
203
204   This command will make the 'GRUB FS' diskette bootable. After this
205is done, you won't require the 'GRUB RAW' diskette anymore and you can
206delete the 'stage1' file from the 'GRUB FS' diskette.
207
208   Next copy all the files you wish to load to the diskette. The GRUB
209loadable test and sample files in the RTEMS distribution have '.exe'
210extension and can be found under the build point in the 'pc386/tests'
211directory. You can compress this files with gzip to save space if you
212wish. GRUB loads 'gzipped' files transparently.
213
214   Finally you have to create a GRUB menu configuration file. We will
215call this file 'grubmenu'. You can call it anything as long as you use
216the correct name in the 'install' command where we used 'grubmenu'.
217
218   The 'grubmenu' file, as far as we are interested has the following
219syntax:
220
221     title=  Hello World Test
222     kernel= (fd0)/hello.exe.gz
223
224   You can add as many of this entries as you want to the 'grubmenu'
225file. There should be one for each program you wish to load. The
226'title=' line provides a description for the program that will appear
227after boot in the GRUB menu for the user to choose and the 'kernel='
228line describes where the file can be found by GRUB (you should leave
229the '(fd0)/' part and just substitute the rest if you've copied the
230files to the root directory of the diskette.
231
232   Just boot the PC with the 'GRUB FS' diskette and you will be able
233to choose which program you want to load from GRUB's menu.
234
235   The GRUB documentation is available in HTML format in the 'docs'
236directory of the GRUB tree starting with the 'index.html' file.
237
238
2396.3  Using NetBoot to load RTEMS PC386 applications
240---------------------------------------------------
241
242    To load the '*.bt' files you can
243
244    Alternatively, if you have a PC connected to a network with a
245BOOTP server and a TFTP server (this can very well be you're Linux
246RTEMS host system), you can use Gero Kuhlmann's NetBoot loader, to
247load RTEMS to a diskless PC across a network. You can get it from:
248
249   ftp://sunsite.unc.edu/pub/Linux/system/boot/ethernet/netboot-0.7.3.tar.gz
250
251or in any of Sunsite's mirrors. It is also available from NetBoot's
252homepage:
253
254      http://www.han.de/~gero/netboot
255
256    After unarchiving 'netboot-0.7.3.tar.gz' you should change to the
257base directory of this and run:
258
259      ./configure --disable-mknbi-dos --disable-mknbi-linux --disable-mknbi-mgl
260
261    Afterwards, you should follow the instructions contained in the
262'INSTALL' file also contained in the base directory, on how to setup the
263server(s) and to build a boot ROM for the client PC network card, or a
264boot diskette, and the PC client should be able to load the '*.bt' files
265from the server.
266
267    The important sections to check in the 'INSTALL FILE' are the last two:
268
269    - Setup of the server (only the BOOTP and TFTP parts - ignore NFS).
270      ===================
271
272    - Setup of the client including building the bootrom
273      ==================================================
274
275all the rest can be safely ignored if you don't care to examine it.
276
277 
2787. Technical Information
279------------------------
280
281    NOTE: All the following paths are relative to the base directory
282of the RTEMS distribution.
283
284    As of the writing of this HOWTO, PC386 images can be loaded either
285in low memory 0x10000 (64KB) until 0x97C00 (607K) using NetBoot or in
286high memory from 0x100000 (1024KB) until the top of the available
287memory using either NetBoot or GRUB.
288
289    If you want to change the default loading address from 1024KB to
290something else, just change the value of the variable RELOCADDR in the
291'make/custom/pc386.cfg' file to the new value you want (make sure you
292follow the instructions indicated before the definition of RELOCADDR).
293
294    Remember that GRUB restricts the loading addresses to values above
2950x100000 (1024KB), only NetBoot can load images in low memory.
296
297    After you make any changes to RELOCADDR and if you are using
298NetLoader, you'll have to recompile the
299'c/src/lib/libbsp/i386/pc386/start/start16.s' file. The easiest way to
300achieve this is just to 'make clean' and the 'make all' again. The
301quickest way is to change to
302'<build_point>/c/src/lib/libbsp/i386/pc386/start' and 'make
303RTEMS_BSP=pc386 clean all'.
304
305    When programming interrupt handlers take into account that the PIC
306is reprogrammed and so you should use the interface functions provided
307in '<build_point>/pc386/lib/include/irq.h> to guarantee that everything
308works ok.
Note: See TracBrowser for help on using the repository browser.