l4/doc/source/getting_started.dox

   1 /**
   2
   3 \page l4re_getting_started Getting Started
   4
   5 Here you can find the first steps to boot a very simple setup.  The setup
   6 consists of the following components:
   7 \li Fiasco.OC --- Microkernel
   8 \li Sigma0 --- Root Pager
   9 \li Moe --- Root Task
  10 \li Ned --- Init Process
  11 \li hello --- Hello World Application
  12
  13 The guide assumes that you already compiled the base components and describes
  14 how to generate an ISO image, with GRUB 1 or GRUB 2 as a boot loader, that
  15 can for example be booted within QEMU.
  16
  17 First you need a \c modules.list file that contains an entry for the scenario.
  18
  19 \code
  20 modaddr  0x002000000
  21
  22 entry hello
  23   kernel   fiasco -serial_esc
  24   roottask moe rom/hello.cfg
  25   module   l4re
  26   module   ned
  27   module   hello.cfg
  28   module   hello
  29 \endcode
  30
  31 This file describes all the binaries and scripts to put into the ISO image,
  32 and also describes the GRUB \c menu.lst contents.  What you need to do is to
  33 set the \c make variable \c MODULE_SEARCH_PATH to contain the path to your
  34 Fiasco.OC build directory and the directory containing your \c hello.cfg
  35 script.
  36
  37 The \c hello.cfg script should look like the following. A ready to use
  38 version can be found in l4/conf/examples.
  39
  40 \code
  41 require("L4");
  42 L4.default_loader:start({}, "rom/hello");
  43 \endcode
  44
  45 The first line of this script ensures that the \c L4 package is available
  46 for the script. The second line uses the default loader object defined in that
  47 package and starts the binary \c rom/hello.
  48 \note All modules defined in \c modules.list are available as data spaces
  49 (L4Re::Dataspace) and registered in a name space (L4Re::Namespace). This
  50 name space is in turn available as 'rom' to the init process
  51 (\ref l4re_servers_ned "Ned").
  52
  53
  54 Now you can go to your L4Re build directory and run the following command.
  55 \note The example assumes that you have created the \c modules.list and \c
  56       hello.cfg files in the /tmp directory. Adapt if you created them
  57       somewhere else.
  58
  59 \code
  60 make grub1iso E=hello MODULES_LIST=/tmp/modules.list MODULE_SEARCH_PATH=/tmp:<path_to_fiasco_builddir>
  61 \endcode
  62
  63 Or as an alternative use GRUB 2:
  64
  65 \code
  66 make grub2iso E=hello MODULES_LIST=/tmp/modules.list MODULE_SEARCH_PATH=/tmp:<path_to_fiasco_builddir>
  67 \endcode
  68
  69 Now you should be able to boot the image in QEMU by running:
  70
  71 \code
  72 qemu -cdrom images/hello.iso -serial stdio
  73 \endcode
  74
  75 If you press <ESC> in the terminal that shows you the serial output you
  76 enter the Fiasco.OC kernel debugger... Have fun.
  77
  78
  79 \subpage Customizations
  80
  81 A basic set of bootable entries can be found in \c l4/conf/modules.list. This file
  82 is the default for any image creation as shown above. It is recommeded that
  83 local modification regarding image creation are done in
  84 \c conf/Makeconf.boot. Initially you may copy \c Makeconf.boot.example to
  85 \c Makeconf.boot. You can overwrite \c MODULES_LIST to set your own
  86 modules-list file. Set \c MODULE_SEARCH_PATH to your setup according to the
  87 examples given in the file.
  88 When configured a \c make call is reduced to:
  89
  90 \code
  91 make grub2iso E=hello
  92 \endcode
  93
  94
  95 All other local configuration can be done in a
  96 \c Makeconf.local file located in the \c l4 directory.
  97
  98 */