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