src/vnet/dpo/dpo.h

   1 /*
   2  * Copyright (c) 2016 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  * @brief
  17  * A Data-Path Object is an object that represents actions that are
  18  * applied to packets are they are switched through VPP's data-path.
  19  *
  20  * The DPO can be considered to be like is a base class that is specialised
  21  * by other objects to provide concreate actions
  22  *
  23  * The VLIB graph nodes are graph of DPO types, the DPO graph is a graph of
  24  * instances.
  25  */
  26
  27 #ifndef __DPO_H__
  28 #define __DPO_H__
  29
  30 #include <vnet/vnet.h>
  31
  32 /**
  33  * @brief An index for adjacencies.
  34  * Alas 'C' is not typesafe enough to b0rk when a u32 is used instead of
  35  * an index_t. However, for us humans, we can glean much more intent
  36  * from the declaration
  37  *  foo barindex_t t);
  38  * than we can from
  39  *  foo bar(u32 t);
  40  */
  41 typedef u32 index_t;
  42
  43 /**
  44  * @brief Invalid index - used when no index is known
  45  * blazoned capitals INVALID speak volumes where ~0 does not.
  46  */
  47 #define INDEX_INVALID ((index_t)(~0))
  48
  49 /**
  50  * @brief Data path protocol.
  51  * Actions performed on packets in the data-plane can be described and represented
  52  * by protocol independent objects, i.e. ADJACENCY, but the spceifics actions
  53  * required during ADJACENCY processing can be protocol dependent. For example,
  54  * the adjacency rewrite node performs a ip4 checksum calculation,  ip6 and MPLS
  55  * do not, all 3 perform a TTL decrement. The VLIB graph nodes are thus protocol
  56  * dependent, and thus each graph edge/arc is too.
  57  * When programming a DPO's next node arc from child to parent it is thus required
  58  * to know the parent's data-path protocol so the correct arc index can be used.
  59  */
  60 typedef enum dpo_proto_t_
  61 {
  62     DPO_PROTO_IP4 = 0,
  63     DPO_PROTO_IP6,
  64     DPO_PROTO_MPLS,
  65     DPO_PROTO_ETHERNET,
  66     DPO_PROTO_BIER,
  67     DPO_PROTO_NSH,
  68 } __attribute__((packed)) dpo_proto_t;
  69
  70 #define DPO_PROTO_NUM ((dpo_proto_t)(DPO_PROTO_NSH+1))
  71 #define DPO_PROTO_NONE ((dpo_proto_t)(DPO_PROTO_NUM+1))
  72
  73 #define DPO_PROTOS {            \
  74     [DPO_PROTO_IP4]  = "ip4",   \
  75     [DPO_PROTO_IP6]  = "ip6",   \
  76     [DPO_PROTO_ETHERNET]  = "ethernet", \
  77     [DPO_PROTO_MPLS] = "mpls",  \
  78     [DPO_PROTO_NSH] = "nsh",    \
  79     [DPO_PROTO_BIER] = "bier",  \
  80 }
  81
  82 #define FOR_EACH_DPO_PROTO(_proto)    \
  83     for (_proto = DPO_PROTO_IP4;      \
  84          _proto <= DPO_PROTO_NSH;    \
  85          _proto++)
  86
  87 /**
  88  * @brief Common types of data-path objects
  89  * New types can be dynamically added using dpo_register_new_type()
  90  */
  91 typedef enum dpo_type_t_ {
  92     /**
  93      * A non-zero value first so we can spot unitialisation errors
  94      */
  95     DPO_FIRST,
  96     DPO_DROP,
  97     DPO_IP_NULL,
  98     DPO_PUNT,
  99     /**
 100      * @brief load-balancing over a choice of [un]equal cost paths
 101      */
 102     DPO_LOAD_BALANCE,
 103     DPO_REPLICATE,
 104     DPO_ADJACENCY,
 105     DPO_ADJACENCY_INCOMPLETE,
 106     DPO_ADJACENCY_MIDCHAIN,
 107     DPO_ADJACENCY_GLEAN,
 108     DPO_ADJACENCY_MCAST,
 109     DPO_ADJACENCY_MCAST_MIDCHAIN,
 110     DPO_RECEIVE,
 111     DPO_LOOKUP,
 112     DPO_LISP_CP,
 113     DPO_CLASSIFY,
 114     DPO_MPLS_DISPOSITION_PIPE,
 115     DPO_MPLS_DISPOSITION_UNIFORM,
 116     DPO_MFIB_ENTRY,
 117     DPO_INTERFACE_RX,
 118     DPO_INTERFACE_TX,
 119     DPO_DVR,
 120     DPO_L3_PROXY,
 121     DPO_BIER_TABLE,
 122     DPO_BIER_FMASK,
 123     DPO_BIER_IMP,
 124     DPO_BIER_DISP_TABLE,
 125     DPO_BIER_DISP_ENTRY,
 126     DPO_IP6_LL,
 127     DPO_LAST,
 128 } __attribute__((packed)) dpo_type_t;
 129
 130 #define DPO_TYPE_NUM DPO_LAST
 131
 132 #define DPO_TYPES {                     \
 133     [DPO_FIRST] = "dpo-invalid",        \
 134     [DPO_DROP] = "dpo-drop",    \
 135     [DPO_IP_NULL] = "dpo-ip-null",              \
 136     [DPO_PUNT] = "dpo-punt",    \
 137     [DPO_ADJACENCY] = "dpo-adjacency",  \
 138     [DPO_ADJACENCY_INCOMPLETE] = "dpo-adjacency-incomplete",    \
 139     [DPO_ADJACENCY_MIDCHAIN] = "dpo-adjacency-midcahin",        \
 140     [DPO_ADJACENCY_GLEAN] = "dpo-glean",        \
 141     [DPO_ADJACENCY_MCAST] = "dpo-adj-mcast",    \
 142     [DPO_ADJACENCY_MCAST_MIDCHAIN] = "dpo-adj-mcast-midchain",  \
 143     [DPO_RECEIVE] = "dpo-receive",      \
 144     [DPO_LOOKUP] = "dpo-lookup",        \
 145     [DPO_LOAD_BALANCE] = "dpo-load-balance",    \
 146     [DPO_REPLICATE] = "dpo-replicate",  \
 147     [DPO_LISP_CP] = "dpo-lisp-cp",      \
 148     [DPO_CLASSIFY] = "dpo-classify",    \
 149     [DPO_MPLS_DISPOSITION_PIPE] = "dpo-mpls-diposition-pipe", \
 150     [DPO_MPLS_DISPOSITION_UNIFORM] = "dpo-mpls-diposition-uniform", \
 151     [DPO_MFIB_ENTRY] = "dpo-mfib-entry", \
 152     [DPO_INTERFACE_RX] = "dpo-interface-rx",    \
 153     [DPO_INTERFACE_TX] = "dpo-interface-tx",    \
 154     [DPO_DVR] = "dpo-dvr",      \
 155     [DPO_L3_PROXY] = "dpo-l3-proxy",    \
 156     [DPO_BIER_TABLE] = "bier-table",    \
 157     [DPO_BIER_FMASK] = "bier-fmask",    \
 158     [DPO_BIER_IMP] = "bier-imposition", \
 159     [DPO_BIER_DISP_ENTRY] = "bier-disp-entry",  \
 160     [DPO_BIER_DISP_TABLE] = "bier-disp-table",  \
 161     [DPO_IP6_LL] = "ip6-link-local",    \
 162 }
 163
 164 /**
 165  * @brief The identity of a DPO is a combination of its type and its
 166  * instance number/index of objects of that type
 167  */
 168 typedef struct dpo_id_t_ {
 169     /**
 170      * the type
 171      */
 172     dpo_type_t dpoi_type;
 173     /**
 174      * the data-path protocol of the type.
 175      */
 176     dpo_proto_t dpoi_proto;
 177     /**
 178      * The next VLIB node to follow.
 179      */
 180     u16 dpoi_next_node;
 181     /**
 182      * the index of objects of that type
 183      */
 184     index_t dpoi_index;
 185 } __attribute__ ((aligned(sizeof(u64)))) dpo_id_t;
 186
 187 STATIC_ASSERT(sizeof(dpo_id_t) <= sizeof(u64),
 188               "DPO ID is greater than sizeof u64 "
 189               "atomic updates need to be revisited");
 190
 191 /**
 192  * @brief An initialiser for DPOs declared on the stack.
 193  * Thenext node is set to 0 since VLIB graph nodes should set 0 index to drop.
 194  */
 195 #define DPO_INVALID                \
 196 {                                  \
 197     .dpoi_type = DPO_FIRST,        \
 198     .dpoi_proto = DPO_PROTO_NONE,  \
 199     .dpoi_index = INDEX_INVALID,   \
 200     .dpoi_next_node = 0,           \
 201 }
 202
 203 /**
 204  * @brief Return true if the DPO object is valid, i.e. has been initialised.
 205  */
 206 static inline int
 207 dpo_id_is_valid (const dpo_id_t *dpoi)
 208 {
 209     return (dpoi->dpoi_type != DPO_FIRST &&
 210             dpoi->dpoi_index != INDEX_INVALID);
 211 }
 212
 213 extern dpo_proto_t vnet_link_to_dpo_proto(vnet_link_t linkt);
 214
 215 /**
 216  * @brief
 217  *  Take a reference counting lock on the DPO
 218  */
 219 extern void dpo_lock(dpo_id_t *dpo);
 220
 221 /**
 222  * @brief
 223  *  Release a reference counting lock on the DPO
 224  */
 225 extern void dpo_unlock(dpo_id_t *dpo);
 226
 227 /**
 228  * @brief
 229  *  Make an interpose DPO from an original
 230  */
 231 extern void dpo_mk_interpose(const dpo_id_t *original,
 232                              const dpo_id_t *parent,
 233                              dpo_id_t *clone);
 234
 235 /**
 236  * @brief Set/create a DPO ID
 237  * The DPO will be locked.
 238  *
 239  * @param dpo
 240  *  The DPO object to configure
 241  *
 242  * @param type
 243  *  The dpo_type_t of the DPO
 244  *
 245  * @param proto
 246  *  The dpo_proto_t of the DPO
 247  *
 248  * @param index
 249  *  The type specific index of the DPO
 250  */
 251 extern void dpo_set(dpo_id_t *dpo,
 252                     dpo_type_t type,
 253                     dpo_proto_t proto,
 254                     index_t index);
 255
 256 /**
 257  * @brief reset a DPO ID
 258  * The DPO will be unlocked.
 259  *
 260  * @param dpo
 261  *  The DPO object to reset
 262  */
 263 extern void dpo_reset(dpo_id_t *dpo);
 264
 265 /**
 266  * @brief compare two DPOs for equality
 267  */
 268 extern int dpo_cmp(const dpo_id_t *dpo1,
 269                    const dpo_id_t *dpo2);
 270
 271 /**
 272  * @brief
 273  *  atomic copy a data-plane object.
 274  * This is safe to use when the dst DPO is currently switching packets
 275  */
 276 extern void dpo_copy(dpo_id_t *dst,
 277                      const dpo_id_t *src);
 278
 279 /**
 280  * @brief Return TRUE is the DPO is any type of adjacency
 281  */
 282 extern int dpo_is_adj(const dpo_id_t *dpo);
 283
 284 /**
 285  * @biref Format a DPO_id_t oject
 286  */
 287 extern u8 *format_dpo_id(u8 * s, va_list * args);
 288
 289 /**
 290  * @biref format a DPO type
 291  */
 292 extern u8 *format_dpo_type(u8 * s, va_list * args);
 293
 294 /**
 295  * @brief format a DPO protocol
 296  */
 297 extern u8 *format_dpo_proto(u8 * s, va_list * args);
 298
 299 /**
 300  * @brief format a DPO protocol
 301  */
 302 extern vnet_link_t dpo_proto_to_link(dpo_proto_t dp);
 303
 304 /**
 305  * @brief
 306  *  Set and stack a DPO.
 307  *  The DPO passed is set to the parent DPO and the necessary
 308  *  VLIB graph arcs are created. The child_type and child_proto
 309  * are used to get the VLID nodes from which the arcs are added.
 310  *
 311  * @param child_type
 312  *  Child DPO type.
 313  *
 314  * @param child_proto
 315  *  Child DPO proto
 316  *
 317  * @parem dpo
 318  *  This is the DPO to stack and set.
 319  *
 320  * @paren parent_dpo
 321  *  The parent DPO to stack onto.
 322  */
 323 extern void dpo_stack(dpo_type_t child_type,
 324                       dpo_proto_t child_proto,
 325                       dpo_id_t *dpo,
 326                       const dpo_id_t *parent_dpo);
 327
 328 /**
 329  * @brief
 330  *  Set and stack a DPO.
 331  *  The DPO passed is set to the parent DPO and the necessary
 332  *  VLIB graph arcs are created, from the child_node passed.
 333  *
 334  * @param child_node
 335  *  The VLIB grpah node index to create an arc from to the parent
 336  *
 337  * @param dpo
 338  *  This is the DPO to stack and set.
 339  *
 340  * @param parent_dpo
 341  *  The parent DPO to stack onto.
 342  */
 343 extern void dpo_stack_from_node(u32 child_node,
 344                                 dpo_id_t *dpo,
 345                                 const dpo_id_t *parent);
 346
 347 /**
 348  * Get a uRPF interface for the DPO
 349  *
 350  * @param dpo
 351  *  The DPO from which to get the uRPF interface
 352  *
 353  * @return valid SW interface index or ~0
 354  */
 355 extern u32 dpo_get_urpf(const dpo_id_t *dpo);
 356
 357 /**
 358  * @brief  A lock function registered for a DPO type
 359  */
 360 typedef void (*dpo_lock_fn_t)(dpo_id_t *dpo);
 361
 362 /**
 363  * @brief An unlock function registered for a DPO type
 364  */
 365 typedef void (*dpo_unlock_fn_t)(dpo_id_t *dpo);
 366
 367 /**
 368  * @brief An memory usage show command
 369  */
 370 typedef void (*dpo_mem_show_t)(void);
 371
 372 /**
 373  * @brief Given a DPO instance return a vector of node indices that
 374  * the type/instance will use.
 375  */
 376 typedef u32* (*dpo_get_next_node_t)(const dpo_id_t *dpo);
 377
 378 /**
 379  * @brief Given a DPO instance return an interface that can
 380  * be used in an uRPF check
 381  */
 382 typedef u32 (*dpo_get_urpf_t)(const dpo_id_t *dpo);
 383
 384 /**
 385  * @brief Called during FIB interposition when the originally
 386  * registered DPO is used to 'clone' an instance for interposition
 387  * at a particular location in the FIB graph.
 388  * The parent is the next DPO in the chain that the clone will
 389  * be used instead of. The clone may then choose to stack itself
 390  * on the parent.
 391  */
 392 typedef void (*dpo_mk_interpose_t)(const dpo_id_t *original,
 393                                    const dpo_id_t *parent,
 394                                    dpo_id_t *clone);
 395
 396 /**
 397  * @brief A virtual function table regisitered for a DPO type
 398  */
 399 typedef struct dpo_vft_t_
 400 {
 401     /**
 402      * A reference counting lock function
 403      */
 404     dpo_lock_fn_t dv_lock;
 405     /**
 406      * A reference counting unlock function
 407      */
 408     dpo_lock_fn_t dv_unlock;
 409     /**
 410      * A format function
 411      */
 412     format_function_t *dv_format;
 413     /**
 414      * A show memory usage function
 415      */
 416     dpo_mem_show_t dv_mem_show;
 417     /**
 418      * A function to get the next VLIB node given an instance
 419      * of the DPO. If this is null, then the node's name MUST be
 420      * retreiveable from the nodes names array passed in the register
 421      * function
 422      */
 423     dpo_get_next_node_t dv_get_next_node;
 424     /**
 425      * Get uRPF interface
 426      */
 427     dpo_get_urpf_t dv_get_urpf;
 428     /**
 429      * Signal on an interposed child that the parent has changed
 430      */
 431     dpo_mk_interpose_t dv_mk_interpose;
 432 } dpo_vft_t;
 433
 434
 435 /**
 436  * @brief For a given DPO type Register:
 437  *   - a virtual function table
 438  *   - a NULL terminated array of graph nodes from which that object type
 439  *     will originate packets, i.e. the nodes in which the object type will be
 440  *     the parent DPO in the DP graph. The ndoes are per-data-path protocol
 441  *     (see above).
 442  *
 443  * @param type
 444  *  The type being registered.
 445  *
 446  * @param vft
 447  *  The virtual function table to register for the type.
 448  *
 449  * @param nodes
 450  *  The string description of the per-protocol VLIB graph nodes.
 451  */
 452 extern void dpo_register(dpo_type_t type,
 453                          const dpo_vft_t *vft,
 454                          const char * const * const * nodes);
 455
 456 /**
 457  * @brief Create and register a new DPO type.
 458  *
 459  * This can be used by plugins to create new DPO types that are not listed
 460  * in dpo_type_t enum
 461  *
 462  * @param vft
 463  *  The virtual function table to register for the type.
 464  *
 465  * @param nodes
 466  *  The string description of the per-protocol VLIB graph nodes.
 467  *
 468  * @return The new dpo_type_t
 469  */
 470 extern dpo_type_t dpo_register_new_type(const dpo_vft_t *vft,
 471                                         const char * const * const * nodes);
 472
 473 /**
 474  * @brief Return already stacked up next node index for a given
 475  *        child_type/child_proto and parent_type/patent_proto.
 476  *        The VLIB graph arc used is taken from the parent and child types
 477  *        passed.
 478  *
 479  * @param child_type
 480  *  Child DPO type.
 481  *
 482  * @param child_proto
 483  *  Child DPO proto
 484  *
 485  * @param parent_type
 486  *  Parent DPO type.
 487  *
 488  * @param parent_proto
 489  *  Parent DPO proto
 490  *
 491  * @return The VLIB Graph node index
 492  */
 493 extern u32
 494 dpo_get_next_node_by_type_and_proto (dpo_type_t   child_type,
 495                                      dpo_proto_t  child_proto,
 496                                      dpo_type_t   parent_type,
 497                                      dpo_proto_t  parent_proto);
 498 #endif