pipeline: add SWX pipeline action
[dpdk.git] / lib / librte_pipeline / rte_swx_pipeline.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2020 Intel Corporation
3  */
4 #ifndef __INCLUDE_RTE_SWX_PIPELINE_H__
5 #define __INCLUDE_RTE_SWX_PIPELINE_H__
6
7 #ifdef __cplusplus
8 extern "C" {
9 #endif
10
11 /**
12  * @file
13  * RTE SWX Pipeline
14  */
15
16 #include <stddef.h>
17 #include <stdint.h>
18
19 #include <rte_compat.h>
20
21 #include "rte_swx_port.h"
22 #include "rte_swx_extern.h"
23
24 /** Name size. */
25 #ifndef RTE_SWX_NAME_SIZE
26 #define RTE_SWX_NAME_SIZE 64
27 #endif
28 /*
29  * Pipeline setup and operation
30  */
31
32 /** Pipeline opaque data structure. */
33 struct rte_swx_pipeline;
34
35 /**
36  * Pipeline configure
37  *
38  * @param[out] p
39  *   Pipeline handle. Must point to valid memory. Contains valid pipeline handle
40  *   when the function returns successfully.
41  * @param[in] numa_node
42  *   Non-Uniform Memory Access (NUMA) node.
43  * @return
44  *   0 on success or the following error codes otherwise:
45  *   -EINVAL: Invalid argument;
46  *   -ENOMEM: Not enough space/cannot allocate memory.
47  */
48 __rte_experimental
49 int
50 rte_swx_pipeline_config(struct rte_swx_pipeline **p,
51                         int numa_node);
52
53 /*
54  * Pipeline input ports
55  */
56
57 /**
58  * Pipeline input port type register
59  *
60  * @param[in] p
61  *   Pipeline handle.
62  * @param[in] name
63  *   Input port type name.
64  * @param[in] ops
65  *   Input port type operations.
66  * @return
67  *   0 on success or the following error codes otherwise:
68  *   -EINVAL: Invalid argument;
69  *   -ENOMEM: Not enough space/cannot allocate memory;
70  *   -EEXIST: Input port type with this name already exists.
71  */
72 __rte_experimental
73 int
74 rte_swx_pipeline_port_in_type_register(struct rte_swx_pipeline *p,
75                                        const char *name,
76                                        struct rte_swx_port_in_ops *ops);
77
78 /**
79  * Pipeline input port configure
80  *
81  * @param[in] p
82  *   Pipeline handle.
83  * @param[in] port_id
84  *   Input port ID.
85  * @param[in] port_type_name
86  *   Existing input port type name.
87  * @param[in] args
88  *   Input port creation arguments.
89  * @return
90  *   0 on success or the following error codes otherwise:
91  *   -EINVAL: Invalid argument;
92  *   -ENOMEM: Not enough space/cannot allocate memory;
93  *   -ENODEV: Input port object creation error.
94  */
95 __rte_experimental
96 int
97 rte_swx_pipeline_port_in_config(struct rte_swx_pipeline *p,
98                                 uint32_t port_id,
99                                 const char *port_type_name,
100                                 void *args);
101
102 /*
103  * Pipeline output ports
104  */
105
106 /**
107  * Pipeline output port type register
108  *
109  * @param[in] p
110  *   Pipeline handle.
111  * @param[in] name
112  *   Output port type name.
113  * @param[in] ops
114  *   Output port type operations.
115  * @return
116  *   0 on success or the following error codes otherwise:
117  *   -EINVAL: Invalid argument;
118  *   -ENOMEM: Not enough space/cannot allocate memory;
119  *   -EEXIST: Output port type with this name already exists.
120  */
121 __rte_experimental
122 int
123 rte_swx_pipeline_port_out_type_register(struct rte_swx_pipeline *p,
124                                         const char *name,
125                                         struct rte_swx_port_out_ops *ops);
126
127 /**
128  * Pipeline output port configure
129  *
130  * @param[in] p
131  *   Pipeline handle.
132  * @param[in] port_id
133  *   Output port ID.
134  * @param[in] port_type_name
135  *   Existing output port type name.
136  * @param[in] args
137  *   Output port creation arguments.
138  * @return
139  *   0 on success or the following error codes otherwise:
140  *   -EINVAL: Invalid argument;
141  *   -ENOMEM: Not enough space/cannot allocate memory;
142  *   -ENODEV: Output port object creation error.
143  */
144 __rte_experimental
145 int
146 rte_swx_pipeline_port_out_config(struct rte_swx_pipeline *p,
147                                  uint32_t port_id,
148                                  const char *port_type_name,
149                                  void *args);
150
151 /*
152  * Extern objects and functions
153  */
154
155 /**
156  * Pipeline extern type register
157  *
158  * @param[in] p
159  *   Pipeline handle.
160  * @param[in] name
161  *   Extern type name.
162  * @param[in] mailbox_struct_type_name
163  *   Name of existing struct type used to define the mailbox size and layout for
164  *   the extern objects that are instances of this type. Each extern object gets
165  *   its own mailbox, which is used to pass the input arguments to the member
166  *   functions and retrieve the output results.
167  * @param[in] constructor
168  *   Function used to create the extern objects that are instances of this type.
169  * @param[in] destructor
170  *   Function used to free the extern objects that are instances of  this type.
171  * @return
172  *   0 on success or the following error codes otherwise:
173  *   -EINVAL: Invalid argument;
174  *   -ENOMEM: Not enough space/cannot allocate memory;
175  *   -EEXIST: Extern type with this name already exists.
176  */
177 __rte_experimental
178 int
179 rte_swx_pipeline_extern_type_register(struct rte_swx_pipeline *p,
180         const char *name,
181         const char *mailbox_struct_type_name,
182         rte_swx_extern_type_constructor_t constructor,
183         rte_swx_extern_type_destructor_t destructor);
184
185 /**
186  * Pipeline extern type member function register
187  *
188  * @param[in] p
189  *   Pipeline handle.
190  * @param[in] extern_type_name
191  *   Existing extern type name.
192  * @param[in] name
193  *   Name for the new member function to be added to the extern type.
194  * @param[in] member_func
195  *   The new member function.
196  * @return
197  *   0 on success or the following error codes otherwise:
198  *   -EINVAL: Invalid argument;
199  *   -ENOMEM: Not enough space/cannot allocate memory;
200  *   -EEXIST: Member function with this name already exists for this type;
201  *   -ENOSPC: Maximum number of member functions reached for this type.
202  */
203 __rte_experimental
204 int
205 rte_swx_pipeline_extern_type_member_func_register(struct rte_swx_pipeline *p,
206         const char *extern_type_name,
207         const char *name,
208         rte_swx_extern_type_member_func_t member_func);
209
210 /**
211  * Pipeline extern object configure
212  *
213  * Instantiate a given extern type to create new extern object.
214  *
215  * @param[in] p
216  *   Pipeline handle.
217  * @param[in] extern_type_name
218  *   Existing extern type name.
219  * @param[in] name
220  *   Name for the new object instantiating the extern type.
221  * @param[in] args
222  *   Extern object constructor arguments.
223  * @return
224  *   0 on success or the following error codes otherwise:
225  *   -EINVAL: Invalid argument;
226  *   -ENOMEM: Not enough space/cannot allocate memory;
227  *   -EEXIST: Extern object with this name already exists;
228  *   -ENODEV: Extern object constructor error.
229  */
230 __rte_experimental
231 int
232 rte_swx_pipeline_extern_object_config(struct rte_swx_pipeline *p,
233                                       const char *extern_type_name,
234                                       const char *name,
235                                       const char *args);
236
237 /**
238  * Pipeline extern function register
239  *
240  * @param[in] p
241  *   Pipeline handle.
242  * @param[in] name
243  *   Extern function name.
244  * @param[in] mailbox_struct_type_name
245  *   Name of existing struct type used to define the mailbox size and layout for
246  *   this extern function. The mailbox is used to pass the input arguments to
247  *   the extern function and retrieve the output results.
248  * @param[in] func
249  *   The extern function.
250  * @return
251  *   0 on success or the following error codes otherwise:
252  *   -EINVAL: Invalid argument;
253  *   -ENOMEM: Not enough space/cannot allocate memory;
254  *   -EEXIST: Extern function with this name already exists.
255  */
256 __rte_experimental
257 int
258 rte_swx_pipeline_extern_func_register(struct rte_swx_pipeline *p,
259                                       const char *name,
260                                       const char *mailbox_struct_type_name,
261                                       rte_swx_extern_func_t func);
262
263 /*
264  * Packet headers and meta-data
265  */
266
267 /** Structure (struct) field. */
268 struct rte_swx_field_params {
269         /** Struct field name. */
270         const char *name;
271
272         /** Struct field size (in bits).
273          * Restriction: All struct fields must be a multiple of 8 bits.
274          * Restriction: All struct fields must be no greater than 64 bits.
275          */
276         uint32_t n_bits;
277 };
278
279 /**
280  * Pipeline struct type register
281  *
282  * Structs are used extensively in many part of the pipeline to define the size
283  * and layout of a specific memory piece such as: headers, meta-data, action
284  * data stored in a table entry, mailboxes for extern objects and functions.
285  * Similar to C language structs, they are a well defined sequence of fields,
286  * with each field having a unique name and a constant size.
287  *
288  * @param[in] p
289  *   Pipeline handle.
290  * @param[in] name
291  *   Struct type name.
292  * @param[in] fields
293  *   The sequence of struct fields.
294  * @param[in] n_fields
295  *   The number of struct fields.
296  * @return
297  *   0 on success or the following error codes otherwise:
298  *   -EINVAL: Invalid argument;
299  *   -ENOMEM: Not enough space/cannot allocate memory;
300  *   -EEXIST: Struct type with this name already exists.
301  */
302 __rte_experimental
303 int
304 rte_swx_pipeline_struct_type_register(struct rte_swx_pipeline *p,
305                                       const char *name,
306                                       struct rte_swx_field_params *fields,
307                                       uint32_t n_fields);
308
309 /**
310  * Pipeline packet header register
311  *
312  * @param[in] p
313  *   Pipeline handle.
314  * @param[in] name
315  *   Header name.
316  * @param[in] struct_type_name
317  *   The struct type instantiated by this packet header.
318  * @return
319  *   0 on success or the following error codes otherwise:
320  *   -EINVAL: Invalid argument;
321  *   -ENOMEM: Not enough space/cannot allocate memory;
322  *   -EEXIST: Header with this name already exists;
323  *   -ENOSPC: Maximum number of headers reached for the pipeline.
324  */
325 __rte_experimental
326 int
327 rte_swx_pipeline_packet_header_register(struct rte_swx_pipeline *p,
328                                         const char *name,
329                                         const char *struct_type_name);
330
331 /**
332  * Pipeline packet meta-data register
333  *
334  * @param[in] p
335  *   Pipeline handle.
336  * @param[in] struct_type_name
337  *   The struct type instantiated by the packet meta-data.
338  * @return
339  *   0 on success or the following error codes otherwise:
340  *   -EINVAL: Invalid argument.
341  */
342 __rte_experimental
343 int
344 rte_swx_pipeline_packet_metadata_register(struct rte_swx_pipeline *p,
345                                           const char *struct_type_name);
346
347 /*
348  * Pipeline action
349  */
350
351 /**
352  * Pipeline action configure
353  *
354  * @param[in] p
355  *   Pipeline handle.
356  * @param[in] name
357  *   Action name.
358  * @param[in] args_struct_type_name
359  *   The struct type instantiated by the action data. The action data represent
360  *   the action arguments that are stored in the table entry together with the
361  *   action ID. Set to NULL when the action does not have any arguments.
362  * @param[in] instructions
363  *   Action instructions.
364  * @param[in] n_instructions
365  *   Number of action instructions.
366  * @return
367  *   0 on success or the following error codes otherwise:
368  *   -EINVAL: Invalid argument;
369  *   -ENOMEM: Not enough space/cannot allocate memory;
370  *   -EEXIST: Action with this name already exists.
371  */
372 __rte_experimental
373 int
374 rte_swx_pipeline_action_config(struct rte_swx_pipeline *p,
375                                const char *name,
376                                const char *args_struct_type_name,
377                                const char **instructions,
378                                uint32_t n_instructions);
379
380 /**
381  * Pipeline build
382  *
383  * Once called, the pipeline build operation marks the end of pipeline
384  * configuration. At this point, all the internal data structures needed to run
385  * the pipeline are built.
386  *
387  * @param[in] p
388  *   Pipeline handle.
389  * @return
390  *   0 on success or the following error codes otherwise:
391  *   -EINVAL: Invalid argument;
392  *   -ENOMEM: Not enough space/cannot allocate memory;
393  *   -EEXIST: Pipeline was already built successfully.
394  */
395 __rte_experimental
396 int
397 rte_swx_pipeline_build(struct rte_swx_pipeline *p);
398
399 /**
400  * Pipeline free
401  *
402  * @param[in] p
403  *   Pipeline handle.
404  */
405 __rte_experimental
406 void
407 rte_swx_pipeline_free(struct rte_swx_pipeline *p);
408
409 #ifdef __cplusplus
410 }
411 #endif
412
413 #endif