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