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