L4 Roottask Reference Manual

Introduction

Roottask is a simple system resource manager for the L4 microkernel. It also functions as an easy-to-use system bootstrapper. It is invoked at boot time from a boot loader (see Booting ).

Roottask acts as a pager for the tasks it starts. It emulates the sigma0 protocol for them (L4 Reference Manual, Appendix B). Moreover, it manages the following system resources: main memory, irq lines and L4 task numbers. Client tasks can request access to these resources using a proprietary protocol, the supervisor protocol (see Rmgr_api ).

Usage

Roottask can be configured by specifying configuration directives either on the command line or in a configuration file. Which alternative is used depends on the following command line argument:

-[no]symbols

Use the module loaded next after Sigma0 as symbol table for Fiasco.

-[no]lines

Use the module loaded next after Symbols (or Sigma0 if no Symbols) as Lines table for Fiasco.

-configfile

Use the configuration file loaded as the first boot module after the L4 kernel (and after Sigma0, if -sigma0 is also used) to find configuration directives.

If this parameter is not specified, configuration directives are taken directly from the command line instead.

-nopentium

Assume we are running on L4 486 even if we actually run on L4/Pentium.

RMGR tries to detect the L4 version during startup to find out about the services the L4 kernel and its servers provide. At the moment the only difference that must be handled is the 4MB page extension of L4/Pentium. All other L4/Pentium specific features are no-ops at L4/486 and therefore don't need any special treatment. If we use L4/pentium but want to be able to simulate L4/486 within respect to 4MB page tables, -nopentium forces RMGR to think it is running on L4/486.

-quiet

Hush.

-verbose

Print verbose output while processing modules.

-memdump

Dump the memory (regions and owners) after startup.

See section Configuration for information on configuration directives.

Booting

Roottask is compatible with the Multiboot standard proposal. It should be started as a boot kernel using a Multiboot-compliant boot loader like GRUB. The L4 μ -kernel should be loaded as the first boot module, and the Rottask config file (if required) as the second boot module. Any boot servers intended to be started by Roottask at boot time should be loaded as further boot modules.

Here is a sample GRUB configuration file (menu.lst) which accomplishes this:

# Bootstrap is the kernel and straps all modules
kernel= (fd0)/bootstrap -serial
# L4 must be the first boot module
module= (fd0)/fiasco
# Sigma0 must come after L4 (as 2nd module)
module= (fd0)/sigma0
# Now its time for roottask
module= (fd0)/roottask 
# Here, the actual programs may start
module= (fd0)/pingpong

After having been loaded in this way, the boot loader will first activate an bootstrap initialization routine which first initializes L4's boot configuration table according to section 2.9 of the L4 Reference Manual. (This renders previous methods of patching the boot table before booting in the boot image on disk obsolete.) Roottask makes sure it will be the first user task running under L4 (the booter task or root task in L4-speak).

Once running under L4, Roottasl parses its configuration data (if supplied) and then starts the executable images loaded as further boot modules as child tasks.

Except for the Roottask configuration file (and modules intended to be passed to sub-tasks as parameters), all boot modules (including the L4 μ -kernel) must be ELF binaries linked to the absolute RAM address they should be loaded into. They don't have to be multiboot-compliant (Roottask doesn't interpret multiboot data structures imbedded into them) but they will be started in a multiboot-compliant way, enabling them to make use of a multiboot_info data structure containing a command line, the machine's RAM size, and a list of multiboot modules (loaded by the boot loader and passed on by RMGR using the module option described below).

Configuration

The configuration data can be specified on RMGR's command line or in a configuration file (see Usage).

When using a configuration file, the first line of the file should contain only the following text:

#!rmgr

#!roottask

In the configuration text, whitespace and newlines are ignored, as is text between the comment character, "#", and the end of the line. Here is the configuration syntax:

file := [ globalconstraint ] rule*

globalconstraint := log_mcp number 
	| boot_mcp number 
	| boot_prio number

rule := taskspec constraint* modules
	| smallsizerule
	| flag

smallsizerule := small_space_size number

flag := bootwait
	| debug
	| debug_log log_options 

log_options := number number
	     | verbose_option+

verbose_option: task_proto
	     | task_alloc
	     | task_get
	     | task_free
	     | task_create
	     | task_delete
	     | task_create_with_prio	
	     | mem_proto
	     | mem_free
	     | mem_free_fp
	     | irq_proto
	     | irq_get
	     | irq_free
	     | rmgr_proto
	     | rmgr_rmgr_ping
	     | log
	     | kdeug

modules := module*
	| attached number modules

module := module ( modname string )*

taskspec := task
	| task modname string
	| task rmgr
	| task sigma0
	| task number

constraint := child numconstraint+
	| memory numconstraint+
	| high_memory numconstraint+
	| mem_offset number
	| irq ( numconstraint+ | mask number )
	| smallL numconstraint+
	| log_mcp number
	| boot_mcp number
	| boot_prio number
	| boot_small number
	| allow_cli

numconstraint := max number
	| in [ number , number ]

number := 0x [0-9a-fA-F]+ | [0-9]+

The configuration text consists of a sequence of directives.

The sequence of task directives corresponds to the sequence of bootstrap tasks loaded as boot modules. Alternatively, the modname parameter can be used to select a module by its name: It selects the first module containign string in the "module=" specification. The task directive can also be qualified by an explicit task number or by one of the task specifiers rmgr or sigma0.

For each task, directives can be given to constrain the set of system resources the task can request from Roottask. For subtasks (child) and memory, these constraints are the maximal number of units that can be acquired and the numeric range the units must be part of. For IRQ lines, it is additionally possible to specify a mask which exactly defines which IRQs can be requested. Also, certain bootstrap parameters can be specified.

All constraints specified for a given resource type are logically AND'd, i.e., all constraints must be true for a resource address to be requestable for the corresponding task.

Tasks can also be passed a list of multiboot modules, to be specified using one or more module options.

The small_space_size directive defines the minimal size of the system's small address spaces. If not specified, the system will run with only large address spaces.

The bootwait directive can be used to cause Roottask to pause before actually starting to serve the bootstrapped tasks. It can be used to review the console messages printed by Roottask before they scroll off the screen.

The verbose, debug, and debug_log directives can be used to modify Roottask's logging and debugging behaviour: verbose enables logging of all run-time error messages to the console, debug enables an invokation of the L4 kernel debugger on run-time errors, and debug_log allows to define which protocol should be logged. For further information, UTSL.

Strings are "- or '-separated literals (which cannot contain the separation character). Numbers can be given in decimal, hexadecimal or octal format (using C syntax).

Here is an example configuration file:

#!roottask

task modname "glinux"
child max 512 in [10, 531]
memory max 0x01000000 in [0, 0x01000000]
irq mask 0xffffffe7

Bugs

Currently, I/O flexpages cannot be constrained.

This manual page:

should explain what state is managed for each resource type