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 typedef u8 vlib_buffer_free_list_index_t;
  55
  56 /** \file
  57     vlib buffer structure definition and a few select
  58     access methods. This structure and the buffer allocation
  59     mechanism should perhaps live in vnet, but it would take a lot
  60     of typing to make it so.
  61 */
  62
  63 /**
  64  * Buffer Flags
  65  */
  66 #define foreach_vlib_buffer_flag \
  67   _( 0, NON_DEFAULT_FREELIST, "non-default-fl")         \
  68   _( 1, IS_TRACED, 0)                                   \
  69   _( 2, NEXT_PRESENT, 0)                                \
  70   _( 3, IS_RECYCLED, "is-recycled")                     \
  71   _( 4, TOTAL_LENGTH_VALID, 0)                          \
  72   _( 5, REPL_FAIL, "repl-fail")                         \
  73   _( 6, RECYCLE, "recycle")                             \
  74   _( 7, EXT_HDR_VALID, "ext-hdr-valid")
  75
  76 /* NOTE: only buffer generic flags should be defined here, please consider
  77    using user flags. i.e. src/vnet/buffer.h */
  78
  79 enum
  80 {
  81 #define _(bit, name, v) VLIB_BUFFER_##name  = (1 << (bit)),
  82   foreach_vlib_buffer_flag
  83 #undef _
  84 };
  85
  86 enum
  87 {
  88 #define _(bit, name, v) VLIB_BUFFER_LOG2_##name  = (bit),
  89   foreach_vlib_buffer_flag
  90 #undef _
  91 };
  92
  93   /* User defined buffer flags. */
  94 #define LOG2_VLIB_BUFFER_FLAG_USER(n) (32 - (n))
  95 #define VLIB_BUFFER_FLAG_USER(n) (1 << LOG2_VLIB_BUFFER_FLAG_USER(n))
  96
  97 /* VLIB buffer representation. */
  98 typedef struct
  99 {
 100   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 101   STRUCT_MARK (template_start);
 102   /* Offset within data[] that we are currently processing.
 103      If negative current header points into predata area. */
 104   i16 current_data;  /**< signed offset in data[], pre_data[]
 105                         that we are currently processing.
 106                         If negative current header points into predata area.
 107                      */
 108   u16 current_length;  /**< Nbytes between current data and
 109                           the end of this buffer.
 110                        */
 111   u32 flags; /**< buffer flags:
 112                 <br> VLIB_BUFFER_FREE_LIST_INDEX_MASK: bits used to store free list index,
 113                 <br> VLIB_BUFFER_IS_TRACED: trace this buffer.
 114                 <br> VLIB_BUFFER_NEXT_PRESENT: this is a multi-chunk buffer.
 115                 <br> VLIB_BUFFER_TOTAL_LENGTH_VALID: as it says
 116                 <br> VLIB_BUFFER_REPL_FAIL: packet replication failure
 117                 <br> VLIB_BUFFER_RECYCLE: as it says
 118                 <br> VLIB_BUFFER_EXT_HDR_VALID: buffer contains valid external buffer manager header,
 119                 set to avoid adding it to a flow report
 120                 <br> VLIB_BUFFER_FLAG_USER(n): user-defined bit N
 121              */
 122
 123
 124     STRUCT_MARK (template_end);
 125
 126   u32 next_buffer;   /**< Next buffer for this linked-list of buffers.
 127                         Only valid if VLIB_BUFFER_NEXT_PRESENT flag is set.
 128                      */
 129
 130   vlib_error_t error;   /**< Error code for buffers to be enqueued
 131                            to error handler.
 132                         */
 133   u32 current_config_index; /**< Used by feature subgraph arcs to
 134                                visit enabled feature nodes
 135                             */
 136
 137   u8 feature_arc_index; /**< Used to identify feature arcs by intermediate
 138                            feature node
 139                         */
 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   u8 dont_waste_me[1]; /**< Available space in the (precious)
 145                           first 32 octets of buffer metadata
 146                           Before allocating any of it, discussion required!
 147                        */
 148
 149   u32 opaque[10]; /**< Opaque data used by sub-graphs for their own purposes.
 150                     See .../vnet/vnet/buffer.h
 151                  */
 152     CLIB_CACHE_LINE_ALIGN_MARK (cacheline1);
 153
 154   u32 trace_index; /**< Specifies index into trace buffer
 155                       if VLIB_PACKET_IS_TRACED flag is set.
 156                    */
 157   u32 recycle_count; /**< Used by L2 path recycle code */
 158
 159   u32 total_length_not_including_first_buffer;
 160   /**< Only valid for first buffer in chain. Current length plus
 161      total length given here give total number of bytes in buffer chain.
 162   */
 163   vlib_buffer_free_list_index_t free_list_index; /** < only used if
 164                                                    VLIB_BUFFER_NON_DEFAULT_FREELIST
 165                                                    flag is set */
 166   u8 align_pad[3]; /**< available */
 167   u32 opaque2[12];  /**< More opaque data, see ../vnet/vnet/buffer.h */
 168
 169   /***** end of second cache line */
 170     CLIB_CACHE_LINE_ALIGN_MARK (cacheline2);
 171   u8 pre_data[VLIB_BUFFER_PRE_DATA_SIZE];  /**< Space for inserting data
 172                                                before buffer start.
 173                                                Packet rewrite string will be
 174                                                rewritten backwards and may extend
 175                                                back before buffer->data[0].
 176                                                Must come directly before packet data.
 177                                             */
 178
 179   u8 data[0]; /**< Packet data. Hardware DMA here */
 180 } vlib_buffer_t;                /* Must be a multiple of 64B. */
 181
 182 #define VLIB_BUFFER_HDR_SIZE  (sizeof(vlib_buffer_t) - VLIB_BUFFER_PRE_DATA_SIZE)
 183
 184 /** \brief Prefetch buffer metadata.
 185     The first 64 bytes of buffer contains most header information
 186
 187     @param b - (vlib_buffer_t *) pointer to the buffer
 188     @param type - LOAD, STORE. In most cases, STORE is the right answer
 189 */
 190
 191 #define vlib_prefetch_buffer_header(b,type) CLIB_PREFETCH (b, 64, type)
 192
 193 always_inline vlib_buffer_t *
 194 vlib_buffer_next_contiguous (vlib_buffer_t * b, u32 buffer_bytes)
 195 {
 196   return (void *) (b + 1) + buffer_bytes;
 197 }
 198
 199 always_inline void
 200 vlib_buffer_struct_is_sane (vlib_buffer_t * b)
 201 {
 202   ASSERT (sizeof (b[0]) % 64 == 0);
 203
 204   /* Rewrite data must be before and contiguous with packet data. */
 205   ASSERT (b->pre_data + VLIB_BUFFER_PRE_DATA_SIZE == b->data);
 206 }
 207
 208 /** \brief Get pointer to current data to process
 209
 210     @param b - (vlib_buffer_t *) pointer to the buffer
 211     @return - (void *) (b->data + b->current_data)
 212 */
 213
 214 always_inline void *
 215 vlib_buffer_get_current (vlib_buffer_t * b)
 216 {
 217   /* Check bounds. */
 218   ASSERT ((signed) b->current_data >= (signed) -VLIB_BUFFER_PRE_DATA_SIZE);
 219   return b->data + b->current_data;
 220 }
 221
 222 /** \brief Advance current data pointer by the supplied (signed!) amount
 223
 224     @param b - (vlib_buffer_t *) pointer to the buffer
 225     @param l - (word) signed increment
 226 */
 227 always_inline void
 228 vlib_buffer_advance (vlib_buffer_t * b, word l)
 229 {
 230   ASSERT (b->current_length >= l);
 231   b->current_data += l;
 232   b->current_length -= l;
 233 }
 234
 235 /** \brief Check if there is enough space in buffer to advance
 236
 237     @param b - (vlib_buffer_t *) pointer to the buffer
 238     @param l - (word) size to check
 239     @return - 0 if there is less space than 'l' in buffer
 240 */
 241 always_inline u8
 242 vlib_buffer_has_space (vlib_buffer_t * b, word l)
 243 {
 244   return b->current_length >= l;
 245 }
 246
 247 /** \brief Reset current header & length to state they were in when
 248     packet was received.
 249
 250     @param b - (vlib_buffer_t *) pointer to the buffer
 251 */
 252
 253 always_inline void
 254 vlib_buffer_reset (vlib_buffer_t * b)
 255 {
 256   b->current_length += clib_max (b->current_data, 0);
 257   b->current_data = 0;
 258 }
 259
 260 /** \brief Get pointer to buffer's opaque data array
 261
 262     @param b - (vlib_buffer_t *) pointer to the buffer
 263     @return - (void *) b->opaque
 264 */
 265 always_inline void *
 266 vlib_get_buffer_opaque (vlib_buffer_t * b)
 267 {
 268   return (void *) b->opaque;
 269 }
 270
 271 /** \brief Get pointer to buffer's opaque2 data array
 272
 273     @param b - (vlib_buffer_t *) pointer to the buffer
 274     @return - (void *) b->opaque2
 275 */
 276 always_inline void *
 277 vlib_get_buffer_opaque2 (vlib_buffer_t * b)
 278 {
 279   return (void *) b->opaque2;
 280 }
 281
 282 /** \brief Get pointer to the end of buffer's data
 283  * @param b     pointer to the buffer
 284  * @return      pointer to tail of packet's data
 285  */
 286 always_inline u8 *
 287 vlib_buffer_get_tail (vlib_buffer_t * b)
 288 {
 289   return b->data + b->current_data + b->current_length;
 290 }
 291
 292 /** \brief Append uninitialized data to buffer
 293  * @param b     pointer to the buffer
 294  * @param size  number of uninitialized bytes
 295  * @return      pointer to beginning of uninitialized data
 296  */
 297 always_inline void *
 298 vlib_buffer_put_uninit (vlib_buffer_t * b, u8 size)
 299 {
 300   void *p = vlib_buffer_get_tail (b);
 301   /* XXX make sure there's enough space */
 302   b->current_length += size;
 303   return p;
 304 }
 305
 306 /** \brief Prepend uninitialized data to buffer
 307  * @param b     pointer to the buffer
 308  * @param size  number of uninitialized bytes
 309  * @return      pointer to beginning of uninitialized data
 310  */
 311 always_inline void *
 312 vlib_buffer_push_uninit (vlib_buffer_t * b, u8 size)
 313 {
 314   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
 315   b->current_data -= size;
 316   b->current_length += size;
 317
 318   return vlib_buffer_get_current (b);
 319 }
 320
 321 /** \brief Make head room, typically for packet headers
 322  * @param b     pointer to the buffer
 323  * @param size  number of head room bytes
 324  * @return      pointer to start of buffer (current data)
 325  */
 326 always_inline void *
 327 vlib_buffer_make_headroom (vlib_buffer_t * b, u8 size)
 328 {
 329   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
 330   b->current_data += size;
 331   return vlib_buffer_get_current (b);
 332 }
 333
 334 /** \brief Retrieve bytes from buffer head
 335  * @param b     pointer to the buffer
 336  * @param size  number of bytes to pull
 337  * @return      pointer to start of buffer (current data)
 338  */
 339 always_inline void *
 340 vlib_buffer_pull (vlib_buffer_t * b, u8 size)
 341 {
 342   if (b->current_length + VLIB_BUFFER_PRE_DATA_SIZE < size)
 343     return 0;
 344
 345   void *data = vlib_buffer_get_current (b);
 346   vlib_buffer_advance (b, size);
 347   return data;
 348 }
 349
 350 /* Forward declaration. */
 351 struct vlib_main_t;
 352
 353 typedef struct vlib_buffer_free_list_t
 354 {
 355   /* Template buffer used to initialize first 16 bytes of buffers
 356      allocated on this free list. */
 357   vlib_buffer_t buffer_init_template;
 358
 359   /* Our index into vlib_main_t's buffer_free_list_pool. */
 360   vlib_buffer_free_list_index_t index;
 361
 362   /* Number of data bytes for buffers in this free list. */
 363   u32 n_data_bytes;
 364
 365   /* Number of buffers to allocate when we need to allocate new buffers
 366      from physmem heap. */
 367   u32 min_n_buffers_each_physmem_alloc;
 368
 369   /* Total number of buffers allocated from this free list. */
 370   u32 n_alloc;
 371
 372   /* Vector of free buffers.  Each element is a byte offset into I/O heap. */
 373   u32 *buffers;
 374
 375   /* global vector of free buffers, used only on main thread.
 376      Bufers are returned to global buffers only in case when number of
 377      buffers on free buffers list grows about threshold */
 378   u32 *global_buffers;
 379   clib_spinlock_t global_buffers_lock;
 380
 381   /* Memory chunks allocated for this free list
 382      recorded here so they can be freed when free list
 383      is deleted. */
 384   void **buffer_memory_allocated;
 385
 386   /* Free list name. */
 387   u8 *name;
 388
 389   /* Callback functions to initialize newly allocated buffers.
 390      If null buffers are zeroed. */
 391   void (*buffer_init_function) (struct vlib_main_t * vm,
 392                                 struct vlib_buffer_free_list_t * fl,
 393                                 u32 * buffers, u32 n_buffers);
 394
 395   /* Callback function to announce that buffers have been
 396      added to the freelist */
 397   void (*buffers_added_to_freelist_function)
 398     (struct vlib_main_t * vm, struct vlib_buffer_free_list_t * fl);
 399
 400   uword buffer_init_function_opaque;
 401 } __attribute__ ((aligned (16))) vlib_buffer_free_list_t;
 402
 403 typedef uword (vlib_buffer_fill_free_list_cb_t) (struct vlib_main_t * vm,
 404                                                  vlib_buffer_free_list_t * fl,
 405                                                  uword min_free_buffers);
 406 typedef void (vlib_buffer_free_cb_t) (struct vlib_main_t * vm, u32 * buffers,
 407                                       u32 n_buffers);
 408 typedef void (vlib_buffer_free_no_next_cb_t) (struct vlib_main_t * vm,
 409                                               u32 * buffers, u32 n_buffers);
 410
 411 typedef struct
 412 {
 413   vlib_buffer_fill_free_list_cb_t *vlib_buffer_fill_free_list_cb;
 414   vlib_buffer_free_cb_t *vlib_buffer_free_cb;
 415   vlib_buffer_free_no_next_cb_t *vlib_buffer_free_no_next_cb;
 416   void (*vlib_packet_template_init_cb) (struct vlib_main_t * vm, void *t,
 417                                         void *packet_data,
 418                                         uword n_packet_data_bytes,
 419                                         uword
 420                                         min_n_buffers_each_physmem_alloc,
 421                                         u8 * name);
 422   void (*vlib_buffer_delete_free_list_cb) (struct vlib_main_t * vm,
 423                                            vlib_buffer_free_list_index_t
 424                                            free_list_index);
 425 } vlib_buffer_callbacks_t;
 426
 427 extern vlib_buffer_callbacks_t *vlib_buffer_callbacks;
 428
 429 typedef struct
 430 {
 431   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 432   uword start;
 433   uword size;
 434   vlib_physmem_region_index_t physmem_region;
 435 } vlib_buffer_pool_t;
 436
 437 typedef struct
 438 {
 439   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 440   /* Virtual memory address and size of buffer memory, used for calculating
 441      buffer index */
 442   uword buffer_mem_start;
 443   uword buffer_mem_size;
 444   vlib_buffer_pool_t *buffer_pools;
 445
 446   /* Buffer free callback, for subversive activities */
 447     u32 (*buffer_free_callback) (struct vlib_main_t * vm,
 448                                  u32 * buffers,
 449                                  u32 n_buffers, u32 follow_buffer_next);
 450   /* Pool of buffer free lists.
 451      Multiple free lists exist for packet generator which uses
 452      separate free lists for each packet stream --- so as to avoid
 453      initializing static data for each packet generated. */
 454   vlib_buffer_free_list_t *buffer_free_list_pool;
 455 #define VLIB_BUFFER_DEFAULT_FREE_LIST_INDEX (0)
 456 #define VLIB_BUFFER_DEFAULT_FREE_LIST_BYTES VLIB_BUFFER_DATA_SIZE
 457
 458   /* Hash table mapping buffer size (rounded to next unit of
 459      sizeof (vlib_buffer_t)) to free list index. */
 460   uword *free_list_by_size;
 461
 462   /* Hash table mapping buffer index into number
 463      0 => allocated but free, 1 => allocated and not-free.
 464      If buffer index is not in hash table then this buffer
 465      has never been allocated. */
 466   uword *buffer_known_hash;
 467   clib_spinlock_t buffer_known_hash_lockp;
 468
 469   /* List of free-lists needing Blue Light Special announcements */
 470   vlib_buffer_free_list_t **announce_list;
 471
 472   /* Callbacks */
 473   vlib_buffer_callbacks_t cb;
 474   int callbacks_registered;
 475 } vlib_buffer_main_t;
 476
 477 u8 vlib_buffer_add_physmem_region (struct vlib_main_t *vm,
 478                                    vlib_physmem_region_index_t region);
 479
 480 clib_error_t *vlib_buffer_main_init (struct vlib_main_t *vm);
 481
 482 typedef struct
 483 {
 484   struct vlib_main_t *vlib_main;
 485
 486   u32 first_buffer, last_buffer;
 487
 488   union
 489   {
 490     struct
 491     {
 492       /* Total accumulated bytes in chain starting with first_buffer. */
 493       u32 n_total_data_bytes;
 494
 495       /* Max number of bytes to accumulate in chain starting with first_buffer.
 496          As this limit is reached buffers are enqueued to next node. */
 497       u32 max_n_data_bytes_per_chain;
 498
 499       /* Next node to enqueue buffers to relative to current process node. */
 500       u32 next_index;
 501
 502       /* Free list to use to allocate new buffers. */
 503       vlib_buffer_free_list_index_t free_list_index;
 504     } tx;
 505
 506     struct
 507     {
 508       /* CLIB fifo of buffer indices waiting to be unserialized. */
 509       u32 *buffer_fifo;
 510
 511       /* Event type used to signal that RX buffers have been added to fifo. */
 512       uword ready_one_time_event;
 513     } rx;
 514   };
 515 } vlib_serialize_buffer_main_t;
 516
 517 void serialize_open_vlib_buffer (serialize_main_t * m, struct vlib_main_t *vm,
 518                                  vlib_serialize_buffer_main_t * sm);
 519 void unserialize_open_vlib_buffer (serialize_main_t * m,
 520                                    struct vlib_main_t *vm,
 521                                    vlib_serialize_buffer_main_t * sm);
 522
 523 u32 serialize_close_vlib_buffer (serialize_main_t * m);
 524 void unserialize_close_vlib_buffer (serialize_main_t * m);
 525 void *vlib_set_buffer_free_callback (struct vlib_main_t *vm, void *fp);
 526
 527 always_inline u32
 528 serialize_vlib_buffer_n_bytes (serialize_main_t * m)
 529 {
 530   serialize_stream_t *s = &m->stream;
 531   vlib_serialize_buffer_main_t *sm
 532     = uword_to_pointer (m->stream.data_function_opaque,
 533                         vlib_serialize_buffer_main_t *);
 534   return sm->tx.n_total_data_bytes + s->current_buffer_index +
 535     vec_len (s->overflow_buffer);
 536 }
 537
 538 /*
 539  */
 540
 541 /** \brief Compile time buffer trajectory tracing option
 542     Turn this on if you run into "bad monkey" contexts,
 543     and you want to know exactly which nodes they've visited...
 544     See vlib/main.c...
 545 */
 546 #define VLIB_BUFFER_TRACE_TRAJECTORY 0
 547
 548 #if VLIB_BUFFER_TRACE_TRAJECTORY > 0
 549 extern void (*vlib_buffer_trace_trajectory_cb) (vlib_buffer_t * b, u32 index);
 550 extern void (*vlib_buffer_trace_trajectory_init_cb) (vlib_buffer_t * b);
 551 extern void vlib_buffer_trace_trajectory_init (vlib_buffer_t * b);
 552 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b) \
 553   vlib_buffer_trace_trajectory_init (b);
 554 #else
 555 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b)
 556 #endif /* VLIB_BUFFER_TRACE_TRAJECTORY */
 557
 558 #endif /* included_vlib_buffer_h */
 559
 560 #define VLIB_BUFFER_REGISTER_CALLBACKS(x,...)                           \
 561     __VA_ARGS__ vlib_buffer_callbacks_t __##x##_buffer_callbacks;       \
 562 static void __vlib_add_buffer_callbacks_t_##x (void)                    \
 563     __attribute__((__constructor__)) ;                                  \
 564 static void __vlib_add_buffer_callbacks_t_##x (void)                    \
 565 {                                                                       \
 566     if (vlib_buffer_callbacks)                                          \
 567       clib_panic ("vlib buffer callbacks already registered");          \
 568     vlib_buffer_callbacks = &__##x##_buffer_callbacks;                  \
 569 }                                                                       \
 570 __VA_ARGS__ vlib_buffer_callbacks_t __##x##_buffer_callbacks
 571
 572 /*
 573  * fd.io coding-style-patch-verification: ON
 574  *
 575  * Local Variables:
 576  * eval: (c-set-style "gnu")
 577  * End:
 578  */