xref: /l4re-core-master/l4sys/include/cxx/ipc_epiface

// vi:set ft=cpp: -*- Mode: C++ -*-
/*
 * (c) 2014-2015 Alexander Warg <alexander.warg@kernkonzept.com>
 *
 * 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
#pragma GCC system_header

#include "capability.h"
#include "ipc_server"
#include "ipc_string"
#include <l4/sys/types.h>
#include <l4/sys/utcb.h>
#include <l4/sys/__typeinfo.h>
#include <l4/sys/meta>
#include <l4/cxx/type_traits>

namespace L4 {

// forward for Irqep_t
class Irq;
class Rcv_endpoint;

namespace Ipc_svr {

class Timeout;

/**
 * \ingroup cxx_ipc_server
 * \brief Interface for server-loop related functions.
 *
 * This interface provides access to high-level server-loop related functions,
 * such as management of receive buffers and timeouts.
 */
class Server_iface
{
private:
  Server_iface(Server_iface const &);
  Server_iface const &operator = (Server_iface const &);

public:
  /// Data type expressing server-side demand for receive buffers.
  typedef L4::Type_info::Demand Demand;

  /// Make a server interface
  Server_iface() {}

  // Destroy the server interface
  virtual ~Server_iface() = 0;

  /**
   * \brief Tells the server to allocate buffers for the given demand.
   * \param demand  The total server-side demand of receive buffers needed for
   *                a given interface, see Demand.
   *
   * This function is not called by user applications directly. Usually the
   * server implementation or the registry implementation calls this function
   * whenever a new object is registered at the server.
   */
  virtual int alloc_buffer_demand(Demand const &demand) = 0;

  /**
   * \brief Get capability slot allocated to the given receive buffer.
   * \param index  The receive buffer index of the expected capability
   *               argument (0 <= \c index < \c caps registered with
   *               alloc_buffer_demand()).
   * \pre 0 <= \c index < \c caps registered with alloc_buffer_demand()
   * \return Capability slot currently allocated to the given receive buffer.
   */
  virtual L4::Cap<void> get_rcv_cap(int index) const = 0;

  /**
   * \brief Allocate a new capability for the given receive buffer.
   * \param index  The receive buffer index of the expected capability
   *               argument (0 <= \c index < \c caps registered with
   *               alloc_buffer_demand()).
   * \pre 0 <= \c index < \c caps registered with alloc_buffer_demand()
   * \return 0 on success, < 0 on error.
   */
  virtual int realloc_rcv_cap(int index) = 0;

  /**
   * \brief Add a timeout to the server internal timeout queue.
   * \param timeout  The timeout object to register.
   * \param time     The time (absolute) at which the timeout shall expire.
   * \pre timeout must not be in any queue.
   * \return 0 on success, 1 if timeout is already expired, < 0 on error.
   */
  virtual int add_timeout(Timeout *timeout, l4_kernel_clock_t time) = 0;

  /**
   * \brief Remove the given timeout from the timer queue.
   * \param timeout  The timout object to remove.
   * \return 0 on success, < 0 on error.
   */
  virtual int remove_timeout(Timeout *timeout) = 0;

  /**
   * \brief Get given receive buffer as typed capability.
   * \see get_rcv_cap()
   * \param index  The receive buffer index of the expected capability
   *               argument. (0 <= \c index < \c caps registered with
   *               alloc_buffer_demand().)
   * \pre 0 <= \c index < \c caps registered with alloc_buffer_demand()
   * \return Capability slot currently allocated to the given receive buffer.
   * \note This is a convenience wrapper for get_rcv_cap() to avoid
   *       L4::cap_cast<>().
   */
  template<typename T>
  L4::Cap<T> rcv_cap(int index) const
  { return L4::cap_cast<T>(get_rcv_cap(index)); }

  /**
   * \brief Get receive cap with the given index as generic (void) type.
   * \param index  The index of the cap receive buffer of the expected
   *               capability. (0 <= \c index < \c caps registered with
   *               alloc_buffer_demand().)
   * \return Capability slot currently allocated to the given capability
   *         buffer.
   * \note This is a convenience wrapper for get_rcv_cap().
   */
  L4::Cap<void> rcv_cap(int index) const
  { return get_rcv_cap(index); }
};

inline Server_iface::~Server_iface() {}

} // namespace Ipc_svr

/**
 * Base class for interface implementations.
 *
 * An Epiface is the base interface of objects registered in the server loop.
 * Incomming IPC gets dispatched to the appropriate Epiface object where
 * the call is then handled appropriately.
 *
 * \note Server loops are allowed to internally keep raw pointers to Epiface
 *              objects for dispatching calls. Instances must therefore never
 *              be copied or moved.
 */
struct Epiface
{
  Epiface(Epiface const &) = delete;
  Epiface &operator = (Epiface const &) = delete;

