L4 Thread Library Reference Manual

Contents

• Introduction
• Usage / Library Configuration
• User API reference
  • Create new threads
  • Exit / shutdown threads
  • Priority management
  • Thread sleep
  • Thread data
  • Miscellaneous
  • Thread library configuration and initialization
• Examples
  • Simple thread creation
  • Syncronous thread creation / startup return data
  • Thread creation, long version
  • Thread shutdown / exit functions
  • Thread local data
  • Library configuration

Introduction

The L4 Thread Library (l4thread) encapsulates native L4 threads and provides a basic abstraction to the thread related system call interface of the L4 microkernel. It provides functionality to ease the usage of threads, this includes:

Thread creation / shutdown

L4thread provides functions to create and shutdown L4 threads. Threads can register exit handlers, which will be executed during the shutdown of the thread.

Stack allocation

The allocation of stacks for new threads can be done internally by l4thread. For special purposes the application can provide its own stack. By having an own stack management l4thread can implement some optimizations, e.g. it uses a stack placement which allows the calculation of the thread id from the stack pointer of a thread, this speeds up the access to the thread management structures.

Basic priority handling

L4thread includes function to set/request the L4 priority of threads.

Thread data management

Threads can have private data (void pointers) assigned to them. To avoid conflicts e.g. by various libraries accessing that private data, l4thread supports serveral data pointers, referenced by data keys. Libraries can allocate a data key and use it to exclusively access the data pointer assigned to that key.

The intention of l4thread is not to compete with other thread libraries (like pthreads), it should rather provide a basis to implement other high-level thread packages without the need to care for too much L4 details.

Usage / Library Configuration

To use the L4 Thread Library you need to include the file <l4/thread/thread.h> and link libthread.a to the binary. L4thread depends on other L4Env libraries, namely l4env, the Region Mapper l4rm, the Memory Dataspace Manager dm_mem and the Logserver log.

The L4 Thread Library is usually initialized by the L4Env startup code during the setup of a new task, the application does not need to do anything. Therefore the configuration of l4thread works a bit different, since there is no initialization function which can be used to set configuration values. Instead, l4thread can be configured redefining some symbols which are weakly defined in l4thread. These parameters can be configured:

Maximum number of threads (l4thread_max_threads)

Max. number of threads l4thread can manage. This mainly affects how much memory is allocated by l4thread for internal thread descriptors, each thread descriptor needs about 128 Bytes. Default is 16.

Default stack size (l4thread_stack_size)

Default stack size for new threads. Default is 64 KB.

Maximum stack size (l4thread_max_stack)

Max. stack size for new threads. This value is required for the optimized stack placement described above, it affects how much virtual memory is reserved to arrange stacks (l4thread_max_stack times l4thread_max_threads). Threads can be created with a larger stack size, but they will not benefit from the described optimizations. Default is 1 MB.

Default priority (l4thread_default_prio)

Default priority for new threads, default is to use the priority of the initial thread.

Stack map area (l4thread_stack_area_addr)

Start address of the virtual memory area used to map the stacks of new threads. Default is to ask the Region Mapper to find a suitable map area. Note that the map area must be big enough to hold the stacks of all threads (specified by l4thread_max_threads and l4thread_max_stack) and that the start address must be aligned to the maximum stack size (l4thread_max_stack).

TCB table map address (l4thread_tcb_table_addr)

Start address of the virtual memory area used to map the thread control blocks (TBC). The map area must be big enough to hold the TCBs of all threads (the size of a TCB is about 128 byte, the number of threads is specified by l4thread_max_threads) and the start address must be page-aligned.

See the User API reference for a description of the l4thread functions.