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

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. 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

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

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

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

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

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

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

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

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

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

	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 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_fpage	Flex-page.
	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 696 of file ipc.h.

References l4_utcb().

Here is the call graph for this function:

Modules

Files

Enumerations

Functions

Detailed Description

Timeouts during IPC

Enumeration Type Documentation

◆ l4_syscall_flags_t

Function Documentation

◆ l4_ipc()

◆ l4_ipc_call()

◆ l4_ipc_receive()

◆ l4_ipc_reply_and_wait()

◆ l4_ipc_send()

◆ l4_ipc_send_and_wait()

◆ l4_ipc_sleep()

◆ l4_ipc_sleep_ms()

◆ l4_ipc_sleep_us()

◆ l4_ipc_wait()

◆ l4_sndfpage_add()