  /// Type for abstract server interface.
  typedef Ipc_svr::Server_iface Server_iface;
  /// Type for server-side receive buffer demand.
  typedef Ipc_svr::Server_iface::Demand Demand;

  class Stored_cap : public Cap<void>
  {
  private:
    enum { Managed = 0x10 };

  public:
    Stored_cap() = default;
    Stored_cap(Cap<void> const &c, bool managed = false)
    : Cap<void>((c.cap() & L4_CAP_MASK) | (managed ? Managed : 0))
    {
      static_assert (!(L4_CAP_MASK & Managed), "conflicting bits used...");
    }

    bool managed() const { return cap() & Managed; }
  };

  /// Make a server object
  Epiface() : _data(0) {}

  /**
   * The abstract handler for client requests to the object.
   * \param tag The message tag for this invocation.
   * \param rights The rights bits in the invoked capability.
   * \param utcb The UTCB used for the invocation.
   * \retval -L4_ENOREPLY  No reply message is send.
   * \retval <0            Error, reply with error code.
   * \retval >=0           Success, reply with return value.
   *
   * This function must be implemented by application specific server
   * objects.
   */
  virtual l4_msgtag_t dispatch(l4_msgtag_t tag, unsigned rights,
                               l4_utcb_t *utcb) = 0;

  /**
   * Get the server-side receive buffer demand for this object.
   * \note This function is usually not implemented directly, but by using
   *       Server_object_t template with an IPC interface definition.
   * \return The needed server-side receive buffers for this object
   */
  virtual Demand get_buffer_demand() const = 0; //{ return Demand(0); }

  /// Destroy the object
  virtual ~Epiface() = 0;

  /**
   * Get the capability to the kernel object belonging to this object.
   * \return Capability for the kernel object behind the server.
   *
   * This is usually either an Ipc_gate or an Irq.
   */
  Stored_cap obj_cap() const { return _cap; }

  /**
   * Get pointer to server interface at which the object is currently registered.
   * \return Pointer to the server at which the object is currently registered,
   *         NULL if the object is not registered at any server.
   */
  Server_iface *server_iface() const { return _data; }

  /**
   * Set server registration info for the object.
   * \param srv      The server to register at
   * \param cap      The capability that connects the object.
   * \param managed  Mark the capability as managed or unmanaged. Typical
   *                 server implementations use this flag to remember whether
   *                 the capability was internally allocated or not.
   * \return 0 on success, -L4_EINVAL if the srv and cap are not consistent.
   */
  int set_server(Server_iface *srv, Cap<void> cap, bool managed = false)
  {
    if ((srv && cap) || (!srv && !cap))
      {
        _data = srv;
        _cap  = Stored_cap(cap, managed);
        return 0;
      }

    return -L4_EINVAL;
  }

  /**
   * Deprecated server registration function.
   */
  void set_obj_cap(Cap<void> const &cap) { _cap = cap; }

private:
  Server_iface *_data;
  Stored_cap _cap;
};

inline Epiface::~Epiface() {}

/**
 * Epiface mixin for generic Kobject-based interfaces.
 *
 * \tparam RPC_IFACE  Data type of the IPC interface definition.
 * \tparam BASE       Base Epiface class.
 *
 */
template<typename RPC_IFACE, typename BASE = Epiface>
struct Epiface_t0 : BASE
{
  /// Data type of the IPC interface definition
  typedef RPC_IFACE Interface;

  /// Get the server-side buffer demand based in \a IFACE.
  typename Type_info::Demand get_buffer_demand() const
  { return typename Kobject_typeid<RPC_IFACE>::Demand(); }

  /**
   * Get the (typed) capability to this object.
   * \return Capability for the kernel object behind the server.
   */
  Cap<RPC_IFACE> obj_cap() const
  { return L4::cap_cast<RPC_IFACE>(BASE::obj_cap()); }
};

/**
 * Epiface implementation for interrupt handlers.
 *
 * \tparam Derived  Irq handler implementation class.
 *                  The class must provide a single function handle_irq().
 * \tparam BASE     Base Epiface class.
 */
template<typename Derived, typename BASE = Epiface,
         bool = cxx::is_polymorphic<BASE>::value>
struct Irqep_t : Epiface_t0<void, BASE>
{
  l4_msgtag_t dispatch(l4_msgtag_t, unsigned, l4_utcb_t *) final
  {
    static_cast<Derived*>(this)->handle_irq();
    return l4_msgtag(-L4_ENOREPLY, 0, 0, 0);
  }

  /**
   * Get the (typed) capability to this object.
   * \return Irq capability for the kernel object behind the server.
   */
  Cap<L4::Irq> obj_cap() const
  { return L4::cap_cast<L4::Irq>(BASE::obj_cap()); }
};

