1// vi:ft=c 2/** 3 * \page l4re_servers_moe Moe, the Root-Task 4 * 5 * Moe is the default root-task implementation for L4Re-based systems. 6 * 7 * \em Moe is the first task which is usually started in L4Re-based systems. 8 * The micro kernel starts \em Moe as the Root-Task. 9 * 10 * 11 * \section l4re_moe_objects Moe objects 12 * 13 * Moe provides a default implementation for the basic L4Re abstractions, such as 14 * data spaces (L4Re::Dataspace), region maps (L4Re::Rm), memory allocators 15 * (L4::Factory, L4Re::Mem_alloc), name spaces (L4Re::Namespace) and so on 16 * (see \link api_l4re L4Re Interface\endlink). These are described in the 17 * following subsections. 18 * 19 * \subsection l4re_moe_factory Factory 20 * 21 * The factory in Moe is responsible for all kinds of dynamic object 22 * allocation. 23 * 24 * Moe's factory allows allocation of the following objects: 25 * - L4Re::Namespace 26 * - L4Re::Dataspace, RAM allocation 27 * - L4Re::Dma_space, memory management for DMA-capable devices 28 * - L4Re::Rm, virtual memory management for application tasks 29 * - L4::Vcon (output only) 30 * - L4::Scheduler, to provide a restricted priority / CPU range for clients 31 * - L4::Factory, to provide a quota limited allocation for clients 32 * 33 * \note L4::Scheduler objects can be only created through the user factory 34 * provided by Moe to the initial application. Other factory instances 35 * cannot create this object. 36 * 37 * \subsubsection l4re_moe_memory_alloc_factory Passing parameters to the create stream 38 * 39 * L4::Factory.create() returns a [create stream](\ref L4::Factory::S) that 40 * allows arguments to be forwarded to the the object creation in Moe. 41 * 42 * Objects that support additional parameters on their creation are presented 43 * next with a non-empty list of parameters. The parameters are listed in the 44 * order they should be provided to a create stream. Optional parameters are 45 * identified by their default values. Multiple entries in the next list 46 * denote different ways of initializing an object. 47 * 48 * - L4Re::Namespace `()` 49 * - For more details see \ref l4re_moe_names 50 * - L4Re::Dataspace `(l4_mword_t size, l4_umword_t flags = 0, 51 l4_umword_t align = 0)` 52 * - Argument `size`: size in bytes (mandatory) 53 * - Argument `flags`: special dataspace properties, see 54 * #L4Re::Mem_alloc::Mem_alloc_flags 55 * - Argument `align`: Log2 alignment of dataspace if supported by allocator 56 * - See detailed description of the parameters in L4Re::Mem_alloc::alloc() 57 * - For details on the types of dataspaces provided by Moe, see 58 * \ref l4re_moe_dataspace 59 * - L4Re::Dma_space `()` 60 * - For more details see \ref l4re_moe_dma_space 61 * - L4Re::Rm `()` 62 * - For more details see \ref l4re_moe_rm 63 * - L4::Vcon `(char const *label, l4_mword_t color = 7)` 64 * - Argument `label`: label used as prefix for the console output 65 * - Argument `color`: color code `0..15` 66 * - For more details see \ref l4re_moe_log 67 * - L4::Vcon `(char const *label, char const *color = "w")` 68 * - Argument `label`: label used as prefix for the console output 69 * - Argument `color`: color code 70 * - The color is identified by a single character 71 * - Supported colors: `N`, `n`, `R`, `r`, `G`, `g`, `Y`, `y`, `B`, `b`, 72 `M`, `m`, `C`, `c`, `W`, `w` 73 * - For more details see \ref l4re_moe_log 74 * - L4::Scheduler `(l4_mword_t limit, l4_mword_t offset, 75 l4_umword_t bitmap = ~0UL)` 76 * - Argument `limit`: maximum priority 77 * - Argument `offset`: priority offset 78 * - Argument `bitmap`: bitmap of CPUs 79 * - Argument `limit` must be greater than `offset` 80 * - For more details see \ref l4re_moe_scheduler 81 * - L4::Factory `(l4_mword_t quota)` 82 * - Argument `quota`: limit in bytes (not zero) 83 * - The limit is deducted from the limit of the factory that creates 84 * the new factory 85 * 86 * \subsection l4re_moe_names Namespace 87 * 88 * Moe provides a name space conforming to the L4Re::Namespace 89 * interface (see \ref api_l4re_namespace). Per default Moe creates a single 90 * name space for the \ref l4re_moe_bootfs. That is available as \c rom 91 * in the initial objects of the init process. 92 * 93 * \subsubsection l4re_moe_bootfs Boot FS 94 * 95 * The Boot FS subsystem provides access to the files loaded 96 * during the platform boot (or available in ROM). These files are either 97 * linked into the boot image or loaded via a flexible boot loader, 98 * such as GRUB. 99 * 100 * The subsystem provides an L4Re::Namespace object as directory and an 101 * L4Re::Dataspace object for each file. 102 * 103 * By default all files are read only and visible in the namespace \em 104 * `rom`. As an option, files can be supplied with the argument `:rw` to mark 105 * them as writable modules. Moe will allow read and write access to these 106 * dataspaces and make them visible in a different namespace called \em `rwfs`. 107 * 108 * An example entry in 'modules.list' would look like this: 109 * 110 * ~~~~~~~~~~~~~~~~~~~~~~ 111 * module somemodule :rw 112 * ~~~~~~~~~~~~~~~~~~~~~~ 113 * 114 * \note In order for a client to receive write permissions to the dataspace, 115 * the corresponding cap also needs write permissions. 116 * 117 * \subsection l4re_moe_dataspace Dataspace 118 * 119 * Dataspaces can be allocated with an arbitrary size. The granularity 120 * for memory allocation however is the machine page size (#L4_PAGESIZE). 121 * A dataspace user must be aware that, as a result of this page-size 122 * granularity, there may be padding memory at the end of a dataspace 123 * which is accessible to each client. Moe currently allows most dataspace 124 * operations on this padding area. Nonetheless, the client must not make any 125 * assumptions about the size or content of the padding area, as this 126 * behaviour might change in the future. 127 * 128 * The provided data spaces can have different characteristics: 129 * - Physically contiguous and pre-allocated 130 * - Non contiguous and on-demand allocated with possible copy on write (COW) 131 * 132 * \subsection l4re_moe_log Log Subsystem 133 * 134 * The logging facility of Moe provides per application tagged and 135 * synchronized log output. 136 * 137 * \subsection l4re_moe_dma_space DMA Space 138 * 139 * \subsection l4re_moe_scheduler Scheduler subsystem 140 * 141 * The scheduler subsystem provides a simple scheduler proxy for scheduling 142 * policy enforcement. 143 * 144 * The priority offset provided on the creation of a scheduler proxy defines 145 * the minimum priority assigned to threads which are scheduled by that 146 * instance of the scheduler proxy. The offset is implicitly added to priorities 147 * provided to L4::Scheduler.run_thread(). 148 * 149 * \subsection l4re_moe_rm Region Map 150 * 151 * \section l4re_moe_options Command Line Options 152 * 153 * Moe's command-line syntax is: 154 * 155 * moe [--debug=<flags>] [--init=<binary>] [--l4re-dbg=<flags>] [--ldr-flags=<flags>] [-- <init options>] 156 * 157 * \par `--debug=<debug flags>` 158 * This option enables debug messages from Moe itself, the `<debug flags>` 159 * values are a combination of `info`, `warn`, `boot`, `server`, `loader`, 160 * `exceptions`, and `ns` (or `all` for full verbosity). 161 * 162 * \par `--init=<init process>` 163 * This options allows to override the default init process binary, which is 164 * 'rom/ned'. 165 * 166 * \par `--l4re-dbg=<debug flags>` 167 * This option allows to set the debug options for the L4Re runtime environment 168 * of the init process. The flags are the same as for `--debug=`. 169 * 170 * \par `--ldr-flags=<loader flags>` 171 * This option allows setting some loader options for the L4Re runtime 172 * environment. The flags are `pre_alloc`, `all_segs_cow`,and `pinned_segs`. 173 * 174 * \par `-- <init options>` 175 * All command-line parameters after the special `--` option are passed 176 * directly to the init process. 177 */ 178