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