dpdk-ipsec-nodes multiarch: nodes are formatted in VLIB_NODE_FN style
[vpp.git] / src / vlib / buffer.h
1 /*
2  * Copyright (c) 2015 Cisco and/or its affiliates.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at:
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 /*
16  * buffer.h: VLIB buffers
17  *
18  * Copyright (c) 2008 Eliot Dresselhaus
19  *
20  * Permission is hereby granted, free of charge, to any person obtaining
21  * a copy of this software and associated documentation files (the
22  * "Software"), to deal in the Software without restriction, including
23  * without limitation the rights to use, copy, modify, merge, publish,
24  * distribute, sublicense, and/or sell copies of the Software, and to
25  * permit persons to whom the Software is furnished to do so, subject to
26  * the following conditions:
27  *
28  * The above copyright notice and this permission notice shall be
29  * included in all copies or substantial portions of the Software.
30  *
31  *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
32  *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
33  *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
34  *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
35  *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
36  *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
37  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
38  */
39
40 #ifndef included_vlib_buffer_h
41 #define included_vlib_buffer_h
42
43 #include <vppinfra/types.h>
44 #include <vppinfra/cache.h>
45 #include <vppinfra/serialize.h>
46 #include <vppinfra/vector.h>
47 #include <vppinfra/lock.h>
48 #include <vlib/error.h>         /* for vlib_error_t */
49
50 #include <vlib/config.h>        /* for __PRE_DATA_SIZE */
51 #define VLIB_BUFFER_DATA_SIZE           (2048)
52 #define VLIB_BUFFER_PRE_DATA_SIZE       __PRE_DATA_SIZE
53
54 /* Minimum buffer chain segment size. Does not apply to last buffer in chain.
55    Dataplane code can safely asume that specified amount of data is not split
56    into 2 chained buffers */
57 #define VLIB_BUFFER_MIN_CHAIN_SEG_SIZE  (128)
58
59 /* Amount of head buffer data copied to each replica head buffer */
60 #define VLIB_BUFFER_CLONE_HEAD_SIZE (256)
61
62 typedef u8 vlib_buffer_free_list_index_t;
63
64 /** \file
65     vlib buffer structure definition and a few select
66     access methods. This structure and the buffer allocation
67     mechanism should perhaps live in vnet, but it would take a lot
68     of typing to make it so.
69 */
70
71 /**
72  * Buffer Flags
73  */
74 #define foreach_vlib_buffer_flag \
75   _( 0, NON_DEFAULT_FREELIST, "non-default-fl")         \
76   _( 1, IS_TRACED, 0)                                   \
77   _( 2, NEXT_PRESENT, 0)                                \
78   _( 3, TOTAL_LENGTH_VALID, 0)                          \
79   _( 4, EXT_HDR_VALID, "ext-hdr-valid")
80
81 /* NOTE: only buffer generic flags should be defined here, please consider
82    using user flags. i.e. src/vnet/buffer.h */
83
84 enum
85 {
86 #define _(bit, name, v) VLIB_BUFFER_##name  = (1 << (bit)),
87   foreach_vlib_buffer_flag
88 #undef _
89 };
90
91 enum
92 {
93 #define _(bit, name, v) VLIB_BUFFER_LOG2_##name  = (bit),
94   foreach_vlib_buffer_flag
95 #undef _
96 };
97
98   /* User defined buffer flags. */
99 #define LOG2_VLIB_BUFFER_FLAG_USER(n) (32 - (n))
100 #define VLIB_BUFFER_FLAG_USER(n) (1 << LOG2_VLIB_BUFFER_FLAG_USER(n))
101
102 /* VLIB buffer representation. */
103 typedef struct
104 {
105   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
106   STRUCT_MARK (template_start);
107   /* Offset within data[] that we are currently processing.
108      If negative current header points into predata area. */
109   i16 current_data;  /**< signed offset in data[], pre_data[]
110                         that we are currently processing.
111                         If negative current header points into predata area.
112                      */
113   u16 current_length;  /**< Nbytes between current data and
114                           the end of this buffer.
115                        */
116   u32 flags; /**< buffer flags:
117                 <br> VLIB_BUFFER_FREE_LIST_INDEX_MASK: bits used to store free list index,
118                 <br> VLIB_BUFFER_IS_TRACED: trace this buffer.
119                 <br> VLIB_BUFFER_NEXT_PRESENT: this is a multi-chunk buffer.
120                 <br> VLIB_BUFFER_TOTAL_LENGTH_VALID: as it says
121                 <br> VLIB_BUFFER_EXT_HDR_VALID: buffer contains valid external buffer manager header,
122                 set to avoid adding it to a flow report
123                 <br> VLIB_BUFFER_FLAG_USER(n): user-defined bit N
124              */
125
126   u32 flow_id;  /**< Generic flow identifier */
127
128
129   u32 next_buffer;   /**< Next buffer for this linked-list of buffers.
130                         Only valid if VLIB_BUFFER_NEXT_PRESENT flag is set.
131                      */
132
133     STRUCT_MARK (template_end);
134
135   u32 current_config_index; /**< Used by feature subgraph arcs to
136                                visit enabled feature nodes
137                             */
138   vlib_error_t error;   /**< Error code for buffers to be enqueued
139                            to error handler.
140                         */
141   u8 n_add_refs; /**< Number of additional references to this buffer. */
142
143   u8 buffer_pool_index; /**< index of buffer pool this buffer belongs. */
144
145   u32 opaque[10]; /**< Opaque data used by sub-graphs for their own purposes.
146                     See .../vnet/vnet/buffer.h
147                  */
148     CLIB_CACHE_LINE_ALIGN_MARK (cacheline1);
149
150   u32 trace_index; /**< Specifies index into trace buffer
151                       if VLIB_PACKET_IS_TRACED flag is set.
152                    */
153   u32 recycle_count; /**< Used by L2 path recycle code */
154
155   u32 total_length_not_including_first_buffer;
156   /**< Only valid for first buffer in chain. Current length plus
157      total length given here give total number of bytes in buffer chain.
158   */
159   vlib_buffer_free_list_index_t free_list_index; /** < only used if
160                                                    VLIB_BUFFER_NON_DEFAULT_FREELIST
161                                                    flag is set */
162   u8 align_pad[3]; /**< available */
163   u32 opaque2[12];  /**< More opaque data, see ../vnet/vnet/buffer.h */
164
165   /***** end of second cache line */
166     CLIB_CACHE_LINE_ALIGN_MARK (cacheline2);
167   u8 pre_data[VLIB_BUFFER_PRE_DATA_SIZE];  /**< Space for inserting data
168                                                before buffer start.
169                                                Packet rewrite string will be
170                                                rewritten backwards and may extend
171                                                back before buffer->data[0].
172                                                Must come directly before packet data.
173                                             */
174
175   u8 data[0]; /**< Packet data. Hardware DMA here */
176 } vlib_buffer_t;                /* Must be a multiple of 64B. */
177
178 #define VLIB_BUFFER_HDR_SIZE  (sizeof(vlib_buffer_t) - VLIB_BUFFER_PRE_DATA_SIZE)
179
180 /** \brief Prefetch buffer metadata.
181     The first 64 bytes of buffer contains most header information
182
183     @param b - (vlib_buffer_t *) pointer to the buffer
184     @param type - LOAD, STORE. In most cases, STORE is the right answer
185 */
186
187 #define vlib_prefetch_buffer_header(b,type) CLIB_PREFETCH (b, 64, type)
188 #define vlib_prefetch_buffer_data(b,type) \
189   CLIB_PREFETCH (vlib_buffer_get_current(b), CLIB_CACHE_LINE_BYTES, type)
190
191 always_inline void
192 vlib_buffer_struct_is_sane (vlib_buffer_t * b)
193 {
194   ASSERT (sizeof (b[0]) % 64 == 0);
195
196   /* Rewrite data must be before and contiguous with packet data. */
197   ASSERT (b->pre_data + VLIB_BUFFER_PRE_DATA_SIZE == b->data);
198 }
199
200 always_inline uword
201 vlib_buffer_get_va (vlib_buffer_t * b)
202 {
203   return pointer_to_uword (b->data);
204 }
205
206 /** \brief Get pointer to current data to process
207
208     @param b - (vlib_buffer_t *) pointer to the buffer
209     @return - (void *) (b->data + b->current_data)
210 */
211
212 always_inline void *
213 vlib_buffer_get_current (vlib_buffer_t * b)
214 {
215   /* Check bounds. */
216   ASSERT ((signed) b->current_data >= (signed) -VLIB_BUFFER_PRE_DATA_SIZE);
217   return b->data + b->current_data;
218 }
219
220 always_inline uword
221 vlib_buffer_get_current_va (vlib_buffer_t * b)
222 {
223   return vlib_buffer_get_va (b) + b->current_data;
224 }
225
226 /** \brief Advance current data pointer by the supplied (signed!) amount
227
228     @param b - (vlib_buffer_t *) pointer to the buffer
229     @param l - (word) signed increment
230 */
231 always_inline void
232 vlib_buffer_advance (vlib_buffer_t * b, word l)
233 {
234   ASSERT (b->current_length >= l);
235   b->current_data += l;
236   b->current_length -= l;
237
238   ASSERT ((b->flags & VLIB_BUFFER_NEXT_PRESENT) == 0 ||
239           b->current_length >= VLIB_BUFFER_MIN_CHAIN_SEG_SIZE);
240 }
241
242 /** \brief Check if there is enough space in buffer to advance
243
244     @param b - (vlib_buffer_t *) pointer to the buffer
245     @param l - (word) size to check
246     @return - 0 if there is less space than 'l' in buffer
247 */
248 always_inline u8
249 vlib_buffer_has_space (vlib_buffer_t * b, word l)
250 {
251   return b->current_length >= l;
252 }
253
254 /** \brief Reset current header & length to state they were in when
255     packet was received.
256
257     @param b - (vlib_buffer_t *) pointer to the buffer
258 */
259
260 always_inline void
261 vlib_buffer_reset (vlib_buffer_t * b)
262 {
263   b->current_length += clib_max (b->current_data, 0);
264   b->current_data = 0;
265 }
266
267 /** \brief Get pointer to buffer's opaque data array
268
269     @param b - (vlib_buffer_t *) pointer to the buffer
270     @return - (void *) b->opaque
271 */
272 always_inline void *
273 vlib_get_buffer_opaque (vlib_buffer_t * b)
274 {
275   return (void *) b->opaque;
276 }
277
278 /** \brief Get pointer to buffer's opaque2 data array
279
280     @param b - (vlib_buffer_t *) pointer to the buffer
281     @return - (void *) b->opaque2
282 */
283 always_inline void *
284 vlib_get_buffer_opaque2 (vlib_buffer_t * b)
285 {
286   return (void *) b->opaque2;
287 }
288
289 /** \brief Get pointer to the end of buffer's data
290  * @param b     pointer to the buffer
291  * @return      pointer to tail of packet's data
292  */
293 always_inline u8 *
294 vlib_buffer_get_tail (vlib_buffer_t * b)
295 {
296   return b->data + b->current_data + b->current_length;
297 }
298
299 /** \brief Append uninitialized data to buffer
300  * @param b     pointer to the buffer
301  * @param size  number of uninitialized bytes
302  * @return      pointer to beginning of uninitialized data
303  */
304 always_inline void *
305 vlib_buffer_put_uninit (vlib_buffer_t * b, u16 size)
306 {
307   void *p = vlib_buffer_get_tail (b);
308   /* XXX make sure there's enough space */
309   b->current_length += size;
310   return p;
311 }
312
313 /** \brief Prepend uninitialized data to buffer
314  * @param b     pointer to the buffer
315  * @param size  number of uninitialized bytes
316  * @return      pointer to beginning of uninitialized data
317  */
318 always_inline void *
319 vlib_buffer_push_uninit (vlib_buffer_t * b, u8 size)
320 {
321   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
322   b->current_data -= size;
323   b->current_length += size;
324
325   return vlib_buffer_get_current (b);
326 }
327
328 /** \brief Make head room, typically for packet headers
329  * @param b     pointer to the buffer
330  * @param size  number of head room bytes
331  * @return      pointer to start of buffer (current data)
332  */
333 always_inline void *
334 vlib_buffer_make_headroom (vlib_buffer_t * b, u8 size)
335 {
336   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
337   b->current_data += size;
338   return vlib_buffer_get_current (b);
339 }
340
341 /** \brief Retrieve bytes from buffer head
342  * @param b     pointer to the buffer
343  * @param size  number of bytes to pull
344  * @return      pointer to start of buffer (current data)
345  */
346 always_inline void *
347 vlib_buffer_pull (vlib_buffer_t * b, u8 size)
348 {
349   if (b->current_length + VLIB_BUFFER_PRE_DATA_SIZE < size)
350     return 0;
351
352   void *data = vlib_buffer_get_current (b);
353   vlib_buffer_advance (b, size);
354   return data;
355 }
356
357 /* Forward declaration. */
358 struct vlib_main_t;
359
360 typedef struct vlib_buffer_free_list_t
361 {
362   /* Template buffer used to initialize first 16 bytes of buffers
363      allocated on this free list. */
364   vlib_buffer_t buffer_init_template;
365
366   /* Our index into vlib_main_t's buffer_free_list_pool. */
367   vlib_buffer_free_list_index_t index;
368
369   /* Number of data bytes for buffers in this free list. */
370   u32 n_data_bytes;
371
372   /* Number of buffers to allocate when we need to allocate new buffers */
373   u32 min_n_buffers_each_alloc;
374
375   /* Total number of buffers allocated from this free list. */
376   u32 n_alloc;
377
378   /* Vector of free buffers.  Each element is a byte offset into I/O heap. */
379   u32 *buffers;
380
381   /* index of buffer pool used to get / put buffers */
382   u8 buffer_pool_index;
383
384   /* Free list name. */
385   u8 *name;
386
387   /* Callback functions to initialize newly allocated buffers.
388      If null buffers are zeroed. */
389   void (*buffer_init_function) (struct vlib_main_t * vm,
390                                 struct vlib_buffer_free_list_t * fl,
391                                 u32 * buffers, u32 n_buffers);
392
393   uword buffer_init_function_opaque;
394 } __attribute__ ((aligned (16))) vlib_buffer_free_list_t;
395
396 typedef uword (vlib_buffer_fill_free_list_cb_t) (struct vlib_main_t * vm,
397                                                  vlib_buffer_free_list_t * fl,
398                                                  uword min_free_buffers);
399 typedef void (vlib_buffer_free_cb_t) (struct vlib_main_t * vm, u32 * buffers,
400                                       u32 n_buffers);
401 typedef void (vlib_buffer_free_no_next_cb_t) (struct vlib_main_t * vm,
402                                               u32 * buffers, u32 n_buffers);
403
404 typedef struct
405 {
406   vlib_buffer_fill_free_list_cb_t *vlib_buffer_fill_free_list_cb;
407   vlib_buffer_free_cb_t *vlib_buffer_free_cb;
408   vlib_buffer_free_no_next_cb_t *vlib_buffer_free_no_next_cb;
409   void (*vlib_packet_template_init_cb) (struct vlib_main_t * vm, void *t,
410                                         void *packet_data,
411                                         uword n_packet_data_bytes,
412                                         uword
413                                         min_n_buffers_each_physmem_alloc,
414                                         u8 * name);
415   void (*vlib_buffer_delete_free_list_cb) (struct vlib_main_t * vm,
416                                            vlib_buffer_free_list_index_t
417                                            free_list_index);
418 } vlib_buffer_callbacks_t;
419
420 extern vlib_buffer_callbacks_t *vlib_buffer_callbacks;
421
422 typedef struct
423 {
424   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
425   uword start;
426   uword size;
427   uword log2_page_size;
428   u32 physmem_map_index;
429   u32 buffer_size;
430   u32 *buffers;
431   clib_spinlock_t lock;
432 } vlib_buffer_pool_t;
433
434 typedef struct
435 {
436   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
437   /* Virtual memory address and size of buffer memory, used for calculating
438      buffer index */
439   uword buffer_mem_start;
440   uword buffer_mem_size;
441   vlib_buffer_pool_t *buffer_pools;
442
443   /* Buffer free callback, for subversive activities */
444     u32 (*buffer_free_callback) (struct vlib_main_t * vm,
445                                  u32 * buffers,
446                                  u32 n_buffers, u32 follow_buffer_next);
447 #define VLIB_BUFFER_DEFAULT_FREE_LIST_INDEX (0)
448 #define VLIB_BUFFER_DEFAULT_FREE_LIST_BYTES VLIB_BUFFER_DATA_SIZE
449
450   /* Hash table mapping buffer size (rounded to next unit of
451      sizeof (vlib_buffer_t)) to free list index. */
452   uword *free_list_by_size;
453
454   /* Hash table mapping buffer index into number
455      0 => allocated but free, 1 => allocated and not-free.
456      If buffer index is not in hash table then this buffer
457      has never been allocated. */
458   uword *buffer_known_hash;
459   clib_spinlock_t buffer_known_hash_lockp;
460
461   /* Callbacks */
462   vlib_buffer_callbacks_t cb;
463   int callbacks_registered;
464 } vlib_buffer_main_t;
465
466 extern vlib_buffer_main_t buffer_main;
467
468 static_always_inline vlib_buffer_pool_t *
469 vlib_buffer_pool_get (u8 buffer_pool_index)
470 {
471   vlib_buffer_main_t *bm = &buffer_main;
472   return vec_elt_at_index (bm->buffer_pools, buffer_pool_index);
473 }
474
475 u8 vlib_buffer_register_physmem_map (struct vlib_main_t * vm,
476                                      u32 physmem_map_index);
477
478 clib_error_t *vlib_buffer_main_init (struct vlib_main_t *vm);
479
480 typedef struct
481 {
482   struct vlib_main_t *vlib_main;
483
484   u32 first_buffer, last_buffer;
485
486   union
487   {
488     struct
489     {
490       /* Total accumulated bytes in chain starting with first_buffer. */
491       u32 n_total_data_bytes;
492
493       /* Max number of bytes to accumulate in chain starting with first_buffer.
494          As this limit is reached buffers are enqueued to next node. */
495       u32 max_n_data_bytes_per_chain;
496
497       /* Next node to enqueue buffers to relative to current process node. */
498       u32 next_index;
499
500       /* Free list to use to allocate new buffers. */
501       vlib_buffer_free_list_index_t free_list_index;
502     } tx;
503
504     struct
505     {
506       /* CLIB fifo of buffer indices waiting to be unserialized. */
507       u32 *buffer_fifo;
508
509       /* Event type used to signal that RX buffers have been added to fifo. */
510       uword ready_one_time_event;
511     } rx;
512   };
513 } vlib_serialize_buffer_main_t;
514
515 void serialize_open_vlib_buffer (serialize_main_t * m, struct vlib_main_t *vm,
516                                  vlib_serialize_buffer_main_t * sm);
517 void unserialize_open_vlib_buffer (serialize_main_t * m,
518                                    struct vlib_main_t *vm,
519                                    vlib_serialize_buffer_main_t * sm);
520
521 u32 serialize_close_vlib_buffer (serialize_main_t * m);
522 void unserialize_close_vlib_buffer (serialize_main_t * m);
523 void *vlib_set_buffer_free_callback (struct vlib_main_t *vm, void *fp);
524
525 always_inline u32
526 serialize_vlib_buffer_n_bytes (serialize_main_t * m)
527 {
528   serialize_stream_t *s = &m->stream;
529   vlib_serialize_buffer_main_t *sm
530     = uword_to_pointer (m->stream.data_function_opaque,
531                         vlib_serialize_buffer_main_t *);
532   return sm->tx.n_total_data_bytes + s->current_buffer_index +
533     vec_len (s->overflow_buffer);
534 }
535
536 /*
537  */
538
539 /** \brief Compile time buffer trajectory tracing option
540     Turn this on if you run into "bad monkey" contexts,
541     and you want to know exactly which nodes they've visited...
542     See vlib/main.c...
543 */
544 #define VLIB_BUFFER_TRACE_TRAJECTORY 0
545
546 #if VLIB_BUFFER_TRACE_TRAJECTORY > 0
547 extern void (*vlib_buffer_trace_trajectory_cb) (vlib_buffer_t * b, u32 index);
548 extern void (*vlib_buffer_trace_trajectory_init_cb) (vlib_buffer_t * b);
549 extern void vlib_buffer_trace_trajectory_init (vlib_buffer_t * b);
550 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b) \
551   vlib_buffer_trace_trajectory_init (b);
552 #else
553 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b)
554 #endif /* VLIB_BUFFER_TRACE_TRAJECTORY */
555
556 #endif /* included_vlib_buffer_h */
557
558 #define VLIB_BUFFER_REGISTER_CALLBACKS(x,...)                           \
559     __VA_ARGS__ vlib_buffer_callbacks_t __##x##_buffer_callbacks;       \
560 static void __vlib_add_buffer_callbacks_t_##x (void)                    \
561     __attribute__((__constructor__)) ;                                  \
562 static void __vlib_add_buffer_callbacks_t_##x (void)                    \
563 {                                                                       \
564     if (vlib_buffer_callbacks)                                          \
565       clib_panic ("vlib buffer callbacks already registered");          \
566     vlib_buffer_callbacks = &__##x##_buffer_callbacks;                  \
567 }                                                                       \
568 static void __vlib_rm_buffer_callbacks_t_##x (void)                     \
569     __attribute__((__destructor__)) ;                                   \
570 static void __vlib_rm_buffer_callbacks_t_##x (void)                     \
571 { vlib_buffer_callbacks = 0; }                                          \
572 __VA_ARGS__ vlib_buffer_callbacks_t __##x##_buffer_callbacks
573
574 /*
575  * fd.io coding-style-patch-verification: ON
576  *
577  * Local Variables:
578  * eval: (c-set-style "gnu")
579  * End:
580  */