MaRTE OS ---------- Minimal Real Time Operating System for Embedded Applications Version 1.7 - Nov 2007 Copyright (C) 2007 Universidad de Cantabria, SPAIN Authors: Mario Aldea Rivas aldeam@unican.es Michael Gonzalez Harbour mgh@unican.es Installation Guide ==================== Requirements ============ - An i386 PC or above. - Linux - Adacore GNAT compiler - Ethernet card for remote loading (optional) - Serial port for remote debugging (optional) Installation ================= 0) Installing Adacore GNAT compiler MaRTE OS is written in Ada, then even in the case you are not going to program Ada applications, you will need the GNAT compiler to compile the MaRTE kernel. Installing it is very easy and can be done in your own user directory without affecting the rest of the system. Each MaRTE OS version has support for a set of Adacore compiler versions. If you want to know which versions are supported by a MaRTE OS release, consult MaRTE OS directory 'libmgnat/' Installing an Adacore GNAT compiler is very simple. Just go to its website at https://libre.adacore.com/ and, after registering, download the compiler. Then, you have to decompress it and execute a simple script. For example, for the GNAT-GPL-2007 version execute: $ cd $HOME/myapps $ tar -zxvf gnat-gpl-2007-i686-gnu-linux-gnu-libc2.3-bin.tar.gz $ cd gnat-gpl-2007-i686-gnu-linux-gnu-libc2.3-bin $ ./doinstall $ Choose a non-standard installation and specify where you want to have the compiler (i.e: $HOME/myapps) Remember to put the directory where GNAT binaries are located AT THE FRONT of your PATH: $ export PATH=$HOME/myapps/gnat/bin:$PATH For making it permanent you can add the previous command to your shell startup script (i.e: $HOME/.bashrc or $HOME/.bash_profile) 1) Installing MaRTE OS MaRTE OS is very simple to install. You just have to uncompress it and run a script. Check that you have the Adacore compiler in front of your path ($ echo $PATH) $ cd $HOME $ tar -zxvf marte-version.tar.gz $ ./minstall 'minstall' will perform some stages and ask you for some data: 1.1) It will try to find your GNAT installation path. 1.2) It will ask you what underlying platform to use. - x86: for a bare x86 machine (Real-Time behaviour) - linux: for compiling MaRTE OS as a Linux process - linux_lib: the same as in linux but with full access to the Linux filesystem (and therefore, to its drivers) 1.3) It will compile MaRTE OS 1.4) You will be asked for a directory to leave the final executable containing MaRTE OS and your application. Finally, you have to include the 'utils/' directory in your path: $ export PATH=$PATH:$HOME/marte/utils For making it permanent you can add the previous command to your shell startup script (i.e: $HOME/.bashrc or $HOME/.bash_profile) Note: Sometimes you will want to have several instances of MaRTE OS installed on the same system (for example to have several versions of MaRTE OS) leading to a collision when using the directories in the $PATH variable. One possibility is to have them with different names and make a symbolic link to know which one you want to use at the moment. (The same goes for the GNAT compilers). For example, in the following tree "marte" is a the symbolic link (ln -s realmarte marte): |-- marte -> marte-gpl2007-august/ |-- marte-gpl2007-august/ `-- marte-gpl2007-september 3) Check your installation with an example At this point, a working MaRTE OS environment should exist in your host. In order to check it you can compile an example from the MaRTE OS 'example/' directory. $ cd $HOME/marte/examples $ mgcc hello_world_c.c (for a C application) or $ mgnatmake hello_world.adb (for an Ada application) or $ mgcc hello_world_cpp.cpp -L$(LIB_CPP_PATH) (for C++ application) LIB_CPP_PATH is the path for libstc++.a (find /usr/lib -name libstdc++.a) The compilation and linking processes should be accomplished without any error, and the resulting application 'mprogram' should be in both, the MaRTE OS installation directory (i.e $HOME/marte) and the exported directory in 1.4) (i.e '$HOME/export'). For more information about building, running, and debugging user applications please refer to the MaRTE OS User's Guide (marte_ug.html). 4) Running the application. If you have chosen linux or linux_lib as the architecture you can run the program as any other linux application: $ cd $HOME/marte $ ./mprogram For the x86 architecture there are several ways of running the 'mprogram' we just built in the previous section. You can use your own PC by adding it to your GRUB menu, you can use an emulator or you can use a target PC. These possibilities are well explained in the tutorials section at the MaRTE OS website (http://marte.unican.es/). For example, using de QEMU emulator download a GRUB image file from the website (check the tutorial "Hello MaRTE OS using an emulator") and configure it for 'mtools' (apt-get install mtools): ~/.mtoolsrc file: drive c: file="/home/user/export/disk.img" partition=1 mtools_skip_check=1 Finally, copy the mprogram into the image file: mcopy -o mprogram c: 5) Debugging the application If you have chosen linux or linux_lib as the architecture you can debug the program as any other linux application: $ cd $HOME/marte $ mgnatmake -g hello_world.adb or $ mgcc -g hello_world_c.c $ gdb mprogram For the x86 architecture if you are using a target PC you can debug it through a Serial Port cable. Edit 'hello_world.adb' or 'hello_world_c.c', uncomment the lines labeled as "For Debugging" and recompile the program with the -g flag: $ mgnatmake -g hello_world.adb or $ mgcc -g hello_world_c.c Now your program gets blocked before displaying the hello world message. At MaRTE installation path (i.e $HOME/marte) run 'gdb': $ cd $HOME/marte $ gdb mprogram The connection with the target is performed executing the following gdb command: (gdb) target remote /dev/ttyS0 Where '/dev/ttyS0' is the device file for the serial port 1. After this you should get a message like this: Remote debugging using /dev/ttyS0 main () at hello_world.c:25 25 printf("\nHello, I'm a C program running on the MaRTE OS.\n\n"); For the x86 architecture if you are using the QEMU emulator as a target PC you can use its built-in debugging capabilities. (More in the tutorials section): qemu -s -S disk.img & ddd & target remote localhost:1234 break main cont 6) Redirecting the output messages of the application You can use the functions included in in order to switch from the standard console to the serial port or to the memory buffer driver. This is helpful when you have a lot of messages in the screen and they go so fast that you don't have time to read them. Example: put SERIAL_CONSOLE_INIT(); at the beginning of your program to redirect your messages to the serial port. If you are using QEMU emulator you can redirect again the serial port to stdio to read the messages in the terminal (with scrolling!) with the followin flag: "-serial stdio" qemu -hda disk.img -net nic,macaddr=00:0E:0C:5B:1E:28,model=rtl8139 -net socket,mcast=230.0.0.1:1234 -serial stdio References ========== [ETHERBOOT] "http://www.etherboot.org/" [GRUB] GRand Unified Bootloader. "http://www.uruk.org/grub/", "http://www.gnu.org/software/grub/". [OSKit] "http://www.cs.utah.edu/flux/oskit/". -------------------------------------------------------------------------- Contact Address: MaRTE OS Internet site: aldeam@unican.es http://marte.unican.es Department of Electronica y Computadores Group of Computadores y Tiempo Real University of Cantabria --------------------------------------------------------------------------