template<typename Derived, typename BASE>
struct Irqep_t<Derived, BASE, false> : Epiface_t0<void, BASE>
{
  l4_msgtag_t dispatch(l4_msgtag_t, unsigned, l4_utcb_t *)
  {
    static_cast<Derived*>(this)->handle_irq();
    return l4_msgtag(-L4_ENOREPLY, 0, 0, 0);
  }

  /**
   * Get the (typed) capability to this object.
   * \return Irq capability for the kernel object behind the server.
   */
  Cap<L4::Irq> obj_cap() const
  { return L4::cap_cast<L4::Irq>(BASE::obj_cap()); }
};

/**
 * Abstract interface for object registries.
 *
 * An object registry allows to register L4::Epiface objects at a server
 * loop either for synchronous RPC messages or for asynchronous IRQ
 * messages.
 */
class Registry_iface
{
public:
  virtual ~Registry_iface() = 0;

  /**
   * Register an L4::Epiface for an IPC gate available in the applications
   * environment under the name `service`.
   * \param o        Pointer to an Epiface object that shall be registered.
   * \param service  Name of the capability that shall be used to connect
   *                 `o` to as a server-side object.
   * \retval L4::Cap<void> The capability known as `service` on success.
   * \retval L4::Cap<void>::Invalid No capability with the given name found.
   *
   * After a successful call to this function `o->obj_cap()` is equal
   * to the capability in the environment with the name given by `service`.
   */
  virtual L4::Cap<void>
  register_obj(L4::Epiface *o, char const *service) = 0;

  /**
   * Register `o` as server-side object for synchronous RPC.
   * \param o  Pointer to an Epiface object that shall be registered as
   *           server-side object for RPC.
   * \retval L4::Cap<void> A valid capability to a new IPC gate.
   * \retval L4::Cap<void>::Invalid  The allocation of the IPC gate
   *                                 has failed.
   *
   * After successful registration `o->obj_cap()` will be the capability
   * of the allocated IPC gate.
   *
   * The function may allocate a capability slot for the object. In that
   * case unregister_obj() is responsible for freeing the slot as well.
   */
  virtual L4::Cap<void>
  register_obj(L4::Epiface *o) = 0;

  /**
   * Register `o` as server-side object for asynchronous IRQs.
   * \param o  Pointer to an Epiface object that shall be registered as
   *           server-side object for IRQs.
   * \retval L4::Cap<L4::Irq>            Capability to a new IRQ object on success.
   * \retval L4::Cap<L4::Irq>::Invalid  The allocation of the IRQ has failed.
   *
   * After successful registration `o->obj_cap()` will be the capability
   * of the allocated IRQ object.
   *
   * The function may allocate a capability slot for the object. In that
   * case unregister_obj() is responsible for freeing the slot as well.
   */
  virtual L4::Cap<L4::Irq> register_irq_obj(L4::Epiface *o) = 0;

  /**
   * Register `o` as server-side object for a pre-allocated capability.
   * \param o    Pointer to an Epiface object that shall be registered as
   *             server-side object.
   * \param ep   Capability to an already allocated capability where `o`
   *             shall be attached as server-side handler. The capability
   *             may point to an IPC gate or an IRQ.
   * \retval L4::Cap<L4::Rcv_endpoint>           Capability `ep` on success.
   * \retval L4::Cap<L4::Rcv_endpoint>::Invalid  The IRQ attach operation has failed.
   *
   * After successful registration `o->obj_cap()` will be equal to `ep`.
   */
  virtual L4::Cap<L4::Rcv_endpoint>
  register_obj(L4::Epiface *o, L4::Cap<L4::Rcv_endpoint> ep) = 0;

  /**
   * Unregister the given object `o` from the server.
   * \param o      Pointer to the Epiface object that shall be unregistered.
   *               The object must have been registered with any of the
   *               register methods if Registry_iface.
   * \param unmap  If true the capability `o->obj_cap()` shall be unmapped
   *               from the local object space.
   *
   * The function always unmaps and frees the capability if it was
   * allocated by either Registry_iface::register_irq_obj(L4::Epiface *),
   * or by Registry_iface::register_obj(L4::Epiface *).
   */
  virtual void
  unregister_obj(L4::Epiface *o, bool unmap = true) = 0;
};

inline Registry_iface::~Registry_iface() {}

namespace Ipc {
namespace Detail {

using namespace L4::Typeid;

template<typename IFACE>
struct Meta_svr
{
  long op_num_interfaces(L4::Meta::Rights)
  { return 1; }

  long op_interface(L4::Meta::Rights, l4_umword_t ifx, long &proto, L4::Ipc::String<char> &name)
  {
    if (ifx > 0)
      return -L4_ERANGE;
    proto = L4::kobject_typeid<IFACE>()->proto();
    if (auto *n = L4::kobject_typeid<IFACE>()->name())
      name.copy_in(n);

    return 0;
  }

