MaRTE OS ---------- Minimal Real Time Operating System for Embedded Applications Version 1.9 - Mar 2009 Copyright (C) 2000-2009 Universidad de Cantabria, SPAIN Authors: Mario Aldea Rivas aldeam@unican.es Michael Gonzalez Harbour mgh@unican.es Installation Guide ==================== Contents ======== Requirements Installation What to do next? Requirements ============ Host Computer (required for architectures X86, Linux and Linux_Lib) - Linux with compilation environment (ie: apt-get install build-essential) - AdaCore GNAT compiler Target Computer (only required for architecture X86) - An i386 PC or above - 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. Make sure you are using the right compiler otherwise the MaRTE OS installer will complain. 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-2008 version execute: $ cd $HOME/myapps $ tar -zxvf gnat-gpl-2008-i686-gnu-linux-gnu-libc2.3-bin.tar.gz $ cd gnat-gpl-2008-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 GNAT compiler in front of your path ($ echo $PATH) and execute the following commands: $ cd $HOME $ tar -zxvf marte-version.tar.gz $ cd marte $ ./minstall 'minstall' will try to find your GNAT installation path and a make a few symbolic links. After 'minstall' has finished its work it is convenient to include the 'utils/' directory in your path in order to have direct access to MaRTE tools : $ export PATH=$PATH:$HOME/marte/utils To make this change permanent you can add the previous command to your shell startup script (i.e: $HOME/.bashrc or $HOME/.bash_profile) If you are installing a binary version of MaRTE OS you have already finished the installation. In your MaRTE directory you can find the MaRTE libraries for the three platform architectures that are currently supported: - 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) To set the active architecture use one of the following commands: $ msetcurrentarch -march linux $ msetcurrentarch -march linux_lib $ msetcurrentarch -march x86 -mproc [i386 | pi | pii] For a binary installation skip the rest of this section and jump to section 2 "Check your installation with an example". If you are installing a source distribution of MaRTE OS the following step will be to compile MaRTE OS kernel and libraries. The compilation is splitted in two parts. First you have to compile the GNAT runtime system (RTS) for your architecture: $ mkrtsmarteuc -march linux $ mkrtsmarteuc -march linux_lib $ mkrtsmarteuc -march x86 -mproc [i386 | pi | pii] Finally, you have to compile the MaRTE OS kernel: $ mkmarte -march linux $ mkmarte -march linux_lib $ mkmarte -march x86 -mproc [i386 | pi | pii] You can compile all the architectures within the same MaRTE OS installation as the object files are stored in different places. To set the current architecture use one of the following commands: $ msetcurrentarch -march linux $ msetcurrentarch -march linux_lib $ msetcurrentarch -march x86 -mproc [i386 | pi | pii] 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-13Jan2009/ |-- marte-22Aug2008/ `-- marte-13Jan2009/ 2) 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) $ mgnatmake hello_world.adb (for an Ada application) $ mg++ hello_world_cpp.cc (for a C++ application) The compilation and linking processes should be accomplished without any error, and the resulting application 'a.out' should have been created. You can use 'mgcc' with the same options as 'gcc'. For instance to set the output path and filename for the application you could use the `-o' option. $ mgcc hello_world_c.c -o /home/user/export/mprogram For more information about building, running, and debugging user applications please chech the next sections and the documentation in the MaRTE OS website (http://marte.unican.es) 3) 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: 4) 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 -o mprogram or $ mgcc -g hello_world_c.c -o mprogram $ 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 -o mprogram or $ mgcc -g hello_world_c.c -o mprogram 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 What to do next? ================ You should read the README and the "MaRTE User's Guide" (marte_ug.html) in order to get an overview of MaRTE services and usage. To know more about some extra utilities provided with MaRTE you should read the tutorial "MaRTE OS misc utilities" in the documentation section of the MaRTE OS web page (http://marte.unican.es/documentation.htm). If you want to use MaRTE OS in a cross development environment (architecture X86) read the "MaRTE OS Boot process (x86 architecture)" tutorial in the documentation section of the MaRTE OS web page. If you want to use MaRTE OS with the QEMU emulator (architecture X86) read the tutorial "Hello MaRTE OS using an emulator" tutorial in the documentation section of the MaRTE OS web page. -------------------------------------------------------------------------- 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 --------------------------------------------------------------------------