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