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

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

	dest	Destination object.
	utcb	UTCB of the caller.
	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

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

object	Capability selector for the object to call.
utcb	UTCB of the caller.
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.

Examples: examples/sys/aliens/main.c, examples/sys/ipc/ipc_example.c, and examples/sys/singlestep/main.c.

Definition at line 448 of file ipc.h.

References l4_ipc(), and L4_SYSF_CALL.

Referenced by L4::Ipc::Iostream::call(), 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.
timeout	Timeout pair (see l4_timeout_t, only the receive part matters).
utcb	UTCB 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 490 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 of the caller.
	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.

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

Definition at line 456 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.
utcb	UTCB of the caller.
tag	Descriptor for the message to be sent.
timeout	Timeout 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 473 of file ipc.h.

References l4_ipc(), and L4_SYSF_SEND.

Referenced by l4_irq_trigger_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.
	utcb	UTCB of the caller.
	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.

Definition at line 464 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

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

Definition at line 499 of file ipc.h.

References L4_INVALID_CAP, and l4_ipc_receive().

Referenced by l4_sleep_forever(), and l4_usleep().

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

	utcb	UTCB of the caller.
[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().

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

Definition at line 481 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.
tag	Tag to be modified.

Return values

tag	Modified 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 559 of file ipc.h.

Modules

Files

Enumerations

Functions

Detailed Description

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_wait()

◆ l4_sndfpage_add()