vlib/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 #if DPDK > 0
  50 #include <rte_config.h>
  51 #define VLIB_BUFFER_DATA_SIZE           (2048)
  52 #define VLIB_BUFFER_PRE_DATA_SIZE       RTE_PKTMBUF_HEADROOM
  53 #else
  54 #include <vlib/config.h>        /* for __PRE_DATA_SIZE */
  55 #define VLIB_BUFFER_DATA_SIZE           (512)
  56 #define VLIB_BUFFER_PRE_DATA_SIZE       __PRE_DATA_SIZE
  57 #endif
  58
  59 #ifdef CLIB_HAVE_VEC128
  60 typedef u8x16 vlib_copy_unit_t;
  61 #else
  62 typedef u64 vlib_copy_unit_t;
  63 #endif
  64
  65 /** \file
  66     vlib buffer structure definition and a few select
  67     access methods. This structure and the buffer allocation
  68     mechanism should perhaps live in vnet, but it would take a lot
  69     of typing to make it so.
  70 */
  71
  72 /* VLIB buffer representation. */
  73 typedef struct {
  74   CLIB_CACHE_LINE_ALIGN_MARK(cacheline0);
  75   /* Offset within data[] that we are currently processing.
  76      If negative current header points into predata area. */
  77   i16 current_data;  /**< signed offset in data[], pre_data[]
  78                         that we are currently processing.
  79                         If negative current header points into predata area.
  80                      */
  81   u16 current_length;  /**< Nbytes between current data and
  82                           the end of this buffer.
  83                        */
  84   u32 flags; /**< buffer flags:
  85                 <br> VLIB_BUFFER_IS_TRACED: trace this buffer.
  86                 <br> VLIB_BUFFER_NEXT_PRESENT: this is a multi-chunk buffer.
  87                 <br> VLIB_BUFFER_TOTAL_LENGTH_VALID: as it says
  88                 <br> VLIB_BUFFER_REPL_FAIL: packet replication failure
  89                 <br> VLIB_BUFFER_FLAG_USER(n): user-defined bit N
  90              */
  91 #define VLIB_BUFFER_IS_TRACED (1 << 0)
  92 #define VLIB_BUFFER_LOG2_NEXT_PRESENT (1)
  93 #define VLIB_BUFFER_NEXT_PRESENT (1 << VLIB_BUFFER_LOG2_NEXT_PRESENT)
  94 #define VLIB_BUFFER_IS_RECYCLED (1 << 2)
  95 #define VLIB_BUFFER_TOTAL_LENGTH_VALID (1 << 3)
  96 #define VLIB_BUFFER_REPL_FAIL (1 << 4)
  97
  98   /* User defined buffer flags. */
  99 #define LOG2_VLIB_BUFFER_FLAG_USER(n) (32 - (n))
 100 #define VLIB_BUFFER_FLAG_USER(n) (1 << LOG2_VLIB_BUFFER_FLAG_USER(n))
 101
 102   u32 free_list_index; /**< Buffer free list that this buffer was
 103                           allocated from and will be freed to.
 104                        */
 105
 106   u32 total_length_not_including_first_buffer;
 107   /**< Only valid for first buffer in chain. Current length plus
 108      total length given here give total number of bytes in buffer chain.
 109   */
 110
 111
 112   u32 next_buffer;   /**< Next buffer for this linked-list of buffers.
 113                         Only valid if VLIB_BUFFER_NEXT_PRESENT flag is set.
 114                      */
 115
 116   u32 trace_index; /**< Specifies index into trace buffer
 117                       if VLIB_PACKET_IS_TRACED flag is set.
 118                    */
 119
 120
 121   u32 clone_count; /**< Specifies whether this buffer should be
 122                       reinitialized when freed. It will be reinitialized
 123                       if the value is 0. This field can be used
 124                       as a counter or for other state during packet
 125                       replication. The buffer free function does not
 126                       modify this value.
 127                    */
 128
 129   vlib_error_t error;   /**< Error code for buffers to be enqueued
 130                            to error handler.
 131                         */
 132
 133   u32 opaque[8]; /**< Opaque data used by sub-graphs for their own purposes.
 134                     See .../vnet/vnet/buffer.h
 135                  */
 136   CLIB_CACHE_LINE_ALIGN_MARK(cacheline1);
 137
 138   u32 opaque2[16];  /**< More opaque data, in its own cache line */
 139
 140   /***** end of second cache line */
 141   CLIB_CACHE_LINE_ALIGN_MARK(cacheline2);
 142   u8 pre_data [VLIB_BUFFER_PRE_DATA_SIZE]; /**< Space for inserting data
 143                                                before buffer start.
 144                                                Packet rewrite string will be
 145                                                rewritten backwards and may extend
 146                                                back before buffer->data[0].
 147                                                Must come directly before packet data.
 148                                             */
 149
 150   u8 data[0]; /**< Packet data. Hardware DMA here */
 151 } vlib_buffer_t;  /* Must be a multiple of 64B. */
 152
 153 #define VLIB_BUFFER_HDR_SIZE  (sizeof(vlib_buffer_t) - VLIB_BUFFER_PRE_DATA_SIZE)
 154
 155 /** \brief Prefetch buffer metadata.
 156     The first 64 bytes of buffer contains most header information
 157
 158     @param b - (vlib_buffer_t *) pointer to the buffer
 159     @param type - LOAD, STORE. In most cases, STORE is the right answer
 160 */
 161
 162 #define vlib_prefetch_buffer_header(b,type) CLIB_PREFETCH (b, 64, type)
 163
 164 always_inline vlib_buffer_t *
 165 vlib_buffer_next_contiguous (vlib_buffer_t * b, u32 buffer_bytes)
 166 { return (void *) (b + 1) + buffer_bytes; }
 167
 168 always_inline void
 169 vlib_buffer_struct_is_sane (vlib_buffer_t * b)
 170 {
 171   ASSERT (sizeof (b[0]) % 64 == 0);
 172
 173   /* Rewrite data must be before and contiguous with packet data. */
 174   ASSERT (b->pre_data + VLIB_BUFFER_PRE_DATA_SIZE == b->data);
 175 }
 176
 177 /** \brief Get pointer to current data to process
 178
 179     @param b - (vlib_buffer_t *) pointer to the buffer
 180     @return - (void *) (b->data + b->current_data)
 181 */
 182
 183 always_inline void *
 184 vlib_buffer_get_current (vlib_buffer_t * b)
 185 {
 186   /* Check bounds. */
 187   ASSERT ((signed) b->current_data >= (signed) -VLIB_BUFFER_PRE_DATA_SIZE);
 188   return b->data + b->current_data;
 189 }
 190
 191 /** \brief Advance current data pointer by the supplied (signed!) amount
 192
 193     @param b - (vlib_buffer_t *) pointer to the buffer
 194     @param l - (word) signed increment
 195 */
 196 always_inline void
 197 vlib_buffer_advance (vlib_buffer_t * b, word l)
 198 {
 199   ASSERT (b->current_length >= l);
 200   b->current_data += l;
 201   b->current_length -= l;
 202 }
 203
 204 /** \brief Reset current header & length to state they were in when
 205     packet was received.
 206
 207     @param b - (vlib_buffer_t *) pointer to the buffer
 208 */
 209
 210 always_inline void
 211 vlib_buffer_reset (vlib_buffer_t * b)
 212 {
 213   b->current_length += clib_max (b->current_data, 0);
 214   b->current_data = 0;
 215 }
 216
 217 /** \brief Get pointer to buffer's opaque data array
 218
 219     @param b - (vlib_buffer_t *) pointer to the buffer
 220     @return - (void *) b->opaque
 221 */
 222 always_inline void *
 223 vlib_get_buffer_opaque (vlib_buffer_t * b)
 224 { return (void *) b->opaque; }
 225
 226 /** \brief Get pointer to buffer's opaque2 data array
 227
 228     @param b - (vlib_buffer_t *) pointer to the buffer
 229     @return - (void *) b->opaque2
 230 */
 231 always_inline void *
 232 vlib_get_buffer_opaque2 (vlib_buffer_t * b)
 233 { return (void *) b->opaque2; }
 234
 235 /* Forward declaration. */
 236 struct vlib_main_t;
 237
 238 typedef struct vlib_buffer_free_list_t {
 239   /* Template buffer used to initialize first 16 bytes of buffers
 240      allocated on this free list. */
 241   vlib_buffer_t buffer_init_template;
 242
 243   /* Our index into vlib_main_t's buffer_free_list_pool. */
 244   u32 index;
 245
 246   /* Number of data bytes for buffers in this free list. */
 247   u32 n_data_bytes;
 248
 249   /* Number of buffers to allocate when we need to allocate new buffers
 250      from physmem heap. */
 251   u32 min_n_buffers_each_physmem_alloc;
 252
 253   /* Total number of buffers allocated from this free list. */
 254   u32 n_alloc;
 255
 256   /* Vector of free buffers.  Each element is a byte offset into I/O heap.
 257      Aligned vectors always has naturally aligned vlib_copy_unit_t sized chunks
 258      of buffer indices.  Unaligned vector has any left over.  This is meant to
 259      speed up copy routines. */
 260   u32 * aligned_buffers, * unaligned_buffers;
 261
 262   /* Memory chunks allocated for this free list
 263      recorded here so they can be freed when free list
 264      is deleted. */
 265   void ** buffer_memory_allocated;
 266
 267   /* Free list name. */
 268   u8 * name;
 269
 270   /* Callback functions to initialize newly allocated buffers.
 271      If null buffers are zeroed. */
 272   void (* buffer_init_function) (struct vlib_main_t * vm,
 273                                  struct vlib_buffer_free_list_t * fl,
 274                                  u32 * buffers, u32 n_buffers);
 275
 276   /* Callback function to announce that buffers have been
 277      added to the freelist */
 278   void (* buffers_added_to_freelist_function)
 279   (struct vlib_main_t * vm,
 280    struct vlib_buffer_free_list_t * fl);
 281
 282   uword buffer_init_function_opaque;
 283 } __attribute__ ((aligned (16))) vlib_buffer_free_list_t;
 284
 285 typedef struct {
 286   /* Buffer free callback, for subversive activities */
 287   u32 (*buffer_free_callback) (struct vlib_main_t *vm,
 288                                u32 * buffers,
 289                                u32 n_buffers,
 290                                u32 follow_buffer_next);
 291   /* Pool of buffer free lists.
 292      Multiple free lists exist for packet generator which uses
 293      separate free lists for each packet stream --- so as to avoid
 294      initializing static data for each packet generated. */
 295   vlib_buffer_free_list_t * buffer_free_list_pool;
 296 #define VLIB_BUFFER_DEFAULT_FREE_LIST_INDEX (0)
 297 #define VLIB_BUFFER_DEFAULT_FREE_LIST_BYTES VLIB_BUFFER_DATA_SIZE
 298
 299   /* Hash table mapping buffer size (rounded to next unit of
 300      sizeof (vlib_buffer_t)) to free list index. */
 301   uword * free_list_by_size;
 302
 303   /* Hash table mapping buffer index into number
 304      0 => allocated but free, 1 => allocated and not-free.
 305      If buffer index is not in hash table then this buffer
 306      has never been allocated. */
 307   uword * buffer_known_hash;
 308
 309   /* List of free-lists needing Blue Light Special announcements */
 310   vlib_buffer_free_list_t **announce_list;
 311
 312   /*  Vector of rte_mempools per socket */
 313 #if DPDK == 1
 314   struct rte_mempool ** pktmbuf_pools;
 315 #endif
 316 } vlib_buffer_main_t;
 317
 318 typedef struct {
 319   struct vlib_main_t * vlib_main;
 320
 321   u32 first_buffer, last_buffer;
 322
 323   union {
 324     struct {
 325       /* Total accumulated bytes in chain starting with first_buffer. */
 326       u32 n_total_data_bytes;
 327
 328       /* Max number of bytes to accumulate in chain starting with first_buffer.
 329          As this limit is reached buffers are enqueued to next node. */
 330       u32 max_n_data_bytes_per_chain;
 331
 332       /* Next node to enqueue buffers to relative to current process node. */
 333       u32 next_index;
 334
 335       /* Free list to use to allocate new buffers. */
 336       u32 free_list_index;
 337     } tx;
 338
 339     struct {
 340       /* CLIB fifo of buffer indices waiting to be unserialized. */
 341       u32 * buffer_fifo;
 342
 343       /* Event type used to signal that RX buffers have been added to fifo. */
 344       uword ready_one_time_event;
 345     } rx;
 346   };
 347 } vlib_serialize_buffer_main_t;
 348
 349 void serialize_open_vlib_buffer (serialize_main_t * m, struct vlib_main_t * vm, vlib_serialize_buffer_main_t * sm);
 350 void unserialize_open_vlib_buffer (serialize_main_t * m, struct vlib_main_t * vm, vlib_serialize_buffer_main_t * sm);
 351
 352 u32 serialize_close_vlib_buffer (serialize_main_t * m);
 353 void unserialize_close_vlib_buffer (serialize_main_t * m);
 354 void *vlib_set_buffer_free_callback (struct vlib_main_t *vm, void *fp);
 355
 356 always_inline u32
 357 serialize_vlib_buffer_n_bytes (serialize_main_t * m)
 358 {
 359   serialize_stream_t * s = &m->stream;
 360   vlib_serialize_buffer_main_t * sm
 361     = uword_to_pointer (m->stream.data_function_opaque, vlib_serialize_buffer_main_t *);
 362   return sm->tx.n_total_data_bytes + s->current_buffer_index + vec_len (s->overflow_buffer);
 363 }
 364
 365 #if DPDK > 0
 366 #define rte_mbuf_from_vlib_buffer(x) (((struct rte_mbuf *)x) - 1)
 367 #define vlib_buffer_from_rte_mbuf(x) ((vlib_buffer_t *)(x+1))
 368 #endif
 369
 370 /*
 371  */
 372
 373 /** \brief Compile time buffer trajectory tracing option
 374     Turn this on if you run into "bad monkey" contexts,
 375     and you want to know exactly which nodes they've visited...
 376     See vlib/main.c...
 377 */
 378 #define VLIB_BUFFER_TRACE_TRAJECTORY 0
 379
 380 #if VLIB_BUFFER_TRACE_TRAJECTORY > 0
 381 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b) (b)->pre_data[0]=0
 382 #else
 383 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b)
 384 #endif /* VLIB_BUFFER_TRACE_TRAJECTORY */
 385
 386 #endif /* included_vlib_buffer_h */