L4Re - L4 Runtime Environment
Object Invocation

API for L4 object invocation. More...

+ Collaboration diagram for Object Invocation:

Modules

 Error Handling
 Error handling for L4 object invocation.
 
 Message Items
 Message item related functions.
 
 Message Tag
 API related to the message tag data type.
 
 Realtime API
 
 Timeouts
 All kinds of timeouts and time related functions.
 
 Virtual Registers (UTCBs)
 L4 Virtual Registers (UTCB).
 

Files

file  utcb.h
 UTCB definitions.
 

Enumerations

enum  l4_syscall_flags_t {
  L4_SYSF_NONE, L4_SYSF_SEND, L4_SYSF_RECV, L4_SYSF_OPEN_WAIT,
  L4_SYSF_REPLY, L4_SYSF_CALL, L4_SYSF_WAIT, L4_SYSF_SEND_AND_WAIT,
  L4_SYSF_REPLY_AND_WAIT
}
 Capability selector flags. More...
 

Functions

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). More...
 
l4_msgtag_t l4_ipc_wait (l4_utcb_t *utcb, l4_umword_t *label, l4_timeout_t timeout) L4_NOTHROW
 Wait for an incoming message from any possible sender. More...
 
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. More...
 
l4_msgtag_t l4_ipc_call (l4_cap_idx_t object, l4_utcb_t *utcb, l4_msgtag_t tag, l4_timeout_t timeout) L4_NOTHROW
 Object call (usual invocation). More...
 
l4_msgtag_t l4_ipc_reply_and_wait (l4_utcb_t *utcb, l4_msgtag_t tag, l4_umword_t *label, l4_timeout_t timeout) L4_NOTHROW
 Reply and wait operation (uses the reply capability). More...
 
l4_msgtag_t l4_ipc_send_and_wait (l4_cap_idx_t dest, l4_utcb_t *utcb, l4_msgtag_t tag, l4_umword_t *label, l4_timeout_t timeout) L4_NOTHROW
 Send a message and do an open wait. More...
 
L4_ALWAYS_INLINE l4_msgtag_t l4_ipc (l4_cap_idx_t dest, l4_utcb_t *utcb, l4_umword_t flags, l4_umword_t slabel, l4_msgtag_t tag, l4_umword_t *rlabel, l4_timeout_t timeout) L4_NOTHROW
 Generic L4 object invocation. More...
 
l4_msgtag_t l4_ipc_sleep (l4_timeout_t timeout) L4_NOTHROW
 Sleep for an amount of time. More...
 
int l4_sndfpage_add (l4_fpage_t const snd_fpage, unsigned long snd_base, l4_msgtag_t *tag) L4_NOTHROW
 Add a flex-page to be sent to the UTCB. More...
 

Detailed Description

API for L4 object invocation.

Include File
#include <l4/sys/ipc.h>

General abstractions for L4 object invocation. The basic principle is that all objects are denoted by a capability that is accessed via a capability selector (see Capabilities ).

This set of functions is common to all kinds of objects provided by the L4 micro kernel. The concrete semantics of an invocation depends on the object that shall be invoked.

Objects may be invoked in various ways, the most common way is to use a call operation (l4_ipc_call()). However, there are a lot more flavours available that have a semantics depending on the object.

See also
IPC-Gate API

Enumeration Type Documentation

◆ l4_syscall_flags_t

Capability selector flags.

These flags determine the concrete operation when a kernel object is invoked.

Enumerator
L4_SYSF_NONE 

Default flags (call to a kernel object).

Using this value as flags in the capability selector for an invocation indicates a call (send and wait for a reply).

L4_SYSF_SEND 

Send-phase flag.

Setting this flag in a capability selector induces a send phase, this means a message is send to the object denoted by the capability. For receive phase see L4_SYSF_RECV.

L4_SYSF_RECV 

Receive-phase flag.

Setting this flag in a capability selector induces a receive phase, this means the invoking thread waits for a message from the object denoted by the capability. For a send phase see L4_SYSF_SEND.

L4_SYSF_OPEN_WAIT 

Open-wait flag.

This flag indicates that the receive operation (see L4_SYSF_RECV) shall be an open wait. Open wait means that the invoking thread shall wait for a message from any possible sender and not from the sender denoted by the capability.

