FD.io VPP  v20.05.1-5-g09f167997
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 {
68 } __attribute__((packed)) dpo_proto_t;
69 
70 #define DPO_PROTO_NUM ((dpo_proto_t)(DPO_PROTO_NSH+1))
71 #define DPO_PROTO_NONE ((dpo_proto_t)(DPO_PROTO_NUM+1))
72 
73 #define DPO_PROTOS { \
74  [DPO_PROTO_IP4] = "ip4", \
75  [DPO_PROTO_IP6] = "ip6", \
76  [DPO_PROTO_ETHERNET] = "ethernet", \
77  [DPO_PROTO_MPLS] = "mpls", \
78  [DPO_PROTO_NSH] = "nsh", \
79  [DPO_PROTO_BIER] = "bier", \
80 }
81 
82 #define FOR_EACH_DPO_PROTO(_proto) \
83  for (_proto = DPO_PROTO_IP4; \
84  _proto <= DPO_PROTO_NSH; \
85  _proto++)
86 
87 /**
88  * @brief Common types of data-path objects
89  * New types can be dynamically added using dpo_register_new_type()
90  */
91 typedef enum dpo_type_t_ {
92  /**
93  * A non-zero value first so we can spot unitialisation errors
94  */
99  /**
100  * @brief load-balancing over a choice of [un]equal cost paths
101  */
129 } __attribute__((packed)) dpo_type_t;
130 
131 #define DPO_TYPE_NUM DPO_LAST
132 
133 #define DPO_TYPES { \
134  [DPO_FIRST] = "dpo-invalid", \
135  [DPO_DROP] = "dpo-drop", \
136  [DPO_IP_NULL] = "dpo-ip-null", \
137  [DPO_PUNT] = "dpo-punt", \
138  [DPO_ADJACENCY] = "dpo-adjacency", \
139  [DPO_ADJACENCY_INCOMPLETE] = "dpo-adjacency-incomplete", \
140  [DPO_ADJACENCY_MIDCHAIN] = "dpo-adjacency-midcahin", \
141  [DPO_ADJACENCY_GLEAN] = "dpo-glean", \
142  [DPO_ADJACENCY_MCAST] = "dpo-adj-mcast", \
143  [DPO_ADJACENCY_MCAST_MIDCHAIN] = "dpo-adj-mcast-midchain", \
144  [DPO_RECEIVE] = "dpo-receive", \
145  [DPO_LOOKUP] = "dpo-lookup", \
146  [DPO_LOAD_BALANCE] = "dpo-load-balance", \
147  [DPO_REPLICATE] = "dpo-replicate", \
148  [DPO_LISP_CP] = "dpo-lisp-cp", \
149  [DPO_CLASSIFY] = "dpo-classify", \
150  [DPO_MPLS_DISPOSITION_PIPE] = "dpo-mpls-diposition-pipe", \
151  [DPO_MPLS_DISPOSITION_UNIFORM] = "dpo-mpls-diposition-uniform", \
152  [DPO_MFIB_ENTRY] = "dpo-mfib-entry", \
153  [DPO_INTERFACE_RX] = "dpo-interface-rx", \
154  [DPO_INTERFACE_TX] = "dpo-interface-tx", \
155  [DPO_DVR] = "dpo-dvr", \
156  [DPO_L3_PROXY] = "dpo-l3-proxy", \
157  [DPO_BIER_TABLE] = "bier-table", \
158  [DPO_BIER_FMASK] = "bier-fmask", \
159  [DPO_BIER_IMP] = "bier-imposition", \
160  [DPO_BIER_DISP_ENTRY] = "bier-disp-entry", \
161  [DPO_BIER_DISP_TABLE] = "bier-disp-table", \
162  [DPO_IP6_LL] = "ip6-link-local", \
163  [DPO_PW_CW] = "PW-CW", \
164 }
165 
166 /**
167  * @brief The identity of a DPO is a combination of its type and its
168  * instance number/index of objects of that type
169  */
170 typedef struct dpo_id_t_ {
171  /**
172  * the type
173  */
174  dpo_type_t dpoi_type;
175  /**
176  * the data-path protocol of the type.
177  */
178  dpo_proto_t dpoi_proto;
179  /**
180  * The next VLIB node to follow.
181  */
183  /**
184  * the index of objects of that type
185  */
186  index_t dpoi_index;
187 } __attribute__ ((aligned(sizeof(u64)))) dpo_id_t;
188 
189 STATIC_ASSERT(sizeof(dpo_id_t) <= sizeof(u64),
190  "DPO ID is greater than sizeof u64 "
191  "atomic updates need to be revisited");
192 
193 /**
194  * @brief An initialiser for DPOs declared on the stack.
195  * Thenext node is set to 0 since VLIB graph nodes should set 0 index to drop.
196  */
197 #define DPO_INVALID \
198 { \
199  .dpoi_type = DPO_FIRST, \
200  .dpoi_proto = DPO_PROTO_NONE, \
201  .dpoi_index = INDEX_INVALID, \
202  .dpoi_next_node = 0, \
203 }
204 
205 /**
206  * @brief Return true if the DPO object is valid, i.e. has been initialised.
207  */
208 static inline int
210 {
211  return (dpoi->dpoi_type != DPO_FIRST &&
212  dpoi->dpoi_index != INDEX_INVALID);
213 }
214 
215 extern dpo_proto_t vnet_link_to_dpo_proto(vnet_link_t linkt);
216 
217 /**
218  * @brief
219  * Take a reference counting lock on the DPO
220  */
221 extern void dpo_lock(dpo_id_t *dpo);
222 
223 /**
224  * @brief
225  * Release a reference counting lock on the DPO
226  */
227 extern void dpo_unlock(dpo_id_t *dpo);
228 
229 /**
230  * @brief
231  * Make an interpose DPO from an original
232  */
233 extern void dpo_mk_interpose(const dpo_id_t *original,
234  const dpo_id_t *parent,
235  dpo_id_t *clone);
236 
237 /**
238  * @brief Set/create a DPO ID
239  * The DPO will be locked.
240  *
241  * @param dpo
242  * The DPO object to configure
243  *
244  * @param type
245  * The dpo_type_t of the DPO
246  *
247  * @param proto
248  * The dpo_proto_t of the DPO
249  *
250  * @param index
251  * The type specific index of the DPO
252  */
253 extern void dpo_set(dpo_id_t *dpo,
254  dpo_type_t type,
255  dpo_proto_t proto,
256  index_t index);
257 
258 /**
259  * @brief reset a DPO ID
260  * The DPO will be unlocked.
261  *
262  * @param dpo
263  * The DPO object to reset
264  */
265 extern void dpo_reset(dpo_id_t *dpo);
266 
267 /**
268  * @brief compare two DPOs for equality
269  */
270 extern int dpo_cmp(const dpo_id_t *dpo1,
271  const dpo_id_t *dpo2);
272 
273 /**
274  * @brief
275  * atomic copy a data-plane object.
276  * This is safe to use when the dst DPO is currently switching packets
277  */
278 extern void dpo_copy(dpo_id_t *dst,
279  const dpo_id_t *src);
280 
281 /**
282  * @brief Return TRUE is the DPO is any type of adjacency
283  */
284 extern int dpo_is_adj(const dpo_id_t *dpo);
285 
286 /**
287  * @brief Format a DPO_id_t oject
288  */
289 extern u8 *format_dpo_id(u8 * s, va_list * args);
290 
291 /**
292  * @brief format a DPO type
293  */
294 extern u8 *format_dpo_type(u8 * s, va_list * args);
295 
296 /**
297  * @brief format a DPO protocol
298  */
299 extern u8 *format_dpo_proto(u8 * s, va_list * args);
300 
301 /**
302  * @brief format a DPO protocol
303  */
304 extern vnet_link_t dpo_proto_to_link(dpo_proto_t dp);
305 
306 /**
307  * @brief
308  * Set and stack a DPO.
309  * The DPO passed is set to the parent DPO and the necessary
310  * VLIB graph arcs are created. The child_type and child_proto
311  * are used to get the VLID nodes from which the arcs are added.
312  *
313  * @param child_type
314  * Child DPO type.
315  *
316  * @param child_proto
317  * Child DPO proto
318  *
319  * @parem dpo
320  * This is the DPO to stack and set.
321  *
322  * @paren parent_dpo
323  * The parent DPO to stack onto.
324  */
325 extern void dpo_stack(dpo_type_t child_type,
326  dpo_proto_t child_proto,
327  dpo_id_t *dpo,
328  const dpo_id_t *parent_dpo);
329 
330 /**
331  * @brief
332  * Set and stack a DPO.
333  * The DPO passed is set to the parent DPO and the necessary
334  * VLIB graph arcs are created, from the child_node passed.
335  *
336  * @param child_node
337  * The VLIB graph node index to create an arc from to the parent
338  *
339  * @param dpo
340  * This is the DPO to stack and set.
341  *
342  * @param parent_dpo
343  * The parent DPO to stack onto.
344  */
345 extern void dpo_stack_from_node(u32 child_node,
346  dpo_id_t *dpo,
347  const dpo_id_t *parent);
348 
349 /**
350  * Get a uRPF interface for the DPO
351  *
352  * @param dpo
353  * The DPO from which to get the uRPF interface
354  *
355  * @return valid SW interface index or ~0
356  */
357 extern u32 dpo_get_urpf(const dpo_id_t *dpo);
358 
359 /**
360  * @brief A lock function registered for a DPO type
361  */
362 typedef void (*dpo_lock_fn_t)(dpo_id_t *dpo);
363 
364 /**
365  * @brief An unlock function registered for a DPO type
366  */
367 typedef void (*dpo_unlock_fn_t)(dpo_id_t *dpo);
368 
369 /**
370  * @brief An memory usage show command
371  */
372 typedef void (*dpo_mem_show_t)(void);
373 
374 /**
375  * @brief Given a DPO instance return a vector of node indices that
376  * the type/instance will use.
377  */
378 typedef u32* (*dpo_get_next_node_t)(const dpo_id_t *dpo);
379 
380 /**
381  * @brief Given a DPO instance return an interface that can
382  * be used in an uRPF check
383  */
384 typedef u32 (*dpo_get_urpf_t)(const dpo_id_t *dpo);
385 
386 /**
387  * @brief Called during FIB interposition when the originally
388  * registered DPO is used to 'clone' an instance for interposition
389  * at a particular location in the FIB graph.
390  * The parent is the next DPO in the chain that the clone will
391  * be used instead of. The clone may then choose to stack itself
392  * on the parent.
393  */
394 typedef void (*dpo_mk_interpose_t)(const dpo_id_t *original,
395  const dpo_id_t *parent,
396  dpo_id_t *clone);
397 
398 /**
399  * @brief A virtual function table regisitered for a DPO type
400  */
401 typedef struct dpo_vft_t_
402 {
403  /**
404  * A reference counting lock function
405  */
407  /**
408  * A reference counting unlock function
409  */
411  /**
412  * A format function
413  */
415  /**
416  * A show memory usage function
417  */
419  /**
420  * A function to get the next VLIB node given an instance
421  * of the DPO. If this is null, then the node's name MUST be
422  * retreiveable from the nodes names array passed in the register
423  * function
424  */
426  /**
427  * Get uRPF interface
428  */
430  /**
431  * Signal on an interposed child that the parent has changed
432  */
434 } dpo_vft_t;
435 
436 
437 /**
438  * @brief For a given DPO type Register:
439  * - a virtual function table
440  * - a NULL terminated array of graph nodes from which that object type
441  * will originate packets, i.e. the nodes in which the object type will be
442  * the parent DPO in the DP graph. The ndoes are per-data-path protocol
443  * (see above).
444  *
445  * @param type
446  * The type being registered.
447  *
448  * @param vft
449  * The virtual function table to register for the type.
450  *
451  * @param nodes
452  * The string description of the per-protocol VLIB graph nodes.
453  */
454 extern void dpo_register(dpo_type_t type,
455  const dpo_vft_t *vft,
456  const char * const * const * nodes);
457 
458 /**
459  * @brief Create and register a new DPO type.
460  *
461  * This can be used by plugins to create new DPO types that are not listed
462  * in dpo_type_t enum
463  *
464  * @param vft
465  * The virtual function table to register for the type.
466  *
467  * @param nodes
468  * The string description of the per-protocol VLIB graph nodes.
469  *
470  * @return The new dpo_type_t
471  */
472 extern dpo_type_t dpo_register_new_type(const dpo_vft_t *vft,
473  const char * const * const * nodes);
474 
475 /**
476  * @brief Return already stacked up next node index for a given
477  * child_type/child_proto and parent_type/patent_proto.
478  * The VLIB graph arc used is taken from the parent and child types
479  * passed.
480  *
481  * @param child_type
482  * Child DPO type.
483  *
484  * @param child_proto
485  * Child DPO proto
486  *
487  * @param parent_type
488  * Parent DPO type.
489  *
490  * @param parent_proto
491  * Parent DPO proto
492  *
493  * @return The VLIB Graph node index
494  */
495 extern u32
496 dpo_get_next_node_by_type_and_proto (dpo_type_t child_type,
497  dpo_proto_t child_proto,
498  dpo_type_t parent_type,
499  dpo_proto_t parent_proto);
500 #endif
dpo_lock_fn_t dv_lock
A reference counting lock function.
Definition: dpo.h:406
Definition: dpo.h:98
void(* dpo_lock_fn_t)(dpo_id_t *dpo)
A lock function registered for a DPO type.
Definition: dpo.h:362
A virtual function table regisitered for a DPO type.
Definition: dpo.h:401
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:209
unsigned long u64
Definition: types.h:89
void dpo_mk_interpose(const dpo_id_t *original, const dpo_id_t *parent, dpo_id_t *clone)
Make an interpose DPO from an original.
Definition: dpo.c:353
dpo_get_urpf_t dv_get_urpf
Get uRPF interface.
Definition: dpo.h:429
dpo_proto_t dpoi_proto
the data-path protocol of the type.
Definition: dpo.h:178
u32 *(* dpo_get_next_node_t)(const dpo_id_t *dpo)
Given a DPO instance return a vector of node indices that the type/instance will use.
Definition: dpo.h:378
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:91
void(* dpo_mk_interpose_t)(const dpo_id_t *original, const dpo_id_t *parent, dpo_id_t *clone)
Called during FIB interposition when the originally registered DPO is used to &#39;clone&#39; an instance for...
Definition: dpo.h:394
u32(* dpo_get_urpf_t)(const dpo_id_t *dpo)
Given a DPO instance return an interface that can be used in an uRPF check.
Definition: dpo.h:384
void dpo_unlock(dpo_id_t *dpo)
Release a reference counting lock on the DPO.
Definition: dpo.c:373
unsigned char u8
Definition: types.h:56
u8 * format_dpo_proto(u8 *s, va_list *args)
format a DPO protocol
Definition: dpo.c:178
u8 *() format_function_t(u8 *s, va_list *args)
Definition: format.h:48
enum dpo_type_t_ dpo_type_t
Common types of data-path objects New types can be dynamically added using dpo_register_new_type() ...
u8 * format_dpo_id(u8 *s, va_list *args)
Format a DPO_id_t oject.
Definition: dpo.c:148
unsigned int u32
Definition: types.h:88
enum dpo_proto_t_ dpo_proto_t
Data path protocol.
dpo_get_next_node_t dv_get_next_node
A function to get the next VLIB node given an instance of the DPO.
Definition: dpo.h:425
u32 dpo_get_urpf(const dpo_id_t *dpo)
Get a uRPF interface for the DPO.
Definition: dpo.c:382
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:186
The identity of a DPO is a combination of its type and its instance number/index of objects of that t...
Definition: dpo.h:170
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:516
void(* dpo_mem_show_t)(void)
An memory usage show command.
Definition: dpo.h:372
Definition: dpo.h:128
dpo_type_t dpoi_type
the type
Definition: dpo.h:174
unsigned short u16
Definition: types.h:57
vnet_link_t dpo_proto_to_link(dpo_proto_t dp)
format a DPO protocol
Definition: dpo.c:118
load-balancing over a choice of [un]equal cost paths
Definition: dpo.h:102
void dpo_reset(dpo_id_t *dpo)
reset a DPO ID The DPO will be unlocked.
Definition: dpo.c:232
int dpo_cmp(const dpo_id_t *dpo1, const dpo_id_t *dpo2)
compare two DPOs for equality
Definition: dpo.c:249
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:322
STATIC_ASSERT(sizeof(dpo_id_t)<=sizeof(u64), "DPO ID is greater than sizeof u64 " "atomic updates need to be revisited")
void dpo_copy(dpo_id_t *dst, const dpo_id_t *src)
atomic copy a data-plane object.
Definition: dpo.c:262
u8 * format_dpo_type(u8 *s, va_list *args)
format a DPO type
Definition: dpo.c:138
int dpo_is_adj(const dpo_id_t *dpo)
Return TRUE is the DPO is any type of adjacency.
Definition: dpo.c:278
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:95
void dpo_lock(dpo_id_t *dpo)
Take a reference counting lock on the DPO.
Definition: dpo.c:364
u32 dpo_get_next_node_by_type_and_proto(dpo_type_t child_type, dpo_proto_t child_proto, dpo_type_t parent_type, dpo_proto_t parent_proto)
Return already stacked up next node index for a given child_type/child_proto and parent_type/patent_p...
Definition: dpo.c:472
void(* dpo_unlock_fn_t)(dpo_id_t *dpo)
An unlock function registered for a DPO type.
Definition: dpo.h:367
struct dpo_id_t_ dpo_id_t
The identity of a DPO is a combination of its type and its instance number/index of objects of that t...
dpo_mem_show_t dv_mem_show
A show memory usage function.
Definition: dpo.h:418
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:342
index_t dpoi_index
the index of objects of that type
Definition: dpo.h:186
format_function_t * dv_format
A format function.
Definition: dpo.h:414
#define INDEX_INVALID
Invalid index - used when no index is known blazoned capitals INVALID speak volumes where ~0 does not...
Definition: dpo.h:47
Definition: dpo.h:127
dpo_lock_fn_t dv_unlock
A reference counting unlock function.
Definition: dpo.h:410
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:531
Definition: dpo.h:119
dpo_proto_t vnet_link_to_dpo_proto(vnet_link_t linkt)
Definition: dpo.c:96
u16 dpoi_next_node
The next VLIB node to follow.
Definition: dpo.h:182
Definition: dpo.h:96
struct dpo_vft_t_ dpo_vft_t
A virtual function table regisitered for a DPO type.
dpo_mk_interpose_t dv_mk_interpose
Signal on an interposed child that the parent has changed.
Definition: dpo.h:433