Loading...
Searching...
No Matches
Object Invocation
Base API

API for L4 object invocation. More...

Collaboration diagram for Object Invocation:

## Topics

| Message Items
| Message-item-related functionality.
| Timeouts
| All kinds of timeouts and time related functions.
| Error Handling
| Error handling for L4 object invocation.
| Realtime API
| Message Tag
| API related to the message tag data type.
| 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 flexpage 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

enum 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:

- L4_SYSF_SEND: send to specified partner
- L4_SYSF_RECV: receive from specified partner
- L4_SYSF_RECV | L4_SYSF_OPEN_WAIT: receive from any sending partner; see L4_SYSF_WAIT
- L4_SYSF_SEND | L4_SYSF_RECV: call specified partner; see L4_SYSF_CALL
- L4_SYSF_SEND | L4_SYSF_RECV | L4_SYSF_OPEN_WAIT: send to specified partner and receive from any sending partner; see L4_SYSF_SEND_AND_WAIT
- L4_SYSF_REPLY | L4_SYSF_SEND: reply to caller
- L4_SYSF_REPLY | L4_SYSF_SEND | L4_SYSF_RECV: call the caller
- L4_SYSF_REPLY | L4_SYSF_SEND | L4_SYSF_RECV | L4_SYSF_OPEN_WAIT: reply to caller and receive from any sending partner; see L4_SYSF_REPLY_AND_WAIT

Enumerator
L4_SYSF_NONE | Empty set of flags.
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 50 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

  | dest | Destination 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.
  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
  | flags | Invocation flags (see l4_syscall_flags_t).
  | slabel | Send label if applicable (may be seen by the receiver).
  | tag | Sending message tag.
  [out] | rlabel | Receiving label.
  | timeout | Timeout pair (see l4_timeout_t).

Returns
  return tag

See also
  L4 Inter-Process Communication (IPC)

Definition at line 23 of file ipc.h.

References L4_NOTHROW.

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

  object | Capability 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.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
  tag | Message tag to describe the message to be sent.
  timeout | Timeout 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 565 of file ipc.h.

References l4_ipc(), L4_NOTHROW, 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_bind_vcpu_u(), l4_irq_detach_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

  object | Object 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.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
  timeout | Timeout 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 602 of file ipc.h.

References l4_ipc(), L4_NOTHROW, 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

  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
  | tag | Describes the message to be sent as reply.
  [out] | label | Label assigned to the source object of the received message.
  | timeout | Timeout 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 572 of file ipc.h.

References L4_INVALID_CAP, l4_ipc(), L4_NOTHROW, 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

  dest | Capability 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.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
  tag | Descriptor for the message to be sent.
  timeout | Timeout 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 586 of file ipc.h.

References l4_ipc(), L4_NOTHROW, 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

  | dest | Object 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.
  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
  | tag | Describes the message that shall be sent.
  [out] | label | Label assigned to the source object of the receive phase.
  | timeout | Timeout 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 579 of file ipc.h.

References l4_ipc(), L4_NOTHROW, 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

  timeout | Timeout pair (see l4_timeout_t, the receive part matters).

Returns
  error code:
  - L4_IPC_RETIMEOUT: success
  - L4_IPC_RECANCELED woken up by a different thread (l4_thread_ex_regs()).

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 611 of file ipc.h.

References L4_INVALID_CAP, l4_ipc_receive(), and L4_NOTHROW.

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

  ms | Number of milliseconds to wait.

Returns
  error code:
  - L4_IPC_RETIMEOUT: success
  - L4_IPC_RECANCELED woken up by a different thread (l4_thread_ex_regs()).

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 615 of file ipc.h.

References l4_ipc_sleep(), L4_IPC_TIMEOUT_NEVER, L4_NOTHROW, 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

  us | Number of microseconds to wait.

Returns
  error code:
  - L4_IPC_RETIMEOUT: success
  - L4_IPC_RECANCELED woken up by a different thread (l4_thread_ex_regs()).

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_ipc_sleep(), L4_IPC_TIMEOUT_NEVER, L4_NOTHROW, 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

  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
  [out] | label | Label assigned to the source object (IPC gate or IRQ).
  | timeout | Timeout 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 593 of file ipc.h.

References L4_INVALID_CAP, l4_ipc(), L4_NOTHROW, 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 flexpage to be sent to the UTCB.

Parameters

  | snd_fpage | Flexpage.
  | snd_base | Send base.
  [in,out] | tag | Tag 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 685 of file ipc.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function: