ipc_gate.h File Reference

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

#include <l4/sys/utcb.h>
#include <l4/sys/types.h>
#include <l4/sys/rcv_endpoint.h>
#include <l4/sys/ipc.h>

Include dependency graph for ipc_gate.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	L4_ipc_gate_ops { L4_IPC_GATE_BIND_OP = 0x10 , L4_IPC_GATE_GET_INFO_OP = 0x11 }
	Operations on the IPC-gate. More...

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

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 that is bound to the IPC gate (cf. l4_rcv_ep_bind_thread()). 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 no thread is bound yet, the forwarded IPC blocks until a thread is bound or the IPC times out.

Forwarded IPC is always forwarded to the userland of the bound thread. That means, the Thread interface of the bound 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 bound thread 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 a thread to an IPC gate, a user-defined, kernel protected, machine-word sized payload called the IPC gate’s label is assigned to the IPC gate (cf. l4_rcv_ep_bind_thread()). 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 the result of bitwise disjunction of the corresponding label bits with the L4_CAP_FPAGE_S and L4_CAP_FPAGE_W permissions of the capability used. Hence, the label provided via l4_rcv_ep_bind_thread() should usually have its two least significant bits set to zero. The replaced label is only visible to the bound thread upon receive. 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, 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 for the first time.

When binding a new thread to an IPC gate that is currently bound, 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> 

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

See also

Object Invocation

Definition in file ipc_gate.h.