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:
7 * http://www.apache.org/licenses/LICENSE-2.0
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.
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.
20 * The DPO can be considered to be like is a base class that is specialised
21 * by other objects to provide concreate actions
23 * The VLIB graph nodes are graph of DPO types, the DPO graph is a graph of
32 #include <vnet/vnet.h>
35 * @brief An index for adjacencies.
36 * Alas 'C' is not typesafe enough to b0rk when a u32 is used instead of
37 * an index_t. However, for us humans, we can glean much more intent
38 * from the declaration
46 * @brief Invalid index - used when no index is known
47 * blazoned capitals INVALID speak volumes where ~0 does not.
49 #define INDEX_INVALID ((index_t)(~0))
52 * @brief Data path protocol.
53 * Actions performed on packets in the data-plane can be described and represented
54 * by protocol independent objects, i.e. ADJACENCY, but the spceifics actions
55 * required during ADJACENCY processing can be protocol dependent. For example,
56 * the adjacency rewrite node performs a ip4 checksum calculation, ip6 and MPLS
57 * do not, all 3 perform a TTL decrement. The VLIB graph nodes are thus protocol
58 * dependent, and thus each graph edge/arc is too.
59 * When programming a DPO's next node arc from child to parent it is thus required
60 * to know the parent's data-path protocol so the correct arc index can be used.
62 typedef enum dpo_proto_t_
70 } __attribute__((packed)) dpo_proto_t;
72 #define DPO_PROTO_NUM ((dpo_proto_t)(DPO_PROTO_NSH+1))
73 #define DPO_PROTO_NONE ((dpo_proto_t)(DPO_PROTO_NUM+1))
75 #define DPO_PROTOS { \
76 [DPO_PROTO_IP4] = "ip4", \
77 [DPO_PROTO_IP6] = "ip6", \
78 [DPO_PROTO_ETHERNET] = "ethernet", \
79 [DPO_PROTO_MPLS] = "mpls", \
80 [DPO_PROTO_NSH] = "nsh", \
81 [DPO_PROTO_BIER] = "bier", \
84 #define FOR_EACH_DPO_PROTO(_proto) \
85 for (_proto = DPO_PROTO_IP4; \
86 _proto <= DPO_PROTO_NSH; \
90 * @brief Common types of data-path objects
91 * New types can be dynamically added using dpo_register_new_type()
93 typedef enum dpo_type_t_ {
95 * A non-zero value first so we can spot unitialisation errors
102 * @brief load-balancing over a choice of [un]equal cost paths
107 DPO_ADJACENCY_INCOMPLETE,
108 DPO_ADJACENCY_MIDCHAIN,
111 DPO_ADJACENCY_MCAST_MIDCHAIN,
116 DPO_MPLS_DISPOSITION_PIPE,
117 DPO_MPLS_DISPOSITION_UNIFORM,
131 } __attribute__((packed)) dpo_type_t;
133 #define DPO_TYPE_NUM DPO_LAST
135 #define DPO_TYPES { \
136 [DPO_FIRST] = "dpo-invalid", \
137 [DPO_DROP] = "dpo-drop", \
138 [DPO_IP_NULL] = "dpo-ip-null", \
139 [DPO_PUNT] = "dpo-punt", \
140 [DPO_ADJACENCY] = "dpo-adjacency", \
141 [DPO_ADJACENCY_INCOMPLETE] = "dpo-adjacency-incomplete", \
142 [DPO_ADJACENCY_MIDCHAIN] = "dpo-adjacency-midcahin", \
143 [DPO_ADJACENCY_GLEAN] = "dpo-glean", \
144 [DPO_ADJACENCY_MCAST] = "dpo-adj-mcast", \
145 [DPO_ADJACENCY_MCAST_MIDCHAIN] = "dpo-adj-mcast-midchain", \
146 [DPO_RECEIVE] = "dpo-receive", \
147 [DPO_LOOKUP] = "dpo-lookup", \
148 [DPO_LOAD_BALANCE] = "dpo-load-balance", \
149 [DPO_REPLICATE] = "dpo-replicate", \
150 [DPO_LISP_CP] = "dpo-lisp-cp", \
151 [DPO_CLASSIFY] = "dpo-classify", \
152 [DPO_MPLS_DISPOSITION_PIPE] = "dpo-mpls-diposition-pipe", \
153 [DPO_MPLS_DISPOSITION_UNIFORM] = "dpo-mpls-diposition-uniform", \
154 [DPO_MFIB_ENTRY] = "dpo-mfib-entry", \
155 [DPO_INTERFACE_RX] = "dpo-interface-rx", \
156 [DPO_INTERFACE_TX] = "dpo-interface-tx", \
157 [DPO_DVR] = "dpo-dvr", \
158 [DPO_L3_PROXY] = "dpo-l3-proxy", \
159 [DPO_BIER_TABLE] = "bier-table", \
160 [DPO_BIER_FMASK] = "bier-fmask", \
161 [DPO_BIER_IMP] = "bier-imposition", \
162 [DPO_BIER_DISP_ENTRY] = "bier-disp-entry", \
163 [DPO_BIER_DISP_TABLE] = "bier-disp-table", \
164 [DPO_IP6_LL] = "ip6-link-local", \
165 [DPO_PW_CW] = "PW-CW", \
169 * @brief The identity of a DPO is a combination of its type and its
170 * instance number/index of objects of that type
172 typedef struct dpo_id_t_ {
178 dpo_type_t dpoi_type;
180 * the data-path protocol of the type.
182 dpo_proto_t dpoi_proto;
184 * The next VLIB node to follow.
188 * the index of objects of that type
196 STATIC_ASSERT(sizeof(dpo_id_t) <= sizeof(u64),
197 "DPO ID is greater than sizeof u64 "
198 "atomic updates need to be revisited");
201 * @brief An initialiser for DPOs declared on the stack.
202 * Thenext node is set to 0 since VLIB graph nodes should set 0 index to drop.
204 #define DPO_INVALID \
206 .dpoi_type = DPO_FIRST, \
207 .dpoi_proto = DPO_PROTO_NONE, \
208 .dpoi_index = INDEX_INVALID, \
209 .dpoi_next_node = 0, \
213 * @brief Return true if the DPO object is valid, i.e. has been initialised.
216 dpo_id_is_valid (const dpo_id_t *dpoi)
218 return (dpoi->dpoi_type != DPO_FIRST &&
219 dpoi->dpoi_index != INDEX_INVALID);
222 extern dpo_proto_t vnet_link_to_dpo_proto(vnet_link_t linkt);
226 * Take a reference counting lock on the DPO
228 extern void dpo_lock(dpo_id_t *dpo);
232 * Release a reference counting lock on the DPO
234 extern void dpo_unlock(dpo_id_t *dpo);
238 * Make an interpose DPO from an original
240 extern void dpo_mk_interpose(const dpo_id_t *original,
241 const dpo_id_t *parent,
245 * @brief Set/create a DPO ID
246 * The DPO will be locked.
249 * The DPO object to configure
252 * The dpo_type_t of the DPO
255 * The dpo_proto_t of the DPO
258 * The type specific index of the DPO
260 extern void dpo_set(dpo_id_t *dpo,
266 * @brief reset a DPO ID
267 * The DPO will be unlocked.
270 * The DPO object to reset
272 extern void dpo_reset(dpo_id_t *dpo);
275 * @brief compare two DPOs for equality
277 extern int dpo_cmp(const dpo_id_t *dpo1,
278 const dpo_id_t *dpo2);
282 * atomic copy a data-plane object.
283 * This is safe to use when the dst DPO is currently switching packets
285 extern void dpo_copy(dpo_id_t *dst,
286 const dpo_id_t *src);
289 * @brief Return TRUE is the DPO is any type of adjacency
291 extern int dpo_is_adj(const dpo_id_t *dpo);
294 * @brief Format a DPO_id_t oject
296 extern u8 *format_dpo_id(u8 * s, va_list * args);
299 * @brief format a DPO type
301 extern u8 *format_dpo_type(u8 * s, va_list * args);
304 * @brief format a DPO protocol
306 extern u8 *format_dpo_proto(u8 * s, va_list * args);
309 * @brief format a DPO protocol
311 extern vnet_link_t dpo_proto_to_link(dpo_proto_t dp);
315 * Set and stack a DPO.
316 * The DPO passed is set to the parent DPO and the necessary
317 * VLIB graph arcs are created. The child_type and child_proto
318 * are used to get the VLID nodes from which the arcs are added.
327 * This is the DPO to stack and set.
330 * The parent DPO to stack onto.
332 extern void dpo_stack(dpo_type_t child_type,
333 dpo_proto_t child_proto,
335 const dpo_id_t *parent_dpo);
339 * Set and stack a DPO.
340 * The DPO passed is set to the parent DPO and the necessary
341 * VLIB graph arcs are created, from the child_node passed.
344 * The VLIB graph node index to create an arc from to the parent
347 * This is the DPO to stack and set.
350 * The parent DPO to stack onto.
352 extern void dpo_stack_from_node(u32 child_node,
354 const dpo_id_t *parent);
357 * Get a uRPF interface for the DPO
360 * The DPO from which to get the uRPF interface
362 * @return valid SW interface index or ~0
364 extern u32 dpo_get_urpf(const dpo_id_t *dpo);
370 * The DPO from which to get the MTU
372 * @return MTU (0xffff if something more usefull was unavailable)
374 extern u16 dpo_get_mtu(const dpo_id_t *dpo);
377 * @brief A lock function registered for a DPO type
379 typedef void (*dpo_lock_fn_t)(dpo_id_t *dpo);
382 * @brief An unlock function registered for a DPO type
384 typedef void (*dpo_unlock_fn_t)(dpo_id_t *dpo);
387 * @brief An memory usage show command
389 typedef void (*dpo_mem_show_t)(void);
392 * @brief Given a DPO instance return a vector of node indices that
393 * the type/instance will use.
395 typedef u32* (*dpo_get_next_node_t)(const dpo_id_t *dpo);
398 * @brief Given a DPO instance return an interface that can
399 * be used in an uRPF check
401 typedef u32 (*dpo_get_urpf_t)(const dpo_id_t *dpo);
404 * @brief Given a DPO instance return the MTU
406 typedef u16 (*dpo_get_mtu_t)(const dpo_id_t *dpo);
409 * @brief Called during FIB interposition when the originally
410 * registered DPO is used to 'clone' an instance for interposition
411 * at a particular location in the FIB graph.
412 * The parent is the next DPO in the chain that the clone will
413 * be used instead of. The clone may then choose to stack itself
416 typedef void (*dpo_mk_interpose_t)(const dpo_id_t *original,
417 const dpo_id_t *parent,
421 * @brief A virtual function table regisitered for a DPO type
423 typedef struct dpo_vft_t_
426 * A reference counting lock function
428 dpo_lock_fn_t dv_lock;
430 * A reference counting unlock function
432 dpo_lock_fn_t dv_unlock;
436 format_function_t *dv_format;
438 * A show memory usage function
440 dpo_mem_show_t dv_mem_show;
442 * A function to get the next VLIB node given an instance
443 * of the DPO. If this is null, then the node's name MUST be
444 * retreiveable from the nodes names array passed in the register
447 dpo_get_next_node_t dv_get_next_node;
451 dpo_get_urpf_t dv_get_urpf;
455 dpo_get_mtu_t dv_get_mtu;
457 * Signal on an interposed child that the parent has changed
459 dpo_mk_interpose_t dv_mk_interpose;
464 * @brief For a given DPO type Register:
465 * - a virtual function table
466 * - a NULL terminated array of graph nodes from which that object type
467 * will originate packets, i.e. the nodes in which the object type will be
468 * the parent DPO in the DP graph. The ndoes are per-data-path protocol
472 * The type being registered.
475 * The virtual function table to register for the type.
478 * The string description of the per-protocol VLIB graph nodes.
480 extern void dpo_register(dpo_type_t type,
481 const dpo_vft_t *vft,
482 const char * const * const * nodes);
485 * @brief Create and register a new DPO type.
487 * This can be used by plugins to create new DPO types that are not listed
491 * The virtual function table to register for the type.
494 * The string description of the per-protocol VLIB graph nodes.
496 * @return The new dpo_type_t
498 extern dpo_type_t dpo_register_new_type(const dpo_vft_t *vft,
499 const char * const * const * nodes);
502 * @brief Return already stacked up next node index for a given
503 * child_type/child_proto and parent_type/patent_proto.
504 * The VLIB graph arc used is taken from the parent and child types
516 * @param parent_proto
519 * @return The VLIB Graph node index
522 dpo_get_next_node_by_type_and_proto (dpo_type_t child_type,
523 dpo_proto_t child_proto,
524 dpo_type_t parent_type,
525 dpo_proto_t parent_proto);
529 * @brief Barrier sync if a dpo pool is about to expand
532 * vlib_main_t *, invariably &vlib_global_main
537 * @param YESNO (output)
538 * typically a u8, 1 => expand will occur, worker barrier held
539 * 0 => no expand, barrier not held
544 #define dpo_pool_barrier_sync(VM,P,YESNO) \
546 YESNO = pool_get_will_expand (P); \
550 VM = vlib_get_main(); \
551 ASSERT ((VM)->thread_index == 0); \
552 vlib_worker_thread_barrier_sync((VM)); \
557 * @brief Release barrier sync after dpo pool expansion
560 * vlib_main_t pointer, must be &vlib_global_main
563 * typically a u8, 1 => release required
564 * 0 => no release required
568 #define dpo_pool_barrier_release(VM,YESNO) \
569 if ((YESNO)) vlib_worker_thread_barrier_release((VM));