1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2020 Intel Corporation
4 #ifndef __INCLUDE_RTE_SWX_PIPELINE_H__
5 #define __INCLUDE_RTE_SWX_PIPELINE_H__
19 #include <rte_compat.h>
21 #include "rte_swx_port.h"
22 #include "rte_swx_table.h"
23 #include "rte_swx_extern.h"
26 #ifndef RTE_SWX_NAME_SIZE
27 #define RTE_SWX_NAME_SIZE 64
30 * Pipeline setup and operation
33 /** Pipeline opaque data structure. */
34 struct rte_swx_pipeline;
40 * Pipeline handle. Must point to valid memory. Contains valid pipeline handle
41 * when the function returns successfully.
42 * @param[in] numa_node
43 * Non-Uniform Memory Access (NUMA) node.
45 * 0 on success or the following error codes otherwise:
46 * -EINVAL: Invalid argument;
47 * -ENOMEM: Not enough space/cannot allocate memory.
51 rte_swx_pipeline_config(struct rte_swx_pipeline **p,
55 * Pipeline input ports
59 * Pipeline input port type register
64 * Input port type name.
66 * Input port type operations.
68 * 0 on success or the following error codes otherwise:
69 * -EINVAL: Invalid argument;
70 * -ENOMEM: Not enough space/cannot allocate memory;
71 * -EEXIST: Input port type with this name already exists.
75 rte_swx_pipeline_port_in_type_register(struct rte_swx_pipeline *p,
77 struct rte_swx_port_in_ops *ops);
80 * Pipeline input port configure
86 * @param[in] port_type_name
87 * Existing input port type name.
89 * Input port creation arguments.
91 * 0 on success or the following error codes otherwise:
92 * -EINVAL: Invalid argument;
93 * -ENOMEM: Not enough space/cannot allocate memory;
94 * -ENODEV: Input port object creation error.
98 rte_swx_pipeline_port_in_config(struct rte_swx_pipeline *p,
100 const char *port_type_name,
104 * Pipeline output ports
108 * Pipeline output port type register
113 * Output port type name.
115 * Output port type operations.
117 * 0 on success or the following error codes otherwise:
118 * -EINVAL: Invalid argument;
119 * -ENOMEM: Not enough space/cannot allocate memory;
120 * -EEXIST: Output port type with this name already exists.
124 rte_swx_pipeline_port_out_type_register(struct rte_swx_pipeline *p,
126 struct rte_swx_port_out_ops *ops);
129 * Pipeline output port configure
135 * @param[in] port_type_name
136 * Existing output port type name.
138 * Output port creation arguments.
140 * 0 on success or the following error codes otherwise:
141 * -EINVAL: Invalid argument;
142 * -ENOMEM: Not enough space/cannot allocate memory;
143 * -ENODEV: Output port object creation error.
147 rte_swx_pipeline_port_out_config(struct rte_swx_pipeline *p,
149 const char *port_type_name,
153 * Extern objects and functions
157 * Pipeline extern type register
163 * @param[in] mailbox_struct_type_name
164 * Name of existing struct type used to define the mailbox size and layout for
165 * the extern objects that are instances of this type. Each extern object gets
166 * its own mailbox, which is used to pass the input arguments to the member
167 * functions and retrieve the output results.
168 * @param[in] constructor
169 * Function used to create the extern objects that are instances of this type.
170 * @param[in] destructor
171 * Function used to free the extern objects that are instances of this type.
173 * 0 on success or the following error codes otherwise:
174 * -EINVAL: Invalid argument;
175 * -ENOMEM: Not enough space/cannot allocate memory;
176 * -EEXIST: Extern type with this name already exists.
180 rte_swx_pipeline_extern_type_register(struct rte_swx_pipeline *p,
182 const char *mailbox_struct_type_name,
183 rte_swx_extern_type_constructor_t constructor,
184 rte_swx_extern_type_destructor_t destructor);
187 * Pipeline extern type member function register
191 * @param[in] extern_type_name
192 * Existing extern type name.
194 * Name for the new member function to be added to the extern type.
195 * @param[in] member_func
196 * The new member function.
198 * 0 on success or the following error codes otherwise:
199 * -EINVAL: Invalid argument;
200 * -ENOMEM: Not enough space/cannot allocate memory;
201 * -EEXIST: Member function with this name already exists for this type;
202 * -ENOSPC: Maximum number of member functions reached for this type.
206 rte_swx_pipeline_extern_type_member_func_register(struct rte_swx_pipeline *p,
207 const char *extern_type_name,
209 rte_swx_extern_type_member_func_t member_func);
212 * Pipeline extern object configure
214 * Instantiate a given extern type to create new extern object.
218 * @param[in] extern_type_name
219 * Existing extern type name.
221 * Name for the new object instantiating the extern type.
223 * Extern object constructor arguments.
225 * 0 on success or the following error codes otherwise:
226 * -EINVAL: Invalid argument;
227 * -ENOMEM: Not enough space/cannot allocate memory;
228 * -EEXIST: Extern object with this name already exists;
229 * -ENODEV: Extern object constructor error.
233 rte_swx_pipeline_extern_object_config(struct rte_swx_pipeline *p,
234 const char *extern_type_name,
239 * Pipeline extern function register
244 * Extern function name.
245 * @param[in] mailbox_struct_type_name
246 * Name of existing struct type used to define the mailbox size and layout for
247 * this extern function. The mailbox is used to pass the input arguments to
248 * the extern function and retrieve the output results.
250 * The extern function.
252 * 0 on success or the following error codes otherwise:
253 * -EINVAL: Invalid argument;
254 * -ENOMEM: Not enough space/cannot allocate memory;
255 * -EEXIST: Extern function with this name already exists.
259 rte_swx_pipeline_extern_func_register(struct rte_swx_pipeline *p,
261 const char *mailbox_struct_type_name,
262 rte_swx_extern_func_t func);
265 * Packet headers and meta-data
268 /** Structure (struct) field. */
269 struct rte_swx_field_params {
270 /** Struct field name. */
273 /** Struct field size (in bits).
274 * Restriction: All struct fields must be a multiple of 8 bits.
275 * Restriction: All struct fields must be no greater than 64 bits.
281 * Pipeline struct type register
283 * Structs are used extensively in many part of the pipeline to define the size
284 * and layout of a specific memory piece such as: headers, meta-data, action
285 * data stored in a table entry, mailboxes for extern objects and functions.
286 * Similar to C language structs, they are a well defined sequence of fields,
287 * with each field having a unique name and a constant size.
294 * The sequence of struct fields.
295 * @param[in] n_fields
296 * The number of struct fields.
298 * 0 on success or the following error codes otherwise:
299 * -EINVAL: Invalid argument;
300 * -ENOMEM: Not enough space/cannot allocate memory;
301 * -EEXIST: Struct type with this name already exists.
305 rte_swx_pipeline_struct_type_register(struct rte_swx_pipeline *p,
307 struct rte_swx_field_params *fields,
311 * Pipeline packet header register
317 * @param[in] struct_type_name
318 * The struct type instantiated by this packet header.
320 * 0 on success or the following error codes otherwise:
321 * -EINVAL: Invalid argument;
322 * -ENOMEM: Not enough space/cannot allocate memory;
323 * -EEXIST: Header with this name already exists;
324 * -ENOSPC: Maximum number of headers reached for the pipeline.
328 rte_swx_pipeline_packet_header_register(struct rte_swx_pipeline *p,
330 const char *struct_type_name);
333 * Pipeline packet meta-data register
337 * @param[in] struct_type_name
338 * The struct type instantiated by the packet meta-data.
340 * 0 on success or the following error codes otherwise:
341 * -EINVAL: Invalid argument.
345 rte_swx_pipeline_packet_metadata_register(struct rte_swx_pipeline *p,
346 const char *struct_type_name);
353 * Pipeline action configure
359 * @param[in] args_struct_type_name
360 * The struct type instantiated by the action data. The action data represent
361 * the action arguments that are stored in the table entry together with the
362 * action ID. Set to NULL when the action does not have any arguments.
363 * @param[in] instructions
364 * Action instructions.
365 * @param[in] n_instructions
366 * Number of action instructions.
368 * 0 on success or the following error codes otherwise:
369 * -EINVAL: Invalid argument;
370 * -ENOMEM: Not enough space/cannot allocate memory;
371 * -EEXIST: Action with this name already exists.
375 rte_swx_pipeline_action_config(struct rte_swx_pipeline *p,
377 const char *args_struct_type_name,
378 const char **instructions,
379 uint32_t n_instructions);
386 * Pipeline table type register
392 * @param[in] match_type
393 * Match type implemented by the new table type.
395 * Table type operations.
397 * 0 on success or the following error codes otherwise:
398 * -EINVAL: Invalid argument;
399 * -ENOMEM: Not enough space/cannot allocate memory;
400 * -EEXIST: Table type with this name already exists.
404 rte_swx_pipeline_table_type_register(struct rte_swx_pipeline *p,
406 enum rte_swx_table_match_type match_type,
407 struct rte_swx_table_ops *ops);
409 /** Match field parameters. */
410 struct rte_swx_match_field_params {
411 /** Match field name. Must be either a field of one of the registered
412 * packet headers ("h.header.field") or a field of the registered
413 * meta-data ("m.field").
417 /** Match type of the field. */
418 enum rte_swx_table_match_type match_type;
421 /** Pipeline table parameters. */
422 struct rte_swx_pipeline_table_params {
423 /** The set of match fields for the current table.
424 * Restriction: All the match fields of the current table need to be
425 * part of the same struct, i.e. either all the match fields are part of
426 * the same header or all the match fields are part of the meta-data.
428 struct rte_swx_match_field_params *fields;
430 /** The number of match fields for the current table. If set to zero, no
431 * "regular" entries (i.e. entries other than the default entry) can be
432 * added to the current table and the match process always results in
437 /** The set of actions for the current table. */
438 const char **action_names;
440 /** The number of actions for the current table. Must be at least one.
444 /** The default table action that gets executed on lookup miss. Must be
445 * one of the table actions included in the *action_names*.
447 const char *default_action_name;
449 /** Default action data. The size of this array is the action data size
450 * of the default action. Must be NULL if the default action data size
453 uint8_t *default_action_data;
455 /** If non-zero (true), then the default action of the current table
456 * cannot be changed. If zero (false), then the default action can be
457 * changed in the future with another action from the *action_names*
460 int default_action_is_const;
464 * Pipeline table configure
472 * @param[in] recommended_table_type_name
473 * Recommended table type. Typically set to NULL. Useful as guidance when
474 * there are multiple table types registered for the match type of the table,
475 * as determined from the table match fields specification. Silently ignored
476 * if the recommended table type does not exist or it serves a different match
479 * Table creation arguments.
481 * Guideline on maximum number of table entries.
483 * 0 on success or the following error codes otherwise:
484 * -EINVAL: Invalid argument;
485 * -ENOMEM: Not enough space/cannot allocate memory;
486 * -EEXIST: Table with this name already exists;
487 * -ENODEV: Table creation error.
491 rte_swx_pipeline_table_config(struct rte_swx_pipeline *p,
493 struct rte_swx_pipeline_table_params *params,
494 const char *recommended_table_type_name,
501 * Once called, the pipeline build operation marks the end of pipeline
502 * configuration. At this point, all the internal data structures needed to run
503 * the pipeline are built.
508 * 0 on success or the following error codes otherwise:
509 * -EINVAL: Invalid argument;
510 * -ENOMEM: Not enough space/cannot allocate memory;
511 * -EEXIST: Pipeline was already built successfully.
515 rte_swx_pipeline_build(struct rte_swx_pipeline *p);
525 rte_swx_pipeline_free(struct rte_swx_pipeline *p);