src/ceph/doc/dev/network-encoding.rst

   1 ==================
   2  Network Encoding
   3 ==================
   4
   5 This describes the encoding used to serialize data.  It doesn't cover specific
   6 objects/messages but focuses on the base types.
   7
   8 The types are not self documenting in any way.  They can not be decoded unless
   9 you know what they are.
  10
  11 Conventions
  12 ===========
  13
  14 Integers
  15 --------
  16
  17 The integer types used will be named ``{signed}{size}{endian}``.  For example
  18 ``u16le`` is an unsigned 16 bit integer encoded in little endian byte order
  19 while ``s64be`` is a signed 64 bit integer in big endian.  Additionally ``u8``
  20 and ``s8`` will represent signed and unsigned bytes respectively.  Signed
  21 integers use two's complement encoding.
  22
  23 Complex Types
  24 -------------
  25
  26 This document will use a c-like syntax for describing structures.  The
  27 structure represents the data that will go over the wire.  There will be no
  28 padding between the elements and the elements will be sent in the order they
  29 appear.  For example::
  30
  31         struct foo {
  32                 u8    tag;
  33                 u32le data;
  34         }
  35
  36 When encoding the values ``0x05`` and ``0x12345678`` respectively will appear on
  37 the wire as ``05 78 56 34 12``.
  38
  39 Variable Arrays
  40 ---------------
  41
  42 Unlike c, length arrays can be used anywhere in structures and will be inline in
  43 the protocol.  Furthermore the length may be described using an earlier item in
  44 the structure.
  45
  46 ::
  47
  48         struct blob {
  49                 u32le size;
  50                 u8    data[size];
  51                 u32le checksum;
  52         }
  53
  54 This structure is encoded as a 32 bit size, followed by ``size`` data bytes,
  55 then a 32 bit checksum.
  56
  57 Primitive Aliases
  58 -----------------
  59
  60 These types are just aliases for primitive types.
  61
  62 ::
  63
  64         // From /src/include/types.h
  65
  66         typedef u32le epoch_t;
  67         typedef u32le ceph_seq_t;
  68         typedef u64le ceph_tid_t;
  69         typedef u64le version_t;
  70
  71
  72 Structures
  73 ==========
  74
  75 These are the way structures are encoded.  Note that these structures don't
  76 actually exist in the source but are the way that different types are encoded.
  77
  78 Optional
  79 --------
  80
  81 Optionals are represented as a presence byte, followed by the item if it exists.
  82
  83 ::
  84
  85         struct ceph_optional<T> {
  86                 u8 present;
  87                 T  element[present? 1 : 0]; // Only if present is non-zero.
  88         }
  89
  90 Optionals are used to encode ``boost::optional``.
  91
  92 Pair
  93 ----
  94
  95 Pairs are simply the first item followed by the second.
  96
  97 ::
  98
  99         struct ceph_pair<A,B> {
 100                 A a;
 101                 B b;
 102         }
 103
 104 Pairs are used to encode ``std::pair``.
 105
 106 Triple
 107 ------
 108
 109 Triples are simply the tree elements one after another.
 110
 111 ::
 112
 113         struct ceph_triple<A,B,C> {
 114                 A a;
 115                 B b;
 116                 C c;
 117         }
 118
 119 Triples are used to encode ``ceph::triple``.
 120
 121
 122 List
 123 ----
 124
 125 Lists are represented as an element count followed by that many elements.
 126
 127 ::
 128
 129         struct ceph_list<T> {
 130                 u32le length;
 131                 T     elements[length];
 132         }
 133
 134 .. note::
 135         The size of the elements in the list are not necessarily uniform.
 136
 137 Lists are used to encode ``std::list``, ``std::vector``, ``std::deque``,
 138 ``std::set`` and ``ceph::unordered_set``.
 139
 140 Blob
 141 ----
 142
 143 A Blob is simply a list of bytes.
 144
 145 ::
 146
 147         struct ceph_string {
 148                 ceph_list<u8>;
 149         }
 150
 151         // AKA
 152
 153         struct ceph_string {
 154                 u32le size;
 155                 u8    data[size];
 156         }
 157
 158 Blobs are used to encode ``std::string``, ``const char *`` and ``bufferlist``.
 159
 160 .. note::
 161         The content of a Blob is arbratrary binary data.
 162
 163 Map
 164 ---
 165
 166 Maps are a list of pairs.
 167
 168 ::
 169
 170         struct ceph_map<K,V> {
 171                 ceph_list<ceph_pair<K,V>>;
 172         }
 173
 174         // AKA
 175
 176         struct ceph_map<K,V> {
 177                 u32le length;
 178                 ceph_pair<K,V> entries[length];
 179         }
 180
 181 Maps are used to encode ``std::map``, ``std::multimap`` and
 182 ``ceph::unordered_map``.
 183
 184 Complex Types
 185 =============
 186
 187 These aren't hard to find in the source but the common ones are listed here for
 188 convenience.
 189
 190 utime_t
 191 -------
 192
 193 ::
 194
 195         // From /src/include/utime.h
 196         struct utime_t {
 197                 u32le tv_sec;  // Seconds since epoch.
 198                 u32le tv_nsec; // Nanoseconds since the last second.
 199         }
 200
 201 ceph_entity_name
 202 ----------------
 203
 204 ::
 205
 206         // From /src/include/msgr.h
 207         struct ceph_entity_name {
 208                 u8    type; // CEPH_ENTITY_TYPE_*
 209                 u64le num;
 210         }
 211
 212         // CEPH_ENTITY_TYPE_* defined in /src/include/msgr.h
 213
 214 .. vi: textwidth=80 noexpandtab