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 /** \file
  63     vlib buffer structure definition and a few select
  64     access methods. This structure and the buffer allocation
  65     mechanism should perhaps live in vnet, but it would take a lot
  66     of typing to make it so.
  67 */
  68
  69 /**
  70  * Buffer Flags
  71  */
  72 #define foreach_vlib_buffer_flag \
  73   _( 0, IS_TRACED, 0)                                   \
  74   _( 1, NEXT_PRESENT, 0)                                \
  75   _( 2, TOTAL_LENGTH_VALID, 0)                          \
  76   _( 3, EXT_HDR_VALID, "ext-hdr-valid")
  77
  78 /* NOTE: only buffer generic flags should be defined here, please consider
  79    using user flags. i.e. src/vnet/buffer.h */
  80
  81 enum
  82 {
  83 #define _(bit, name, v) VLIB_BUFFER_##name  = (1 << (bit)),
  84   foreach_vlib_buffer_flag
  85 #undef _
  86 };
  87
  88 enum
  89 {
  90 #define _(bit, name, v) VLIB_BUFFER_LOG2_##name  = (bit),
  91   foreach_vlib_buffer_flag
  92 #undef _
  93 };
  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 #define VLIB_BUFFER_FLAGS_ALL (0x0f)
  99
 100 /** VLIB buffer representation. */
 101 typedef union
 102 {
 103   struct
 104   {
 105     CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 106
 107     /** signed offset in data[], pre_data[] that we are currently
 108       * processing. If negative current header points into predata area.  */
 109     i16 current_data;
 110
 111     /** Nbytes between current data and the end of this buffer.  */
 112     u16 current_length;
 113
 114     /** buffer flags:
 115         <br> VLIB_BUFFER_FREE_LIST_INDEX_MASK: bits used to store free list index,
 116         <br> VLIB_BUFFER_IS_TRACED: trace this buffer.
 117         <br> VLIB_BUFFER_NEXT_PRESENT: this is a multi-chunk buffer.
 118         <br> VLIB_BUFFER_TOTAL_LENGTH_VALID: as it says
 119         <br> VLIB_BUFFER_EXT_HDR_VALID: buffer contains valid external buffer manager header,
 120         set to avoid adding it to a flow report
 121         <br> VLIB_BUFFER_FLAG_USER(n): user-defined bit N
 122      */
 123     u32 flags;
 124
 125     /** Generic flow identifier */
 126     u32 flow_id;
 127
 128     /** Reference count for this buffer. */
 129     volatile u8 ref_count;
 130
 131     /** index of buffer pool this buffer belongs. */
 132     u8 buffer_pool_index;
 133
 134     /** Error code for buffers to be enqueued to error handler.  */
 135     vlib_error_t error;
 136
 137     /** Next buffer for this linked-list of buffers. Only valid if
 138       * VLIB_BUFFER_NEXT_PRESENT flag is set. */
 139     u32 next_buffer;
 140
 141     /** Used by feature subgraph arcs to visit enabled feature nodes */
 142     u32 current_config_index;
 143
 144     /** Opaque data used by sub-graphs for their own purposes. */
 145     u32 opaque[10];
 146
 147     /** part of buffer metadata which is initialized on alloc ends here. */
 148       STRUCT_MARK (template_end);
 149
 150     /** start of 2nd cache line */
 151       CLIB_CACHE_LINE_ALIGN_MARK (cacheline1);
 152
 153     /** Specifies index into trace buffer if VLIB_PACKET_IS_TRACED flag is
 154       * set. */
 155     u32 trace_index;
 156
 157     /** Only valid for first buffer in chain. Current length plus total length
 158       * given here give total number of bytes in buffer chain. */
 159     u32 total_length_not_including_first_buffer;
 160
 161     /**< More opaque data, see ../vnet/vnet/buffer.h */
 162     u32 opaque2[14];
 163
 164     /** start of third cache line */
 165       CLIB_CACHE_LINE_ALIGN_MARK (cacheline2);
 166
 167     /** Space for inserting data before buffer start.  Packet rewrite string
 168       * will be rewritten backwards and may extend back before
 169       * buffer->data[0].  Must come directly before packet data.  */
 170     u8 pre_data[VLIB_BUFFER_PRE_DATA_SIZE];
 171
 172     /** Packet data */
 173     u8 data[0];
 174   };
 175 #ifdef CLIB_HAVE_VEC128
 176   u8x16 as_u8x16[4];
 177 #endif
 178 #ifdef CLIB_HAVE_VEC256
 179   u8x32 as_u8x32[2];
 180 #endif
 181 #ifdef CLIB_HAVE_VEC512
 182   u8x64 as_u8x64[1];
 183 #endif
 184 } vlib_buffer_t;
 185
 186 #define VLIB_BUFFER_HDR_SIZE  (sizeof(vlib_buffer_t) - VLIB_BUFFER_PRE_DATA_SIZE)
 187
 188 /** \brief Prefetch buffer metadata.
 189     The first 64 bytes of buffer contains most header information
 190
 191     @param b - (vlib_buffer_t *) pointer to the buffer
 192     @param type - LOAD, STORE. In most cases, STORE is the right answer
 193 */
 194
 195 #define vlib_prefetch_buffer_header(b,type) CLIB_PREFETCH (b, 64, type)
 196 #define vlib_prefetch_buffer_data(b,type) \
 197   CLIB_PREFETCH (vlib_buffer_get_current(b), CLIB_CACHE_LINE_BYTES, type)
 198
 199 always_inline void
 200 vlib_buffer_struct_is_sane (vlib_buffer_t * b)
 201 {
 202   ASSERT (sizeof (b[0]) % 64 == 0);
 203
 204   /* Rewrite data must be before and contiguous with packet data. */
 205   ASSERT (b->pre_data + VLIB_BUFFER_PRE_DATA_SIZE == b->data);
 206 }
 207
 208 always_inline uword
 209 vlib_buffer_get_va (vlib_buffer_t * b)
 210 {
 211   return pointer_to_uword (b->data);
 212 }
 213
 214 /** \brief Get pointer to current data to process
 215
 216     @param b - (vlib_buffer_t *) pointer to the buffer
 217     @return - (void *) (b->data + b->current_data)
 218 */
 219
 220 always_inline void *
 221 vlib_buffer_get_current (vlib_buffer_t * b)
 222 {
 223   /* Check bounds. */
 224   ASSERT ((signed) b->current_data >= (signed) -VLIB_BUFFER_PRE_DATA_SIZE);
 225   return b->data + b->current_data;
 226 }
 227
 228 always_inline uword
 229 vlib_buffer_get_current_va (vlib_buffer_t * b)
 230 {
 231   return vlib_buffer_get_va (b) + b->current_data;
 232 }
 233
 234 /** \brief Advance current data pointer by the supplied (signed!) amount
 235
 236     @param b - (vlib_buffer_t *) pointer to the buffer
 237     @param l - (word) signed increment
 238 */
 239 always_inline void
 240 vlib_buffer_advance (vlib_buffer_t * b, word l)
 241 {
 242   ASSERT (b->current_length >= l);
 243   b->current_data += l;
 244   b->current_length -= l;
 245
 246   ASSERT ((b->flags & VLIB_BUFFER_NEXT_PRESENT) == 0 ||
 247           b->current_length >= VLIB_BUFFER_MIN_CHAIN_SEG_SIZE);
 248 }
 249
 250 /** \brief Check if there is enough space in buffer to advance
 251
 252     @param b - (vlib_buffer_t *) pointer to the buffer
 253     @param l - (word) size to check
 254     @return - 0 if there is less space than 'l' in buffer
 255 */
 256 always_inline u8
 257 vlib_buffer_has_space (vlib_buffer_t * b, word l)
 258 {
 259   return b->current_length >= l;
 260 }
 261
 262 /** \brief Reset current header & length to state they were in when
 263     packet was received.
 264
 265     @param b - (vlib_buffer_t *) pointer to the buffer
 266 */
 267
 268 always_inline void
 269 vlib_buffer_reset (vlib_buffer_t * b)
 270 {
 271   b->current_length += clib_max (b->current_data, 0);
 272   b->current_data = 0;
 273 }
 274
 275 /** \brief Get pointer to buffer's opaque data array
 276
 277     @param b - (vlib_buffer_t *) pointer to the buffer
 278     @return - (void *) b->opaque
 279 */
 280 always_inline void *
 281 vlib_get_buffer_opaque (vlib_buffer_t * b)
 282 {
 283   return (void *) b->opaque;
 284 }
 285
 286 /** \brief Get pointer to buffer's opaque2 data array
 287
 288     @param b - (vlib_buffer_t *) pointer to the buffer
 289     @return - (void *) b->opaque2
 290 */
 291 always_inline void *
 292 vlib_get_buffer_opaque2 (vlib_buffer_t * b)
 293 {
 294   return (void *) b->opaque2;
 295 }
 296
 297 /** \brief Get pointer to the end of buffer's data
 298  * @param b     pointer to the buffer
 299  * @return      pointer to tail of packet's data
 300  */
 301 always_inline u8 *
 302 vlib_buffer_get_tail (vlib_buffer_t * b)
 303 {
 304   return b->data + b->current_data + b->current_length;
 305 }
 306
 307 /** \brief Append uninitialized data to buffer
 308  * @param b     pointer to the buffer
 309  * @param size  number of uninitialized bytes
 310  * @return      pointer to beginning of uninitialized data
 311  */
 312 always_inline void *
 313 vlib_buffer_put_uninit (vlib_buffer_t * b, u16 size)
 314 {
 315   void *p = vlib_buffer_get_tail (b);
 316   /* XXX make sure there's enough space */
 317   b->current_length += size;
 318   return p;
 319 }
 320
 321 /** \brief Prepend uninitialized data to buffer
 322  * @param b     pointer to the buffer
 323  * @param size  number of uninitialized bytes
 324  * @return      pointer to beginning of uninitialized data
 325  */
 326 always_inline void *
 327 vlib_buffer_push_uninit (vlib_buffer_t * b, u8 size)
 328 {
 329   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
 330   b->current_data -= size;
 331   b->current_length += size;
 332
 333   return vlib_buffer_get_current (b);
 334 }
 335
 336 /** \brief Make head room, typically for packet headers
 337  * @param b     pointer to the buffer
 338  * @param size  number of head room bytes
 339  * @return      pointer to start of buffer (current data)
 340  */
 341 always_inline void *
 342 vlib_buffer_make_headroom (vlib_buffer_t * b, u8 size)
 343 {
 344   ASSERT (b->current_data + VLIB_BUFFER_PRE_DATA_SIZE >= size);
 345   b->current_data += size;
 346   return vlib_buffer_get_current (b);
 347 }
 348
 349 /** \brief Retrieve bytes from buffer head
 350  * @param b     pointer to the buffer
 351  * @param size  number of bytes to pull
 352  * @return      pointer to start of buffer (current data)
 353  */
 354 always_inline void *
 355 vlib_buffer_pull (vlib_buffer_t * b, u8 size)
 356 {
 357   if (b->current_length + VLIB_BUFFER_PRE_DATA_SIZE < size)
 358     return 0;
 359
 360   void *data = vlib_buffer_get_current (b);
 361   vlib_buffer_advance (b, size);
 362   return data;
 363 }
 364
 365 /* Forward declaration. */
 366 struct vlib_main_t;
 367
 368 typedef struct
 369 {
 370   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 371   u32 *cached_buffers;
 372   u32 n_alloc;
 373 } vlib_buffer_pool_thread_t;
 374 typedef struct
 375 {
 376   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 377   uword start;
 378   uword size;
 379   uword log2_page_size;
 380   u8 index;
 381   u32 numa_node;
 382   u32 physmem_map_index;
 383   u32 data_size;
 384   u32 n_buffers;
 385   u32 *buffers;
 386   u8 *name;
 387   clib_spinlock_t lock;
 388
 389   /* per-thread data */
 390   vlib_buffer_pool_thread_t *threads;
 391
 392   /* buffer metadata template */
 393   vlib_buffer_t buffer_template;
 394 } vlib_buffer_pool_t;
 395
 396 typedef struct
 397 {
 398   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
 399   /* Virtual memory address and size of buffer memory, used for calculating
 400      buffer index */
 401   uword buffer_mem_start;
 402   uword buffer_mem_size;
 403   vlib_buffer_pool_t *buffer_pools;
 404
 405   /* Hash table mapping buffer index into number
 406      0 => allocated but free, 1 => allocated and not-free.
 407      If buffer index is not in hash table then this buffer
 408      has never been allocated. */
 409   uword *buffer_known_hash;
 410   clib_spinlock_t buffer_known_hash_lockp;
 411   u32 n_numa_nodes;
 412
 413   /* config */
 414   u32 buffers_per_numa;
 415   u16 ext_hdr_size;
 416
 417   /* logging */
 418   vlib_log_class_t log_default;
 419 } vlib_buffer_main_t;
 420
 421 clib_error_t *vlib_buffer_main_init (struct vlib_main_t *vm);
 422
 423 /*
 424  */
 425
 426 /** \brief Compile time buffer trajectory tracing option
 427     Turn this on if you run into "bad monkey" contexts,
 428     and you want to know exactly which nodes they've visited...
 429     See vlib/main.c...
 430 */
 431 #define VLIB_BUFFER_TRACE_TRAJECTORY 0
 432
 433 #if VLIB_BUFFER_TRACE_TRAJECTORY > 0
 434 extern void (*vlib_buffer_trace_trajectory_cb) (vlib_buffer_t * b, u32 index);
 435 extern void (*vlib_buffer_trace_trajectory_init_cb) (vlib_buffer_t * b);
 436 extern void vlib_buffer_trace_trajectory_init (vlib_buffer_t * b);
 437 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b) \
 438   vlib_buffer_trace_trajectory_init (b);
 439 #else
 440 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b)
 441 #endif /* VLIB_BUFFER_TRACE_TRAJECTORY */
 442
 443 extern u16 __vlib_buffer_external_hdr_size;
 444 #define VLIB_BUFFER_SET_EXT_HDR_SIZE(x) \
 445 static void __clib_constructor \
 446 vnet_buffer_set_ext_hdr_size() \
 447 { \
 448   if (__vlib_buffer_external_hdr_size) \
 449     clib_error ("buffer external header space already set"); \
 450   __vlib_buffer_external_hdr_size = CLIB_CACHE_LINE_ROUND (x); \
 451 }
 452
 453 #endif /* included_vlib_buffer_h */
 454
 455 /*
 456  * fd.io coding-style-patch-verification: ON
 457  *
 458  * Local Variables:
 459  * eval: (c-set-style "gnu")
 460  * End:
 461  */