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