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