L4Re Operating System Framework
Interface and Usage Documentation
Loading...
Searching...
No Matches
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).
 
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.
 
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.
 
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).
 
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).
 
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.
 
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.
 
l4_msgtag_t l4_ipc_sleep (l4_timeout_t timeout) L4_NOTHROW
 Sleep for an amount of time.
 
l4_msgtag_t l4_ipc_sleep_ms (l4_uint32_t ms) L4_NOTHROW
 Sleep for a certain amount of milliseconds.
 
l4_msgtag_t l4_ipc_sleep_us (l4_uint64_t us) L4_NOTHROW
 Sleep for a certain amount of microseconds.
 
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.
 

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
L4 Inter-Process Communication (IPC)

Timeouts during IPC

IPC operation between two communication partners may consist of up to two phases (send phase and receive phase). For both phases, a timeout may be specified (send timeout and receive timeout).

Note
When IPC communication happens across CPU cores and a timeout is specified, then the counting of the timeout only begins after the target thread has been scheduled at least once. In particular, this means that an IPC timeout, including a timeout of zero, may be delayed depending on the scheduling on the target CPU core. If a higher priority thread on the target core is executing a busy loop, that delay may even be indefinitely.
See also
Timeouts

Enumeration Type Documentation

◆ l4_syscall_flags_t

Capability selector flags.

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

The following combinations of flags are supported when invoking IPC (see l4_ipc()); with other combinations, behavior is undefined:

Enumerator
L4_SYSF_NONE 

Empty set of flags.

Deprecated:

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 sent to the object denoted by the capability. For receive phase see L4_SYSF_RECV.

In l4_vcpu_state_t::user_task this flag means that the kernel has cached the user task capability internally, see l4_thread_vcpu_resume_commit().

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 61 of file consts.h.

Function Documentation

◆ l4_ipc()

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. L4_INVALID_CAP denotes the current thread. An IPC to the current thread will always abort after the specified timeout and can be used for sleeping without busy waiting.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
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
See also
L4 Inter-Process Communication (IPC)

Definition at line 34 of file ipc.h.

References l4_msgtag_t::raw.

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. A value of L4_INVALID_CAP denotes the current thread and will abort the IPC after the time specified in the snd part of the timeout parameter has expired.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
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.
If a finite receive timeout is specified, the IPC receive operation could abort before the partner was able to send the reply message. Under certain circumstances the partner may still have the temporary reply capability to the calling thread and may use this capability to reply to the caller at a later, unexpected time specifying an arbitrary IPC label. This case is relevant for servers which call another, possibly untrusted, server while serving a client request.
See also
L4 Inter-Process Communication (IPC)
Examples
examples/sys/aliens/main.c, examples/sys/ipc/ipc_example.c, and examples/sys/singlestep/main.c.

Definition at line 576 of file ipc.h.

References l4_ipc(), and L4_SYSF_CALL.

Referenced by __kdebug_3_text(), __kdebug_op(), __kdebug_op_1(), __kdebug_text(), L4::Ipc::Iostream::call(), enter_kdebug(), fiasco_amd64_segment_info(), fiasco_amd64_set_fs(), fiasco_amd64_set_segment_base(), fiasco_gdt_get_entry_offset(), fiasco_gdt_set(), fiasco_ldt_set(), l4_icu_bind_u(), l4_icu_info_u(), l4_icu_msi_info_u(), l4_icu_set_mode_u(), l4_icu_unbind_u(), l4_irq_detach_u(), l4_irq_mux_chain_u(), l4_irq_receive_u(), l4_thread_ex_regs_u(), l4_thread_vcpu_control_ext_u(), l4_thread_vcpu_control_u(), l4_vcon_get_attr_u(), l4_vcon_set_attr_u(), l4util_ioport_map(), and L4::Thread::modify_senders().

