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