L4Re – L4 Runtime Environment

This example shows how to send IPC using the UTCB to store payload.

* (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
* Alexander Warg <warg@os.inf.tu-dresden.de>,
* Björn Döbel <doebel@os.inf.tu-dresden.de>
* economic rights: Technische Universität Dresden (Germany)
* This file is part of TUD:OS and distributed under the terms of the
* GNU General Public License 2.
* Please see the COPYING-GPL-2 file for details.
#include <l4/sys/ipc.h>
#include <l4/sys/thread.h>
#include <l4/sys/factory.h>
#include <l4/sys/utcb.h>
#include <l4/re/env.h>
#include <l4/util/thread.h>
#include <stdio.h>
#include <string.h>
static unsigned char stack2[8 << 10];
static l4_cap_idx_t thread1_cap, thread2_cap;
static void thread1(void)
int i, j;
printf("Thread1 up (%p)\n", l4_utcb());
for (i = 0; i < 10; i++)
for (j = 0; j < L4_UTCB_GENERIC_DATA_SIZE; j++)
mr->mr[j] = 'A' + (i + j) % ('~' - 'A' + 1);
if (l4_msgtag_has_error(l4_ipc_send(thread2_cap, l4_utcb(), tag, L4_IPC_NEVER)))
printf("IPC-send error\n");
unsigned i;
printf("Thread2 up (%p)\n", l4_utcb());
while (1)
if (l4_msgtag_has_error(tag = l4_ipc_receive(thread1_cap, l4_utcb(), L4_IPC_NEVER)))
printf("IPC receive error\n");
memcpy(&mr, l4_utcb_mr(), sizeof(mr));
printf("Thread2 receive (%d): ", l4_msgtag_words(tag));
for (i = 0; i < l4_msgtag_words(tag); i++)
printf("%c", (char)mr.mr[i]);
int main(void)
thread1_cap = l4re_env()->main_thread;
thread2_cap = l4re_util_cap_alloc();
if (l4_is_invalid_cap(thread2_cap))
return 1;
tag = l4_factory_create_thread(l4re_env()->factory, thread2_cap);
if (l4_error(tag))
return 1;
l4_thread_control_bind((l4_utcb_t *)l4re_env()->first_free_utcb,
tag = l4_thread_control_commit(thread2_cap);
if (l4_error(tag))
return 2;
tag = l4_thread_ex_regs(thread2_cap,
(l4_umword_t)(stack2 + sizeof(stack2)), 0);
if (l4_error(tag))
return 3;
tag = l4_scheduler_run_thread(l4re_env()->scheduler, thread2_cap, &sp);
if (l4_error(tag))
return 4;
return 0;
Capability allocator C interface.
Environment interface.
Common factory related definitions.
l4_cap_idx_t l4re_util_cap_alloc(void) L4_NOTHROW
Get free capability index at capability allocator.
l4re_env_t * l4re_env(void) L4_NOTHROW
Get L4Re initial environment.
Definition: env.h:185
unsigned long l4_umword_t
Unsigned machine word.
Definition: l4int.h:51
unsigned long l4_cap_idx_t
L4 Capability selector Type.
Definition: types.h:342
unsigned l4_is_invalid_cap(l4_cap_idx_t c) L4_NOTHROW
Test if a capability selector is the invalid capability.
Definition: types.h:392
l4_msgtag_t l4_factory_create_thread(l4_cap_idx_t factory, l4_cap_idx_t target_cap) L4_NOTHROW
Create a new thread.
Definition: factory.h:366
l4_msgtag_t l4_ipc_receive(l4_cap_idx_t object, l4_utcb_t *utcb, l4_timeout_t timeout) L4_NOTHROW
Wait for a message from a specific source.
Definition: ipc.h:505
l4_msgtag_t l4_ipc_send(l4_cap_idx_t dest, l4_utcb_t *utcb, l4_msgtag_t tag, l4_timeout_t timeout) L4_NOTHROW
Send a message to an object (do not wait for a reply).
Definition: ipc.h:488
long l4_error(l4_msgtag_t tag) L4_NOTHROW
Return error code of a system call return message tag or the tag label.
Definition: ipc.h:535
unsigned l4_msgtag_has_error(l4_msgtag_t t) L4_NOTHROW
Test for error indicator flag.
Definition: types.h:437
l4_msgtag_t l4_msgtag(long label, unsigned words, unsigned items, unsigned flags) L4_NOTHROW
Create a message tag from the specified values.
Definition: types.h:408
unsigned l4_msgtag_words(l4_msgtag_t t) L4_NOTHROW
Get the number of untyped words.
Definition: types.h:424
l4_sched_param_t l4_sched_param(unsigned prio, l4_cpu_time_t quantum=0) L4_NOTHROW
Construct scheduler parameter.
Definition: scheduler.h:221
l4_msgtag_t l4_scheduler_run_thread(l4_cap_idx_t scheduler, l4_cap_idx_t thread, l4_sched_param_t const *sp) L4_NOTHROW
Run a thread on a Scheduler.
Definition: scheduler.h:316
l4_msgtag_t l4_thread_ex_regs(l4_cap_idx_t thread, l4_addr_t ip, l4_addr_t sp, l4_umword_t flags) L4_NOTHROW
Exchange basic thread registers.
Definition: thread.h:838
void l4_thread_control_bind(l4_utcb_t *thread_utcb, l4_cap_idx_t task) L4_NOTHROW
Bind the thread to a task.
Definition: thread.h:871
l4_msgtag_t l4_thread_control_commit(l4_cap_idx_t thread) L4_NOTHROW
Commit the thread control parameters.
Definition: thread.h:889
void l4_thread_control_exc_handler(l4_cap_idx_t exc_handler) L4_NOTHROW
Set the exception handler.
Definition: thread.h:864
void l4_thread_control_start(void) L4_NOTHROW
Start a thread control API sequence.
Definition: thread.h:852
void l4_thread_control_pager(l4_cap_idx_t pager) L4_NOTHROW
Set the pager.
Definition: thread.h:858
Total number of message register (MRs) available.
Definition: utcb.h:47
l4_msg_regs_t * l4_utcb_mr(void) L4_NOTHROW L4_PURE
Get the message-register block of a UTCB.
Definition: utcb.h:352
struct l4_utcb_t l4_utcb_t
Opaque type for the UTCB.
Definition: utcb.h:67
l4_utcb_t * l4_utcb(void) L4_NOTHROW L4_PURE
Get the UTCB address.
Definition: utcb.h:340
Low-level Thread Functions.
Message tag data structure.
Definition: types.h:160
Scheduler parameter set.
Definition: scheduler.h:121
l4_cap_idx_t main_thread
Object-capability of the first user thread.
Definition: env.h:115
Encapsulation of the message-register block in the UTCB.
Definition: utcb.h:79
l4_umword_t mr[L4_UTCB_GENERIC_DATA_SIZE]
Message registers.
Definition: utcb.h:80