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 | |
---|
22 | CVS Revision: $Id$ |
---|
23 | |
---|
24 | |
---|
25 | 1. Introduction |
---|
26 | --------------- |
---|
27 | |
---|
28 | This tries to explain how to setup the RTEMS host environment so |
---|
29 | that RTEMS applications can be built for and run in a bare PC 386 or |
---|
30 | above. |
---|
31 | |
---|
32 | It covers essentially the aspects of loading images, since |
---|
33 | information concerning other issues such as building the development |
---|
34 | tools and the RTEMS distribution can be found in the 'RTEMS 4.6.0 |
---|
35 | On-Line Library' under 'Getting Started with RTEMS for C/C++ Users'. |
---|
36 | |
---|
37 | Please note that everything in the following text using the |
---|
38 | notation '<...>' is just an alias to something and should always be |
---|
39 | substituted by the real thing! |
---|
40 | |
---|
41 | |
---|
42 | 2. Building the GNU C/C++ Cross Compiler Toolset |
---|
43 | ------------------------------------------------ |
---|
44 | |
---|
45 | Obtaining, building and installing the tools for building the |
---|
46 | PC386 BSP of RTEMS is covered in detail in the 'RTEMS 4.6.0 On-Line |
---|
47 | Library' -> 'Getting Started with RTEMS for C/C++ Users'. You can |
---|
48 | either use pre-built toolset executables or build your own from |
---|
49 | the instructions given there. |
---|
50 | |
---|
51 | This BSP is designed to work only with ELF toolset configurations. |
---|
52 | This is format used by the i386-rtems target. |
---|
53 | |
---|
54 | |
---|
55 | 4. Building RTEMS |
---|
56 | ----------------- |
---|
57 | Obtaining, building and installing the tools for building the |
---|
58 | PC386 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 |
---|
62 | options with an i386-rtems toolset: |
---|
63 | |
---|
64 | --target=i386-rtems |
---|
65 | --enable-rtemsbsp=pc386 |
---|
66 | |
---|
67 | |
---|
68 | 5. RTEMS Tests |
---|
69 | -------------- |
---|
70 | |
---|
71 | If you've completed the last step successfully, you'll find the |
---|
72 | RTEMS sample and test files that can be loaded with GRUB in the |
---|
73 | '<build_point>/pc386/tests' directory, RTEMS sample and test files in |
---|
74 | a format suitable for use with NetBoot in the |
---|
75 | '<build_point>/pc386/BootImgs' directory. |
---|
76 | |
---|
77 | |
---|
78 | 6. Loading RTEMS PC386 applications |
---|
79 | ----------------------------------- |
---|
80 | |
---|
81 | 6.1. Unarchiving |
---|
82 | ---------------- |
---|
83 | |
---|
84 | Files which have been "tarred, gzipped" (i.e. .tar.gz or .tgz |
---|
85 | extension) may be unarchived with a command similar to one of the |
---|
86 | following: |
---|
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) |
---|
99 | Unices, since the GNU utilities are not the standard 'tar' will be |
---|
100 | gtar (GNU tar) and 'zcat' will be 'gzcat'. |
---|
101 | |
---|
102 | Given that the necessary utility programs are installed, any of |
---|
103 | the above commands will extract the contents of <file>.tar.gz into the |
---|
104 | current directory. To view the contents of an archive without |
---|
105 | restoring any files, use a command similar to the following: |
---|
106 | |
---|
107 | zcat <file>.tgz | tar tvf - |
---|
108 | |
---|
109 | |
---|
110 | 6.2 Using GRUB to load RTEMS PC386 applications from Floppy |
---|
111 | ----------------------------------------------------------- |
---|
112 | |
---|
113 | Using GRUB (GRand Unified Bootloader) is the simplest way to load |
---|
114 | and run your PC386 BSP samples, tests and programs. You will need to build GRUB |
---|
115 | so you need a working GCC and friends. The online documentation for GRUB lists |
---|
116 | what 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 | |
---|
128 | Download the lastest version (grub-0.93.tar.gz), change to a temporary |
---|
129 | directory (you won't need the grub files after this and can just go ahead and |
---|
130 | delete 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 | |
---|
138 | after this is done create a build directory and decend into it: |
---|
139 | |
---|
140 | $ mkdir build |
---|
141 | $ cd build |
---|
142 | |
---|
143 | then configure GRUB with the standard options: |
---|
144 | |
---|
145 | $ ../grub-0.93/configure |
---|
146 | |
---|
147 | and if successful run make: |
---|
148 | |
---|
149 | $ make |
---|
150 | |
---|
151 | Once complete you should have the 'stage1' and 'stage2' files. They will be |
---|
152 | in the directories with the same name. |
---|
153 | |
---|
154 | You should have two (2) formatted diskettes available. One of |
---|
155 | these will only be used temporarily to create the other one, and we'll |
---|
156 | refer to it as 'RAW GRUB' diskette (you can label it accordingly if |
---|
157 | you wish). The other diskette, which we will refer to as 'GRUB FS' |
---|
158 | should be high-level formatted with one of GRUB's supported file |
---|
159 | systems, 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 |
---|
163 | add 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' |
---|
187 | diskette. |
---|
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 |
---|
192 | FreeBSD 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' |
---|
210 | diskette (if you are using Linux you can mount the diskette in an |
---|
211 | appropriate mount point and then 'cp' the files to it, if it is either |
---|
212 | a DOS FAT or an EXT2FS diskette, or in the case of a DOS FAT diskette |
---|
213 | you can use 'mcopy' from 'mtools'.) |
---|
214 | |
---|
215 | After this is done boot a PC using the 'GRUB RAW' diskette. After |
---|
216 | this 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 |
---|
218 | following 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 |
---|
223 | is done, you won't require the 'GRUB RAW' diskette anymore and you can |
---|
224 | delete the 'stage1' file from the 'GRUB FS' diskette. |
---|
225 | |
---|
226 | Next copy all the files you wish to load to the diskette. The GRUB |
---|
227 | loadable test and sample files in the RTEMS distribution have '.exe' |
---|
228 | extension and can be found under the build point in the 'pc386/tests' |
---|
229 | directory. You can compress this files with gzip to save space if you |
---|
230 | wish. GRUB loads 'gzipped' files transparently. |
---|
231 | |
---|
232 | Finally you have to create a GRUB menu configuration file. We will |
---|
233 | call this file 'grubmenu'. You can call it anything as long as you use |
---|
234 | the correct name in the 'install' command where we used 'grubmenu'. |
---|
235 | |
---|
236 | The 'grubmenu' file, as far as we are interested has the following |
---|
237 | syntax: |
---|
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' |
---|
243 | file. There should be one for each program you wish to load. The |
---|
244 | 'title=' line provides a description for the program that will appear |
---|
245 | after boot in the GRUB menu for the user to choose and the 'kernel=' |
---|
246 | line describes where the file can be found by GRUB (you should leave |
---|
247 | the '(fd0)/' part and just substitute the rest if you've copied the |
---|
248 | files to the root directory of the diskette. |
---|
249 | |
---|
250 | Just boot the PC with the 'GRUB FS' diskette and you will be able |
---|
251 | to choose which program you want to load from GRUB's menu. |
---|
252 | |
---|
253 | The GRUB documentation is available in HTML format in the 'docs' |
---|
254 | directory of the GRUB tree starting with the 'index.html' file. |
---|
255 | |
---|
256 | |
---|
257 | 6.3 Using GRUB to load RTEMS PC386 applications via PXE NetBoot |
---|
258 | ---------------------------------------------------------------- |
---|
259 | |
---|
260 | PXE is the Intel Preboot Execution Environment. A number of PC |
---|
261 | manufactures provide a PXE option in the BIOS. This is usually a |
---|
262 | Net Boot option in a BIOS configuration screen. The simplist way to |
---|
263 | load an RTEMS application via PXE is to use GRUB as a first stage |
---|
264 | loader. |
---|
265 | |
---|
266 | You will need to determine your network card, and have a working |
---|
267 | network with a DHCP (or BOOTP), and TFTP server. |
---|
268 | |
---|
269 | You may to find a TFTP server that does not support option |
---|
270 | negotiations. A google search shows a number of PC's have a buggy |
---|
271 | PXE loader. Supressing option negotiations seems to make them |
---|
272 | work. |
---|
273 | |
---|
274 | You will need to build GRUB for your network card. Follow the |
---|
275 | procedure in item 6.2 up to the configure point. At this point |
---|
276 | run the following configure command: |
---|
277 | |
---|
278 | $ ../grub-0.93/configure --enable-diskless --enable-eepro100 |
---|
279 | |
---|
280 | for an Etherexpress Pro 100 network card, then run make: |
---|
281 | |
---|
282 | $ make |
---|
283 | |
---|
284 | Once complete you should have the 'stage2/pxegrub' file. Copy |
---|
285 | this to your TFTP server's download directory. Configure your |
---|
286 | DHCP server to provide an IP address and download the image. For |
---|
287 | the ISC server found on operating systems such as Linux something |
---|
288 | like 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 | |
---|
300 | If 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 | |
---|
315 | Copy your RTEMS executable to the TFTP server directory then enter |
---|
316 | the 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 | |
---|
326 | The GRUB documents how to get GRUB to load a configuration file. |
---|
327 | |
---|
328 | |
---|
329 | 6.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 |
---|
335 | BOOTP server and a TFTP server (this can very well be you're Linux |
---|
336 | RTEMS host system), you can use Gero Kuhlmann's NetBoot loader, to |
---|
337 | load 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 | |
---|
341 | or in any of Sunsite's mirrors. It is also available from NetBoot's |
---|
342 | homepage: |
---|
343 | |
---|
344 | http://www.han.de/~gero/netboot |
---|
345 | |
---|
346 | After unarchiving 'netboot-0.7.3.tar.gz' you should change to the |
---|
347 | base 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 |
---|
353 | server(s) and to build a boot ROM for the client PC network card, or a |
---|
354 | boot diskette, and the PC client should be able to load the '*.bt' files |
---|
355 | from 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 | |
---|
365 | all the rest can be safely ignored if you don't care to examine it. |
---|
366 | |
---|
367 | |
---|
368 | 7. Technical Information |
---|
369 | ------------------------ |
---|
370 | |
---|
371 | NOTE: All the following paths are relative to the base directory |
---|
372 | of the RTEMS distribution. |
---|
373 | |
---|
374 | As of the writing of this HOWTO, PC386 images can be loaded either |
---|
375 | in low memory 0x10000 (64KB) until 0x97C00 (607K) using NetBoot or in |
---|
376 | high memory from 0x100000 (1024KB) until the top of the available |
---|
377 | memory using either NetBoot or GRUB. |
---|
378 | |
---|
379 | If you want to change the default loading address from 1024KB to |
---|
380 | something 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 |
---|
382 | follow the instructions indicated before the definition of RELOCADDR). |
---|
383 | |
---|
384 | Remember that GRUB restricts the loading addresses to values above |
---|
385 | 0x100000 (1024KB), only NetBoot can load images in low memory. |
---|
386 | |
---|
387 | After you make any changes to RELOCADDR and if you are using |
---|
388 | NetLoader, you'll have to recompile the |
---|
389 | 'c/src/lib/libbsp/i386/pc386/start/start16.s' file. The easiest way to |
---|
390 | achieve this is just to 'make clean' and the 'make all' again. The |
---|
391 | quickest way is to change to |
---|
392 | '<build_point>/c/src/lib/libbsp/i386/pc386/start' and 'make |
---|
393 | RTEMS_BSP=pc386 clean all'. |
---|
394 | |
---|
395 | When programming interrupt handlers take into account that the PIC |
---|
396 | is reprogrammed and so you should use the interface functions provided |
---|
397 | in '<build_point>/pc386/lib/include/irq.h> to guarantee that everything |
---|
398 | works ok. |
---|