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 | |
---|
19 | 1. Introduction |
---|
20 | --------------- |
---|
21 | |
---|
22 | This tries to explain how to setup the RTEMS host environment so |
---|
23 | that RTEMS applications can be built for and run in a bare PC 386 or |
---|
24 | above. |
---|
25 | |
---|
26 | It covers essentially the aspects of loading images, since |
---|
27 | information concerning other issues such as building the development |
---|
28 | tools and the RTEMS distribution can be found in the 'RTEMS 4.0.0 |
---|
29 | On-Line Library' under 'Getting Started with RTEMS for C/C++ Users'. |
---|
30 | |
---|
31 | Please note that everything in the following text using the |
---|
32 | notation '<...>' is just an alias to something and should always be |
---|
33 | substituted by the real thing! |
---|
34 | |
---|
35 | |
---|
36 | 2. Building the GNU C/C++ Cross Compiler Toolset |
---|
37 | ------------------------------------------------ |
---|
38 | |
---|
39 | Obtaining, building and installing the tools for building the |
---|
40 | PC386 BSP of RTEMS is covered in detail in the 'RTEMS 4.0.0 On-Line |
---|
41 | Library' -> 'Getting Started with RTEMS for C/C++ Users' -> 'Building |
---|
42 | the GNU C/C++ Cross Compiler Toolset'. |
---|
43 | |
---|
44 | When running the 'bit' script you should specift the argumetn as |
---|
45 | either: |
---|
46 | |
---|
47 | + 'i386-elf' to indicate an 'i386-rtemself' toolset, or |
---|
48 | + 'i386' to indicate an 'i386-rtems' toolset. |
---|
49 | |
---|
50 | |
---|
51 | 4. Building RTEMS |
---|
52 | ----------------- |
---|
53 | Obtaining, building and installing the tools for building the |
---|
54 | PC386 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 |
---|
58 | options: |
---|
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 | |
---|
69 | 5. RTEMS Tests |
---|
70 | -------------- |
---|
71 | |
---|
72 | If you've completed the last step successfully, you'll find the |
---|
73 | RTEMS sample and test files that can be loaded with GRUB in the |
---|
74 | '<build_point>/pc386/tests' directory, RTEMS sample and test files in |
---|
75 | a format suitable for use with NetBoot in the |
---|
76 | '<build_point>/pc386/BootImgs' directory. |
---|
77 | |
---|
78 | |
---|
79 | 6. Loading RTEMS PC386 applications |
---|
80 | ----------------------------------- |
---|
81 | |
---|
82 | 6.1. Unarchiving |
---|
83 | ---------------- |
---|
84 | |
---|
85 | Files which have been "tarred, gzipped" (i.e. .tar.gz or .tgz |
---|
86 | extension) may be unarchived with a command similar to one of the |
---|
87 | following: |
---|
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) |
---|
100 | Unices, since the GNU utilities are not the standard 'tar' will be |
---|
101 | gtar (GNU tar) and 'zcat' will be 'gzcat'. |
---|
102 | |
---|
103 | Given that the necessary utility programs are installed, any of |
---|
104 | the above commands will extract the contents of <file>.tar.gz into the |
---|
105 | current directory. To view the contents of an archive without |
---|
106 | restoring any files, use a command similar to the following: |
---|
107 | |
---|
108 | zcat <file>.tgz | tar tvf - |
---|
109 | |
---|
110 | |
---|
111 | 6.2 Using GRUB to load RTEMS PC386 applications |
---|
112 | ----------------------------------------------- |
---|
113 | |
---|
114 | Using GRUB (GRand Unified Bootloader) is the simplest way to load |
---|
115 | and 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 | |
---|
121 | or 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 |
---|
126 | temporary directory (you won't need the grub files after this and can |
---|
127 | just go ahead and delete the whole directory structure that was |
---|
128 | generated) and unarchive 'grub-0.4.tar.gz' following the instructions |
---|
129 | given above in [2. Unarchiving]. |
---|
130 | |
---|
131 | After this is done change the directory to: |
---|
132 | |
---|
133 | grub-0.4/bin_std |
---|
134 | |
---|
135 | and 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 |
---|
139 | these will only be used temporarily to create the other one, and we'll |
---|
140 | refer to it as 'RAW GRUB' diskette (you can label it accordingly if |
---|
141 | you wish). The other diskette, which we will refer to as 'GRUB FS' |
---|
142 | should be high-level formatted with one of GRUB's supported file |
---|
143 | systems, 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 |
---|
147 | add 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' |
---|
171 | diskette. |
---|
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 |
---|
176 | FreeBSD 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' |
---|
192 | diskette (if you are using Linux you can mount the diskette in an |
---|
193 | appropriate mount point and then 'cp' the files to it, if it is either |
---|
194 | a DOS FAT or an EXT2FS diskette, or in the case of a DOS FAT diskette |
---|
195 | you can use 'mcopy' from 'mtools'.) |
---|
196 | |
---|
197 | After this is done boot a PC using the 'GRUB RAW' diskette. After |
---|
198 | this 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 |
---|
200 | following 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 |
---|
205 | is done, you won't require the 'GRUB RAW' diskette anymore and you can |
---|
206 | delete the 'stage1' file from the 'GRUB FS' diskette. |
---|
207 | |
---|
208 | Next copy all the files you wish to load to the diskette. The GRUB |
---|
209 | loadable test and sample files in the RTEMS distribution have '.exe' |
---|
210 | extension and can be found under the build point in the 'pc386/tests' |
---|
211 | directory. You can compress this files with gzip to save space if you |
---|
212 | wish. GRUB loads 'gzipped' files transparently. |
---|
213 | |
---|
214 | Finally you have to create a GRUB menu configuration file. We will |
---|
215 | call this file 'grubmenu'. You can call it anything as long as you use |
---|
216 | the correct name in the 'install' command where we used 'grubmenu'. |
---|
217 | |
---|
218 | The 'grubmenu' file, as far as we are interested has the following |
---|
219 | syntax: |
---|
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' |
---|
225 | file. There should be one for each program you wish to load. The |
---|
226 | 'title=' line provides a description for the program that will appear |
---|
227 | after boot in the GRUB menu for the user to choose and the 'kernel=' |
---|
228 | line describes where the file can be found by GRUB (you should leave |
---|
229 | the '(fd0)/' part and just substitute the rest if you've copied the |
---|
230 | files to the root directory of the diskette. |
---|
231 | |
---|
232 | Just boot the PC with the 'GRUB FS' diskette and you will be able |
---|
233 | to choose which program you want to load from GRUB's menu. |
---|
234 | |
---|
235 | The GRUB documentation is available in HTML format in the 'docs' |
---|
236 | directory of the GRUB tree starting with the 'index.html' file. |
---|
237 | |
---|
238 | |
---|
239 | 6.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 |
---|
245 | BOOTP server and a TFTP server (this can very well be you're Linux |
---|
246 | RTEMS host system), you can use Gero Kuhlmann's NetBoot loader, to |
---|
247 | load 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 | |
---|
251 | or in any of Sunsite's mirrors. It is also available from NetBoot's |
---|
252 | homepage: |
---|
253 | |
---|
254 | http://www.han.de/~gero/netboot |
---|
255 | |
---|
256 | After unarchiving 'netboot-0.7.3.tar.gz' you should change to the |
---|
257 | base 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 |
---|
263 | server(s) and to build a boot ROM for the client PC network card, or a |
---|
264 | boot diskette, and the PC client should be able to load the '*.bt' files |
---|
265 | from 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 | |
---|
275 | all the rest can be safely ignored if you don't care to examine it. |
---|
276 | |
---|
277 | |
---|
278 | 7. Technical Information |
---|
279 | ------------------------ |
---|
280 | |
---|
281 | NOTE: All the following paths are relative to the base directory |
---|
282 | of the RTEMS distribution. |
---|
283 | |
---|
284 | As of the writing of this HOWTO, PC386 images can be loaded either |
---|
285 | in low memory 0x10000 (64KB) until 0x97C00 (607K) using NetBoot or in |
---|
286 | high memory from 0x100000 (1024KB) until the top of the available |
---|
287 | memory using either NetBoot or GRUB. |
---|
288 | |
---|
289 | If you want to change the default loading address from 1024KB to |
---|
290 | something 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 |
---|
292 | follow the instructions indicated before the definition of RELOCADDR). |
---|
293 | |
---|
294 | Remember that GRUB restricts the loading addresses to values above |
---|
295 | 0x100000 (1024KB), only NetBoot can load images in low memory. |
---|
296 | |
---|
297 | After you make any changes to RELOCADDR and if you are using |
---|
298 | NetLoader, you'll have to recompile the |
---|
299 | 'c/src/lib/libbsp/i386/pc386/start/start16.s' file. The easiest way to |
---|
300 | achieve this is just to 'make clean' and the 'make all' again. The |
---|
301 | quickest way is to change to |
---|
302 | '<build_point>/c/src/lib/libbsp/i386/pc386/start' and 'make |
---|
303 | RTEMS_BSP=pc386 clean all'. |
---|
304 | |
---|
305 | When programming interrupt handlers take into account that the PIC |
---|
306 | is reprogrammed and so you should use the interface functions provided |
---|
307 | in '<build_point>/pc386/lib/include/irq.h> to guarantee that everything |
---|
308 | works ok. |
---|