L4_SYSF_REPLY 

Reply flag.

This flag indicates that the send phase shall use the in-kernel reply capability instead of the capability denoted by the selector index.

L4_SYSF_CALL 

Call flags (combines send and receive).

Combines L4_SYSF_SEND and L4_SYSF_RECV.

L4_SYSF_WAIT 

Wait flags (combines receive and open wait).

Combines L4_SYSF_RECV and L4_SYSF_OPEN_WAIT.

L4_SYSF_SEND_AND_WAIT 

Send-and-wait flags.

Combines L4_SYSF_SEND and L4_SYSF_WAIT.

L4_SYSF_REPLY_AND_WAIT 

Reply-and-wait flags.

Combines L4_SYSF_SEND, L4_SYSF_REPLY, and L4_SYSF_WAIT.

Definition at line 39 of file consts.h.

Function Documentation

◆ l4_ipc()

L4_ALWAYS_INLINE l4_msgtag_t l4_ipc ( l4_cap_idx_t  dest,
l4_utcb_t utcb,
l4_umword_t  flags,
l4_umword_t  slabel,
l4_msgtag_t  tag,
l4_umword_t rlabel,
l4_timeout_t  timeout 
)
inline

Generic L4 object invocation.

Parameters
destDestination object.
utcbUTCB of the caller.
flagsInvocation flags (see l4_syscall_flags_t).
slabelSend label if applicable (may be seen by the receiver).
tagSending message tag.
[out]rlabelReceiving label.
timeoutTimeout pair (see l4_timeout_t).
Returns
return tag

Definition at line 34 of file ipc.h.

Referenced by l4_ipc_call(), l4_ipc_receive(), l4_ipc_reply_and_wait(), l4_ipc_send(), l4_ipc_send_and_wait(), and l4_ipc_wait().

+ Here is the caller graph for this function:

◆ l4_ipc_call()

l4_msgtag_t l4_ipc_call ( l4_cap_idx_t  object,
l4_utcb_t utcb,
l4_msgtag_t  tag,
l4_timeout_t  timeout 
)
inline

Object call (usual invocation).

Parameters
objectCapability selector for the object to call.
utcbUTCB of the caller.
tagMessage tag to describe the message to be sent.
timeoutTimeout pair for send an receive phase (see l4_timeout_t).
Returns
result tag

A message is sent to the object and the invoker waits for a reply from the object. Messages from other sources are not accepted.

Note
The send-to-receive transition needs no time, the object can reply with a send timeout of zero.
Examples:
examples/sys/aliens/main.c, examples/sys/ipc/ipc_example.c, and examples/sys/singlestep/main.c.

Definition at line 445 of file ipc.h.

References l4_ipc(), and L4_SYSF_CALL.

Referenced by l4util_ioport_map().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ l4_ipc_receive()

l4_msgtag_t l4_ipc_receive ( l4_cap_idx_t  object,
l4_utcb_t utcb,
l4_timeout_t  timeout 
)
inline

Wait for a message from a specific source.

Parameters
objectObject to receive a message from.
timeoutTimeout pair (see l4_timeout_t, only the receive part matters).
utcbUTCB of the caller.
Returns
result tag.

This operation waits for a message from the specified object. Messages from other sources are not accepted by this operation. The operation does not include a send phase, this means no message is sent to the object.

Note
This operation is usually used to receive messages from a specific IRQ or thread. However, it is not common to use this operation for normal applications.
Examples:
examples/sys/aliens/main.c, examples/sys/singlestep/main.c, examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 487 of file ipc.h.

References l4_ipc(), L4_SYSF_RECV, and l4_msgtag_t::raw.

Referenced by l4_ipc_sleep(), and l4_thread_yield().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ l4_ipc_reply_and_wait()

l4_msgtag_t l4_ipc_reply_and_wait ( l4_utcb_t utcb,
l4_msgtag_t  tag,
l4_umword_t label,
l4_timeout_t  timeout 
)
inline

Reply and wait operation (uses the reply capability).

Parameters
tagDescribes the message to be sent as reply.
utcbUTCB of the caller.
[out]labelLabel assigned to the source object of the received message.
timeoutTimeout pair (see l4_timeout_t).
Returns
result tag

