 |
L4Re Operating System Framework
Interface and Usage Documentation
|
|
L4Re Operating System Framework
Interface and Usage Documentation
|
Moe is the default root-task implementation for L4Re-based systems.
Moe is the first task which is usually started in L4Re-based systems. The microkernel starts Moe as the Root-Task.
Moe provides a default implementation for the basic L4Re abstractions, such as data spaces (L4Re::Dataspace), region maps (L4Re::Rm), memory allocators (L4::Factory, L4Re::Mem_alloc), name spaces (L4Re::Namespace) and so on (see L4Re Interface). These are described in the following subsections.
The factory in Moe is responsible for all kinds of dynamic object allocation.
Moe's factory allows allocation of the following objects:
L4::Factory.create() returns a create stream that allows arguments to be forwarded to the object creation in Moe.
Every factory in Moe carries a configuration that determines the physical memory the factory may hand out and the operations it is allowed to perform. The configuration of the root factory, which Moe provides to the init process, is set with the `--root-factory` command line option. The configuration of a sub-factory is provided when creating the factory.
A configuration consists of a list of physical memory regions and a set of permissions. It is described by the following arguments:
untyped=<size>@<base>, or short ut=<size>@<base>
Adds an untyped memory region. Untyped memory backs ordinary dataspace allocations of a factory. Additionally, moe's internal allocations are governed by the untyped memory of the root factory. If any regions were specified on the root factory, at least one untyped region must be present.
typed=<name>=<size>@<base>, or short t=<name>=<size>@<base>
Adds a typed memory region named <name>. Typed memory is never used for ordinary allocations. It is handed out only to clients that request it explicitly by passing type=<name> when creating a dataspace. The name must consist of alphanumeric characters only and must not be longer than 23 characters. Multiple regions may carry the same name, in which case they form a single pool.
allow=<permissions>, or short a=<permissions>
Grants permissions to the factory. <permissions> is a string built from the following characters:
This argument must be given at most once.
<size> and <base> are unsigned numbers, written either in decimal, in hexadecimal with a 0x prefix or in octal with a leading 0. Both may carry a single K, M or G suffix, which multiplies the value by 1024, 1024^2 or 1024^3 respectively.
<size> must not be zero and a region must not extend beyond the end of the physical address space. Regions carrying the same name must neither overlap nor exceed the number of 15 regions per configuration. Adjacent regions of the same name are merged.
The configuration of a sub-factory must be covered by the configuration of the factory that creates it:
If a sub-factory does not specify any memory region, it inherits the untyped regions of the creating factory. Likewise, a root factory that does not specify any memory region get's all memory of the system as untyped memory. Typed regions and permissions are never inherited implicitly.
Moe provides a name space conforming to the L4Re::Namespace interface (see Namespace. Per default Moe creates a single name space for the Boot FS. That is available as rom in the initial objects of the init process.
The Boot FS subsystem provides access to the files loaded during the platform boot (or available in ROM). These files are either linked into the boot image or loaded via a flexible boot loader, such as GRUB.
The subsystem provides an L4Re::Namespace object as directory and an L4Re::Dataspace object for each file.
By default all files are read only and visible in the namespace rom. As an option, files can be supplied with the argument :rw to mark them as writable modules. Moe will allow read and write access to these dataspaces and make them visible in a different namespace called rwfs.
An example entry in 'modules.list' would look like this:
svr
Server Capability of application. Endpoint for IPC calls
Mandatory capability.
--debug=<flags>
This option enables debug messages from Moe itself.
Multiple Flags in one string separated through '|', '+' or ','.
Possible values for <flags> are
--init=<init_process>
This options allows to set the init process binary.
String value.
Default: rom/ned
--root-factory=<config>
This option provides the configuration of the root factory, that is the physical memory regions the factory may allocate from and the permissions it holds. The value is a comma separated list of configuration arguments, see Factory configuration.
At least one untyped memory region must be specified. Note that no permission is granted implicitly, in particular allow=s is required to let the init process create L4::Scheduler proxy objects.
The option must be given at most once and is mutually exclusive with the --brk option.
Example: --root-factory=ut=256M@0x40000000,t=vram=16M@0x80000000,a=ps
If the option is not given, the root factory may allocate from the whole physical address space and holds the scheduler permission.
String value.
--l4re-dbg=<flags>
This option allows to set the debug options for the L4Re runtime environment of the init process.
Multiple Flags in one string separated through '|', '+' or ','.
Possible values for <flags> are
--ldr-flags=<flags>
This option allows setting some loader options for the L4Re runtime environment.
Multiple Flags in one string separated through '|', '+' or ','.
Possible values for <flags> are
--brk=<address>
This option is only present on systems without MMU. It restricts dynamic allocations to addresses equal or higher than <address>. Use it to prevent moe from allocating memory in regions that shall later be used by other applications or virtual machines.
This option is obsolete and only kept for backwards compatibility. Use the --root-factory option instead, which is mutually exclusive with this option.
Hexadecimal number without '0x' prefix.
-- <init_options>
All command-line parameters after the special -- option are passed directly to the init process.
Call: create(L4.Proto.Namespace)
Dataspaces can be allocated with an arbitrary size. The granularity for memory allocation however is the machine page size (L4_PAGESIZE). A dataspace user must be aware that, as a result of this page-size granularity, there may be padding memory at the end of a dataspace which is accessible to each client. Moe currently allows most dataspace operations on this padding area. Nonetheless, the client must not make any assumptions about the size or content of the padding area, as this behaviour might change in the future.
The provided data spaces can have different characteristics:
Dataspaces allocated via the Moe's factory allow mappings with any combination of the read-write-execute (RWX) rights, subject to a possible restriction of the writable right for client capabilities lacking the 'W' right.
The physical memory backing a dataspace is taken from the memory regions of the factory the dataspace is created by, see Factory configuration. By default the untyped regions of the factory are used. The optional type argument selects the typed regions of the given name instead.
Allocations can be further constrained to a range of physical addresses, as required by devices with a limited DMA addressing capability. Use L4Re::Mem_alloc::Dma_mask() to construct the flags value that restricts the allocation to physical addresses that fit into the given number of bits. Together with the L4Re::Mem_alloc::Invert_dma_mask flag the allocation is restricted to the addresses above that limit instead. Both require the Continuous flag to be set and the DMA constraints permission of the factory (see Factory configuration), otherwise the allocation is rejected with -L4_EPERM. A DMA mask of less than L4_PAGESHIFT bits is rejected with -L4_EINVAL.
Call: create(L4.Proto.Dataspace, size [, flags, align, base, type])
size
Size in bytes.
Numerical value.
flags
Special dataspace properties
Bitmap of length 4 with the single bits holding the following meaning:
align
Log2 alignment of dataspace if supported by allocator
Numerical value.
base
Physical base address of the dataspace. Only consumed if the Fixed physical Address flag is set. The requested address range must be covered by the memory regions of the factory.
Numerical value.
type
Allocate from typed memory. The argument is the string type=<name>, where <name> refers to the typed memory regions of the factory. Without this argument the dataspace is allocated from untyped memory.
String value.
Call: create(L4.Proto.Dma_space)
Call: create(L4.Proto.Rm)
The logging facility of Moe provides per application tagged and synchronized log output.
Call: create(L4.Proto.Log [, label, "color=(string|int)"])
label
Label used as prefix for the console output.
String value.
"color=(string|int)"
Color of client's output
The Value for this parameter can be one of the following:
string
Define the color by the first character of the given string
Possible values are
int
Define the color by integer.
Possible values are
Default: white
The scheduler subsystem provides a simple scheduler proxy for scheduling policy enforcement.
The priority offset provided on the creation of a scheduler proxy defines the minimum priority assigned to threads which are scheduled by that instance of the scheduler proxy. The offset is implicitly added to priorities provided to L4::Scheduler.run_thread().
Call: create(L4.Proto.Scheduler, limit, offset [, bitmap])
limit
Maximum priority.
Numerical value.
offset
Priority offset.
Numerical value.
bitmap
Bitmap of CPUs - can be repeated to address higher order CPUs
Numerical value.
Creates a sub-factory with a restricted quota and, optionally, a restricted factory configuration.
The configuration of the sub-factory must be covered by the configuration of the factory that creates it. Otherwise the creation fails with -L4_EPERM. Malformed configuration arguments are rejected with -L4_EINVAL.
If no memory region is specified, the sub-factory inherits the untyped memory regions of the creating factory. Typed memory regions and permissions are never inherited implicitly.
Call: create(L4.Proto.Factory [, quota, config])
quota
Limit in bytes. The limit is deducted from the limit of the factory that creates the new factory.
Numerical value.
config
Factory configuration argument, either untyped=<size>@<base>, typed=<name>=<size>@<base> or allow=<permissions> - can be repeated to provide multiple arguments.
String value.
1.15.0