+ 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. A value of L4_INVALID_CAP denotes the current thread. It could be used for sleeping without busy waiting for the time specified in the rcv part of the timeout parameter.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
timeoutTimeout pair (see l4_timeout_t, only the receive part matters).
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.
See also
L4 Inter-Process Communication (IPC)
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 613 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
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
tagDescribes the message to be sent as reply.
[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.
In case of multiple senders trying to send to the thread performing this system call, the thread receives from a sender with the highest priority. In this respect, IRQ sources have the highest priority 255.
See also
L4 Inter-Process Communication (IPC)
Examples
examples/sys/ipc/ipc_example.c.

Definition at line 583 of file ipc.h.

References L4_INVALID_CAP, l4_ipc(), and L4_SYSF_REPLY_AND_WAIT.

Referenced by L4::Ipc::Iostream::reply_and_wait(), and L4::Server< LOOP_HOOKS >::reply_n_wait().

+ Here is the call graph for this function:
+ Here is the caller 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. A value of L4_INVALID_CAP denotes the current thread and could be used for sleeping without busy waiting for the time specified in the snd part of the timeout parameter.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
tagDescriptor for the message to be sent.
timeoutTimeout pair (see l4_timeout_t) only send part is relevant.
Returns
Syscall return tag for the send-only operation, this means there is no return value except L4_MSGTAG_ERROR indicating success or failure of the send operation. Use l4_ipc_error() to check for errors and do not use l4_error().

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

Note
This is a special-purpose message transfer. Objects usually support only invocation via l4_ipc_call() consisting of a send phase and a receive phase for returning the result of the object invocation. For example, l4_icu_unmask(), l4_icu_mask() and l4_irq_trigger() use send-only IPC operations for object invocation.
See also
L4 Inter-Process Communication (IPC)
Examples
examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 597 of file ipc.h.

References l4_ipc(), and L4_SYSF_SEND.

Referenced by l4_irq_trigger_u(), l4_irq_unmask_u(), l4_vcon_send_u(), L4::Server< LOOP_HOOKS >::reply_n_wait(), and L4::Ipc::Ostream::send().

+ 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. A value of L4_INVALID_CAP denotes the current thread and will abort the IPC after the time specified in the snd part of the timeout parameter has expired.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
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.
In case of multiple senders trying to send to the thread performing this system call, the thread receives from a sender with the highest priority. In this respect, IRQ sources have the highest priority 255.
See also
L4 Inter-Process Communication (IPC)

Definition at line 590 of file ipc.h.

References l4_ipc(), and L4_SYSF_SEND_AND_WAIT.

Referenced by l4_irq_wait_u().

+ Here is the call graph for this function:
+ Here is the caller 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().

See also
L4 Inter-Process Communication (IPC)

Definition at line 622 of file ipc.h.

References L4_INVALID_CAP, and l4_ipc_receive().

Referenced by l4_ipc_sleep_ms(), l4_ipc_sleep_us(), and l4_sleep_forever().

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

◆ l4_ipc_sleep_ms()

l4_msgtag_t l4_ipc_sleep_ms ( l4_uint32_t  ms)
inline

Sleep for a certain amount of milliseconds.

Parameters
msNumber of milliseconds to wait.
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().

See also
L4 Inter-Process Communication (IPC)

Definition at line 626 of file ipc.h.

References l4_ipc_sleep(), L4_IPC_TIMEOUT_NEVER, and l4_timeout().

+ Here is the call graph for this function:

◆ l4_ipc_sleep_us()

l4_msgtag_t l4_ipc_sleep_us ( l4_uint64_t  us)
inline

Sleep for a certain amount of microseconds.

Parameters
usNumber of microseconds to wait.
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().

See also
L4 Inter-Process Communication (IPC)

Definition at line 633 of file ipc.h.

References l4_ipc_sleep(), L4_IPC_TIMEOUT_NEVER, and l4_timeout().

+ Here is the call 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 to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
[out]labelLabel assigned to the source object (IPC gate or IRQ).
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().

Note
In case of multiple senders trying to send to the thread performing this system call, the thread receives from a sender with the highest priority. In this respect, IRQ sources have the highest priority 255.
See also
L4 Inter-Process Communication (IPC)
Examples
examples/sys/ipc/ipc_example.c.

Definition at line 604 of file ipc.h.

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

Referenced by L4::Server< LOOP_HOOKS >::reply_n_wait(), and L4::Ipc::Istream::wait().

+ 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.
[in,out]tagTag to be updated. Only the number of items is incremented in the updated tag, all other members remain unmodified.
Returns
0 on success, negative error code otherwise
See also
L4 Inter-Process Communication (IPC)

Definition at line 696 of file ipc.h.

References l4_utcb().

+ Here is the call graph for this function: