// vi:set ft=cpp: -*- Mode: C++ -*-
/**
 * \file
 * The C++ IPC gate interface.
 */
/*
 * (c) 2009-2010 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
 *               Alexander Warg <warg@os.inf.tu-dresden.de>
 *     economic rights: Technische Universität Dresden (Germany)
 *
 * License: see LICENSE.spdx (in this directory or the directories above)
 */
#pragma once

#include <l4/sys/ipc_gate.h>
#include <l4/sys/capability>
#include <l4/sys/rcv_endpoint>
#include <l4/sys/cxx/ipc_iface>

namespace L4 {

class Thread;

/**
 * The C++ IPC gate interface, see \ref l4_kernel_object_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.
 *
 * \includefile{l4/sys/ipc_gate}
 *
 * For the C interface refer to the C \ref l4_kernel_object_gate_api.
 *
 * \see \ref l4_ipc_api
 */
class L4_EXPORT Ipc_gate :
  public Kobject_t<Ipc_gate, Rcv_endpoint, L4_PROTO_KOBJECT,
                   Type_info::Demand_t<1> >
{
public:
  /**
   * Get information about the IPC-gate.
   *
   * \param[out] label  The label of the IPC gate is returned here.
   *
   * \return System call return tag.
   *
   * \pre 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.
   */
  L4_INLINE_RPC_OP(L4_IPC_GATE_GET_INFO_OP,
      l4_msgtag_t, get_infos, (l4_umword_t *label));

  typedef L4::Typeid::Rpcs_sys<bind_thread_t, get_infos_t> Rpcs;
};

}
