The C IPC gate interface, see L4::Ipc_gate for the C++ interface. More...

Collaboration diagram for IPC-Gate API:

Functions
l4_msgtag_t	l4_ipc_gate_get_infos (l4_cap_idx_t gate, l4_umword_t *label)
	Get information about the IPC-gate.

l4_msgtag_t	l4_rcv_ep_bind_thread (l4_cap_idx_t ep, l4_cap_idx_t thread, l4_umword_t label)
	Bind the IPC receive endpoint to a thread.

l4_msgtag_t	l4_rcv_ep_bind_snd_destination (l4_cap_idx_t ep, l4_cap_idx_t snd_dst, l4_umword_t label)
	Bind the IPC receive endpoint to a send destination (a thread).

Detailed Description

The C IPC gate interface, see L4::Ipc_gate for the C++ interface.

IPC gates are used to create secure communication channels between protection domains. An IPC gate can be created using the Factory interface.

Depending on the permissions of the capability used, an IPC gate forwards IPC to the Thread the IPC gate is bound to (cf. l4_rcv_ep_bind_thread() and l4_rcv_ep_bind_snd_destination()). If the capability has the L4_FPAGE_C_IPCGATE_SVR permission, only IPC using a protocol different from the L4_PROTO_KOBJECT protocol is forwarded. Without the L4_FPAGE_C_IPCGATE_SVR permission, all IPC is forwarded. The latter is the usual case for a client in a client/server scenario. When not bound to a thread or thread group yet, the forwarded IPC blocks until the IPC gate is bound to a thread or thread group, or the IPC times out.

Forwarded IPC is always forwarded to the userland of the thread the IPC gate is bound to, either directly or indirectly using a thread group. That means, the Thread interface of that thread is not accessible via an IPC gate. The IPC-Gate API of an IPC gate is only accessible if the capability used has the L4_FPAGE_C_IPCGATE_SVR permission (cf. previous paragraph). Conversely that means, if the capability used lacks the L4_FPAGE_C_IPCGATE_SVR permission, IPC-Gate API calls are forwarded to the thread or thread group the IPC gate is bound to instead of being processed by the IPC gate itself. In a client/server scenario, a client should only get IPC gate capabilities without L4_FPAGE_C_IPCGATE_SVR permission so the client cannot tamper with the IPC gate.

When binding an IPC gate to a thread or thread group, a user-defined, kernel protected, machine-word sized payload called the IPC gate’s label is assigned to the IPC gate (note that the two least significant bits of the label must be zero; cf. l4_rcv_ep_bind_thread() and l4_rcv_ep_bind_snd_destination()). When a send-only IPC or call IPC is forwarded via an IPC gate, the label provided by the sender is ignored and replaced by the IPC gate’s label where the two least significant bits are set to the L4_CAP_FPAGE_S and L4_CAP_FPAGE_W permissions of the capability used. The replaced label is only visible to the thread the IPC gate is bound to upon receive (or to the selected thread from the thread group the IPC gate is bound to). However, the configured label of an IPC gate can also be queried via l4_ipc_gate_get_infos() if the capability used has the L4_FPAGE_C_IPCGATE_SVR permission.

When deleting an IPC gate or when unbinding it from a thread or thread group, the label of IPC already in flight won't be changed. To ensure that no IPC from this IPC gate is received by a thread with an unexpected label, l4_thread_modify_sender_start() shall be used to change the labels of every pending IPC to that gate. This is also required if the label of an already bound IPC gate is changed. It is not necessary after binding the IPC gate to a thread or thread group for the first time.

When binding a currently bound IPC gate to a new thread or thread group, the same label should be used that was used with the old thread. Otherwise the old and the new thread need to synchronize to avoid IPC messages with unexpected labels.

Include File: #include <l4/sys/ipc_gate.h>

ipc_gate.h
The C IPC gate interface, see L4::Ipc_gate for the C++ interface.

