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 <vlib/error.h>         /* for vlib_error_t */
  48
  49 #include <vlib/config.h>        /* for __PRE_DATA_SIZE */
  50 #define VLIB_BUFFER_DATA_SIZE           (2048)
  51 #define VLIB_BUFFER_PRE_DATA_SIZE       __PRE_DATA_SIZE
  52
  53 /** \file
  54     vlib buffer structure definition and a few select
  55     access methods. This structure and the buffer allocation
  56     mechanism should perhaps live in vnet, but it would take a lot
  57     of typing to make it so.
  58 */
  59
  60 /* VLIB buffer representation. */
  61 typedef struct
  62 {
  63   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
  64   /* Offset within data[] that we are currently processing.
  65      If negative current header points into predata area. */
  66   i16 current_data;  /**< signed offset in data[], pre_data[]
  67                         that we are currently processing.
  68                         If negative current header points into predata area.
  69                      */
  70   u16 current_length;  /**< Nbytes between current data and
  71                           the end of this buffer.
  72                        */
  73   u32 flags; /**< buffer flags:
  74                 <br> VLIB_BUFFER_IS_TRACED: trace this buffer.
  75                 <br> VLIB_BUFFER_NEXT_PRESENT: this is a multi-chunk buffer.
  76                 <br> VLIB_BUFFER_TOTAL_LENGTH_VALID: as it says
  77                 <br> VLIB_BUFFER_REPL_FAIL: packet replication failure
  78                 <br> VLIB_BUFFER_RECYCLE: as it says
  79                 <br> VLIB_BUFFER_FLOW_REPORT: buffer is a flow report,
  80                 <br> VLIB_BUFFER_EXT_HDR_VALID: buffer contains valid external buffer manager header,
  81                 set to avoid adding it to a flow report
  82                 <br> VLIB_BUFFER_FLAG_USER(n): user-defined bit N
  83              */
  84 #define VLIB_BUFFER_IS_TRACED (1 << 0)
  85 #define VLIB_BUFFER_LOG2_NEXT_PRESENT (1)
  86 #define VLIB_BUFFER_NEXT_PRESENT (1 << VLIB_BUFFER_LOG2_NEXT_PRESENT)
  87 #define VLIB_BUFFER_IS_RECYCLED (1 << 2)
  88 #define VLIB_BUFFER_TOTAL_LENGTH_VALID (1 << 3)
  89 #define VLIB_BUFFER_REPL_FAIL (1 << 4)
  90 #define VLIB_BUFFER_RECYCLE (1 << 5)
  91 #define VLIB_BUFFER_FLOW_REPORT (1 << 6)
  92 #define VLIB_BUFFER_EXT_HDR_VALID (1 << 7)
  93
  94   /* User defined buffer flags. */
  95 #define LOG2_VLIB_BUFFER_FLAG_USER(n) (32 - (n))
  96 #define VLIB_BUFFER_FLAG_USER(n) (1 << LOG2_VLIB_BUFFER_FLAG_USER(n))
  97
  98   u32 free_list_index; /**< Buffer free list that this buffer was
  99                           allocated from and will be freed to.
 100                        */
 101
 102   u32 total_length_not_including_first_buffer;
 103   /**< Only valid for first buffer in chain. Current length plus
 104      total length given here give total number of bytes in buffer chain.
 105   */
 106
 107   u32 next_buffer;   /**< Next buffer for this linked-list of buffers.
 108                         Only valid if VLIB_BUFFER_NEXT_PRESENT flag is set.
 109                      */
 110
 111   vlib_error_t error;   /**< Error code for buffers to be enqueued
 112                            to error handler.
 113                         */
 114   u32 current_config_index; /**< Used by feature subgraph arcs to
 115                                visit enabled feature nodes
 116                             */
 117
 118   u8 feature_arc_index; /**< Used to identify feature arcs by intermediate
 119                            feature node
 120                         */
 121
 122   u8 dont_waste_me[3]; /**< Available space in the (precious)
 123                           first 32 octets of buffer metadata
 124                           Before allocating any of it, discussion required!
 125                        */
 126
 127   u32 opaque[8]; /**< Opaque data used by sub-graphs for their own purposes.
 128                     See .../vnet/vnet/buffer.h
 129                  */
 130     CLIB_CACHE_LINE_ALIGN_MARK (cacheline1);
 131
 132   u32 trace_index; /**< Specifies index into trace buffer
 133                       if VLIB_PACKET_IS_TRACED flag is set.
 134                    */
 135   u32 recycle_count; /**< Used by L2 path recycle code */
 136   u32 opaque2[14];  /**< More opaque data, currently unused */
 137
 138   /***** end of second cache line */
 139     CLIB_CACHE_LINE_ALIGN_MARK (cacheline2);
 140   u8 pre_data[VLIB_BUFFER_PRE_DATA_SIZE];  /**< Space for inserting data
 141                                                before buffer start.
 142                                                Packet rewrite string will be
 143                                                rewritten backwards and may extend
 144                                                back before buffer->data[0].
 145                                                Must come directly before packet data.
 146                                             */
 147
 148   u8 data[0]; /**< Packet data. Hardware DMA here */
 149 } vlib_buffer_t;                /* Must be a multiple of 64B. */
 150
 151 #define VLIB_BUFFER_HDR_SIZE  (sizeof(vlib_buffer_t) - VLIB_BUFFER_PRE_DATA_SIZE)
 152
 153 /** \brief Prefetch buffer metadata.
 154     The first 64 bytes of buffer contains most header information
 155
 156     @param b - (vlib_buffer_t *) pointer to the buffer
 157     @param type - LOAD, STORE. In most cases, STORE is the right answer
 158 */
 159
 160 #define vlib_prefetch_buffer_header(b,type) CLIB_PREFETCH (b, 64, type)
 161
 162 always_inline vlib_buffer_t *
 163 vlib_buffer_next_contiguous (vlib_buffer_t * b, u32 buffer_bytes)
 164 {
 165   return (void *) (b + 1) + buffer_bytes;
 166 }
 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 {
 225   return (void *) b->opaque;
 226 }
 227
 228 /** \brief Get pointer to buffer's opaque2 data array
 229
 230     @param b - (vlib_buffer_t *) pointer to the buffer
 231     @return - (void *) b->opaque2
 232 */
 233 always_inline void *
 234 vlib_get_buffer_opaque2 (vlib_buffer_t * b)
 235 {
 236   return (void *) b->opaque2;
 237 }
 238
 239 /* Forward declaration. */
 240 struct vlib_main_t;
 241
 242 typedef struct vlib_buffer_free_list_t
 243 {
 244   /* Template buffer used to initialize first 16 bytes of buffers
 245      allocated on this free list. */
 246   vlib_buffer_t buffer_init_template;
 247
 248   /* Our index into vlib_main_t's buffer_free_list_pool. */
 249   u32 index;
 250
 251   /* Number of data bytes for buffers in this free list. */
 252   u32 n_data_bytes;
 253
 254   /* Number of buffers to allocate when we need to allocate new buffers
 255      from physmem heap. */
 256   u32 min_n_buffers_each_physmem_alloc;
 257
 258   /* Total number of buffers allocated from this free list. */
 259   u32 n_alloc;
 260
 261   /* Vector of free buffers.  Each element is a byte offset into I/O heap. */
 262   u32 *buffers;
 263
 264   /* Memory chunks allocated for this free list
 265      recorded here so they can be freed when free list
 266      is deleted. */
 267   void **buffer_memory_allocated;
 268
 269   /* Free list name. */
 270   u8 *name;
 271
 272   /* Callback functions to initialize newly allocated buffers.
 273      If null buffers are zeroed. */
 274   void (*buffer_init_function) (struct vlib_main_t * vm,
 275                                 struct vlib_buffer_free_list_t * fl,
 276                                 u32 * buffers, u32 n_buffers);
 277
 278   /* Callback function to announce that buffers have been
 279      added to the freelist */
 280   void (*buffers_added_to_freelist_function)
 281     (struct vlib_main_t * vm, struct vlib_buffer_free_list_t * fl);
 282
 283   uword buffer_init_function_opaque;
 284 } __attribute__ ((aligned (16))) vlib_buffer_free_list_t;
 285
 286 typedef struct
 287 {
 288   u32 (*vlib_buffer_alloc_cb) (struct vlib_main_t * vm, u32 * buffers,
 289                                u32 n_buffers);
 290   u32 (*vlib_buffer_alloc_from_free_list_cb) (struct vlib_main_t * vm,
 291                                               u32 * buffers, u32 n_buffers,
 292                                               u32 free_list_index);
 293   void (*vlib_buffer_free_cb) (struct vlib_main_t * vm, u32 * buffers,
 294                                u32 n_buffers);
 295   void (*vlib_buffer_free_no_next_cb) (struct vlib_main_t * vm, u32 * buffers,
 296                                        u32 n_buffers);
 297   void (*vlib_packet_template_init_cb) (struct vlib_main_t * vm, void *t,
 298                                         void *packet_data,
 299                                         uword n_packet_data_bytes,
 300                                         uword
 301                                         min_n_buffers_each_physmem_alloc,
 302                                         u8 * name);
 303   void (*vlib_buffer_delete_free_list_cb) (struct vlib_main_t * vm,
 304                                            u32 free_list_index);
 305 } vlib_buffer_callbacks_t;
 306
 307 typedef struct
 308 {
 309   /* Buffer free callback, for subversive activities */
 310   u32 (*buffer_free_callback) (struct vlib_main_t * vm,
 311                                u32 * buffers,
 312                                u32 n_buffers, u32 follow_buffer_next);
 313   /* Pool of buffer free lists.
 314      Multiple free lists exist for packet generator which uses
 315      separate free lists for each packet stream --- so as to avoid
 316      initializing static data for each packet generated. */
 317   vlib_buffer_free_list_t *buffer_free_list_pool;
 318 #define VLIB_BUFFER_DEFAULT_FREE_LIST_INDEX (0)
 319 #define VLIB_BUFFER_DEFAULT_FREE_LIST_BYTES VLIB_BUFFER_DATA_SIZE
 320
 321   /* Hash table mapping buffer size (rounded to next unit of
 322      sizeof (vlib_buffer_t)) to free list index. */
 323   uword *free_list_by_size;
 324
 325   /* Hash table mapping buffer index into number
 326      0 => allocated but free, 1 => allocated and not-free.
 327      If buffer index is not in hash table then this buffer
 328      has never been allocated. */
 329   uword *buffer_known_hash;
 330
 331   /* List of free-lists needing Blue Light Special announcements */
 332   vlib_buffer_free_list_t **announce_list;
 333
 334   /* Callbacks */
 335   vlib_buffer_callbacks_t cb;
 336   int extern_buffer_mgmt;
 337 } vlib_buffer_main_t;
 338
 339 void vlib_buffer_cb_init (struct vlib_main_t *vm);
 340 int vlib_buffer_cb_register (struct vlib_main_t *vm,
 341                              vlib_buffer_callbacks_t * cb);
 342
 343 typedef struct
 344 {
 345   struct vlib_main_t *vlib_main;
 346
 347   u32 first_buffer, last_buffer;
 348
 349   union
 350   {
 351     struct
 352     {
 353       /* Total accumulated bytes in chain starting with first_buffer. */
 354       u32 n_total_data_bytes;
 355
 356       /* Max number of bytes to accumulate in chain starting with first_buffer.
 357          As this limit is reached buffers are enqueued to next node. */
 358       u32 max_n_data_bytes_per_chain;
 359
 360       /* Next node to enqueue buffers to relative to current process node. */
 361       u32 next_index;
 362
 363       /* Free list to use to allocate new buffers. */
 364       u32 free_list_index;
 365     } tx;
 366
 367     struct
 368     {
 369       /* CLIB fifo of buffer indices waiting to be unserialized. */
 370       u32 *buffer_fifo;
 371
 372       /* Event type used to signal that RX buffers have been added to fifo. */
 373       uword ready_one_time_event;
 374     } rx;
 375   };
 376 } vlib_serialize_buffer_main_t;
 377
 378 void serialize_open_vlib_buffer (serialize_main_t * m, struct vlib_main_t *vm,
 379                                  vlib_serialize_buffer_main_t * sm);
 380 void unserialize_open_vlib_buffer (serialize_main_t * m,
 381                                    struct vlib_main_t *vm,
 382                                    vlib_serialize_buffer_main_t * sm);
 383
 384 u32 serialize_close_vlib_buffer (serialize_main_t * m);
 385 void unserialize_close_vlib_buffer (serialize_main_t * m);
 386 void *vlib_set_buffer_free_callback (struct vlib_main_t *vm, void *fp);
 387
 388 always_inline u32
 389 serialize_vlib_buffer_n_bytes (serialize_main_t * m)
 390 {
 391   serialize_stream_t *s = &m->stream;
 392   vlib_serialize_buffer_main_t *sm
 393     = uword_to_pointer (m->stream.data_function_opaque,
 394                         vlib_serialize_buffer_main_t *);
 395   return sm->tx.n_total_data_bytes + s->current_buffer_index +
 396     vec_len (s->overflow_buffer);
 397 }
 398
 399 /*
 400  */
 401
 402 /** \brief Compile time buffer trajectory tracing option
 403     Turn this on if you run into "bad monkey" contexts,
 404     and you want to know exactly which nodes they've visited...
 405     See vlib/main.c...
 406 */
 407 #define VLIB_BUFFER_TRACE_TRAJECTORY 0
 408
 409 #if VLIB_BUFFER_TRACE_TRAJECTORY > 0
 410 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b) (b)->pre_data[0]=0
 411 #else
 412 #define VLIB_BUFFER_TRACE_TRAJECTORY_INIT(b)
 413 #endif /* VLIB_BUFFER_TRACE_TRAJECTORY */
 414
 415 #endif /* included_vlib_buffer_h */
 416
 417 /*
 418  * fd.io coding-style-patch-verification: ON
 419  *
 420  * Local Variables:
 421  * eval: (c-set-style "gnu")
 422  * End:
 423  */