ipc_types

Go to the documentation of this file.

// vi:set ft=cpp: -*- Mode: C++ -*-
/*
 * (c) 2014 Alexander Warg <alexander.warg@kernkonzept.com>
 *
 * License: see LICENSE.spdx (in this directory or the directories above)
 */
#pragma once
 
#include "capability.h"
#include "types"
#include "ipc_basics"
 
namespace L4 {

using Opcode = int;
 
namespace Ipc {

template<typename T> struct L4_EXPORT Out;
 

template<typename T> struct  L4_EXPORT In_out
{
  T v;
  In_out() {}
  In_out(T v) : v(v) {}
  operator T () const { return v; }
  operator T & () { return v; }
};
 
namespace Msg {
 
template<typename A> struct Elem< In_out<A *> > : Elem<A *>
{
  static constexpr bool Is_input = true;
  static constexpr bool Is_output = true;
};
 
template<typename A>
struct Is_valid_rpc_type< In_out<A *> > : Is_valid_rpc_type<A *> {};
template<typename A>
struct Is_valid_rpc_type< In_out<A const *> > : L4::Types::False {};
 
template<typename A>
struct Is_valid_rpc_type< In_out<A &> > : L4::Types::False {};
 
// Value types don't make sense for output.
template<typename A>
struct Is_valid_rpc_type< In_out<A> > : L4::Types::False {};
 
}
 

template<typename T> struct L4_EXPORT Opt
{
  T _value{};          
  bool _valid = false; 

  Opt() noexcept = default;

  Opt(T value) noexcept : _value(value), _valid(true) {}

  Opt &operator = (T value) noexcept
  {
    this->_value = value;
    this->_valid = true;
    return *this;
  }

  void set_valid(bool valid = true) noexcept { _valid = valid; }

  T *operator -> () noexcept { return &this->_value; }
  T const *operator -> () const noexcept { return &this->_value; }
  T const &value() const noexcept { return this->_value; }
  T &value() noexcept { return this->_value; }
  bool is_valid() const noexcept { return this->_valid; }
};
 
namespace Msg {
 
template<typename T> struct Elem< Opt<T &> > : Elem<T &>
{
  static constexpr bool Is_optional = true;
  using svr_arg_type = Opt<typename Elem<T &>::svr_type> &;
  using svr_type = Opt<typename Elem<T &>::svr_type>;
};
 
template<typename T> struct Elem< Opt<T *> > : Elem<T *>
{
  static constexpr bool Is_optional = true;
  using svr_arg_type = Opt<typename Elem<T *>::svr_type> &;
  using svr_type = Opt<typename Elem<T *>::svr_type>;
};
 
template<typename T> struct Elem< Opt<T> > : Elem<T>
{
  static constexpr bool Is_optional = true;
  using arg_type = Opt<T>;
};
 
template<typename T> struct Elem< Opt<T const *> > : Elem<T const *>
{
  static constexpr bool Is_optional = true;
  using arg_type = Opt<T const *>;
};
 
template<typename T>
struct Is_valid_rpc_type< Opt<T const &> > : L4::Types::False {};
 
// This specialization is only used for optional input arguments. Optional
// output arguments use a plain `T &` or `T *` on the client side. If the
// argument is not present, it stays default constructed.
template<typename T>
struct Clnt_val_ops<Opt<T>>
{
  using Native = Detail::_Clnt_val_ops<T>;
  using Plain = Detail::_Plain<T>;
 
  static int to_msg_data(char *msg, unsigned offset, unsigned limit,
                         Opt<T> const &arg) noexcept
  {
    if (arg.is_valid())
      return Native::to_msg_data(msg, offset, limit, Plain::deref(arg.value()));
    return offset;
  }
 
  static int to_msg_items(char *msg, unsigned offset, unsigned limit,
                          Opt<T> const &arg) noexcept
  {
    if (arg.is_valid())
      return Native::to_msg_items(msg, offset, limit,
                                  Plain::deref(arg.value()));
    return offset;
  }
 
  // No to_msg_* methods. They are never called because optional output
  // arguments don't use the Opt<> type on the client side (see Elem<Opt<...>>
  // above). Likewise, intentionally left without to_msg_buffers(). Buffer
  // items are not supported because they are client side output arguments.
};
 
// This specialization is only used for optional output arguments. Optional
// input arguments use a plain `T` on the server side. If the argument is not
// present, it stays default constructed.
template<typename T>
struct Svr_val_ops<Opt<T>>
{
  using Native = Svr_val_ops<T>;
 
