docs/developer/corearchitecture/buffer_metadata.rst

   1 Buffer Metadata
   2 ===============
   3
   4 Each vlib_buffer_t (packet buffer) carries buffer metadata which
   5 describes the current packet-processing state. The underlying techniques
   6 have been used for decades, across multiple packet processing
   7 environments.
   8
   9 We will examine vpp buffer metadata in some detail, but folks who need
  10 to manipulate and/or extend the scheme should expect to do a certain
  11 level of code inspection.
  12
  13 Vlib (Vector library) primary buffer metadata
  14 ---------------------------------------------
  15
  16 The first 64 octets of each vlib_buffer_t carries the primary buffer
  17 metadata. See …/src/vlib/buffer.h for full details.
  18
  19 Important fields:
  20
  21 -  i16 current_data: the signed offset in data[], pre_data[] that we are
  22    currently processing. If negative current header points into the
  23    pre-data (rewrite space) area.
  24 -  u16 current_length: nBytes between current_data and the end of this
  25    buffer.
  26 -  u32 flags: Buffer flag bits. Heavily used, not many bits left
  27
  28    -  src/vlib/buffer.h flag bits
  29
  30       -  VLIB_BUFFER_IS_TRACED: buffer is traced
  31       -  VLIB_BUFFER_NEXT_PRESENT: buffer has multiple chunks
  32       -  VLIB_BUFFER_TOTAL_LENGTH_VALID:
  33          total_length_not_including_first_buffer is valid (see below)
  34
  35    -  src/vnet/buffer.h flag bits
  36
  37       -  VNET_BUFFER_F_L4_CHECKSUM_COMPUTED: tcp/udp checksum has been
  38          computed
  39       -  VNET_BUFFER_F_L4_CHECKSUM_CORRECT: tcp/udp checksum is correct
  40       -  VNET_BUFFER_F_VLAN_2_DEEP: two vlan tags present
  41       -  VNET_BUFFER_F_VLAN_1_DEEP: one vlan tag present
  42       -  VNET_BUFFER_F_SPAN_CLONE: packet has already been cloned (span
  43          feature)
  44       -  VNET_BUFFER_F_LOOP_COUNTER_VALID: packet look-up loop count
  45          valid
  46       -  VNET_BUFFER_F_LOCALLY_ORIGINATED: packet built by vpp
  47       -  VNET_BUFFER_F_IS_IP4: packet is ipv4, for checksum offload
  48       -  VNET_BUFFER_F_IS_IP6: packet is ipv6, for checksum offload
  49       -  VNET_BUFFER_F_OFFLOAD_IP_CKSUM: hardware ip checksum offload
  50          requested
  51       -  VNET_BUFFER_F_OFFLOAD_TCP_CKSUM: hardware tcp checksum offload
  52          requested
  53       -  VNET_BUFFER_F_OFFLOAD_UDP_CKSUM: hardware udp checksum offload
  54          requested
  55       -  VNET_BUFFER_F_IS_NATED: natted packet, skip input checks
  56       -  VNET_BUFFER_F_L2_HDR_OFFSET_VALID: L2 header offset valid
  57       -  VNET_BUFFER_F_L3_HDR_OFFSET_VALID: L3 header offset valid
  58       -  VNET_BUFFER_F_L4_HDR_OFFSET_VALID: L4 header offset valid
  59       -  VNET_BUFFER_F_FLOW_REPORT: packet is an ipfix packet
  60       -  VNET_BUFFER_F_IS_DVR: packet to be reinjected into the l2
  61          output path
  62       -  VNET_BUFFER_F_QOS_DATA_VALID: QoS data valid in
  63          vnet_buffer_opaque2
  64       -  VNET_BUFFER_F_GSO: generic segmentation offload requested
  65       -  VNET_BUFFER_F_AVAIL1: available bit
  66       -  VNET_BUFFER_F_AVAIL2: available bit
  67       -  VNET_BUFFER_F_AVAIL3: available bit
  68       -  VNET_BUFFER_F_AVAIL4: available bit
  69       -  VNET_BUFFER_F_AVAIL5: available bit
  70       -  VNET_BUFFER_F_AVAIL6: available bit
  71       -  VNET_BUFFER_F_AVAIL7: available bit
  72
  73 -  u32 flow_id: generic flow identifier
  74 -  u8 ref_count: buffer reference / clone count (e.g. for span
  75    replication)
  76 -  u8 buffer_pool_index: buffer pool index which owns this buffer
  77 -  vlib_error_t (u16) error: error code for buffers enqueued to error
  78    handler
  79 -  u32 next_buffer: buffer index of next buffer in chain. Only valid if
  80    VLIB_BUFFER_NEXT_PRESENT is set
  81 -  union
  82
  83    -  u32 current_config_index: current index on feature arc
  84    -  u32 punt_reason: reason code once packet punted. Mutually
  85       exclusive with current_config_index
  86
  87 -  u32 opaque[10]: primary vnet-layer opaque data (see below)
  88 -  END of first cache line / data initialized by the buffer allocator
  89 -  u32 trace_index: buffer’s index in the packet trace subsystem
  90 -  u32 total_length_not_including_first_buffer: see
  91    VLIB_BUFFER_TOTAL_LENGTH_VALID above
  92 -  u32 opaque2[14]: secondary vnet-layer opaque data (see below)
  93 -  u8 pre_data[VLIB_BUFFER_PRE_DATA_SIZE]: rewrite space, often used to
  94    prepend tunnel encapsulations
  95 -  u8 data[0]: buffer data received from the wire. Ordinarily, hardware
  96    devices use b->data[0] as the DMA target but there are exceptions. Do
  97    not write code which blindly assumes that packet data starts in
  98    b->data[0]. Use vlib_buffer_get_current(…).
  99
 100 Vnet (network stack) primary buffer metadata
 101 --------------------------------------------
 102
 103 Vnet primary buffer metadata occupies space reserved in the vlib opaque
 104 field shown above, and has the type name vnet_buffer_opaque_t.
 105 Ordinarily accessed using the vnet_buffer(b) macro. See
 106 ../src/vnet/buffer.h for full details.
 107
 108 Important fields:
 109
 110 -  u32 sw_if_index[2]: RX and TX interface handles. At the ip lookup
 111    stage, vnet_buffer(b)->sw_if_index[VLIB_TX] is interpreted as a FIB
 112    index.
 113 -  i16 l2_hdr_offset: offset from b->data[0] of the packet L2 header.
 114    Valid only if b->flags & VNET_BUFFER_F_L2_HDR_OFFSET_VALID is set
 115 -  i16 l3_hdr_offset: offset from b->data[0] of the packet L3 header.
 116    Valid only if b->flags & VNET_BUFFER_F_L3_HDR_OFFSET_VALID is set
 117 -  i16 l4_hdr_offset: offset from b->data[0] of the packet L4 header.
 118    Valid only if b->flags & VNET_BUFFER_F_L4_HDR_OFFSET_VALID is set
 119 -  u8 feature_arc_index: feature arc that the packet is currently
 120    traversing
 121 -  union
 122
 123    -  ip
 124
 125       -  u32 adj_index[2]: adjacency from dest IP lookup in [VLIB_TX],
 126          adjacency from source ip lookup in [VLIB_RX], set to ~0 until
 127          source lookup done
 128       -  union
 129
 130          -  generic fields
 131          -  ICMP fields
 132          -  reassembly fields
 133
 134    -  mpls fields
 135    -  l2 bridging fields, only valid in the L2 path
 136    -  l2tpv3 fields
 137    -  l2 classify fields
 138    -  vnet policer fields
 139    -  MAP fields
 140    -  MAP-T fields
 141    -  ip fragmentation fields
 142    -  COP (whitelist/blacklist filter) fields
 143    -  LISP fields
 144    -  TCP fields
 145
 146       -  connection index
 147       -  sequence numbers
 148       -  header and data offsets
 149       -  data length
 150       -  flags
 151
 152    -  SCTP fields
 153    -  NAT fields
 154    -  u32 unused[6]
 155
 156 Vnet (network stack) secondary buffer metadata
 157 ----------------------------------------------
 158
 159 Vnet primary buffer metadata occupies space reserved in the vlib opaque2
 160 field shown above, and has the type name vnet_buffer_opaque2_t.
 161 Ordinarily accessed using the vnet_buffer2(b) macro. See
 162 ../src/vnet/buffer.h for full details.
 163
 164 Important fields:
 165
 166 -  qos fields
 167
 168    -  u8 bits
 169    -  u8 source
 170
 171 -  u8 loop_counter: used to detect and report internal forwarding loops
 172 -  group-based policy fields
 173
 174    -  u8 flags
 175    -  u16 sclass: the packet’s source class
 176
 177 -  u16 gso_size: L4 payload size, persists all the way to
 178    interface-output in case GSO is not enabled
 179 -  u16 gso_l4_hdr_sz: size of the L4 protocol header
 180 -  union
 181
 182    -  packet trajectory tracer (largely deprecated)
 183
 184       -  u16 \*trajectory_trace; only #if VLIB_BUFFER_TRACE_TRAJECTORY >
 185          0
 186
 187    -  packet generator
 188
 189       -  u64 pg_replay_timestamp: timestamp for replayed pcap trace
 190          packets
 191
 192    -  u32 unused[8]
 193
 194 Buffer Metadata Extensions
 195 --------------------------
 196
 197 Plugin developers may wish to extend either the primary or secondary
 198 vnet buffer opaque unions. Please perform a manual live variable
 199 analysis, otherwise nodes which use shared buffer metadata space may
 200 break things.
 201
 202 It’s not OK to add plugin or proprietary metadata to the core vpp engine
 203 header files named above. Instead, proceed as follows. The example
 204 concerns the vnet primary buffer opaque union vlib_buffer_opaque_t. It’s
 205 a very simple variation to use the vnet secondary buffer opaque union
 206 vlib_buffer_opaque2_t.
 207
 208 In a plugin header file:
 209
 210 ::
 211
 212        /* Add arbitrary buffer metadata */
 213        #include <vnet/buffer.h>
 214
 215        typedef struct
 216        {
 217          u32 my_stuff[6];
 218        } my_buffer_opaque_t;
 219
 220        STATIC_ASSERT (sizeof (my_buffer_opaque_t) <=
 221                       STRUCT_SIZE_OF (vnet_buffer_opaque_t, unused),
 222                       "Custom meta-data too large for vnet_buffer_opaque_t");
 223
 224        #define my_buffer_opaque(b)  \
 225          ((my_buffer_opaque_t *)((u8 *)((b)->opaque) + STRUCT_OFFSET_OF (vnet_buffer_opaque_t, unused)))
 226
 227 To set data in the custom buffer opaque type given a vlib_buffer_t \*b:
 228
 229 ::
 230
 231        my_buffer_opaque (b)->my_stuff[2] = 123;
 232
 233 To read data from the custom buffer opaque type:
 234
 235 ::
 236
 237        stuff0 = my_buffer_opaque (b)->my_stuff[2];