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
 189 always_inline void
 190 vlib_buffer_struct_is_sane (vlib_buffer_t * b)
 191 {
 192   ASSERT (sizeof (b[0]) % 64 == 0);
 193
 194   /* Rewrite data must be before and contiguous with packet data. */
 195   ASSERT (b->pre_data + VLIB_BUFFER_PRE_DATA_SIZE == b->data);
 196 }
 197
 198 always_inline uword
 199 vlib_buffer_get_va (vlib_buffer_t * b)
 200 {
 201   return pointer_to_uword (b->data);
 202 }
 203
 204 /** \brief Get pointer to current data to process
 205
 206     @param b - (vlib_buffer_t *) pointer to the buffer
 207     @return - (void *) (b->data + b->current_data)
 208 */
 209
 210 always_inline void *
 211 vlib_buffer_get_current (vlib_buffer_t * b)
 212 {
 213   /* Check bounds. */
 214   ASSERT ((signed) b->current_data >= (signed) -VLIB_BUFFER_PRE_DATA_SIZE);
 215   return b->data + b->current_data;
 216 }
 217
 218 always_inline uword
 219 vlib_buffer_get_current_va (vlib_buffer_t * b)
 220 {
 221   return vlib_buffer_get_va (b) + b->current_data;
 222 }
 223
 224 /** \brief Advance current data pointer by the supplied (signed!) amount
 225
 226     @param b - (vlib_buffer_t *) pointer to the buffer
 227     @param l - (word) signed increment
 228 */
 229 always_inline void
 230 vlib_buffer_advance (vlib_buffer_t * b, word l)
 231 {
 232   ASSERT (b->current_length >= l);
 233   b->current_data += l;
 234   b->current_length -= l;
 235
 236   ASSERT ((b->flags & VLIB_BUFFER_NEXT_PRESENT) == 0 ||
 237           b->current_length >= VLIB_BUFFER_MIN_CHAIN_SEG_SIZE);
 238 }
 239
 240 /** \brief Check if there is enough space in buffer to advance
 241
 242     @param b - (vlib_buffer_t *) pointer to the buffer
 243     @param l - (word) size to check
 244     @return - 0 if there is less space than 'l' in buffer
 245 */
 246 always_inline u8
 247 vlib_buffer_has_space (vlib_buffer_t * b, word l)
 248 {
 249   return b->current_length >= l;
 250 }
 251
 252 /** \brief Reset current header & length to state they were in when
 253     packet was received.
 254
 255     @param b - (vlib_buffer_t *) pointer to the buffer
 256 */
 257
 258 always_inline void
 259 vlib_buffer_reset (vlib_buffer_t * b)
 260 {
 261   b->current_length += clib_max (b->current_data, 0);
 262   b->current_data = 0;
 263 }
 264
 265 /** \brief Get pointer to buffer's opaque data array
 266
 267     @param b - (vlib_buffer_t *) pointer to the buffer
 268     @return - (void *) b->opaque
 269 */
 270 always_inline void *
 271 vlib_get_buffer_opaque (vlib_buffer_t * b)
 272 {
 273   return (void *) b->opaque;
 274 }
 275
 276 /** \brief Get pointer to buffer's opaque2 data array
 277
 278     @param b - (vlib_buffer_t *) pointer to the buffer
 279     @return - (void *) b->opaque2
 280 */
 281 always_inline void *
 282 vlib_get_buffer_opaque2 (vlib_buffer_t * b)
 283 {
 284   return (void *) b->opaque2;
 285 }
 286
 287 /** \brief Get pointer to the end of buffer's data
 288  * @param b     pointer to the buffer
 289  * @return      pointer to tail of packet's data
 290  */
 291 always_inline u8 *
 292 vlib_buffer_get_tail (vlib_buffer_t * b)
 293 {
 294   return b->data + b->current_data + b->current_length;
 295 }
 296
 297 /** \brief Append uninitialized data to buffer
 298  * @param b     pointer to the buffer
 299  * @param size  number of uninitialized bytes
 300  * @return      pointer to beginning of uninitialized data
 301  */
 302 always_inline void *
 303 vlib_buffer_put_uninit (vlib_buffer_t * b, u8 size)
 304 {
 305   void *p = vlib_buffer_get_tail (b);
 306   /* XXX make sure there's enough space */
 307   b->current_length += size;
 308   return p;
 309 }
 310
 311 /** \brief Prepend uninitialized data to buffer
 312  * @param b     pointer to the buffer
 313  * @param size  number of uninitialized bytes
 314  * @return      pointer to beginning of uninitialized data
 315  */
 316 always_inline void *
 317 vlib_buffer_push_uninit (vlib_buffer_t * b, u8 size)
 318 {
 319   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
 320   b->current_data -= size;
 321   b->current_length += size;
 322
 323   return vlib_buffer_get_current (b);
 324 }
 325
 326 /** \brief Make head room, typically for packet headers
 327  * @param b     pointer to the buffer
 328  * @param size  number of head room bytes
 329  * @return      pointer to start of buffer (current data)
 330  */
 331 always_inline void *
 332 vlib_buffer_make_headroom (vlib_buffer_t * b, u8 size)
 333 {
 334   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
 335   b->current_data += size;
 336   return vlib_buffer_get_current (b);
 337 }
 338
 339 /** \brief Retrieve bytes from buffer head
 340  * @param b     pointer to the buffer
 341  * @param size  number of bytes to pull
 342  * @return      pointer to start of buffer (current data)
 343  */
 344 always_inline void *
 345 vlib_buffer_pull (vlib_buffer_t * b, u8 size)
 346 {
 347   if (b->current_length + VLIB_BUFFER_PRE_DATA_SIZE < size)
 348     return 0;
 349
 350   void *data = vlib_buffer_get_current (b);
 351   vlib_buffer_advance (b, size);
 352   return data;
 353 }
 354
 355 /* Forward declaration. */
 356 struct vlib_main_t;
 357
 358 typedef struct vlib_buffer_free_list_t
 359 {
 360   /* Template buffer used to initialize first 16 bytes of buffers
 361      allocated on this free list. */
 362   vlib_buffer_t buffer_init_template;
 363
 364   /* Our index into vlib_main_t's buffer_free_list_pool. */
 365   vlib_buffer_free_list_index_t index;
 366
 367   /* Number of data bytes for buffers in this free list. */
 368   u32 n_data_bytes;
 369
 370   /* Number of buffers to allocate when we need to allocate new buffers */
 371   u32 min_n_buffers_each_alloc;
 372
 373   /* Total number of buffers allocated from this free list. */
 374   u32 n_alloc;
 375
 376   /* Vector of free buffers.  Each element is a byte offset into I/O heap. */
 377   u32 *buffers;
 378
 379   /* index of buffer pool used to get / put buffers */
 380   u8 buffer_pool_index;
 381
 382   /* Free list name. */
 383   u8 *name;
 384
 385   /* Callback functions to initialize newly allocated buffers.
 386      If null buffers are zeroed. */
 387   void (*buffer_init_function) (struct vlib_main_t * vm,
 388                                 struct vlib_buffer_free_list_t * fl,
 389                                 u32 * buffers, u32 n_buffers);
 390
 391   uword buffer_init_function_opaque;
 392 } __attribute__ ((aligned (16))) vlib_buffer_free_list_t;
 393
 394 typedef uword (vlib_buffer_fill_free_list_cb_t) (struct vlib_main_t * vm,
 395                                                  vlib_buffer_free_list_t * fl,
 396                                                  uword min_free_buffers);
 397 typedef void (vlib_buffer_free_cb_t) (struct vlib_main_t * vm, u32 * buffers,
 398                                       u32 n_buffers);
 399 typedef void (vlib_buffer_free_no_next_cb_t) (struct vlib_main_t * vm,
 400                                               u32 * buffers, u32 n_buffers);
 401
 402 typedef struct
 403 {
 404   vlib_buffer_fill_free_list_cb_t *vlib_buffer_fill_free_list_cb;
 405   vlib_buffer_free_cb_t *vlib_buffer_free_cb;
 406   vlib_buffer_free_no_next_cb_t *vlib_buffer_free_no_next_cb;
 407   void (*vlib_packet_template_init_cb) (struct vlib_main_t * vm, void *t,
 408                                         void *packet_data,
 409                                         uword n_packet_data_bytes,
 410                                         uword
 411                                         min_n_buffers_each_physmem_alloc,
 412                                         u8 * name);
 413   void (*vlib_buffer_delete_free_list_cb) (struct vlib_main_t * vm,
 414                                            vlib_buffer_free_list_index_t
 415                                            free_list_index);
 416 } vlib_buffer_callbacks_t;
 417
 418 extern vlib_buffer_callbacks_t *vlib_buffer_callbacks;
 419
 420 typedef struct
 421 {
 422   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 423   uword start;
 424   uword size;
 425   uword log2_page_size;
 426   u32 physmem_map_index;
 427   u32 buffer_size;
 428   u32 *buffers;
 429   clib_spinlock_t lock;
 430 } vlib_buffer_pool_t;
 431
 432 typedef struct
 433 {
 434   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 435   /* Virtual memory address and size of buffer memory, used for calculating
 436      buffer index */
 437   uword buffer_mem_start;
 438   uword buffer_mem_size;
 439   vlib_buffer_pool_t *buffer_pools;
 440
 441   /* Buffer free callback, for subversive activities */
 442     u32 (*buffer_free_callback) (struct vlib_main_t * vm,
 443                                  u32 * buffers,
 444                                  u32 n_buffers, u32 follow_buffer_next);
 445 #define VLIB_BUFFER_DEFAULT_FREE_LIST_INDEX (0)
 446 #define VLIB_BUFFER_DEFAULT_FREE_LIST_BYTES VLIB_BUFFER_DATA_SIZE
 447
 448   /* Hash table mapping buffer size (rounded to next unit of
 449      sizeof (vlib_buffer_t)) to free list index. */
 450   uword *free_list_by_size;
 451
 452   /* Hash table mapping buffer index into number
 453      0 => allocated but free, 1 => allocated and not-free.
 454      If buffer index is not in hash table then this buffer
 455      has never been allocated. */
 456   uword *buffer_known_hash;
 457   clib_spinlock_t buffer_known_hash_lockp;
 458
 459   /* Callbacks */
 460   vlib_buffer_callbacks_t cb;
 461   int callbacks_registered;
 462 } vlib_buffer_main_t;
 463
 464 extern vlib_buffer_main_t buffer_main;
 465
 466 static_always_inline vlib_buffer_pool_t *
 467 vlib_buffer_pool_get (u8 buffer_pool_index)
 468 {
 469   vlib_buffer_main_t *bm = &buffer_main;
 470   return vec_elt_at_index (bm->buffer_pools, buffer_pool_index);
 471 }
 472
 473 u8 vlib_buffer_register_physmem_map (struct vlib_main_t * vm,
 474                                      u32 physmem_map_index);
 475
 476 clib_error_t *vlib_buffer_main_init (struct vlib_main_t *vm);
 477
 478 typedef struct
 479 {
 480   struct vlib_main_t *vlib_main;
 481
 482   u32 first_buffer, last_buffer;
 483
 484   union
 485   {
 486     struct
 487     {
 488       /* Total accumulated bytes in chain starting with first_buffer. */
 489       u32 n_total_data_bytes;
 490
 491       /* Max number of bytes to accumulate in chain starting with first_buffer.
 492          As this limit is reached buffers are enqueued to next node. */
 493       u32 max_n_data_bytes_per_chain;
 494
 495       /* Next node to enqueue buffers to relative to current process node. */
 496       u32 next_index;
 497
 498       /* Free list to use to allocate new buffers. */
 499       vlib_buffer_free_list_index_t free_list_index;
 500     } tx;
 501
 502     struct
 503     {
 504       /* CLIB fifo of buffer indices waiting to be unserialized. */
 505       u32 *buffer_fifo;
 506
 507       /* Event type used to signal that RX buffers have been added to fifo. */
 508       uword ready_one_time_event;
 509     } rx;
 510   };
 511 } vlib_serialize_buffer_main_t;
 512
 513 void serialize_open_vlib_buffer (serialize_main_t * m, struct vlib_main_t *vm,
 514                                  vlib_serialize_buffer_main_t * sm);
 515 void unserialize_open_vlib_buffer (serialize_main_t * m,
 516                                    struct vlib_main_t *vm,
 517                                    vlib_serialize_buffer_main_t * sm);
 518
 519 u32 serialize_close_vlib_buffer (serialize_main_t * m);
 520 void unserialize_close_vlib_buffer (serialize_main_t * m);
 521 void *vlib_set_buffer_free_callback (struct vlib_main_t *vm, void *fp);
 522
 523 always_inline u32
 524 serialize_vlib_buffer_n_bytes (serialize_main_t * m)
 525 {
 526   serialize_stream_t *s = &m->stream;
 527   vlib_serialize_buffer_main_t *sm
 528     = uword_to_pointer (m->stream.data_function_opaque,
 529                         vlib_serialize_buffer_main_t *);
 530   return sm->tx.n_total_data_bytes + s->current_buffer_index +
 531     vec_len (s->overflow_buffer);
 532 }
 533
 534 /*
 535  */
 536
 537 /** \brief Compile time buffer trajectory tracing option
 538     Turn this on if you run into "bad monkey" contexts,
 539     and you want to know exactly which nodes they've visited...
 540     See vlib/main.c...
 541 */
 542 #define VLIB_BUFFER_TRACE_TRAJECTORY 0
 543
 544 #if VLIB_BUFFER_TRACE_TRAJECTORY > 0
 545 extern void (*vlib_buffer_trace_trajectory_cb) (vlib_buffer_t * b, u32 index);
 546 extern void (*vlib_buffer_trace_trajectory_init_cb) (vlib_buffer_t * b);
 547 extern void vlib_buffer_trace_trajectory_init (vlib_buffer_t * b);
 548 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b) \
 549   vlib_buffer_trace_trajectory_init (b);
 550 #else
 551 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b)
 552 #endif /* VLIB_BUFFER_TRACE_TRAJECTORY */
 553
 554 #endif /* included_vlib_buffer_h */
 555
 556 #define VLIB_BUFFER_REGISTER_CALLBACKS(x,...)                           \
 557     __VA_ARGS__ vlib_buffer_callbacks_t __##x##_buffer_callbacks;       \
 558 static void __vlib_add_buffer_callbacks_t_##x (void)                    \
 559     __attribute__((__constructor__)) ;                                  \
 560 static void __vlib_add_buffer_callbacks_t_##x (void)                    \
 561 {                                                                       \
 562     if (vlib_buffer_callbacks)                                          \
 563       clib_panic ("vlib buffer callbacks already registered");          \
 564     vlib_buffer_callbacks = &__##x##_buffer_callbacks;                  \
 565 }                                                                       \
 566 static void __vlib_rm_buffer_callbacks_t_##x (void)                     \
 567     __attribute__((__destructor__)) ;                                   \
 568 static void __vlib_rm_buffer_callbacks_t_##x (void)                     \
 569 { vlib_buffer_callbacks = 0; }                                          \
 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  */