A message is sent to the previous caller using the implicit reply capability. Afterwards the invoking thread waits for a message from any source.

Note
This is the standard server operation: it sends a reply to the actual client and waits for the next incoming request, which may come from any other client.
Examples:
examples/sys/ipc/ipc_example.c.

Definition at line 453 of file ipc.h.

References L4_INVALID_CAP, l4_ipc(), and L4_SYSF_REPLY_AND_WAIT.

+ Here is the call graph for this function:

◆ l4_ipc_send()

l4_msgtag_t l4_ipc_send ( l4_cap_idx_t  dest,
l4_utcb_t utcb,
l4_msgtag_t  tag,
l4_timeout_t  timeout 
)
inline

Send a message to an object (do not wait for a reply).

Parameters
destCapability selector for the destination object.
utcbUTCB of the caller.
tagDescriptor for the message to be sent.
timeoutTimeout pair (see l4_timeout_t) only send part is relevant.
Returns
result tag

A message is sent to the destination object. There is no receive phase included. The invoker continues working after sending the message.

Attention
This is a special-purpose message transfer, objects usually support only invocation via l4_ipc_call().
Examples:
examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 470 of file ipc.h.

References l4_ipc(), and L4_SYSF_SEND.

Referenced by l4_irq_trigger_u().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ l4_ipc_send_and_wait()

l4_msgtag_t l4_ipc_send_and_wait ( l4_cap_idx_t  dest,
l4_utcb_t utcb,
l4_msgtag_t  tag,
l4_umword_t label,
l4_timeout_t  timeout 
)
inline

Send a message and do an open wait.

Parameters
destObject to send a message to.
utcbUTCB of the caller.
tagDescribes the message that shall be sent.
[out]labelLabel assigned to the source object of the receive phase.
timeoutTimeout pair (see l4_timeout_t).
Returns
result tag

A message is sent to the destination object and the invoking thread waits for a reply from any source.

Note
This is a special-purpose operation and shall not be used in general applications.

Definition at line 461 of file ipc.h.

References l4_ipc(), and L4_SYSF_SEND_AND_WAIT.

+ Here is the call graph for this function:

◆ l4_ipc_sleep()

l4_msgtag_t l4_ipc_sleep ( l4_timeout_t  timeout)
inline

Sleep for an amount of time.

Parameters
timeoutTimeout pair (see l4_timeout_t, the receive part matters).
Returns
error code:

The invoking thread waits until the timeout is expired or the wait was aborted by another thread by l4_thread_ex_regs().

Definition at line 496 of file ipc.h.

References L4_INVALID_CAP, and l4_ipc_receive().

Referenced by l4_sleep_forever().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ l4_ipc_wait()

l4_msgtag_t l4_ipc_wait ( l4_utcb_t utcb,
l4_umword_t label,
l4_timeout_t  timeout 
)
inline

Wait for an incoming message from any possible sender.

Parameters
utcbUTCB of the caller.
Return values
labelLabel assigned to the source object (IPC gate or IRQ).
Parameters
timeoutTimeout pair (see l4_timeout_t, only the receive part is used).
Returns
return tag

This operation does an open wait, and therefore needs no capability to denote the possible source of a message. This means the calling thread waits for an incoming message from any possible source. There is no send phase included in this operation.

The usual usage of this function is to call that function when entering a server loop in a user-level server that implements user-level objects, see also l4_ipc_reply_and_wait().

Examples:
examples/sys/ipc/ipc_example.c.

Definition at line 478 of file ipc.h.

References L4_INVALID_CAP, l4_ipc(), L4_SYSF_WAIT, and l4_msgtag_t::raw.

Referenced by l4vcpu_irq_disable_save().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ l4_sndfpage_add()

int l4_sndfpage_add ( l4_fpage_t const  snd_fpage,
unsigned long  snd_base,
l4_msgtag_t tag 
)
inline

Add a flex-page to be sent to the UTCB.

Parameters
snd_fpageFlex-page.
snd_baseSend base.
tagTag to be modified.
Return values
tagModified tag, the number of items will be increased, all other values in the tag will be retained.
Returns
0 on success, negative error code otherwise

Definition at line 556 of file ipc.h.