  // Intentinally without to_svr_data() and to_svr_items(). They are never
  // called. Optional input arguments don't use the Opt<> type on the server
  // side. See Elem<Opt<...>> above.
 
  static int reserve_data(char *msg, unsigned offset, unsigned limit,
                          Opt<T> &arg) noexcept
  {
    return Native::reserve_data(msg, offset, limit, arg.value());
  }
 
  static int from_svr_data(char *msg, unsigned offset, unsigned limit,
                           Opt<T> const &arg) noexcept
  {
    if (arg.is_valid())
      return Native::from_svr_data(msg, offset, limit, arg.value());
    return offset;
  }
 
  static int from_svr_items(char *msg, unsigned offset, unsigned limit,
                            Opt<T> const &arg) noexcept
  {
    if (arg.is_valid())
      return Native::from_svr_items(msg, offset, limit, arg.value());
    return offset;
  }
};
 
}

class  L4_EXPORT Small_buf
{
public:
  explicit Small_buf(L4::Cap<void> cap, unsigned long flags = 0) noexcept
  : _data(cap.cap() | L4_RCV_ITEM_SINGLE_CAP | flags) {}

  explicit Small_buf(l4_cap_idx_t cap, unsigned long flags = 0) noexcept
  : _data(cap | L4_RCV_ITEM_SINGLE_CAP | flags) {}

  l4_umword_t raw() const noexcept { return _data; }
private:
  l4_umword_t _data;
};

class L4_EXPORT Gen_fpage
{
public:
  enum Type
  {
    Special = L4_FPAGE_SPECIAL << 4,  
    Memory  = L4_FPAGE_MEMORY  << 4,  
    Io      = L4_FPAGE_IO      << 4,  
    Obj     = L4_FPAGE_OBJ     << 4   
  };

  Gen_fpage(l4_umword_t base, l4_umword_t data) noexcept
  : _base(base), _data(data)
  {}

  l4_umword_t data() const noexcept { return _data; }
  l4_umword_t base_x() const noexcept { return _base; }
 
protected:
  l4_umword_t _base;
  l4_umword_t _data;
};

class Snd_fpage : public Gen_fpage
{
public:
  enum Map_type
  {
    Map   = L4_MAP_ITEM_MAP,    
    Grant = L4_MAP_ITEM_GRANT,  
  };

  enum Cacheopt
  {
    None     = 0,                          
    Cached   = L4_FPAGE_CACHEABLE   << 4,  
    Buffered = L4_FPAGE_BUFFERABLE  << 4,  
    Uncached = L4_FPAGE_UNCACHEABLE << 4   
  };

  enum Continue
  {
    Single   = 0,             
    Last     = 0,             
    More     = L4_ITEM_CONT,  
    Compound = L4_ITEM_CONT,  
  };

  Snd_fpage(l4_umword_t base = 0, l4_umword_t data = 0) noexcept
  : Gen_fpage(base, data)
  {}

  Snd_fpage(l4_fpage_t const &fp, l4_addr_t snd_base = 0,
            Map_type map_type = Map,
            Cacheopt cache = None, Continue cont = Last) noexcept
  : Gen_fpage(L4_ITEM_MAP | (snd_base & (~0UL << 12)) | l4_umword_t(map_type)
                | l4_umword_t(cache) | l4_umword_t(cont),
              fp.raw)
  {}

  Snd_fpage(L4::Cap<void> cap, unsigned rights, Map_type map_type = Map) noexcept
  : Gen_fpage(L4_ITEM_MAP | l4_umword_t(map_type) | (rights & 0xf0),
              cap.fpage(rights).raw)
  {}

  static Snd_fpage obj(l4_cap_idx_t base, int order,
                       unsigned char rights,
                       l4_addr_t snd_base = 0,
                       Map_type map_type = Map,
                       Continue cont = Last) noexcept
  {
    return Snd_fpage(l4_obj_fpage(base, order, rights), snd_base,
                     map_type, None, cont);
  }

  static Snd_fpage mem(l4_addr_t base, int order,
                       unsigned char rights,
                       l4_addr_t snd_base = 0,
                       Map_type map_type = Map,
                       Cacheopt cache = None, Continue cont = Last) noexcept
  {
    return Snd_fpage(l4_fpage(base, order, rights), snd_base, map_type, cache,
                     cont);
  }

  static Snd_fpage io(unsigned long base, int order,
                      unsigned char rights,
                      l4_addr_t snd_base = 0,
                      Map_type map_type = Map,
                      Continue cont = Last) noexcept
  {
    return Snd_fpage(l4_fpage_set_rights(l4_iofpage(base, order), rights),
                     snd_base, map_type, None, cont);
  }

