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 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 entry hello
  21   modaddr  0x002000000
  22   kernel   fiasco -serial_esc
  23   roottask moe rom/hello.lua
  24   module   l4re
  25   module   ned
  26   module   hello.lua
  27   module   hello
  28 \endcode
  29
  30 This file describes all the binaries and scripts to put into the ISO image,
  31 and also describes the GRUB \c menu.lst contents.  What you need to do is to
  32 set the \c make variable \c MODULE_SEARCH_PATH to contain the path to your
  33 Fiasco.OC build directory and the directory containing your \c hello.lua
  34 script.
  35
  36 The \c hello.lua script should look like the following.
  37
  38 \code
  39 require("L4");
  40 L4.default_loader:start({}, "rom/hello");
  41 \endcode
  42
  43 The first line of this script ensures that the \c L4 package is available
  44 for the script. The second line uses the default loader object defined in that
  45 package and starts the binary \c rom/hello.
  46 \note All modules defined in \c modules.list are available as data spaces
  47 (L4Re::Dataspace) and registered in a name space (L4Re::Namespace). This
  48 name space is in turn available as 'rom' to the init process
  49 (\ref l4re_servers_ned "Ned").
  50
  51
  52 Now you can go to your L4Re build directory and run the following command.
  53 \note The example assumes that you have created the \c modules.list and \c
  54       hello.lua files in the /tmp directory. Adapt if you created them
  55       somewhere else.
  56
  57 \code
  58 make grub1iso E=hello MODULES_LIST=/tmp/modules.list MODULE_SEARCH_PATH=/tmp:<path_to_fiasco_builddir>
  59 \endcode
  60
  61 Or as an alternative use GRUB 2:
  62
  63 \code
  64 make grub2iso E=hello MODULES_LIST=/tmp/modules.list MODULE_SEARCH_PATH=/tmp:<path_to_fiasco_builddir>
  65 \endcode
  66
  67 Now you should be able to boot the image in QEMU by running:
  68
  69 \code
  70 qemu -cdrom images/hello.iso -serial stdio
  71 \endcode
  72
  73 If you press <ESC> in the terminal that shows you the serial output you
  74 enter the Fiasco.OC kernel debugger... Have fun.
  75
  76
  77 \subpage Customizations
  78
  79 A basic set of bootable entries can be found in \c l4/conf/modules.list. This file
  80 is the default for any image creation as shown above. Local modifications can be done in a
  81 \c Makeconf.local file located in the \c l4 directory. Put the \c MODULES_LIST and
  82 \c MODULE_SEARCH_PATH definitions there to have them always set. A \c make call
  83 is then reduced to:
  84
  85 \code
  86 make grub2iso E=hello
  87 \endcode
  88
  89
  90
  91 */