For the C++ interface refer to the L4::Ipc_gate documentation.

See also: Object Invocation

Function Documentation

◆ l4_ipc_gate_get_infos()

l4_msgtag_t l4_ipc_gate_get_infos	(	l4_cap_idx_t	gate,
		l4_umword_t *	label
	)

inline

Get information about the IPC-gate.

Parameters

	gate	The IPC gate object to get information about.
[out]	label	The label of the IPC gate is returned here.

Returns: System call return tag.

Precondition: If gate does not possess the L4_FPAGE_C_IPCGATE_SVR right, the kernel will not perform this operation. Instead, the underlying IPC message will be forwarded to the thread or thread group the IPC gate is bound to, blocking the caller if the IPC gate is not bound yet.

Definition at line 166 of file ipc_gate.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_rcv_ep_bind_snd_destination()

l4_msgtag_t l4_rcv_ep_bind_snd_destination	(	l4_cap_idx_t	ep,
		l4_cap_idx_t	snd_dst,
		l4_umword_t	label
	)

inline

Bind the IPC receive endpoint to a send destination (a thread).

Parameters

ep	The IPC receive endpoint object.
snd_dst	The send destination (thread) object `ep` shall be bound to.
label	Label to assign to `ep`. For IPC gates, the two least significant bits must be set to zero.

Returns: Syscall return tag containing one of the following return codes.

Return values

L4_EOK	Operation successful.
-L4_EINVAL	`snd_dst` is not a thread object or other arguments were malformed.
-L4_EPERM	No L4_CAP_FPAGE_S right on `ep` or `snd_dst`.

Precondition: If ep is an IPC gate capability without the L4_FPAGE_C_IPCGATE_SVR right, the kernel will not perform this operation. Instead, the underlying IPC message will be forwarded to the send destination the IPC gate is bound to, blocking the caller if the IPC gate was not bound yet.

The specified label is passed to the receiver of the incoming IPC. It is possible to re-bind a receive endpoint to the same or a different send destination. In this case, IPC already in flight will be delivered with the old label to the previously bound thread unless l4_thread_modify_sender_start() is used to change these labels.

Definition at line 138 of file rcv_endpoint.h.

References l4_utcb().

Referenced by L4::Rcv_endpoint::bind_snd_destination().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_rcv_ep_bind_thread()

l4_msgtag_t l4_rcv_ep_bind_thread	(	l4_cap_idx_t	ep,
		l4_cap_idx_t	thread,
		l4_umword_t	label
	)

inline

Bind the IPC receive endpoint to a thread.

Parameters

ep	The IPC receive endpoint object.
thread	The thread object `ep` shall be bound to.
label	Label to assign to `ep`. For IPC gates, the two least significant bits must be set to zero.

Returns: Syscall return tag containing one of the following return codes.

Return values

L4_EOK	Operation successful.
-L4_EINVAL	`thread` is not a thread object or other arguments were malformed.
-L4_EPERM	Insufficient permissions; see precondition.

Precondition: The capabilities ep and thread both must have the permission L4_CAP_FPAGE_S.; If ep is an IPC gate capability without the L4_FPAGE_C_IPCGATE_SVR right, the kernel will not perform this operation. Instead, the underlying IPC message will be forwarded to the thread the IPC gate is bound to, blocking the caller if the IPC gate was not bound yet.

The specified label is passed to the receiver of the incoming IPC. It is possible to re-bind a receive endpoint to the same or a different thread. In this case, IPC already in flight will be delivered with the old label to the previously bound thread unless l4_thread_modify_sender_start() is used to change these labels.

Examples: examples/sys/isr/main.c.

Definition at line 131 of file rcv_endpoint.h.

References l4_utcb().

Here is the call graph for this function:

Functions

Detailed Description

Function Documentation

◆ l4_ipc_gate_get_infos()

◆ l4_rcv_ep_bind_snd_destination()

◆ l4_rcv_ep_bind_thread()