  unsigned order() const noexcept { return (_data >> 6) & 0x3f; }

  unsigned snd_order() const noexcept { return (_data >> 6) & 0x3f; }

  unsigned rcv_order() const noexcept { return (_base >> 6) & 0x3f; }

  l4_addr_t base() const noexcept { return _data & (~0UL << 12); }

  l4_addr_t snd_base() const noexcept { return _base & (~0UL << 12); }

  void snd_base(l4_addr_t b) noexcept { _base = (_base & ~(~0UL << 12)) | (b & (~0UL << 12)); }

  bool is_valid() const noexcept { return _base & L4_ITEM_MAP; }

  bool cap_received() const noexcept { return (_base & 0x3e) == 0x38; }
  bool id_received() const noexcept { return (_base & 0x3e) == 0x3c; }
  bool local_id_received() const noexcept { return (_base & 0x3e) == 0x3e; }
  bool is_compound() const noexcept { return _base & 1; }
};

class Rcv_fpage : public Gen_fpage
{
public:
  Rcv_fpage() noexcept : Gen_fpage(0, 0), _rcv_task(L4_INVALID_CAP) {}

  Rcv_fpage(l4_fpage_t const &fp, l4_addr_t snd_base = 0,
            l4_cap_idx_t rcv_task = L4_INVALID_CAP) noexcept
  : Gen_fpage(L4_ITEM_MAP | (snd_base & (~0UL << 12))
               | (l4_is_valid_cap(rcv_task) ? L4_RCV_ITEM_FORWARD_MAPPINGS : 0),
              fp.raw),
    _rcv_task(rcv_task)
  {}

  static Rcv_fpage obj(l4_cap_idx_t base, int order, l4_addr_t snd_base = 0,
                      L4::Cap<void> rcv_task = L4::Cap<void>::Invalid) noexcept
  {
    return Rcv_fpage(l4_obj_fpage(base, order, 0), snd_base,
                     rcv_task.cap());
  }

  static Rcv_fpage mem(l4_addr_t base, int order, l4_addr_t snd_base = 0,
                       L4::Cap<void> rcv_task = L4::Cap<void>::Invalid) noexcept
  {
    return Rcv_fpage(l4_fpage(base, order, 0), snd_base, rcv_task.cap());
  }

  static Rcv_fpage io(unsigned long base, int order, l4_addr_t snd_base = 0,
                      L4::Cap<void> rcv_task = L4::Cap<void>::Invalid) noexcept
  {
    return Rcv_fpage(l4_iofpage(base, order), snd_base, rcv_task.cap());
  }

  l4_cap_idx_t rcv_task() const { return _rcv_task; }

