4 Each vlib_buffer_t (packet buffer) carries buffer metadata which
5 describes the current packet-processing state. The underlying
6 techniques have been used for decades, across multiple packet
7 processing environments.
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.
13 Vlib (Vector library) primary buffer metadata
14 ----------------------------------------------
16 The first 64 octets of each vlib_buffer_t carries the primary buffer
17 metadata. See .../src/vlib/buffer.h for full details.
21 * i16 current_data: the signed offset in data[], pre_data[] that we
22 are currently processing. If negative current header points into
23 the pre-data (rewrite space) area.
24 * u16 current_length: nBytes between current_data and the end of this buffer.
25 * u32 flags: Buffer flag bits. Heavily used, not many bits left
26 * src/vlib/buffer.h flag bits
27 * VLIB_BUFFER_IS_TRACED: buffer is traced
28 * VLIB_BUFFER_NEXT_PRESENT: buffer has multiple chunks
29 * VLIB_BUFFER_TOTAL_LENGTH_VALID: total_length_not_including_first_buffer is valid (see below)
30 * src/vnet/buffer.h flag bits
31 * VNET_BUFFER_F_L4_CHECKSUM_COMPUTED: tcp/udp checksum has been computed
32 * VNET_BUFFER_F_L4_CHECKSUM_CORRECT: tcp/udp checksum is correct
33 * VNET_BUFFER_F_VLAN_2_DEEP: two vlan tags present
34 * VNET_BUFFER_F_VLAN_1_DEEP: one vlan tag present
35 * VNET_BUFFER_F_SPAN_CLONE: packet has already been cloned (span feature)
36 * VNET_BUFFER_F_LOOP_COUNTER_VALID: packet look-up loop count valid
37 * VNET_BUFFER_F_LOCALLY_ORIGINATED: packet built by vpp
38 * VNET_BUFFER_F_IS_IP4: packet is ipv4, for checksum offload
39 * VNET_BUFFER_F_IS_IP6: packet is ipv6, for checksum offload
40 * VNET_BUFFER_F_OFFLOAD_IP_CKSUM: hardware ip checksum offload requested
41 * VNET_BUFFER_F_OFFLOAD_TCP_CKSUM: hardware tcp checksum offload requested
42 * VNET_BUFFER_F_OFFLOAD_UDP_CKSUM: hardware udp checksum offload requested
43 * VNET_BUFFER_F_IS_NATED: natted packet, skip input checks
44 * VNET_BUFFER_F_L2_HDR_OFFSET_VALID: L2 header offset valid
45 * VNET_BUFFER_F_L3_HDR_OFFSET_VALID: L3 header offset valid
46 * VNET_BUFFER_F_L4_HDR_OFFSET_VALID: L4 header offset valid
47 * VNET_BUFFER_F_FLOW_REPORT: packet is an ipfix packet
48 * VNET_BUFFER_F_IS_DVR: packet to be reinjected into the l2 output path
49 * VNET_BUFFER_F_QOS_DATA_VALID: QoS data valid in vnet_buffer_opaque2
50 * VNET_BUFFER_F_GSO: generic segmentation offload requested
51 * VNET_BUFFER_F_AVAIL1: available bit
52 * VNET_BUFFER_F_AVAIL2: available bit
53 * VNET_BUFFER_F_AVAIL3: available bit
54 * VNET_BUFFER_F_AVAIL4: available bit
55 * VNET_BUFFER_F_AVAIL5: available bit
56 * VNET_BUFFER_F_AVAIL6: available bit
57 * VNET_BUFFER_F_AVAIL7: available bit
58 * u32 flow_id: generic flow identifier
59 * u8 ref_count: buffer reference / clone count (e.g. for span replication)
60 * u8 buffer_pool_index: buffer pool index which owns this buffer
61 * vlib_error_t (u16) error: error code for buffers enqueued to error handler
62 * u32 next_buffer: buffer index of next buffer in chain. Only valid if VLIB_BUFFER_NEXT_PRESENT is set
64 * u32 current_config_index: current index on feature arc
65 * u32 punt_reason: reason code once packet punted. Mutually exclusive with current_config_index
66 * u32 opaque[10]: primary vnet-layer opaque data (see below)
67 * END of first cache line / data initialized by the buffer allocator
68 * u32 trace_index: buffer's index in the packet trace subsystem
69 * u32 total_length_not_including_first_buffer: see VLIB_BUFFER_TOTAL_LENGTH_VALID above
70 * u32 opaque2[14]: secondary vnet-layer opaque data (see below)
71 * u8 pre_data[VLIB_BUFFER_PRE_DATA_SIZE]: rewrite space, often used to prepend tunnel encapsulations
72 * u8 data[0]: buffer data received from the wire. Ordinarily, hardware devices use b->data[0] as the DMA target but there are exceptions. Do not write code which blindly assumes that packet data starts in b->data[0]. Use vlib_buffer_get_current(...).
74 Vnet (network stack) primary buffer metadata
75 --------------------------------------------
77 Vnet primary buffer metadata occupies space reserved in the vlib
78 opaque field shown above, and has the type name
79 vnet_buffer_opaque_t. Ordinarily accessed using the vnet_buffer(b)
80 macro. See ../src/vnet/buffer.h for full details.
84 * u32 sw_if_index[2]: RX and TX interface handles. At the ip lookup
85 stage, vnet_buffer(b)->sw_if_index[VLIB_TX] is interpreted as a FIB
87 * i16 l2_hdr_offset: offset from b->data[0] of the packet L2 header.
88 Valid only if b->flags & VNET_BUFFER_F_L2_HDR_OFFSET_VALID is set
89 * i16 l3_hdr_offset: offset from b->data[0] of the packet L3 header.
90 Valid only if b->flags & VNET_BUFFER_F_L3_HDR_OFFSET_VALID is set
91 * i16 l4_hdr_offset: offset from b->data[0] of the packet L4 header.
92 Valid only if b->flags & VNET_BUFFER_F_L4_HDR_OFFSET_VALID is set
93 * u8 feature_arc_index: feature arc that the packet is currently traversing
96 * u32 adj_index[2]: adjacency from dest IP lookup in [VLIB_TX], adjacency
97 from source ip lookup in [VLIB_RX], set to ~0 until source lookup done
103 * l2 bridging fields, only valid in the L2 path
106 * vnet policer fields
109 * ip fragmentation fields
110 * COP (whitelist/blacklist filter) fields
115 * header and data offsets
122 Vnet (network stack) secondary buffer metadata
123 -----------------------------------------------
125 Vnet primary buffer metadata occupies space reserved in the vlib
126 opaque2 field shown above, and has the type name
127 vnet_buffer_opaque2_t. Ordinarily accessed using the vnet_buffer2(b)
128 macro. See ../src/vnet/buffer.h for full details.
135 * u8 loop_counter: used to detect and report internal forwarding loops
136 * group-based policy fields
138 * u16 sclass: the packet's source class
139 * u16 gso_size: L4 payload size, persists all the way to
140 interface-output in case GSO is not enabled
141 * u16 gso_l4_hdr_sz: size of the L4 protocol header
143 * packet trajectory tracer (largely deprecated)
144 * u16 *trajectory_trace; only #if VLIB_BUFFER_TRACE_TRAJECTORY > 0
146 * u64 pg_replay_timestamp: timestamp for replayed pcap trace packets
149 Buffer Metadata Extensions
150 ==========================
152 Plugin developers may wish to extend either the primary or secondary
153 vnet buffer opaque unions. Please perform a
154 manual live variable analysis, otherwise nodes which use shared buffer metadata space may break things.
156 It's not OK to add plugin or proprietary metadata to the core vpp
157 engine header files named above. Instead, proceed as follows. The
158 example concerns the vnet primary buffer opaque union
159 vlib_buffer_opaque_t. It's a very simple variation to use the vnet
160 secondary buffer opaque union vlib_buffer_opaque2_t.
162 In a plugin header file:
165 /* Add arbitrary buffer metadata */
166 #include <vnet/buffer.h>
171 } my_buffer_opaque_t;
173 STATIC_ASSERT (sizeof (my_buffer_opaque_t) <=
174 STRUCT_SIZE_OF (vnet_buffer_opaque_t, unused),
175 "Custom meta-data too large for vnet_buffer_opaque_t");
177 #define my_buffer_opaque(b) \
178 ((my_buffer_opaque_t *)((u8 *)((b)->opaque) + STRUCT_OFFSET_OF (vnet_buffer_opaque_t, unused)))
180 To set data in the custom buffer opaque type given a vlib_buffer_t *b:
183 my_buffer_opaque (b)->my_stuff[2] = 123;
186 To read data from the custom buffer opaque type:
189 stuff0 = my_buffer_opaque (b)->my_stuff[2];