  long op_supports(L4::Meta::Rights, l4_mword_t proto)
  { return L4::kobject_typeid<IFACE>()->has_proto(proto); }
};

template<typename IFACE, typename LIST>
struct _Dispatch;

// No match dispatcher found
template<typename IFACE>
struct _Dispatch<IFACE, Iface_list_end>
{
  template< typename THIS, typename A1, typename A2 >
  static l4_msgtag_t f(THIS *, l4_msgtag_t, A1, A2 &)
  { return l4_msgtag(-L4_EBADPROTO, 0, 0, 0); }
};

// call matching p_dispatch() function
template<typename IFACE, typename I, typename LIST >
struct _Dispatch<IFACE, Iface_list<I, LIST> >
{
  // special handling for the meta protocol, to avoid 'using' murx
  template< typename THIS >
  static l4_msgtag_t _f(THIS *, l4_msgtag_t tag, unsigned r,
                        l4_utcb_t *utcb, True::type)
  {
    using L4::Ipc::Msg::dispatch_call;
    typedef L4::Meta::Rpcs Meta;
    typedef Meta_svr<IFACE> Msvr;
    return dispatch_call<Meta>((Msvr *)0, utcb, tag, r);
  }

  // normal dispatch to the op_<func> methods of \a self.
  template< typename THIS >
  static l4_msgtag_t _f(THIS *self, l4_msgtag_t t, unsigned r,
                        l4_utcb_t *utcb, False::type)
  {
    using L4::Ipc::Msg::dispatch_call;
    return dispatch_call<typename I::iface_type::Rpcs>(self, utcb, t, r);
  }

  // dispatch function with switch for meta protocol
  template< typename THIS >
  static l4_msgtag_t f(THIS *self, l4_msgtag_t tag, unsigned r,
                       l4_utcb_t *utcb)
  {
    if (I::Proto == tag.label())
      return _f(self, tag, r, utcb, Bool<I::Proto == (long)L4_PROTO_META>());

    return _Dispatch<IFACE, typename LIST::type>::f(self, tag, r, utcb);
  }
};

template<typename IFACE>
struct Dispatch :
  _Dispatch<IFACE, typename L4::Kobject_typeid<IFACE>::Iface_list::type>
{};

} // namespace Detail

template<typename EPIFACE>
struct Dispatch : Detail::Dispatch<typename EPIFACE::Interface>
{};

} // namespace Ipc

/**
 * Epiface implementation for Kobject-based interface implementations.
 *
 * \tparam Derived  Class providing the interface implementations.
 * \tparam BASE     Epiface base class.
 */
template<typename Derived, typename IFACE, typename BASE = L4::Epiface,
         bool = cxx::is_polymorphic<BASE>::value>
struct Epiface_t : Epiface_t0<IFACE, BASE>
{
  l4_msgtag_t
  dispatch(l4_msgtag_t tag, unsigned rights, l4_utcb_t *utcb) final
  {
    typedef Ipc::Dispatch<Derived> Dispatch;
    return Dispatch::f(static_cast<Derived*>(this), tag, rights, utcb);
  }
};

template<typename Derived, typename IFACE, typename BASE>
struct Epiface_t<Derived, IFACE, BASE, false> : Epiface_t0<IFACE, BASE>
{
  l4_msgtag_t
  dispatch(l4_msgtag_t tag, unsigned rights, l4_utcb_t *utcb)
  {
    typedef Ipc::Dispatch<Derived> Dispatch;
    return Dispatch::f(static_cast<Derived*>(this), tag, rights, utcb);
  }
};

/**
 * \ingroup cxx_ipc_server
 * \brief This registry returns the corresponding server object
 *        based on the label of an Ipc_gate.
 */
class Basic_registry
{
public:
  typedef Epiface Value;
  /**
   * \brief Get the server object for an Ipc_gate label.
   * \param label The label usually stored in an Ipc_gate.
   * \return A pointer to the Epiface identified by the given label.
   */
  static Value *find(l4_umword_t label)
  { return reinterpret_cast<Value*>(label & ~3UL); }

  /**
   * \brief The dispatch function called by the server loop.
   *
   * This function forwards the message to the server object identified by the
   * given \a label.
   *
   * \param tag The message tag used for the invocation.
   * \param label The label used to find the object including the rights bits
   *              of the invoked capability.
   * \param utcb The UTCB used for the invocation.
   * \return The return code from the object's dispatch function or -L4_ENOENT
   *         if the object does not exist.
   */
  static l4_msgtag_t dispatch(l4_msgtag_t tag, l4_umword_t label,
                              l4_utcb_t *utcb)
  {
    return find(label)->dispatch(tag, label, utcb);
  }
};


} // namespace L4