  bool forward_mappings() const noexcept
  { return _base & L4_RCV_ITEM_FORWARD_MAPPINGS; }
 
protected:
  l4_cap_idx_t _rcv_task;
};
 
 
namespace Msg {
 
template<>
struct Clnt_val_ops<L4::Ipc::Snd_fpage>
  : Clnt_noops<L4::Ipc::Snd_fpage>
{
  static int to_msg_items(char *msg, unsigned offset, unsigned limit,
                          L4::Ipc::Snd_fpage const &arg) noexcept
  { return msg_add<L4::Ipc::Snd_fpage>(msg, offset, limit, arg); }
 
  static int from_msg_items(char *msg, unsigned offset, unsigned limit,
                            L4::Ipc::Snd_fpage &arg) noexcept
  { return msg_get<L4::Ipc::Snd_fpage>(msg, offset, limit, arg); }
};
 
template<>
struct Svr_val_ops<L4::Ipc::Snd_fpage>
  : Svr_noops<L4::Ipc::Snd_fpage>
{
  static int to_svr_items(char *msg, unsigned offset, unsigned limit,
                          L4::Ipc::Snd_fpage &arg) noexcept
  { return msg_get<L4::Ipc::Snd_fpage>(msg, offset, limit, arg); }
 
  static int from_svr_items(char *msg, unsigned offset, unsigned limit,
                            L4::Ipc::Snd_fpage const &arg) noexcept
  { return msg_add(msg, offset, limit, arg); }
};
 
// Rcv_fpage are special buffer items. They are invisible on the server side
// and must be passed literally to setup the client receive buffers.
template<> struct Is_valid_rpc_type<L4::Ipc::Rcv_fpage *> : L4::Types::False {};
template<> struct Is_valid_rpc_type<L4::Ipc::Rcv_fpage &> : L4::Types::False {};
 
template<>
struct Clnt_val_ops<L4::Ipc::Rcv_fpage>
  : Clnt_noops<L4::Ipc::Rcv_fpage>
{
  static int to_msg_buffers(char *brs, unsigned offs, unsigned limit,
                            L4::Ipc::Rcv_fpage const &arg) noexcept
  {
    offs = align_to<l4_umword_t>(offs);
    unsigned words = arg.forward_mappings() ? 3 : 2;
    if (L4_UNLIKELY(!check_size<l4_umword_t>(offs, limit, words)))
      return -L4_EMSGTOOLONG;
    auto *buf = reinterpret_cast<l4_umword_t*>(brs + offs);
    *buf++ = arg.base_x();
    *buf++ = arg.data();
    if (arg.forward_mappings())
      *buf++ = arg.rcv_task();
    return offs + sizeof(l4_umword_t) * words;
  }
};
 
 
// Remove receive buffers from server-side arguments
template<> struct Elem<L4::Ipc::Rcv_fpage>
{
  using arg_type = L4::Ipc::Rcv_fpage;
  using svr_type = void;
  using svr_arg_type = void;
  static constexpr bool Is_optional = false;
  static constexpr bool Is_input = false;
  static constexpr bool Is_output = true;
};
 
// Small_buf are special buffer items. They are invisible on the server side
// and must be passed literally to setup the client receive buffers.
template<> struct Is_valid_rpc_type<L4::Ipc::Small_buf *> : L4::Types::False {};
template<> struct Is_valid_rpc_type<L4::Ipc::Small_buf &> : L4::Types::False {};
 
template<>
struct Clnt_val_ops<L4::Ipc::Small_buf>
  : Clnt_noops<L4::Ipc::Small_buf>
{
  static int to_msg_buffers(char *brs, unsigned offs, unsigned limit,
                            L4::Ipc::Small_buf const &arg) noexcept
  { return msg_add<L4::Ipc::Small_buf>(brs, offs, limit, arg); }
};
 
// Remove receive buffers from server-side arguments
template<> struct Elem<L4::Ipc::Small_buf>
{
  using arg_type = L4::Ipc::Small_buf;
  using svr_type = void;
  using svr_arg_type = void;
  static constexpr bool Is_optional = false;
  static constexpr bool Is_input = false;
  static constexpr bool Is_output = true;
};
 
} // namespace Msg
 
// L4::Cap<> handling

template<typename T> class Cap
{
  template<typename O> friend class Cap;
  l4_umword_t _cap_n_rights;
 
public:
  enum
  {
    Rights_mask = 0xff,

    Map_type_mask  = 0x100,

    Cap_mask    = L4_CAP_MASK
  };

  enum Map_type
  {
    Map   = 0,
    Grant = 0x100,
  };

  template<typename O>
  Cap(Cap<O> const &o) noexcept : _cap_n_rights(o._cap_n_rights)
  {
    L4::Cap<T>::template check_convertible_from<O>();
  }

  Cap(L4::Cap<T> cap) noexcept
  : _cap_n_rights((cap.cap() & Cap_mask) | (cap ? L4_CAP_FPAGE_R : 0))
  {}

  template<typename O>
  Cap(L4::Cap<O> cap) noexcept
  : _cap_n_rights((cap.cap() & Cap_mask) | (cap ? L4_CAP_FPAGE_R : 0))
  {
    L4::Cap<T>::template check_convertible_from<O>();
  }

  Cap() noexcept : _cap_n_rights(L4_INVALID_CAP) {}

  Cap(L4::Cap<T> cap, unsigned char rights) noexcept
  : _cap_n_rights((cap.cap() & Cap_mask) | (rights & Rights_mask)) {}

  Cap(L4::Cap<T> cap, unsigned char rights, Map_type map_type) noexcept
  : _cap_n_rights((cap.cap() & Cap_mask) | (rights & Rights_mask)
                  | (static_cast<l4_umword_t>(map_type) & Map_type_mask))
  {}

  static Cap from_ci(l4_cap_idx_t c) noexcept
  { return Cap(L4::Cap<T>(c & Cap_mask), c & Rights_mask); }

  L4::Cap<T> cap() const noexcept
  { return L4::Cap<T>(_cap_n_rights & Cap_mask); }

  unsigned rights() const noexcept
  { return _cap_n_rights & Rights_mask; }
 
  Map_type map_type() const noexcept
  { return static_cast<Map_type>(_cap_n_rights & Map_type_mask); }

  L4::Ipc::Snd_fpage fpage() const noexcept
  {
    return L4::Ipc::Snd_fpage(cap(), rights(), map_type() == Map
                                               ? Snd_fpage::Map
                                               : Snd_fpage::Grant);
  }

  bool is_valid() const noexcept
  { return !(_cap_n_rights & L4_INVALID_CAP_BIT); }
};

template<typename T>
Cap<T> make_cap(L4::Cap<T> cap, unsigned rights) noexcept
{ return Cap<T>(cap, rights); }

template<typename T>
Cap<T> make_cap_rw(L4::Cap<T> cap) noexcept
{ return Cap<T>(cap, L4_CAP_FPAGE_RW); }

template<typename T>
Cap<T> make_cap_rws(L4::Cap<T> cap) noexcept
{ return Cap<T>(cap, L4_CAP_FPAGE_RWS); }

template<typename T>
Cap<T> make_cap_full(L4::Cap<T> cap) noexcept
{ return Cap<T>(cap, L4_CAP_FPAGE_RWSD | L4_FPAGE_C_OBJ_RIGHTS); }

template<typename T>
Cap<T> make_cap_grant(L4::Cap<T> cap) noexcept
{
  return Cap<T>(cap, L4_CAP_FPAGE_RWSD | L4_FPAGE_C_OBJ_RIGHTS, Cap<T>::Grant);
}
 
// caps are special, they have an invalid representation
template<typename T> struct L4_EXPORT Opt< Cap<T> >
{
  Cap<T> _value;
  Opt() noexcept {}
  Opt(Cap<T> value) noexcept : _value(value) {}
  Opt(L4::Cap<T> value) noexcept : _value(value) {}
  Opt &operator = (Cap<T> value) noexcept
  { this->_value = value; return *this; }
  Opt &operator = (L4::Cap<T> value) noexcept
  { this->_value = value; return *this; }
 
  Cap<T> value() const noexcept { return this->_value; }
  bool is_valid() const noexcept { return this->_value.is_valid(); }
};
 
 
namespace Msg {
// prohibit L4::Cap as argument
template<typename A>
struct Is_valid_rpc_type< L4::Cap<A> > : L4::Types::False {};
 
template<typename A> struct Elem< Cap<A> >
{
  using arg_type = Cap<A>;
  using svr_type = L4::Ipc::Snd_fpage;
  using svr_arg_type = L4::Ipc::Snd_fpage;
  static constexpr bool Is_optional = false;
  static constexpr bool Is_input = true;
  static constexpr bool Is_output = false;
};
 
 
template<typename A>
struct Svr_val_ops<Cap<A>>
  : Svr_noops<Cap<A>>
{
  static int from_svr_items(char *msg, unsigned offset, unsigned limit,
                            Cap<A> const &arg) noexcept
  {
    if (L4_UNLIKELY(!arg.is_valid()))
      // do not map anything
      return msg_add(msg, offset, limit, L4::Ipc::Snd_fpage(arg.cap(), 0));
 
    return msg_add(msg, offset, limit, arg.fpage());
  }
};
 
template<typename A>
struct Clnt_val_ops<Cap<A>> :
  Clnt_noops< Cap<A> >
{
  static int to_msg_items(char *msg, unsigned offset, unsigned limit,
                          Cap<A> const &arg) noexcept
  {
    // passing an invalid cap as mandatory argument is an error
    if (L4_UNLIKELY(!arg.is_valid()))
      return -L4_EMSGMISSARG;
 
    return msg_add(msg, offset, limit, arg.fpage());
  }
};
 
template<typename A>
struct Elem<Out<L4::Cap<A> > >
{
  using arg_type = L4::Cap<A>;
  using svr_type = Ipc::Cap<A>;
  using svr_arg_type = svr_type &;
  static constexpr bool Is_optional = false;
  static constexpr bool Is_input = false;
  static constexpr bool Is_output = true;
};
 
template<typename A>
struct Clnt_val_ops< L4::Cap<A> > :
  Clnt_noops< L4::Cap<A> >
{
  static int to_msg_buffers(char *brs, unsigned offset, unsigned limit,
                            L4::Cap<A> const &arg) noexcept
  {
    if (L4_UNLIKELY(!arg.is_valid()))
      return -L4_EMSGMISSARG; // no buffer inserted
    return msg_add(brs, offset, limit, Small_buf(arg));
  }
};
 
// prohibit a UTCB pointer as normal RPC argument
template<> struct Is_valid_rpc_type<l4_utcb_t *> : L4::Types::False {};
 
} // namespace Msg
} // namespace Ipc
} // namespace L4