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