kernel/fiasco/src/abi/l4_msg_item.cpp

   1 INTERFACE:
   2
   3 #include "types.h"
   4 #include "l4_fpage.h"
   5
   6 /**
   7  * The first word of a message item, either a send item or a receive buffer.
   8  *
   9  * L4_msg_item is the first word of a typed message item in system calls (incl.
  10  * IPC) The L4_msg_item is usually followed by a second word. The
  11  * interpretation of the second word depends on the contents of the
  12  * L4_msg_item.
  13  *
  14  * A generic message item has the following binary layout.
  15  * \verbatim
  16  * +----------------------------+ 3 + 2 .. 1 + 0 +
  17  * |                            | t |        | c |
  18  * +----------------------------+---+--------+---+ \endverbatim
  19  *
  20  * Bit 3 (\a t) is the type bit, if t is set the item is a map
  21  * item. \note Fiasco.OC currently has no support for other types
  22  * than map items.
  23  *
  24  * Bit 0 (\a c) is the compound bit and is available
  25  * for scatter-gather behavior. For map items the \a c bit is useful
  26  * for send items only, and described afterwards.
  27  *
  28  * A map item has a more specific layout:
  29  * \verbatim
  30  * +-- x .. 12 --+- 11 .. 8 -+- 7 .. 4 -+ 3 + 2 +- 1 -+ 0 +
  31  * | hot_spot    |     SBZ   |   attr   | 1 | i | g/s | c |
  32  * +-------------+-----------+----------+---+---+-----+---+ \endverbatim
  33  *
  34  * Bit 0 (\a c), the compound bit: if this bit is set on a send map item
  35  * the next message item of the same type shall be mapped using the same
  36  * receive buffer as this send item. The caller should properly use the
  37  * \a hot_spot to avoid overlapping mappings.
  38  *
  39  * Bit 1 (\a g/s): On a send map item a set \a g bit flags a grant operation.
  40  * This means, the sender delegates access to the receiver and atomically
  41  * removes the own rights (basically a move operation). On a receive buffer
  42  * a set \a s bit flags a small object buffer. This means, the whole buffer
  43  * item is just a single buffer register in size and provides a receive buffer
  44  * for a single object mapping, the address of the buffer is stored in the
  45  * \a hot_spot.
  46  *
  47  * Bit 2 (\a i): This bit is defined for small receive buffers only, a set \a i
  48  * bit denotes that he receiver wants to avoid a full mapping.  Instead, if all
  49  * preconditions are met, the receiver will get either the label of an Ipc_gate
  50  * or a capability selector in its message registers.  A label of an Ipc_gate
  51  * is sent if and only if the receiving thread is in the same task as the
  52  * thread that is attached to the Ipc_gate.  A capability selector is received
  53  * if the sending and the receiving thread are in the same task.
  54  *
  55  * Bits 7..4 (\a attr): This bits contain extra attributes that influence the
  56  * mapping itself. For memory mapping these bits contain cachebility information.
  57  * For object mappings these bits contain extra rights on the object.
  58  *
  59  * Bits x..12 (\a hot_spot): These bits are the so called hot spot and are used
  60  * to disambiguate the cases where either the send flex page or the receive flex
  61  * page is larger that the other.
  62  */
  63 class L4_msg_item
  64 {
  65 private:
  66   enum
  67   {
  68     Addr_shift = 12, ///< number of bits an index must be shifted, or
  69                      ///  an address must be aligned to, in the control word
  70   };
  71
  72 public:
  73   /**
  74    * Additional rights for objects (capabilities) apply to the control word of L4_msg_item.
  75    */
  76   enum Obj_attribs
  77   {
  78     C_weak_ref            = 0x10, ///< Map a weak reference (not counted in the kernel)
  79     C_ref                 = 0x00, ///< Map a normal reference (counted, if not derived
  80                                   ///  from a weak reference)
  81
  82     C_obj_right_1         = 0x20, ///< Some kernel internal, object-type specific right
  83     C_obj_right_2         = 0x40, ///< Some kernel internal, object-type specific right
  84     C_obj_right_3         = 0x80, ///< Some kernel internal, object-type specific right
  85
  86     C_obj_specific_rights = C_obj_right_1 | C_obj_right_2 | C_obj_right_3,
  87     C_ctl_rights          = C_obj_specific_rights | C_weak_ref,
  88   };
  89
  90   /**
  91    * Additional flags for memory send items.
  92    *
  93    * These flags are to control the caching attributes of memory mappings.
  94    */
  95   enum Memory_attribs
  96   {
  97     Caching_opt = 0x10, ///< This flag denotes the presence of a cachability option
  98     Cached      = 0x30, ///< Map the memory cachable
  99     Buffered    = 0x50, ///< Map the memory bufferable (write combining in Intel speech)
 100     Uncached    = 0x10, ///< Map the memory fully uncachable
 101   };
 102
 103   enum Type
 104   {
 105     Map    = 8,
 106   };
 107
 108   /**
 109    * Create a message item from its binary represenation.
 110    * \param raw is the binary representation of the message item.
 111    */
 112   explicit L4_msg_item(Mword raw) : _raw(raw) {}
 113
 114   /**
 115    * Use the same receive buffer for the next send item.
 116    * \pre The item must be a send item.
 117    * \return true if the next send item shall be handled with the
 118    *         same receive buffer as this one.
 119    */
 120   Mword compound() const { return _raw & 1; }
 121
 122   /**
 123    * Get the type of the message item.
 124    * \return the type of the message item, currently Fiasco.OC
 125    *         supports map items only, see #L4_msg_item::Map).
 126    */
 127   Type type() const { return Type(_raw & 8); }
 128
 129   /**
 130    * Is the item a a void item?
 131    * \return true if the item is \a void, false if it is valid.
 132    */
 133   bool is_void() const { return _raw == 0; }
 134
 135   /**
 136    * Is the buffer item a small object buffer?
 137    * \pre The item must be a receive buffer.
 138    * \pre type() == #L4_msg_item::Map
 139    * \return true if the buffer is a single-word single-object
 140    *         receive buffer, false else.
 141    */
 142   Mword is_small_obj() const { return _raw & 2; }
 143
 144   /**
 145    * Receiver tries to receive an object ID or a
 146    * capability selector?
 147    * \pre The item must be a receive buffer.
 148    * \pre type() == #L4_msg_item::Map
 149    * \pre is_small_obj() == true
 150    * \return true if the receiver is willing to receive an object ID
 151    *         or a capability selector, if possible.
 152    */
 153   Mword is_rcv_id() const { return _raw & 4; }
 154
 155   /**
 156    * Is the map item actually a grant item?
 157    * \pre type() == #L4_msg_item::Map
 158    * \pre The item is a send item.
 159    * \return true if the sender does a grant operation.
 160    */
 161   Mword is_grant() const { return _raw & 2; }
 162
 163   /**
 164    * Get the binary representation of the item.
 165    * \return the binary representation of this item.
 166    */
 167   Mword raw() const { return _raw; }
 168
 169   /**
 170    * Get the extra attributes for the send item.
 171    * \pre The item is a send item.
 172    * \pre type() == #L4_msg_item::Map.
 173    * \return the extra attributes for this send item.
 174    *
 175    * The semantics of the extra attributes depends on
 176    * the type of the second word, the L4_fpage, of the
 177    * complete send item.
 178    * \see L4_msg_item::Memory_attribs, L4_msg_item::Obj_attribs
 179    */
 180   Mword attr() const { return _raw & 0xf0; }
 181
 182   /**
 183    * Get the value of the most significant bits of a map item.
 184    * \pre type() == #L4_msg_item::Map
 185    * \return the most significant bits (shifted by #L4_msg_item::Addr_shift).
 186    */
 187   Mword index() const { return _raw >> Addr_shift; }
 188
 189   /**
 190    * Get the most significant bits of a map item (masked).
 191    * \pre type() == #L4_msg_item::Map
 192    * \return the most significant bits (masked the lower
 193    *         #L4_msg_item::Addr_shift bits).
 194    */
 195   Mword address() const { return _raw & (~0UL << Addr_shift); }
 196
 197   /**
 198    * Get the L4_fpage that represents the small buffer item.
 199    * \pre type() == #L4_msg_item::Map
 200    * \pre is_small_obj() == true
 201    * \return the flex page (L4_fpage) representing the single
 202    *         object slot with index index().
 203    */
 204
 205   L4_fpage get_small_buf() { return L4_fpage::obj(_raw, 0, attr() >> 4); }
 206
 207   /**
 208    * Create a map item.
 209    * \param base the hot spot address of the map item.
 210    */
 211   static L4_msg_item map(Mword base) { return L4_msg_item(base | Map); }
 212
 213 private:
 214   /**
 215    * The binary representation.
 216    */
 217   Mword _raw;
 218 };