// 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)
 *
 * This file is part of TUD:OS and distributed under the terms of the
 * GNU General Public License 2.
 * Please see the COPYING-GPL-2 file for details.
 *
 * As a special exception, you may use this file as part of a free software
 * library without restriction.  Specifically, if other files instantiate
 * templates or use macros or inline functions from this file, or you compile
 * this file and link it with other files to produce an executable, this
 * file does not by itself cause the resulting executable to be covered by
 * the GNU General Public License.  This exception does not however
 * invalidate any other reasons why the executable file might be covered by
 * the GNU General Public License.
 */
#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.
 *
 * IPC gates are used to create secure communication channels between
 * protection domains. An IPC gate can be created using the L4::Factory
 * interface. L4::Ipc_gate::bind_thread() binds an L4::Thread as the receiver
 * of all messages to an IPC gate.
 *
 * The bind_thread() call allows to assign each IPC gate a kernel protected,
 * machine-word sized payload called a *label*. It securely identifies the
 * gate. The two least significant bits of the *label* are ORed with the
 * L4_CAP_FPAGE_S and L4_CAP_FPAGE_W bits stored in the capability when
 * transferred to the receiver. This means the *label* should usually have its
 * two least significant bits set to zero. The *label* is only visible in the
 * #L4::Task which is running the thread the IPC gate was bound to and cannot
 * be altered by the sender.
 *
 * \includefile{l4/sys/ipc_gate}
 *
 * For the C interface refer to the C \ref l4_kernel_object_gate_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.
   */
  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;
};

}
