vlib/vlib/node.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  * node.h: VLIB processing nodes
  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_node_h
  41 #define included_vlib_node_h
  42
  43 #include <vppinfra/longjmp.h>
  44 #include <vppinfra/timing_wheel.h>
  45 #include <vlib/trace.h>         /* for vlib_trace_filter_t */
  46
  47 /* Forward declaration. */
  48 struct vlib_node_runtime_t;
  49 struct vlib_frame_t;
  50
  51 /* Internal nodes (including output nodes) move data from node to
  52    node (or out of the graph for output nodes). */
  53 typedef uword (vlib_node_function_t) (struct vlib_main_t * vm,
  54                                       struct vlib_node_runtime_t * node,
  55                                       struct vlib_frame_t * frame);
  56
  57 typedef enum {
  58   /* An internal node on the call graph (could be output). */
  59   VLIB_NODE_TYPE_INTERNAL,
  60
  61   /* Nodes which input data into the processing graph.
  62      Input nodes are called for each iteration of main loop. */
  63   VLIB_NODE_TYPE_INPUT,
  64
  65   /* Nodes to be called before all input nodes.
  66      Used, for example, to clean out driver TX rings before
  67      processing input. */
  68   VLIB_NODE_TYPE_PRE_INPUT,
  69
  70   /* "Process" nodes which can be suspended and later resumed. */
  71   VLIB_NODE_TYPE_PROCESS,
  72
  73   VLIB_N_NODE_TYPE,
  74 } vlib_node_type_t;
  75
  76 typedef struct _vlib_node_registration {
  77   /* Vector processing function for this node. */
  78   vlib_node_function_t * function;
  79
  80   /* Node name. */
  81   char * name;
  82
  83   /* Name of sibling (if applicable). */
  84   char * sibling_of;
  85
  86   /* Node index filled in by registration. */
  87   u32 index;
  88
  89   /* Type of this node. */
  90   vlib_node_type_t type;
  91
  92   /* Error strings indexed by error code for this node. */
  93   char ** error_strings;
  94
  95   /* Buffer format/unformat for this node. */
  96   format_function_t * format_buffer;
  97   unformat_function_t * unformat_buffer;
  98
  99   /* Trace format/unformat for this node. */
 100   format_function_t * format_trace;
 101   unformat_function_t * unformat_trace;
 102
 103   /* Function to validate incoming frames. */
 104   u8 * (* validate_frame) (struct vlib_main_t * vm,
 105                            struct vlib_node_runtime_t *,
 106                            struct vlib_frame_t * f);
 107
 108   /* Per-node runtime data. */
 109   void * runtime_data;
 110
 111   /* Process stack size. */
 112   u16 process_log2_n_stack_bytes;
 113
 114   /* Number of bytes of per-node run time data. */
 115   u8 runtime_data_bytes;
 116
 117   /* State for input nodes. */
 118   u8 state;
 119
 120   /* Node flags. */
 121   u16 flags;
 122
 123   /* Size of scalar and vector arguments in bytes. */
 124   u16 scalar_size, vector_size;
 125
 126   /* Number of error codes used by this node. */
 127   u16 n_errors;
 128
 129   /* Number of next node names that follow. */
 130   u16 n_next_nodes;
 131
 132   /* Constructor link-list, don't ask... */
 133   struct _vlib_node_registration * next_registration;
 134
 135   /* Names of next nodes which this node feeds into. */
 136   char * next_nodes[];
 137
 138 } vlib_node_registration_t;
 139
 140 #define VLIB_REGISTER_NODE(x,...)                                       \
 141     __VA_ARGS__ vlib_node_registration_t x;                             \
 142 static void __vlib_add_node_registration_##x (void)                     \
 143     __attribute__((__constructor__)) ;                                  \
 144 static void __vlib_add_node_registration_##x (void)                     \
 145 {                                                                       \
 146     vlib_main_t * vm = vlib_get_main();                                 \
 147     x.next_registration = vm->node_main.node_registrations;             \
 148     vm->node_main.node_registrations = &x;                              \
 149 }                                                                       \
 150 __VA_ARGS__ vlib_node_registration_t x
 151
 152 always_inline vlib_node_registration_t *
 153 vlib_node_next_registered (vlib_node_registration_t * c)
 154 {
 155   c = clib_elf_section_data_next (c, c->n_next_nodes * sizeof (c->next_nodes[0]));
 156   return c;
 157 }
 158
 159 typedef struct {
 160   /* Total calls, clock ticks and vector elements processed for this node. */
 161   u64 calls, vectors, clocks, suspends;
 162   u64 max_clock;
 163   u64 max_clock_n;
 164 } vlib_node_stats_t;
 165
 166 #define foreach_vlib_node_state                                 \
 167   /* Input node is called each iteration of main loop.          \
 168      This is the default (zero). */                             \
 169   _ (POLLING)                                                   \
 170   /* Input node is called when device signals an interrupt. */  \
 171   _ (INTERRUPT)                                                 \
 172   /* Input node is never called. */                             \
 173   _ (DISABLED)
 174
 175 typedef enum {
 176 #define _(f) VLIB_NODE_STATE_##f,
 177   foreach_vlib_node_state
 178 #undef _
 179   VLIB_N_NODE_STATE,
 180 } vlib_node_state_t;
 181
 182 typedef struct vlib_node_t {
 183   /* Vector processing function for this node. */
 184   vlib_node_function_t * function;
 185
 186   /* Node name. */
 187   u8 * name;
 188
 189   /* Node name index in elog string table. */
 190   u32 name_elog_string;
 191
 192   /* Total statistics for this node. */
 193   vlib_node_stats_t stats_total;
 194
 195   /* Saved values as of last clear (or zero if never cleared).
 196      Current values are always stats_total - stats_last_clear. */
 197   vlib_node_stats_t stats_last_clear;
 198
 199   /* Type of this node. */
 200   vlib_node_type_t type;
 201
 202   /* Node index. */
 203   u32 index;
 204
 205   /* Index of corresponding node runtime. */
 206   u32 runtime_index;
 207
 208   /* Runtime data for this node. */
 209   void * runtime_data;
 210
 211   /* Node flags. */
 212   u16 flags;
 213
 214   /* Processing function keeps frame.  Tells node dispatching code not
 215      to free frame after dispatch is done.  */
 216 #define VLIB_NODE_FLAG_FRAME_NO_FREE_AFTER_DISPATCH (1 << 0)
 217
 218   /* Node counts as output/drop/punt node for stats purposes. */
 219 #define VLIB_NODE_FLAG_IS_OUTPUT (1 << 1)
 220 #define VLIB_NODE_FLAG_IS_DROP (1 << 2)
 221 #define VLIB_NODE_FLAG_IS_PUNT (1 << 3)
 222 #define VLIB_NODE_FLAG_IS_HANDOFF (1 << 4)
 223
 224   /* Set if current node runtime has traced vectors. */
 225 #define VLIB_NODE_FLAG_TRACE (1 << 5)
 226
 227 #define VLIB_NODE_FLAG_SWITCH_FROM_INTERRUPT_TO_POLLING_MODE (1 << 6)
 228 #define VLIB_NODE_FLAG_SWITCH_FROM_POLLING_TO_INTERRUPT_MODE (1 << 7)
 229
 230   /* State for input nodes. */
 231   u8 state;
 232
 233   /* Number of bytes of run time data. */
 234   u8 runtime_data_bytes;
 235
 236   /* Number of error codes used by this node. */
 237   u16 n_errors;
 238
 239   /* Size of scalar and vector arguments in bytes. */
 240   u16 scalar_size, vector_size;
 241
 242   /* Handle/index in error heap for this node. */
 243   u32 error_heap_handle;
 244   u32 error_heap_index;
 245
 246   /* Error strings indexed by error code for this node. */
 247   char ** error_strings;
 248
 249   /* Vector of next node names.
 250      Only used before next_nodes array is initialized. */
 251   char ** next_node_names;
 252
 253   /* Next node indices for this node. */
 254   u32 * next_nodes;
 255
 256   /* Name of node that we are sibling of. */
 257   char * sibling_of;
 258
 259   /* Bitmap of all of this node's siblings. */
 260   uword * sibling_bitmap;
 261
 262   /* Total number of vectors sent to each next node. */
 263   u64 * n_vectors_by_next_node;
 264
 265   /* Hash table mapping next node index into slot in
 266      next_nodes vector.  Quickly determines whether this node
 267      is connected to given next node and, if so, with which slot. */
 268   uword * next_slot_by_node;
 269
 270   /* Bitmap of node indices which feed this node. */
 271   uword * prev_node_bitmap;
 272
 273   /* Node/next-index which own enqueue rights with to this node. */
 274   u32 owner_node_index, owner_next_index;
 275
 276   /* Buffer format/unformat for this node. */
 277   format_function_t * format_buffer;
 278   unformat_function_t * unformat_buffer;
 279
 280   /* Trace buffer format/unformat for this node. */
 281   format_function_t * format_trace;
 282
 283   /* Function to validate incoming frames. */
 284   u8 * (* validate_frame) (struct vlib_main_t * vm,
 285                            struct vlib_node_runtime_t *,
 286                            struct vlib_frame_t * f);
 287 } vlib_node_t;
 288
 289 #define VLIB_INVALID_NODE_INDEX ((u32) ~0)
 290
 291 /* Max number of vector elements to process at once per node. */
 292 #define VLIB_FRAME_SIZE 256
 293 #define VLIB_FRAME_ALIGN VLIB_MAX_CPUS
 294
 295 /* Calling frame (think stack frame) for a node. */
 296 typedef struct vlib_frame_t {
 297   /* Frame flags. */
 298   u16 flags;
 299
 300   /* Number of scalar bytes in arguments. */
 301   u8 scalar_size;
 302
 303   /* Number of bytes per vector argument. */
 304   u8 vector_size;
 305
 306   /* Number of vector elements currently in frame. */
 307   u16 n_vectors;
 308
 309   /* Owner cpuid / heap id */
 310   u16 cpu_index;
 311
 312   /* Scalar and vector arguments to next node. */
 313   u8 arguments[0];
 314 } vlib_frame_t;
 315
 316 typedef struct {
 317   /* Frame index. */
 318   u32 frame_index;
 319
 320   /* Node runtime for this next. */
 321   u32 node_runtime_index;
 322
 323   /* Next frame flags. */
 324   u32 flags;
 325
 326   /* Reflects node frame-used flag for this next. */
 327 #define VLIB_FRAME_NO_FREE_AFTER_DISPATCH \
 328   VLIB_NODE_FLAG_FRAME_NO_FREE_AFTER_DISPATCH
 329
 330   /* This next frame owns enqueue to node
 331      corresponding to node_runtime_index. */
 332 #define VLIB_FRAME_OWNER (1 << 15)
 333
 334   /* Set when frame has been allocated for this next. */
 335 #define VLIB_FRAME_IS_ALLOCATED VLIB_NODE_FLAG_IS_OUTPUT
 336
 337   /* Set when frame has been added to pending vector. */
 338 #define VLIB_FRAME_PENDING VLIB_NODE_FLAG_IS_DROP
 339
 340   /* Set when frame is to be freed after dispatch. */
 341 #define VLIB_FRAME_FREE_AFTER_DISPATCH VLIB_NODE_FLAG_IS_PUNT
 342
 343   /* Set when frame has traced packets. */
 344 #define VLIB_FRAME_TRACE VLIB_NODE_FLAG_TRACE
 345
 346   /* Number of vectors enqueue to this next since last overflow. */
 347   u32 vectors_since_last_overflow;
 348 } vlib_next_frame_t;
 349
 350 always_inline void
 351 vlib_next_frame_init (vlib_next_frame_t * nf)
 352 {
 353   memset (nf, 0, sizeof (nf[0]));
 354   nf->frame_index = ~0;
 355   nf->node_runtime_index = ~0;
 356 }
 357
 358 /* A frame pending dispatch by main loop. */
 359 typedef struct {
 360   /* Node and runtime for this frame. */
 361   u32 node_runtime_index;
 362
 363   /* Frame index (in the heap). */
 364   u32 frame_index;
 365
 366   /* Start of next frames for this node. */
 367   u32 next_frame_index;
 368
 369   /* Special value for next_frame_index when there is no next frame. */
 370 #define VLIB_PENDING_FRAME_NO_NEXT_FRAME ((u32) ~0)
 371 } vlib_pending_frame_t;
 372
 373 typedef struct vlib_node_runtime_t {
 374   /* Node function to call. */
 375   vlib_node_function_t * function;
 376
 377   /* Vector of errors for this node. */
 378   vlib_error_t * errors;
 379
 380   /* Number of clock cycles. */
 381   u32 clocks_since_last_overflow;
 382
 383   /* Maximum clock cycle for an invocation. */
 384   u32 max_clock;
 385
 386   /* Number of vectors in the recorded max_clock. */
 387   u32 max_clock_n;
 388
 389   /* Number of calls. */
 390   u32 calls_since_last_overflow;
 391
 392   /* Number of vector elements processed by this node. */
 393   u32 vectors_since_last_overflow;
 394
 395   /* Start of next frames for this node. */
 396   u32 next_frame_index;
 397
 398   /* Node index. */
 399   u32 node_index;
 400
 401   /* For input nodes: decremented on each main loop interation until it reaches zero
 402      and function is called.  Allows some input nodes to be called
 403      more than others. */
 404   u32 input_main_loops_per_call;
 405
 406   /* Saved main loop counter of last dispatch of this node. */
 407   u32 main_loop_count_last_dispatch;
 408
 409   u32 main_loop_vector_stats[2];
 410
 411   /* Copy of main node flags. */
 412   u16 flags;
 413
 414   /* Input node state. */
 415   u16 state;
 416
 417   u16 n_next_nodes;
 418
 419   /* Next frame index that vector arguments were last enqueued to
 420      last time this node ran.  Set to zero before first run
 421      of this node. */
 422   u16 cached_next_index;
 423
 424   /* CPU this node runs on */
 425   u16 cpu_index;
 426
 427   /* Function dependent node-runtime. */
 428   uword runtime_data[(128
 429                       - 1 * sizeof (vlib_node_function_t *)
 430                       - 1 * sizeof (vlib_error_t *)
 431                       - 11 * sizeof (u32)
 432                       - 5 * sizeof (u16)) / sizeof (uword)];
 433 } vlib_node_runtime_t;
 434
 435 typedef struct {
 436   /* Number of allocated frames for this scalar/vector size. */
 437   u32 n_alloc_frames;
 438
 439   /* Vector of free frame indices for this scalar/vector size. */
 440   u32 * free_frame_indices;
 441 } vlib_frame_size_t;
 442
 443 typedef struct {
 444   /* Users opaque value for event type. */
 445   uword opaque;
 446 } vlib_process_event_type_t;
 447
 448 typedef struct {
 449   /* Node runtime for this process. */
 450   vlib_node_runtime_t node_runtime;
 451
 452   /* Where to longjmp when process is done. */
 453   clib_longjmp_t return_longjmp;
 454
 455 #define VLIB_PROCESS_RETURN_LONGJMP_RETURN ((uword) ~0 - 0)
 456 #define VLIB_PROCESS_RETURN_LONGJMP_SUSPEND ((uword) ~0 - 1)
 457
 458   /* Where to longjmp to resume node after suspend. */
 459   clib_longjmp_t resume_longjmp;
 460 #define VLIB_PROCESS_RESUME_LONGJMP_SUSPEND 0
 461 #define VLIB_PROCESS_RESUME_LONGJMP_RESUME  1
 462
 463   u16 flags;
 464 #define VLIB_PROCESS_IS_SUSPENDED_WAITING_FOR_CLOCK (1 << 0)
 465 #define VLIB_PROCESS_IS_SUSPENDED_WAITING_FOR_EVENT (1 << 1)
 466   /* Set to indicate that this process has been added to resume vector. */
 467 #define VLIB_PROCESS_RESUME_PENDING (1 << 2)
 468
 469   /* Process function is currently running. */
 470 #define VLIB_PROCESS_IS_RUNNING (1 << 3)
 471
 472   /* Size of process stack. */
 473   u16 log2_n_stack_bytes;
 474
 475   u32 suspended_process_frame_index;
 476
 477   /* Number of times this process was suspended. */
 478   u32 n_suspends;
 479
 480   /* Vectors of pending event data indexed by event type index. */
 481   void ** pending_event_data_by_type_index;
 482
 483   /* Bitmap of event type-indices with non-empty vectors. */
 484   uword * non_empty_event_type_bitmap;
 485
 486   /* Bitmap of event type-indices which are one time events. */
 487   uword * one_time_event_type_bitmap;
 488
 489   /* Type is opaque pointer -- typically a pointer to an event handler
 490      function.  Hash table to map opaque to a type index. */
 491   uword * event_type_index_by_type_opaque;
 492
 493   /* Pool of currently valid event types. */
 494   vlib_process_event_type_t * event_type_pool;
 495
 496   /* When suspending saves cpu cycle counter when process is to be resumed. */
 497   u64 resume_cpu_time;
 498
 499   /* Default output function and its argument for any CLI outputs
 500      within the process. */
 501   vlib_cli_output_function_t *output_function;
 502   uword output_function_arg;
 503
 504 #ifdef CLIB_UNIX
 505   /* Pad to a multiple of the page size so we can mprotect process stacks */
 506 #define PAGE_SIZE_MULTIPLE 0x1000
 507 #define ALIGN_ON_MULTIPLE_PAGE_BOUNDARY_FOR_MPROTECT  __attribute__ ((aligned (PAGE_SIZE_MULTIPLE)))
 508 #else
 509 #define ALIGN_ON_MULTIPLE_PAGE_BOUNDARY_FOR_MPROTECT
 510 #endif
 511
 512   /* Process stack.  Starts here and extends 2^log2_n_stack_bytes
 513      bytes. */
 514
 515 #define VLIB_PROCESS_STACK_MAGIC (0xdead7ead)
 516   u32 stack[0] ALIGN_ON_MULTIPLE_PAGE_BOUNDARY_FOR_MPROTECT;
 517 } vlib_process_t __attribute__ ((aligned (CLIB_CACHE_LINE_BYTES)));
 518
 519 #ifdef CLIB_UNIX
 520   /* Ensure that the stack is aligned on the multiple of the page size */
 521 typedef char assert_process_stack_must_be_aligned_exactly_to_page_size_multiple
 522                 [(sizeof(vlib_process_t) - PAGE_SIZE_MULTIPLE) == 0 ? 0 : -1];
 523 #endif
 524
 525 typedef struct {
 526     u32 node_index;
 527
 528     u32 one_time_event;
 529 } vlib_one_time_waiting_process_t;
 530
 531 typedef struct {
 532   u16 n_data_elts;
 533
 534   u16 n_data_elt_bytes;
 535
 536   /* n_data_elts * n_data_elt_bytes */
 537   u32 n_data_bytes;
 538
 539   /* Process node & event type to be used to signal event. */
 540   u32 process_node_index;
 541
 542   u32 event_type_index;
 543
 544   union {
 545     u8 inline_event_data[64 - 3 * sizeof (u32) - 2 * sizeof (u16)];
 546
 547     /* Vector of event data used only when data does not fit inline. */
 548     u8 * event_data_as_vector;
 549   };
 550 } vlib_signal_timed_event_data_t;
 551
 552 always_inline uword
 553 vlib_timing_wheel_data_is_timed_event (u32 d)
 554 { return d & 1; }
 555
 556 always_inline u32
 557 vlib_timing_wheel_data_set_suspended_process (u32 i)
 558 { return 0 + 2*i; }
 559
 560 always_inline u32
 561 vlib_timing_wheel_data_set_timed_event (u32 i)
 562 { return 1 + 2*i; }
 563
 564 always_inline uword
 565 vlib_timing_wheel_data_get_index (u32 d)
 566 { return d / 2; }
 567
 568 typedef struct {
 569   /* Public nodes. */
 570   vlib_node_t ** nodes;
 571
 572   /* Node index hashed by node name. */
 573   uword * node_by_name;
 574
 575   u32 flags;
 576 #define VLIB_NODE_MAIN_RUNTIME_STARTED (1 << 0)
 577
 578   /* Nodes segregated by type for cache locality.
 579      Does not apply to nodes of type VLIB_NODE_TYPE_INTERNAL. */
 580   vlib_node_runtime_t * nodes_by_type[VLIB_N_NODE_TYPE];
 581
 582   /* Node runtime indices for input nodes with pending interrupts. */
 583   u32 * pending_interrupt_node_runtime_indices;
 584
 585   /* Input nodes are switched from/to interrupt to/from polling mode
 586      when average vector length goes above/below polling/interrupt
 587      thresholds. */
 588   u32 polling_threshold_vector_length;
 589   u32 interrupt_threshold_vector_length;
 590
 591   /* Vector of next frames. */
 592   vlib_next_frame_t * next_frames;
 593
 594   /* Vector of internal node's frames waiting to be called. */
 595   vlib_pending_frame_t * pending_frames;
 596
 597   /* Timing wheel for scheduling time-based node dispatch. */
 598   timing_wheel_t timing_wheel;
 599
 600   vlib_signal_timed_event_data_t * signal_timed_event_data_pool;
 601
 602   /* Opaque data vector added via timing_wheel_advance. */
 603   u32 * data_from_advancing_timing_wheel;
 604
 605   /* CPU time of next process to be ready on timing wheel. */
 606   u64 cpu_time_next_process_ready;
 607
 608   /* Vector of process nodes.
 609      One for each node of type VLIB_NODE_TYPE_PROCESS. */
 610   vlib_process_t ** processes;
 611
 612   /* Current running process or ~0 if no process running. */
 613   u32 current_process_index;
 614
 615   /* Pool of pending process frames. */
 616   vlib_pending_frame_t * suspended_process_frames;
 617
 618   /* Vector of event data vectors pending recycle. */
 619   void ** recycled_event_data_vectors;
 620
 621   /* Current counts of nodes in each state. */
 622   u32 input_node_counts_by_state[VLIB_N_NODE_STATE];
 623
 624   /* Hash of (scalar_size,vector_size) to frame_sizes index. */
 625   uword * frame_size_hash;
 626
 627   /* Per-size frame allocation information. */
 628   vlib_frame_size_t * frame_sizes;
 629
 630   /* Time of last node runtime stats clear. */
 631   f64 time_last_runtime_stats_clear;
 632
 633   /* Node registrations added by constructors */
 634   vlib_node_registration_t * node_registrations;
 635 } vlib_node_main_t;
 636
 637 #endif /* included_vlib_node_h */