forked from Imagelibrary/rtems
397 lines
15 KiB
Plaintext
397 lines
15 KiB
Plaintext
+-----------------------------------------------------------------------------+
|
|
| RTEMS 4.6.0 PC386 BSP HOWTO - 2003/05/08 |
|
|
| |
|
|
+-----------------------------------------------------------------------------+
|
|
| (C) Copyright 1998 - |
|
|
| - NavIST Group - Real-Time Distributed Systems and Industrial Automation |
|
|
| |
|
|
| http://pandora.ist.utl.pt |
|
|
| |
|
|
| Instituto Superior Tecnico * Lisboa * PORTUGAL |
|
|
+-----------------------------------------------------------------------------+
|
|
| Disclaimer: |
|
|
| |
|
|
| This file is provided "AS IS" without warranty of any kind, either |
|
|
| expressed or implied. |
|
|
+-----------------------------------------------------------------------------+
|
|
| History: |
|
|
| 12 June 2000 - Updated to 4.5 (Joel) |
|
|
| 8 May 2003 - PXE GRUB (Chris Johns) |
|
|
+-----------------------------------------------------------------------------+
|
|
|
|
|
|
1. Introduction
|
|
---------------
|
|
|
|
This tries to explain how to setup the RTEMS host environment so
|
|
that RTEMS applications can be built for and run in a bare PC 386 or
|
|
above.
|
|
|
|
It covers essentially the aspects of loading images, since
|
|
information concerning other issues such as building the development
|
|
tools and the RTEMS distribution can be found in the 'RTEMS 4.6.0
|
|
On-Line Library' under 'Getting Started with RTEMS for C/C++ Users'.
|
|
|
|
Please note that everything in the following text using the
|
|
notation '<...>' is just an alias to something and should always be
|
|
substituted by the real thing!
|
|
|
|
|
|
2. Building the GNU C/C++ Cross Compiler Toolset
|
|
------------------------------------------------
|
|
|
|
Obtaining, building and installing the tools for building the
|
|
PC386 BSP of RTEMS is covered in detail in the 'RTEMS 4.6.0 On-Line
|
|
Library' -> 'Getting Started with RTEMS for C/C++ Users'. You can
|
|
either use pre-built toolset executables or build your own from
|
|
the instructions given there.
|
|
|
|
This BSP is designed to work only with ELF toolset configurations.
|
|
This is format used by the i386-rtems target.
|
|
|
|
|
|
4. Building RTEMS
|
|
-----------------
|
|
Obtaining, building and installing the tools for building the
|
|
PC386 BSP is covered in detail in the 'RTEMS 4.6.0 On-Line Library' ->
|
|
'Getting Started with RTEMS for C/C++ Users' -> 'Building RTEMS'.
|
|
|
|
When running configure, use the following values for the listed
|
|
options with an i386-rtems toolset:
|
|
|
|
--target=i386-rtems
|
|
--enable-rtemsbsp=pc386
|
|
|
|
|
|
5. RTEMS Tests
|
|
--------------
|
|
|
|
If you've completed the last step successfully, you'll find the
|
|
RTEMS sample and test files that can be loaded with GRUB in the
|
|
'<build_point>/pc386/tests' directory, RTEMS sample and test files in
|
|
a format suitable for use with NetBoot in the
|
|
'<build_point>/pc386/BootImgs' directory.
|
|
|
|
|
|
6. Loading RTEMS PC386 applications
|
|
-----------------------------------
|
|
|
|
6.1. Unarchiving
|
|
----------------
|
|
|
|
Files which have been "tarred, gzipped" (i.e. .tar.gz or .tgz
|
|
extension) may be unarchived with a command similar to one of the
|
|
following:
|
|
|
|
zcat <file>.tgz | tar xvof -
|
|
|
|
OR
|
|
|
|
gunzip -c <file>.tgz | tar xvof -
|
|
|
|
OR
|
|
|
|
tar xzvf <file>.tgz
|
|
|
|
NOTE: gunzip -c is equivalent to zcat. On commercial (non-Linux)
|
|
Unices, since the GNU utilities are not the standard 'tar' will be
|
|
gtar (GNU tar) and 'zcat' will be 'gzcat'.
|
|
|
|
Given that the necessary utility programs are installed, any of
|
|
the above commands will extract the contents of <file>.tar.gz into the
|
|
current directory. To view the contents of an archive without
|
|
restoring any files, use a command similar to the following:
|
|
|
|
zcat <file>.tgz | tar tvf -
|
|
|
|
|
|
6.2 Using GRUB to load RTEMS PC386 applications from Floppy
|
|
-----------------------------------------------------------
|
|
|
|
Using GRUB (GRand Unified Bootloader) is the simplest way to load
|
|
and run your PC386 BSP samples, tests and programs. You will need to build GRUB
|
|
so you need a working GCC and friends. The online documentation for GRUB lists
|
|
what you need:
|
|
|
|
- http://www.gnu.org/manual/grub/html_node/index.html
|
|
|
|
You can get the latest release of GRUB from its homepage:
|
|
|
|
- http://www.gnu.org/software/grub/
|
|
|
|
Once you obtain the .tar.gz archive from:
|
|
|
|
- ftp://alpha.gnu.org/gnu/grub/
|
|
|
|
Download the lastest version (grub-0.93.tar.gz), change to a temporary
|
|
directory (you won't need the grub files after this and can just go ahead and
|
|
delete the whole directory structure that was generated) and unarchive
|
|
'grub-0.93.tar.gz' following the instructions given above in [2. Unarchiving].
|
|
|
|
$ cd /tmp
|
|
$ mkdir grub
|
|
$ cd grub
|
|
$ cat grub-0.93.tar.gz | gzip -d | tar xf -
|
|
|
|
after this is done create a build directory and decend into it:
|
|
|
|
$ mkdir build
|
|
$ cd build
|
|
|
|
then configure GRUB with the standard options:
|
|
|
|
$ ../grub-0.93/configure
|
|
|
|
and if successful run make:
|
|
|
|
$ make
|
|
|
|
Once complete you should have the 'stage1' and 'stage2' files. They will be
|
|
in the directories with the same name.
|
|
|
|
You should have two (2) formatted diskettes available. One of
|
|
these will only be used temporarily to create the other one, and we'll
|
|
refer to it as 'RAW GRUB' diskette (you can label it accordingly if
|
|
you wish). The other diskette, which we will refer to as 'GRUB FS'
|
|
should be high-level formatted with one of GRUB's supported file
|
|
systems, which are: DOS FAT, BSD FFS, and Linux ext2fs.
|
|
|
|
A DOS FAT diskette can, obviously, be created under DOS with the
|
|
'FORMAT' command. Under Linux, the following commands are available to
|
|
add file systems to low-level formatted diskettes:
|
|
|
|
1. To add a DOS FAT file system to a low-level formatted diskette:
|
|
|
|
a) If you have mtools installed:
|
|
|
|
'mformat a:'.
|
|
|
|
b) Assuming that you are formatting the diskette in the first
|
|
floppy disk drive ('/dev/fd0' under Linux):
|
|
|
|
'mkdosfs /dev/fd0' or
|
|
|
|
'mkfs.msdos /dev/fd0'.
|
|
|
|
2. To add a Linux ext2fs file system to a low-level formatted
|
|
diskette, assuming that you are formatting the diskette in the
|
|
first floppy disk drive ('/dev/fd0' under Linux):
|
|
|
|
'mke2fs /dev/fd0' or
|
|
|
|
'mkfs.ext2 /dev/fd0'.
|
|
|
|
Next we will install using 'rawrite' or 'dd' to the 'GRUB RAW'
|
|
diskette.
|
|
|
|
NOTE: This will destroy any data currently on the diskette.
|
|
|
|
Execute your OS's equivalent of (this should work for recent
|
|
FreeBSD versions and Linux just fine):
|
|
|
|
dd if=stage1/stage1 of=/dev/fd0 bs=512 count=1
|
|
dd if=stage2/stage2 of=/dev/fd0 bs=512 seek=1
|
|
|
|
Under DOS/Windows/NT, courtesy of Eric Hanchrow (erich@microsoft.com):
|
|
|
|
* Use the copy /b command to binary concatenate the stage1 and
|
|
stage2 files together via:
|
|
|
|
copy /b stage1\stage1 stage2\stage2 grub.raw
|
|
|
|
* Use rawrite.exe (which is available in many places on the net and
|
|
in some Linux distributions) to write grub.raw to a diskette.
|
|
|
|
(CCJ: I am not sure about the Windows location etc)
|
|
|
|
Next stage: copy the 'stage1' and 'stage2' files to the 'GRUB FS'
|
|
diskette (if you are using Linux you can mount the diskette in an
|
|
appropriate mount point and then 'cp' the files to it, if it is either
|
|
a DOS FAT or an EXT2FS diskette, or in the case of a DOS FAT diskette
|
|
you can use 'mcopy' from 'mtools'.)
|
|
|
|
After this is done boot a PC using the 'GRUB RAW' diskette. After
|
|
this is done, you will get GRUB's command line interface. Exchange
|
|
'GRUB RAW' with the 'GRUB FS' diskette in the drive and issue the
|
|
following command from GRUB's prompt:
|
|
|
|
install=(fd0)/stage1 (fd0) (fd0)/stage2 0x8000 (fd0)/grubmenu
|
|
|
|
This command will make the 'GRUB FS' diskette bootable. After this
|
|
is done, you won't require the 'GRUB RAW' diskette anymore and you can
|
|
delete the 'stage1' file from the 'GRUB FS' diskette.
|
|
|
|
Next copy all the files you wish to load to the diskette. The GRUB
|
|
loadable test and sample files in the RTEMS distribution have '.exe'
|
|
extension and can be found under the build point in the 'pc386/tests'
|
|
directory. You can compress this files with gzip to save space if you
|
|
wish. GRUB loads 'gzipped' files transparently.
|
|
|
|
Finally you have to create a GRUB menu configuration file. We will
|
|
call this file 'grubmenu'. You can call it anything as long as you use
|
|
the correct name in the 'install' command where we used 'grubmenu'.
|
|
|
|
The 'grubmenu' file, as far as we are interested has the following
|
|
syntax:
|
|
|
|
title= Hello World Test
|
|
kernel= (fd0)/hello.exe.gz
|
|
|
|
You can add as many of this entries as you want to the 'grubmenu'
|
|
file. There should be one for each program you wish to load. The
|
|
'title=' line provides a description for the program that will appear
|
|
after boot in the GRUB menu for the user to choose and the 'kernel='
|
|
line describes where the file can be found by GRUB (you should leave
|
|
the '(fd0)/' part and just substitute the rest if you've copied the
|
|
files to the root directory of the diskette.
|
|
|
|
Just boot the PC with the 'GRUB FS' diskette and you will be able
|
|
to choose which program you want to load from GRUB's menu.
|
|
|
|
The GRUB documentation is available in HTML format in the 'docs'
|
|
directory of the GRUB tree starting with the 'index.html' file.
|
|
|
|
|
|
6.3 Using GRUB to load RTEMS PC386 applications via PXE NetBoot
|
|
----------------------------------------------------------------
|
|
|
|
PXE is the Intel Preboot Execution Environment. A number of PC
|
|
manufactures provide a PXE option in the BIOS. This is usually a
|
|
Net Boot option in a BIOS configuration screen. The simplist way to
|
|
load an RTEMS application via PXE is to use GRUB as a first stage
|
|
loader.
|
|
|
|
You will need to determine your network card, and have a working
|
|
network with a DHCP (or BOOTP), and TFTP server.
|
|
|
|
You may to find a TFTP server that does not support option
|
|
negotiations. A google search shows a number of PC's have a buggy
|
|
PXE loader. Supressing option negotiations seems to make them
|
|
work.
|
|
|
|
You will need to build GRUB for your network card. Follow the
|
|
procedure in item 6.2 up to the configure point. At this point
|
|
run the following configure command:
|
|
|
|
$ ../grub-0.93/configure --enable-diskless --enable-eepro100
|
|
|
|
for an Etherexpress Pro 100 network card, then run make:
|
|
|
|
$ make
|
|
|
|
Once complete you should have the 'stage2/pxegrub' file. Copy
|
|
this to your TFTP server's download directory. Configure your
|
|
DHCP server to provide an IP address and download the image. For
|
|
the ISC server found on operating systems such as Linux something
|
|
like the following should do:
|
|
|
|
#
|
|
# PC loading RTEMS via PXE and GRUB
|
|
#
|
|
|
|
group
|
|
{
|
|
filename "/tftpboot/pxeboot";
|
|
host rtems-pc { hardware ethernet 00:08:c7:73:41:65; }
|
|
}
|
|
|
|
If all works your PC should boot and load GRUB over the network:
|
|
|
|
GRUB version 0.93 (639K lower / 64512K upper memory)
|
|
|
|
Address: 10.10.10.10
|
|
NetMask: 255.255.255.0
|
|
Server: 10.10.10.1
|
|
Gateway: 10.10.10.1
|
|
|
|
[ Minimal BASH-like line editing is supported. For the first word, TAB
|
|
lists possible command completions. Anywhere else TAB lists the possible
|
|
completions of a device/filename. ]
|
|
|
|
grub>
|
|
|
|
Copy your RTEMS executable to the TFTP server directory then enter
|
|
the following GRUB commands:
|
|
|
|
grub> root (nd)
|
|
Filesystem type is tftp, using whole disk
|
|
|
|
grub> kernel ticker.exe
|
|
[Multiboot-elf, <0x100000:0x1e5a4:0x2b08>, shtab=0x122140, entry=0x10000c]
|
|
|
|
grub> boot
|
|
|
|
The GRUB documents how to get GRUB to load a configuration file.
|
|
|
|
|
|
6.4 Using NetBoot to load RTEMS PC386 applications
|
|
---------------------------------------------------
|
|
|
|
To load the '*.bt' files you can
|
|
|
|
Alternatively, if you have a PC connected to a network with a
|
|
BOOTP server and a TFTP server (this can very well be you're Linux
|
|
RTEMS host system), you can use Gero Kuhlmann's NetBoot loader, to
|
|
load RTEMS to a diskless PC across a network. You can get it from:
|
|
|
|
ftp://sunsite.unc.edu/pub/Linux/system/boot/ethernet/netboot-0.7.3.tar.gz
|
|
|
|
or in any of Sunsite's mirrors. It is also available from NetBoot's
|
|
homepage:
|
|
|
|
http://www.han.de/~gero/netboot
|
|
|
|
After unarchiving 'netboot-0.7.3.tar.gz' you should change to the
|
|
base directory of this and run:
|
|
|
|
./configure --disable-mknbi-dos --disable-mknbi-linux --disable-mknbi-mgl
|
|
|
|
Afterwards, you should follow the instructions contained in the
|
|
'INSTALL' file also contained in the base directory, on how to setup the
|
|
server(s) and to build a boot ROM for the client PC network card, or a
|
|
boot diskette, and the PC client should be able to load the '*.bt' files
|
|
from the server.
|
|
|
|
The important sections to check in the 'INSTALL FILE' are the last two:
|
|
|
|
- Setup of the server (only the BOOTP and TFTP parts - ignore NFS).
|
|
===================
|
|
|
|
- Setup of the client including building the bootrom
|
|
==================================================
|
|
|
|
all the rest can be safely ignored if you don't care to examine it.
|
|
|
|
|
|
7. Technical Information
|
|
------------------------
|
|
|
|
NOTE: All the following paths are relative to the base directory
|
|
of the RTEMS distribution.
|
|
|
|
As of the writing of this HOWTO, PC386 images can be loaded either
|
|
in low memory 0x10000 (64KB) until 0x97C00 (607K) using NetBoot or in
|
|
high memory from 0x100000 (1024KB) until the top of the available
|
|
memory using either NetBoot or GRUB.
|
|
|
|
If you want to change the default loading address from 1024KB to
|
|
something else, just change the value of the variable RELOCADDR in the
|
|
'make/custom/pc386.cfg' file to the new value you want (make sure you
|
|
follow the instructions indicated before the definition of RELOCADDR).
|
|
|
|
Remember that GRUB restricts the loading addresses to values above
|
|
0x100000 (1024KB), only NetBoot can load images in low memory.
|
|
|
|
After you make any changes to RELOCADDR and if you are using
|
|
NetLoader, you'll have to recompile the
|
|
'c/src/lib/libbsp/i386/pc386/start/start16.s' file. The easiest way to
|
|
achieve this is just to 'make clean' and the 'make all' again. The
|
|
quickest way is to change to
|
|
'<build_point>/c/src/lib/libbsp/i386/pc386/start' and 'make
|
|
RTEMS_BSP=pc386 clean all'.
|
|
|
|
When programming interrupt handlers take into account that the PIC
|
|
is reprogrammed and so you should use the interface functions provided
|
|
in '<build_point>/pc386/lib/include/irq.h> to guarantee that everything
|
|
works ok.
|