1// vi:set ft=cpp: -*- Mode: C++ -*-
2/**
3 * \file
4 * The C++ IPC gate interface.
5 */
6/*
7 * (c) 2009-2010 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
8 *               Alexander Warg <warg@os.inf.tu-dresden.de>
9 *     economic rights: Technische Universität Dresden (Germany)
10 *
11 * This file is part of TUD:OS and distributed under the terms of the
12 * GNU General Public License 2.
13 * Please see the COPYING-GPL-2 file for details.
14 *
15 * As a special exception, you may use this file as part of a free software
16 * library without restriction.  Specifically, if other files instantiate
17 * templates or use macros or inline functions from this file, or you compile
18 * this file and link it with other files to produce an executable, this
19 * file does not by itself cause the resulting executable to be covered by
20 * the GNU General Public License.  This exception does not however
21 * invalidate any other reasons why the executable file might be covered by
22 * the GNU General Public License.
23 */
24#pragma once
25
26#include <l4/sys/ipc_gate.h>
27#include <l4/sys/capability>
28#include <l4/sys/rcv_endpoint>
29#include <l4/sys/cxx/ipc_iface>
30
31namespace L4 {
32
33class Thread;
34
35/**
36 * The C++ IPC gate interface.
37 *
38 * IPC gates are used to create secure communication channels between protection
39 * domains. An IPC gate can be created using the L4::Factory interface.
40 *
41 * Depending on the permissions of the capability used, an IPC gate forwards IPC
42 * to the L4::Thread that is *bound* to the IPC gate (cf. bind_thread()). If the
43 * capability has the #L4_FPAGE_C_IPCGATE_SVR permission, only IPC using a
44 * protocol different from the #L4_PROTO_KOBJECT protocol is forwarded. Without
45 * the #L4_FPAGE_C_IPCGATE_SVR permission, all IPC is forwarded. The latter is
46 * the usual case for a client in a client/server scenario. When no thread is
47 * bound yet, the forwarded IPC blocks until a thread is bound or the IPC times
48 * out.
49 *
50 * Forwarded IPC is always forwarded to the userland of the bound thread. That
51 * means, the L4::Thread interface of the bound thread is not accessible via an
52 * IPC gate. The L4::Ipc_gate interface of an IPC gate is only accessible if the
53 * capability used has the #L4_FPAGE_C_IPCGATE_SVR permission (cf. previous
54 * paragraph). Conversely that means, if the capability used lacks the
55 * #L4_FPAGE_C_IPCGATE_SVR permission, L4::Ipc_gate interface calls are
56 * forwarded to the bound thread instead of being processed by the IPC gate
57 * itself. In a client/server scenario, a client should only get IPC gate
58 * capabilities without #L4_FPAGE_C_IPCGATE_SVR permission so the client cannot
59 * tamper with the IPC gate.
60 *
61 * When binding a thread to an IPC gate, a user-defined, kernel protected,
62 * machine-word sized payload called the IPC gate’s *label* is assigned to the
63 * IPC gate (cf. bind_thread()). When a send-only IPC or call IPC is forwarded
64 * via an IPC gate, the label provided by the sender is ignored and replaced by
65 * the IPC gate’s label where the two least significant bits are the result of
66 * bitwise disjunction of the corresponding label bits with the #L4_CAP_FPAGE_S
67 * and #L4_CAP_FPAGE_W permissions of the capability used. Hence, the label
68 * provided via bind_thread() should usually have its two least significant bits
69 * set to zero. The replaced label is only visible to the bound thread upon
70 * receive. However, the configured label of an IPC gate can also be queried via
71 * get_infos() if the capability used has the #L4_FPAGE_C_IPCGATE_SVR
72 * permission.
73 *
74 * \includefile{l4/sys/ipc_gate}
75 *
76 * For the C interface refer to the C \ref l4_kernel_object_gate_api.
77 *
78 * \see \ref l4_ipc_api
79 */
80class L4_EXPORT Ipc_gate :
81  public Kobject_t<Ipc_gate, Rcv_endpoint, L4_PROTO_KOBJECT,
82                   Type_info::Demand_t<1> >
83{
84public:
85  /**
86   * Get information about the IPC-gate.
87   *
88   * \param[out] label  The label of the IPC gate is returned here.
89   *
90   * \return System call return tag.
91   */
92  L4_INLINE_RPC_OP(L4_IPC_GATE_GET_INFO_OP,
93      l4_msgtag_t, get_infos, (l4_umword_t *label));
94
95  typedef L4::Typeid::Rpcs_sys<bind_thread_t, get_infos_t> Rpcs;
96};
97
98}
99