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
30 #include <vnet/vnet.h>
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
44 * @brief Invalid index - used when no index is known
45 * blazoned capitals INVALID speak volumes where ~0 does not.
47 #define INDEX_INVALID ((index_t)(~0))
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.
60 typedef enum dpo_proto_t_
69 } __attribute__((packed)) dpo_proto_t;
71 #define DPO_PROTO_NUM (DPO_PROTO_MPLS+1)
72 #define DPO_PROTO_NONE (DPO_PROTO_NUM+1)
74 #define DPO_PROTOS { \
75 [DPO_PROTO_IP4] = "ip4", \
76 [DPO_PROTO_IP6] = "ip6", \
77 [DPO_PROTO_MPLS] = "mpls", \
81 * @brief Common types of data-path objects
82 * New types can be dynamically added using dpo_register_new_type()
84 typedef enum dpo_type_t_ {
86 * A non-zero value first so we can spot unitialisation errors
92 * @brief load-balancing over a choice of [un]equal cost paths
96 DPO_ADJACENCY_INCOMPLETE,
97 DPO_ADJACENCY_MIDCHAIN,
105 } __attribute__((packed)) dpo_type_t;
107 #define DPO_TYPE_NUM DPO_LAST
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", \
126 * @brief The identity of a DPO is a combination of its type and its
127 * instance number/index of objects of that type
129 typedef struct dpo_id_t_ {
133 dpo_type_t dpoi_type;
135 * the data-path protocol of the type.
137 dpo_proto_t dpoi_proto;
139 * The next VLIB node to follow.
143 * the index of objects of that type
146 } __attribute__ ((aligned(sizeof(u64)))) dpo_id_t;
148 _Static_assert(sizeof(dpo_id_t) <= sizeof(u64),
149 "DPO ID is greater than sizeof u64 "
150 "atomic updates need to be revisited");
153 * @brief An initialiser for DPos declared on the stack.
158 * @brief Return true if the DPO object is valid, i.e. has been initialised.
161 dpo_id_is_valid (const dpo_id_t *dpoi)
163 return (dpoi->dpoi_type != DPO_FIRST &&
164 dpoi->dpoi_index != INDEX_INVALID);
169 * Take a reference counting lock on the DPO
171 extern void dpo_lock(dpo_id_t *dpo);
175 * Release a reference counting lock on the DPO
177 extern void dpo_unlock(dpo_id_t *dpo);
180 * @brief Set/create a DPO ID
181 * The DPO will be locked.
184 * The DPO object to configure
187 * The dpo_type_t of the DPO
190 * The dpo_proto_t of the DPO
193 * The type specific index of the DPO
195 extern void dpo_set(dpo_id_t *dpo,
201 * @brief reset a DPO ID
202 * The DPO will be unlocked.
205 * The DPO object to reset
207 extern void dpo_reset(dpo_id_t *dpo);
210 * @brief compare two DPOs for equality
212 extern int dpo_cmp(const dpo_id_t *dpo1,
213 const dpo_id_t *dpo2);
217 * atomic copy a data-plane object.
218 * This is safe to use when the dst DPO is currently switching packets
220 extern void dpo_copy(dpo_id_t *dst,
221 const dpo_id_t *src);
224 * @brief Return TRUE is the DPO is any type of adjacency
226 extern int dpo_is_adj(const dpo_id_t *dpo);
229 * @biref Format a DPO_id_t oject
231 extern u8 *format_dpo_id(u8 * s, va_list * args);
234 * @biref format a DPO type
236 extern u8 *format_dpo_type(u8 * s, va_list * args);
239 * @brief format a DPO protocol
241 extern u8 *format_dpo_proto(u8 * s, va_list * args);
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.
257 * This is the DPO to stack and set.
260 * The parent DPO to stack onto.
262 extern void dpo_stack(dpo_type_t child_type,
263 dpo_proto_t child_proto,
265 const dpo_id_t *parent_dpo);
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.
274 * The VLIB grpah node index to create an arc from to the parent
277 * This is the DPO to stack and set.
280 * The parent DPO to stack onto.
282 extern void dpo_stack_from_node(u32 child_node,
284 const dpo_id_t *parent);
287 * @brief A lock function registered for a DPO type
289 typedef void (*dpo_lock_fn_t)(dpo_id_t *dpo);
292 * @brief An unlock function registered for a DPO type
294 typedef void (*dpo_unlock_fn_t)(dpo_id_t *dpo);
297 * @brief A virtual function table regisitered for a DPO type
299 typedef struct dpo_vft_t_
302 * A reference counting lock function
304 dpo_lock_fn_t dv_lock;
306 * A reference counting unlock function
308 dpo_lock_fn_t dv_unlock;
312 format_function_t *dv_format;
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
325 * The type being registered.
328 * The virtual function table to register for the type.
331 * The string description of the per-protocol VLIB graph nodes.
333 void dpo_register(dpo_type_t type,
334 const dpo_vft_t *vft,
335 const char * const * const * nodes);
338 * @brief Create and register a new DPO type.
340 * This can be used by plugins to create new DPO types that are not listed
344 * The virtual function table to register for the type.
347 * The string description of the per-protocol VLIB graph nodes.
349 * @return The new dpo_type_t
351 dpo_type_t dpo_register_new_type(const dpo_vft_t *vft,
352 const char * const * const * nodes);