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   u32 flow_id;  /**< Generic flow identifier */
 124
 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     STRUCT_MARK (template_end);
 131
 132   u32 current_config_index; /**< Used by feature subgraph arcs to
 133                                visit enabled feature nodes
 134                             */
 135   vlib_error_t error;   /**< Error code for buffers to be enqueued
 136                            to error handler.
 137                         */
 138   u8 n_add_refs; /**< Number of additional references to this buffer. */
 139
 140   u8 buffer_pool_index; /**< index of buffer pool this buffer belongs. */
 141
 142   u32 opaque[10]; /**< Opaque data used by sub-graphs for their own purposes.
 143                     See .../vnet/vnet/buffer.h
 144                  */
 145     CLIB_CACHE_LINE_ALIGN_MARK (cacheline1);
 146
 147   u32 trace_index; /**< Specifies index into trace buffer
 148                       if VLIB_PACKET_IS_TRACED flag is set.
 149                    */
 150   u32 recycle_count; /**< Used by L2 path recycle code */
 151
 152   u32 total_length_not_including_first_buffer;
 153   /**< Only valid for first buffer in chain. Current length plus
 154      total length given here give total number of bytes in buffer chain.
 155   */
 156   vlib_buffer_free_list_index_t free_list_index; /** < only used if
 157                                                    VLIB_BUFFER_NON_DEFAULT_FREELIST
 158                                                    flag is set */
 159   u8 align_pad[3]; /**< available */
 160   u32 opaque2[12];  /**< More opaque data, see ../vnet/vnet/buffer.h */
 161
 162   /***** end of second cache line */
 163     CLIB_CACHE_LINE_ALIGN_MARK (cacheline2);
 164   u8 pre_data[VLIB_BUFFER_PRE_DATA_SIZE];  /**< Space for inserting data
 165                                                before buffer start.
 166                                                Packet rewrite string will be
 167                                                rewritten backwards and may extend
 168                                                back before buffer->data[0].
 169                                                Must come directly before packet data.
 170                                             */
 171
 172   u8 data[0]; /**< Packet data. Hardware DMA here */
 173 } vlib_buffer_t;                /* Must be a multiple of 64B. */
 174
 175 #define VLIB_BUFFER_HDR_SIZE  (sizeof(vlib_buffer_t) - VLIB_BUFFER_PRE_DATA_SIZE)
 176
 177 /** \brief Prefetch buffer metadata.
 178     The first 64 bytes of buffer contains most header information
 179
 180     @param b - (vlib_buffer_t *) pointer to the buffer
 181     @param type - LOAD, STORE. In most cases, STORE is the right answer
 182 */
 183
 184 #define vlib_prefetch_buffer_header(b,type) CLIB_PREFETCH (b, 64, type)
 185
 186 always_inline void
 187 vlib_buffer_struct_is_sane (vlib_buffer_t * b)
 188 {
 189   ASSERT (sizeof (b[0]) % 64 == 0);
 190
 191   /* Rewrite data must be before and contiguous with packet data. */
 192   ASSERT (b->pre_data + VLIB_BUFFER_PRE_DATA_SIZE == b->data);
 193 }
 194
 195 /** \brief Get pointer to current data to process
 196
 197     @param b - (vlib_buffer_t *) pointer to the buffer
 198     @return - (void *) (b->data + b->current_data)
 199 */
 200
 201 always_inline void *
 202 vlib_buffer_get_current (vlib_buffer_t * b)
 203 {
 204   /* Check bounds. */
 205   ASSERT ((signed) b->current_data >= (signed) -VLIB_BUFFER_PRE_DATA_SIZE);
 206   return b->data + b->current_data;
 207 }
 208
 209 /** \brief Advance current data pointer by the supplied (signed!) amount
 210
 211     @param b - (vlib_buffer_t *) pointer to the buffer
 212     @param l - (word) signed increment
 213 */
 214 always_inline void
 215 vlib_buffer_advance (vlib_buffer_t * b, word l)
 216 {
 217   ASSERT (b->current_length >= l);
 218   b->current_data += l;
 219   b->current_length -= l;
 220 }
 221
 222 /** \brief Check if there is enough space in buffer to advance
 223
 224     @param b - (vlib_buffer_t *) pointer to the buffer
 225     @param l - (word) size to check
 226     @return - 0 if there is less space than 'l' in buffer
 227 */
 228 always_inline u8
 229 vlib_buffer_has_space (vlib_buffer_t * b, word l)
 230 {
 231   return b->current_length >= l;
 232 }
 233
 234 /** \brief Reset current header & length to state they were in when
 235     packet was received.
 236
 237     @param b - (vlib_buffer_t *) pointer to the buffer
 238 */
 239
 240 always_inline void
 241 vlib_buffer_reset (vlib_buffer_t * b)
 242 {
 243   b->current_length += clib_max (b->current_data, 0);
 244   b->current_data = 0;
 245 }
 246
 247 /** \brief Get pointer to buffer's opaque data array
 248
 249     @param b - (vlib_buffer_t *) pointer to the buffer
 250     @return - (void *) b->opaque
 251 */
 252 always_inline void *
 253 vlib_get_buffer_opaque (vlib_buffer_t * b)
 254 {
 255   return (void *) b->opaque;
 256 }
 257
 258 /** \brief Get pointer to buffer's opaque2 data array
 259
 260     @param b - (vlib_buffer_t *) pointer to the buffer
 261     @return - (void *) b->opaque2
 262 */
 263 always_inline void *
 264 vlib_get_buffer_opaque2 (vlib_buffer_t * b)
 265 {
 266   return (void *) b->opaque2;
 267 }
 268
 269 /** \brief Get pointer to the end of buffer's data
 270  * @param b     pointer to the buffer
 271  * @return      pointer to tail of packet's data
 272  */
 273 always_inline u8 *
 274 vlib_buffer_get_tail (vlib_buffer_t * b)
 275 {
 276   return b->data + b->current_data + b->current_length;
 277 }
 278
 279 /** \brief Append uninitialized data to buffer
 280  * @param b     pointer to the buffer
 281  * @param size  number of uninitialized bytes
 282  * @return      pointer to beginning of uninitialized data
 283  */
 284 always_inline void *
 285 vlib_buffer_put_uninit (vlib_buffer_t * b, u8 size)
 286 {
 287   void *p = vlib_buffer_get_tail (b);
 288   /* XXX make sure there's enough space */
 289   b->current_length += size;
 290   return p;
 291 }
 292
 293 /** \brief Prepend uninitialized data to buffer
 294  * @param b     pointer to the buffer
 295  * @param size  number of uninitialized bytes
 296  * @return      pointer to beginning of uninitialized data
 297  */
 298 always_inline void *
 299 vlib_buffer_push_uninit (vlib_buffer_t * b, u8 size)
 300 {
 301   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
 302   b->current_data -= size;
 303   b->current_length += size;
 304
 305   return vlib_buffer_get_current (b);
 306 }
 307
 308 /** \brief Make head room, typically for packet headers
 309  * @param b     pointer to the buffer
 310  * @param size  number of head room bytes
 311  * @return      pointer to start of buffer (current data)
 312  */
 313 always_inline void *
 314 vlib_buffer_make_headroom (vlib_buffer_t * b, u8 size)
 315 {
 316   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
 317   b->current_data += size;
 318   return vlib_buffer_get_current (b);
 319 }
 320
 321 /** \brief Retrieve bytes from buffer head
 322  * @param b     pointer to the buffer
 323  * @param size  number of bytes to pull
 324  * @return      pointer to start of buffer (current data)
 325  */
 326 always_inline void *
 327 vlib_buffer_pull (vlib_buffer_t * b, u8 size)
 328 {
 329   if (b->current_length + VLIB_BUFFER_PRE_DATA_SIZE < size)
 330     return 0;
 331
 332   void *data = vlib_buffer_get_current (b);
 333   vlib_buffer_advance (b, size);
 334   return data;
 335 }
 336
 337 /* Forward declaration. */
 338 struct vlib_main_t;
 339
 340 typedef struct vlib_buffer_free_list_t
 341 {
 342   /* Template buffer used to initialize first 16 bytes of buffers
 343      allocated on this free list. */
 344   vlib_buffer_t buffer_init_template;
 345
 346   /* Our index into vlib_main_t's buffer_free_list_pool. */
 347   vlib_buffer_free_list_index_t index;
 348
 349   /* Number of data bytes for buffers in this free list. */
 350   u32 n_data_bytes;
 351
 352   /* Number of buffers to allocate when we need to allocate new buffers */
 353   u32 min_n_buffers_each_alloc;
 354
 355   /* Total number of buffers allocated from this free list. */
 356   u32 n_alloc;
 357
 358   /* Vector of free buffers.  Each element is a byte offset into I/O heap. */
 359   u32 *buffers;
 360
 361   /* index of buffer pool used to get / put buffers */
 362   u8 buffer_pool_index;
 363
 364   /* Free list name. */
 365   u8 *name;
 366
 367   /* Callback functions to initialize newly allocated buffers.
 368      If null buffers are zeroed. */
 369   void (*buffer_init_function) (struct vlib_main_t * vm,
 370                                 struct vlib_buffer_free_list_t * fl,
 371                                 u32 * buffers, u32 n_buffers);
 372
 373   /* Callback function to announce that buffers have been
 374      added to the freelist */
 375   void (*buffers_added_to_freelist_function)
 376     (struct vlib_main_t * vm, struct vlib_buffer_free_list_t * fl);
 377
 378   uword buffer_init_function_opaque;
 379 } __attribute__ ((aligned (16))) vlib_buffer_free_list_t;
 380
 381 typedef uword (vlib_buffer_fill_free_list_cb_t) (struct vlib_main_t * vm,
 382                                                  vlib_buffer_free_list_t * fl,
 383                                                  uword min_free_buffers);
 384 typedef void (vlib_buffer_free_cb_t) (struct vlib_main_t * vm, u32 * buffers,
 385                                       u32 n_buffers);
 386 typedef void (vlib_buffer_free_no_next_cb_t) (struct vlib_main_t * vm,
 387                                               u32 * buffers, u32 n_buffers);
 388
 389 typedef struct
 390 {
 391   vlib_buffer_fill_free_list_cb_t *vlib_buffer_fill_free_list_cb;
 392   vlib_buffer_free_cb_t *vlib_buffer_free_cb;
 393   vlib_buffer_free_no_next_cb_t *vlib_buffer_free_no_next_cb;
 394   void (*vlib_packet_template_init_cb) (struct vlib_main_t * vm, void *t,
 395                                         void *packet_data,
 396                                         uword n_packet_data_bytes,
 397                                         uword
 398                                         min_n_buffers_each_physmem_alloc,
 399                                         u8 * name);
 400   void (*vlib_buffer_delete_free_list_cb) (struct vlib_main_t * vm,
 401                                            vlib_buffer_free_list_index_t
 402                                            free_list_index);
 403 } vlib_buffer_callbacks_t;
 404
 405 extern vlib_buffer_callbacks_t *vlib_buffer_callbacks;
 406
 407 typedef struct
 408 {
 409   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 410   uword start;
 411   uword size;
 412   uword log2_page_size;
 413   vlib_physmem_region_index_t physmem_region;
 414
 415   u32 *buffers;
 416
 417   u16 buffer_size;
 418   uword buffers_per_page;
 419   uword n_elts;
 420   uword n_used;
 421   uword next_clear;
 422   uword *bitmap;
 423   clib_spinlock_t lock;
 424 } vlib_buffer_pool_t;
 425
 426 typedef struct
 427 {
 428   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 429   /* Virtual memory address and size of buffer memory, used for calculating
 430      buffer index */
 431   uword buffer_mem_start;
 432   uword buffer_mem_size;
 433   vlib_buffer_pool_t *buffer_pools;
 434
 435   /* Buffer free callback, for subversive activities */
 436     u32 (*buffer_free_callback) (struct vlib_main_t * vm,
 437                                  u32 * buffers,
 438                                  u32 n_buffers, u32 follow_buffer_next);
 439 #define VLIB_BUFFER_DEFAULT_FREE_LIST_INDEX (0)
 440 #define VLIB_BUFFER_DEFAULT_FREE_LIST_BYTES VLIB_BUFFER_DATA_SIZE
 441
 442   /* Hash table mapping buffer size (rounded to next unit of
 443      sizeof (vlib_buffer_t)) to free list index. */
 444   uword *free_list_by_size;
 445
 446   /* Hash table mapping buffer index into number
 447      0 => allocated but free, 1 => allocated and not-free.
 448      If buffer index is not in hash table then this buffer
 449      has never been allocated. */
 450   uword *buffer_known_hash;
 451   clib_spinlock_t buffer_known_hash_lockp;
 452
 453   /* Callbacks */
 454   vlib_buffer_callbacks_t cb;
 455   int callbacks_registered;
 456 } vlib_buffer_main_t;
 457
 458 extern vlib_buffer_main_t buffer_main;
 459
 460 static_always_inline vlib_buffer_pool_t *
 461 vlib_buffer_pool_get (u8 buffer_pool_index)
 462 {
 463   vlib_buffer_main_t *bm = &buffer_main;
 464   return vec_elt_at_index (bm->buffer_pools, buffer_pool_index);
 465 }
 466
 467 u8 vlib_buffer_pool_create (struct vlib_main_t * vm,
 468                             vlib_physmem_region_index_t region,
 469                             u16 buffer_size);
 470
 471 clib_error_t *vlib_buffer_main_init (struct vlib_main_t *vm);
 472
 473 typedef struct
 474 {
 475   struct vlib_main_t *vlib_main;
 476
 477   u32 first_buffer, last_buffer;
 478
 479   union
 480   {
 481     struct
 482     {
 483       /* Total accumulated bytes in chain starting with first_buffer. */
 484       u32 n_total_data_bytes;
 485
 486       /* Max number of bytes to accumulate in chain starting with first_buffer.
 487          As this limit is reached buffers are enqueued to next node. */
 488       u32 max_n_data_bytes_per_chain;
 489
 490       /* Next node to enqueue buffers to relative to current process node. */
 491       u32 next_index;
 492
 493       /* Free list to use to allocate new buffers. */
 494       vlib_buffer_free_list_index_t free_list_index;
 495     } tx;
 496
 497     struct
 498     {
 499       /* CLIB fifo of buffer indices waiting to be unserialized. */
 500       u32 *buffer_fifo;
 501
 502       /* Event type used to signal that RX buffers have been added to fifo. */
 503       uword ready_one_time_event;
 504     } rx;
 505   };
 506 } vlib_serialize_buffer_main_t;
 507
 508 void serialize_open_vlib_buffer (serialize_main_t * m, struct vlib_main_t *vm,
 509                                  vlib_serialize_buffer_main_t * sm);
 510 void unserialize_open_vlib_buffer (serialize_main_t * m,
 511                                    struct vlib_main_t *vm,
 512                                    vlib_serialize_buffer_main_t * sm);
 513
 514 u32 serialize_close_vlib_buffer (serialize_main_t * m);
 515 void unserialize_close_vlib_buffer (serialize_main_t * m);
 516 void *vlib_set_buffer_free_callback (struct vlib_main_t *vm, void *fp);
 517
 518 always_inline u32
 519 serialize_vlib_buffer_n_bytes (serialize_main_t * m)
 520 {
 521   serialize_stream_t *s = &m->stream;
 522   vlib_serialize_buffer_main_t *sm
 523     = uword_to_pointer (m->stream.data_function_opaque,
 524                         vlib_serialize_buffer_main_t *);
 525   return sm->tx.n_total_data_bytes + s->current_buffer_index +
 526     vec_len (s->overflow_buffer);
 527 }
 528
 529 /*
 530  */
 531
 532 /** \brief Compile time buffer trajectory tracing option
 533     Turn this on if you run into "bad monkey" contexts,
 534     and you want to know exactly which nodes they've visited...
 535     See vlib/main.c...
 536 */
 537 #define VLIB_BUFFER_TRACE_TRAJECTORY 0
 538
 539 #if VLIB_BUFFER_TRACE_TRAJECTORY > 0
 540 extern void (*vlib_buffer_trace_trajectory_cb) (vlib_buffer_t * b, u32 index);
 541 extern void (*vlib_buffer_trace_trajectory_init_cb) (vlib_buffer_t * b);
 542 extern void vlib_buffer_trace_trajectory_init (vlib_buffer_t * b);
 543 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b) \
 544   vlib_buffer_trace_trajectory_init (b);
 545 #else
 546 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b)
 547 #endif /* VLIB_BUFFER_TRACE_TRAJECTORY */
 548
 549 #endif /* included_vlib_buffer_h */
 550
 551 #define VLIB_BUFFER_REGISTER_CALLBACKS(x,...)                           \
 552     __VA_ARGS__ vlib_buffer_callbacks_t __##x##_buffer_callbacks;       \
 553 static void __vlib_add_buffer_callbacks_t_##x (void)                    \
 554     __attribute__((__constructor__)) ;                                  \
 555 static void __vlib_add_buffer_callbacks_t_##x (void)                    \
 556 {                                                                       \
 557     if (vlib_buffer_callbacks)                                          \
 558       clib_panic ("vlib buffer callbacks already registered");          \
 559     vlib_buffer_callbacks = &__##x##_buffer_callbacks;                  \
 560 }                                                                       \
 561 static void __vlib_rm_buffer_callbacks_t_##x (void)                     \
 562     __attribute__((__destructor__)) ;                                   \
 563 static void __vlib_rm_buffer_callbacks_t_##x (void)                     \
 564 { vlib_buffer_callbacks = 0; }                                          \
 565 __VA_ARGS__ vlib_buffer_callbacks_t __##x##_buffer_callbacks
 566
 567 /*
 568  * fd.io coding-style-patch-verification: ON
 569  *
 570  * Local Variables:
 571  * eval: (c-set-style "gnu")
 572  * End:
 573  */