L4::Ipc_gate Class Reference

The C++ IPC gate interface, see IPC-Gate API for the C interface. More...

#include <ipc_gate>

Inheritance diagram for L4::Ipc_gate:

Collaboration diagram for L4::Ipc_gate:

Public Member Functions
l4_msgtag_t	get_infos (l4_umword_t *label)
	Get information about the IPC-gate.
Public Member Functions inherited from L4::Rcv_endpoint
l4_msgtag_t	bind_thread (Ipc::Cap< Thread > t, l4_umword_t label)
	Bind the IPC receive endpoint to a thread.
l4_msgtag_t	bind_snd_destination (Cap< Snd_destination > snd_dst, l4_umword_t label)
	Bind a send destination (a thread or thread group) to an IPC receive endpoint.
Public Member Functions inherited from L4::Kobject
l4_msgtag_t	dec_refcnt (l4_mword_t diff, l4_utcb_t *utcb=l4_utcb())
	Decrement the in kernel reference counter for the object.

Additional Inherited Members
Protected Types inherited from L4::Kobject_t< Ipc_gate, Rcv_endpoint, L4_PROTO_KOBJECT, Type_info::Demand_t< 1 > >
typedef Ipc_gate	Class
	The target interface type (inheriting from Kobject_t)
typedef Typeid::Iface< PROTO, Ipc_gate >	__Iface
	The interface description for the derived class.
typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Base::__Iface_list >	__Iface_list
	The list of all RPC interfaces provided directly or through inheritance.
Protected Types inherited from L4::Kobject_t< Rcv_endpoint, Kobject, L4_PROTO_KOBJECT, Type_info::Demand_t< 1 > >
typedef Rcv_endpoint	Class
	The target interface type (inheriting from Kobject_t)
typedef Typeid::Iface< PROTO, Rcv_endpoint >	__Iface
	The interface description for the derived class.
typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Base::__Iface_list >	__Iface_list
	The list of all RPC interfaces provided directly or through inheritance.
Protected Member Functions inherited from L4::Kobject_t< Ipc_gate, Rcv_endpoint, L4_PROTO_KOBJECT, Type_info::Demand_t< 1 > >
L4::Cap< Class >	c () const noexcept
	Get the capability to ourselves.
Protected Member Functions inherited from L4::Kobject_t< Rcv_endpoint, Kobject, L4_PROTO_KOBJECT, Type_info::Demand_t< 1 > >
L4::Cap< Class >	c () const noexcept
	Get the capability to ourselves.
Protected Member Functions inherited from L4::Kobject
l4_cap_idx_t	cap () const noexcept
	Return capability selector.
Static Protected Member Functions inherited from L4::Kobject_t< Ipc_gate, Rcv_endpoint, L4_PROTO_KOBJECT, Type_info::Demand_t< 1 > >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.
Static Protected Member Functions inherited from L4::Kobject_t< Rcv_endpoint, Kobject, L4_PROTO_KOBJECT, Type_info::Demand_t< 1 > >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.

Detailed Description

The C++ IPC gate interface, see IPC-Gate API for the C interface.

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

Depending on the permissions of the capability used, an IPC gate forwards IPC to the L4::Thread or L4::Thread_group the IPC gate is bound to (cf. bind_thread() and 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 L4::Thread interface of that thread is not accessible via an IPC gate. The L4::Ipc_gate interface 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, L4::Ipc_gate interface 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. bind_thread() and 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 (or to the selected thread of the thread group the IPC gate is bound to) upon receive. However, the configured label of an IPC gate can also be queried via 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_senders() 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> 

For the C interface refer to the C IPC-Gate API.

See also

Object Invocation

Definition at line 85 of file ipc_gate.

Member Function Documentation

get_infos()

l4_msgtag_t L4::Ipc_gate::get_infos

(

l4_umword_t *

label

)

Get information about the IPC-gate.

Parameters

[out]

label

The label of the IPC gate is returned here.

Returns

System call return tag.

Precondition

If the IPC gate capability used to invoke this operation does not possess the L4_FPAGE_C_IPCGATE_SVR right, the kernel will not perform the 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.

---

The documentation for this class was generated from the following file:

• l4/sys/ipc_gate