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