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 #if CLIB_DEBUG > 0
  63     DPO_PROTO_IP4 = 1,
  64 #else
  65     DPO_PROTO_IP4 = 0,
  66 #endif
  67     DPO_PROTO_IP6,
  68     DPO_PROTO_ETHERNET,
  69     DPO_PROTO_MPLS,
  70     DPO_PROTO_NSH,
  71 } __attribute__((packed)) dpo_proto_t;
  72
  73 #define DPO_PROTO_NUM ((dpo_proto_t)(DPO_PROTO_NSH+1))
  74 #define DPO_PROTO_NONE ((dpo_proto_t)(DPO_PROTO_NUM+1))
  75
  76 #define DPO_PROTOS {            \
  77     [DPO_PROTO_IP4]  = "ip4",   \
  78     [DPO_PROTO_IP6]  = "ip6",   \
  79     [DPO_PROTO_ETHERNET]  = "ethernet", \
  80     [DPO_PROTO_MPLS] = "mpls",  \
  81     [DPO_PROTO_NSH] = "nsh",    \
  82 }
  83
  84 #define FOR_EACH_DPO_PROTO(_proto)    \
  85     for (_proto = DPO_PROTO_IP4;      \
  86          _proto <= DPO_PROTO_NSH;    \
  87          _proto++)
  88
  89 /**
  90  * @brief Common types of data-path objects
  91  * New types can be dynamically added using dpo_register_new_type()
  92  */
  93 typedef enum dpo_type_t_ {
  94     /**
  95      * A non-zero value first so we can spot unitialisation errors
  96      */
  97     DPO_FIRST,
  98     DPO_DROP,
  99     DPO_IP_NULL,
 100     DPO_PUNT,
 101     /**
 102      * @brief load-balancing over a choice of [un]equal cost paths
 103      */
 104     DPO_LOAD_BALANCE,
 105     DPO_REPLICATE,
 106     DPO_ADJACENCY,
 107     DPO_ADJACENCY_INCOMPLETE,
 108     DPO_ADJACENCY_MIDCHAIN,
 109     DPO_ADJACENCY_GLEAN,
 110     DPO_ADJACENCY_MCAST,
 111     DPO_RECEIVE,
 112     DPO_LOOKUP,
 113     DPO_LISP_CP,
 114     DPO_CLASSIFY,
 115     DPO_MPLS_LABEL,
 116     DPO_MFIB_ENTRY,
 117     DPO_LAST,
 118 } __attribute__((packed)) dpo_type_t;
 119
 120 #define DPO_TYPE_NUM DPO_LAST
 121
 122 #define DPO_TYPES {                     \
 123     [DPO_FIRST] = "dpo-invalid",        \
 124     [DPO_DROP] = "dpo-drop",    \
 125     [DPO_IP_NULL] = "dpo-ip-null",              \
 126     [DPO_PUNT] = "dpo-punt",    \
 127     [DPO_ADJACENCY] = "dpo-adjacency",  \
 128     [DPO_ADJACENCY_INCOMPLETE] = "dpo-adjacency-incomplete",    \
 129     [DPO_ADJACENCY_MIDCHAIN] = "dpo-adjacency-midcahin",        \
 130     [DPO_ADJACENCY_GLEAN] = "dpo-glean",        \
 131     [DPO_ADJACENCY_MCAST] = "dpo-adj-mcast",    \
 132     [DPO_RECEIVE] = "dpo-receive",      \
 133     [DPO_LOOKUP] = "dpo-lookup",        \
 134     [DPO_LOAD_BALANCE] = "dpo-load-balance",    \
 135     [DPO_REPLICATE] = "dpo-replicate",  \
 136     [DPO_LISP_CP] = "dpo-lisp-cp",      \
 137     [DPO_CLASSIFY] = "dpo-classify",    \
 138     [DPO_MPLS_LABEL] = "dpo-mpls-label", \
 139     [DPO_MFIB_ENTRY] = "dpo-mfib_entry" \
 140 }
 141
 142 /**
 143  * @brief The identity of a DPO is a combination of its type and its
 144  * instance number/index of objects of that type
 145  */
 146 typedef struct dpo_id_t_ {
 147     /**
 148      * the type
 149      */
 150     dpo_type_t dpoi_type;
 151     /**
 152      * the data-path protocol of the type.
 153      */
 154     dpo_proto_t dpoi_proto;
 155     /**
 156      * The next VLIB node to follow.
 157      */
 158     u16 dpoi_next_node;
 159     /**
 160      * the index of objects of that type
 161      */
 162     index_t dpoi_index;
 163 } __attribute__ ((aligned(sizeof(u64)))) dpo_id_t;
 164
 165 STATIC_ASSERT(sizeof(dpo_id_t) <= sizeof(u64),
 166               "DPO ID is greater than sizeof u64 "
 167               "atomic updates need to be revisited");
 168
 169 /**
 170  * @brief An initialiser for DPOs declared on the stack.
 171  * Thenext node is set to 0 since VLIB graph nodes should set 0 index to drop.
 172  */
 173 #define DPO_INVALID                \
 174 {                                  \
 175     .dpoi_type = DPO_FIRST,        \
 176     .dpoi_proto = DPO_PROTO_NONE,  \
 177     .dpoi_index = INDEX_INVALID,   \
 178     .dpoi_next_node = 0,           \
 179 }
 180
 181 /**
 182  * @brief Return true if the DPO object is valid, i.e. has been initialised.
 183  */
 184 static inline int
 185 dpo_id_is_valid (const dpo_id_t *dpoi)
 186 {
 187     return (dpoi->dpoi_type != DPO_FIRST &&
 188             dpoi->dpoi_index != INDEX_INVALID);
 189 }
 190
 191 extern dpo_proto_t vnet_link_to_dpo_proto(vnet_link_t linkt);
 192
 193 /**
 194  * @brief
 195  *  Take a reference counting lock on the DPO
 196  */
 197 extern void dpo_lock(dpo_id_t *dpo);
 198
 199 /**
 200  * @brief
 201  *  Release a reference counting lock on the DPO
 202  */
 203 extern void dpo_unlock(dpo_id_t *dpo);
 204
 205 /**
 206  * @brief Set/create a DPO ID
 207  * The DPO will be locked.
 208  *
 209  * @param dpo
 210  *  The DPO object to configure
 211  *
 212  * @param type
 213  *  The dpo_type_t of the DPO
 214  *
 215  * @param proto
 216  *  The dpo_proto_t of the DPO
 217  *
 218  * @param index
 219  *  The type specific index of the DPO
 220  */
 221 extern void dpo_set(dpo_id_t *dpo,
 222                     dpo_type_t type,
 223                     dpo_proto_t proto,
 224                     index_t index);
 225
 226 /**
 227  * @brief reset a DPO ID
 228  * The DPO will be unlocked.
 229  *
 230  * @param dpo
 231  *  The DPO object to reset
 232  */
 233 extern void dpo_reset(dpo_id_t *dpo);
 234
 235 /**
 236  * @brief compare two DPOs for equality
 237  */
 238 extern int dpo_cmp(const dpo_id_t *dpo1,
 239                    const dpo_id_t *dpo2);
 240
 241 /**
 242  * @brief
 243  *  atomic copy a data-plane object.
 244  * This is safe to use when the dst DPO is currently switching packets
 245  */
 246 extern void dpo_copy(dpo_id_t *dst,
 247                      const dpo_id_t *src);
 248
 249 /**
 250  * @brief Return TRUE is the DPO is any type of adjacency
 251  */
 252 extern int dpo_is_adj(const dpo_id_t *dpo);
 253
 254 /**
 255  * @biref Format a DPO_id_t oject
 256  */
 257 extern u8 *format_dpo_id(u8 * s, va_list * args);
 258
 259 /**
 260  * @biref format a DPO type
 261  */
 262 extern u8 *format_dpo_type(u8 * s, va_list * args);
 263
 264 /**
 265  * @brief format a DPO protocol
 266  */
 267 extern u8 *format_dpo_proto(u8 * s, va_list * args);
 268
 269 /**
 270  * @brief
 271  *  Set and stack a DPO.
 272  *  The DPO passed is set to the parent DPO and the necessary
 273  *  VLIB graph arcs are created. The child_type and child_proto
 274  * are used to get the VLID nodes from which the arcs are added.
 275  *
 276  * @param child_type
 277  *  Child DPO type.
 278  *
 279  * @param child_proto
 280  *  Child DPO proto
 281  *
 282  * @parem dpo
 283  *  This is the DPO to stack and set.
 284  *
 285  * @paren parent_dpo
 286  *  The parent DPO to stack onto.
 287  */
 288 extern void dpo_stack(dpo_type_t child_type,
 289                       dpo_proto_t child_proto,
 290                       dpo_id_t *dpo,
 291                       const dpo_id_t *parent_dpo);
 292
 293 /**
 294  * @brief
 295  *  Set and stack a DPO.
 296  *  The DPO passed is set to the parent DPO and the necessary
 297  *  VLIB graph arcs are created, from the child_node passed.
 298  *
 299  * @param child_node
 300  *  The VLIB grpah node index to create an arc from to the parent
 301  *
 302  * @parem dpo
 303  *  This is the DPO to stack and set.
 304  *
 305  * @paren parent_dpo
 306  *  The parent DPO to stack onto.
 307  */
 308 extern void dpo_stack_from_node(u32 child_node,
 309                                 dpo_id_t *dpo,
 310                                 const dpo_id_t *parent);
 311
 312 /**
 313  * @brief  A lock function registered for a DPO type
 314  */
 315 typedef void (*dpo_lock_fn_t)(dpo_id_t *dpo);
 316
 317 /**
 318  * @brief An unlock function registered for a DPO type
 319  */
 320 typedef void (*dpo_unlock_fn_t)(dpo_id_t *dpo);
 321
 322 /**
 323  * @brief An memory usage show command
 324  */
 325 typedef void (*dpo_mem_show_t)(void);
 326
 327 /**
 328  * @brief A virtual function table regisitered for a DPO type
 329  */
 330 typedef struct dpo_vft_t_
 331 {
 332     /**
 333      * A reference counting lock function
 334      */
 335     dpo_lock_fn_t dv_lock;
 336     /**
 337      * A reference counting unlock function
 338      */
 339     dpo_lock_fn_t dv_unlock;
 340     /**
 341      * A format function
 342      */
 343     format_function_t *dv_format;
 344     /**
 345      * A show memory usage function
 346      */
 347     dpo_mem_show_t dv_mem_show;
 348 } dpo_vft_t;
 349
 350
 351 /**
 352  * @brief For a given DPO type Register:
 353  *   - a virtual function table
 354  *   - a NULL terminated array of graph nodes from which that object type
 355  *     will originate packets, i.e. the nodes in which the object type will be
 356  *     the parent DPO in the DP graph. The ndoes are per-data-path protocol
 357  *     (see above).
 358  *
 359  * @param type
 360  *  The type being registered.
 361  *
 362  * @param vft
 363  *  The virtual function table to register for the type.
 364  *
 365  * @param nodes
 366  *  The string description of the per-protocol VLIB graph nodes.
 367  */
 368 extern void dpo_register(dpo_type_t type,
 369                          const dpo_vft_t *vft,
 370                          const char * const * const * nodes);
 371
 372 /**
 373  * @brief Create and register a new DPO type.
 374  *
 375  * This can be used by plugins to create new DPO types that are not listed
 376  * in dpo_type_t enum
 377  *
 378  * @param vft
 379  *  The virtual function table to register for the type.
 380  *
 381  * @param nodes
 382  *  The string description of the per-protocol VLIB graph nodes.
 383  *
 384  * @return The new dpo_type_t
 385  */
 386 extern dpo_type_t dpo_register_new_type(const dpo_vft_t *vft,
 387                                         const char * const * const * nodes);
 388
 389 #endif