Hi Gregory
> -----Original Message-----
> From: Gregory Etelson <getel...@nvidia.com>
> Sent: Friday, May 19, 2023 3:00 PM
>
> Indirect API creates a shared flow action with unique action handle.
> Flow rules can access the shared flow action and resources related to
> that action through the indirect action handle.
> In addition, the API allows to update existing shared flow action
> configuration. After the update completes, new action configuration
> is available to all flows that reference that shared action.
>
> Indirect actions list expands the indirect action API:
> • Indirect action list creates a handle for one or several
> flow actions, while legacy indirect action handle references
> single action only.
> Input flow actions arranged in END terminated list.
> • Flow rule can provide rule specific configuration parameters to
> existing shared handle.
> Updates of flow rule specific configuration will not change the base
> action configuration.
> Base action configuration was set during the action creation.
>
> Indirect action list handle defines 2 types of resources:
> • Mutable handle resource can be changed during handle lifespan.
> • Immutable handle resource value is set during handle creation
> and cannot be changed.
>
> There are 2 types of mutable indirect handle contexts:
> • Action mutable context is always shared between all flows
> that referenced indirect actions list handle.
> Action mutable context can be changed by explicit invocation
> of indirect handle update function.
> • Flow mutable context is private to a flow.
> Flow mutable context can be updated by indirect list handle
> flow rule configuration.
>
> flow 1:
> / indirect handle H conf C1 /
> | |
> | |
> | | flow 2:
> | | / indirect handle H conf C2 /
> | | | |
> | | | |
> | | | |
> =========================================================
> ^ | | | |
> | | V | V
> | ~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
> | flow mutable flow mutable
> | context 1 context 2
> | ~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
> indirect | | |
> action | | |
> context | V V
> | -----------------------------------------------------
> | action mutable context
> | -----------------------------------------------------
> v action immutable context
> =========================================================
>
> Indirect action types - immutable, action / flow mutable, are mutually
> exclusive and depend on the action definition.
> For example:
> • Indirect METER_MARK policy is immutable action member and profile is
> action mutable action member.
> • Indirect METER_MARK flow action defines init_color as flow mutable
> member.
> • Indirect QUOTA flow action does not define flow mutable members.
>
> If indirect list handle was created from a list of actions
> A1 / A2 ... An / END
> indirect list flow action can update Ai flow mutable context in the
> action configuration parameter.
> Indirect list action configuration is and array [C1, C2, .., Cn]
> where Ci corresponds to Ai in the action handle source.
> Ci configuration element points Ai flow mutable update, or it's NULL
> if Ai has no flow mutable update.
> Indirect list action configuration can be NULL if the action
> has no flow mutable updates.
>
> Template API:
>
> Action template format:
>
> template .. indirect_list handle Htmpl conf Ctmpl ..
> mask .. indirect_list handle Hmask conf Cmask ..
>
> 1 If Htmpl was masked (Hmask != 0), it will be fixed in that template.
> Otherwise, indirect action value is set in a flow rule.
>
> 2 If Htmpl and Ctmpl[i] were masked (Hmask !=0 and Cmask[i] != 0),
> Htmpl's Ai action flow mutable context fill be updated to
> Ctmpl[i] values and will be fixed in that template.
>
> Flow rule format:
>
> actions .. indirect_list handle Hflow conf Cflow ..
>
> 3 If Htmpl was not masked in actions template, Hflow references an
> action of the same type as Htmpl.
>
> 4 Cflow[i] updates handle's Ai flow mutable configuration if
> the Ci was not masked in action template.
>
> Signed-off-by: Gregory Etelson <getel...@nvidia.com>
> ---
[Snip]
> diff --git a/lib/ethdev/rte_flow.h b/lib/ethdev/rte_flow.h
> index 713ba8b65c..b65096b3b7 100644
> --- a/lib/ethdev/rte_flow.h
> +++ b/lib/ethdev/rte_flow.h
> @@ -2912,6 +2912,13 @@ enum rte_flow_action_type {
> * applied to the given ethdev Rx queue.
> */
> RTE_FLOW_ACTION_TYPE_SKIP_CMAN,
> +
> + /**
> + * Action handle to reference flow actions list.
> + *
> + * @see struct rte_flow_action_indirect_list
> + */
> + RTE_FLOW_ACTION_TYPE_INDIRECT_LIST,
> };
>
> /**
> @@ -6118,6 +6125,268 @@
> rte_flow_async_action_handle_query_update(uint16_t port_id, uint32_t
> queue_id,
> void *user_data,
> struct rte_flow_error *error);
>
> +struct rte_flow_action_list_handle;
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Configure INDIRECT_LIST flow action.
> + *
> + * @see RTE_FLOW_ACTION_TYPE_INDIRECT_LIST
> + */
> +struct rte_flow_action_indirect_list {
> + /** Indirect action list handle */
> + struct rte_flow_action_list_handle *handle;
> + /**
> + * Flow mutable configuration array.
> + * NULL if the handle has no flow mutable configuration update.
> + * Otherwise, if the handle was created with list A1 / A2 .. An / END
> + * size of conf is n.
> + * conf[i] points to flow mutable update of Ai in the handle
> + * actions list or NULL if Ai has no update.
> + */
> + const void **conf;
> +};
> +
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Create an indirect flow action object from flow actions list.
> + * The object is identified by a unique handle.
> + * The handle has single state and configuration
> + * across all the flow rules using it.
> + *
> + * @param[in] port_id
> + * The port identifier of the Ethernet device.
> + * @param[in] conf
> + * Action configuration for the indirect action list creation.
> + * @param[in] actions
> + * Specific configuration of the indirect action lists.
> + * @param[out] error
> + * Perform verbose error reporting if not NULL. PMDs initialize this
> + * structure in case of error only.
> + * @return
> + * A valid handle in case of success, NULL otherwise and rte_errno is set
> + * to one of the error codes defined:
> + * - (-ENODEV) if *port_id* invalid.
> + * - (-ENOSYS) if underlying device does not support this functionality.
> + * - (-EIO) if underlying device is removed.
> + * - (-EINVAL) if *actions* list invalid.
> + * - (-ENOTSUP) if *action* list element valid but unsupported.
> + */
> +__rte_experimental
> +struct rte_flow_action_list_handle *
> +rte_flow_action_list_handle_create(uint16_t port_id,
> + const
> + struct rte_flow_indir_action_conf *conf,
> + const struct rte_flow_action *actions,
> + struct rte_flow_error *error);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Async function call to create an indirect flow action object
> + * from flow actions list.
> + * The object is identified by a unique handle.
> + * The handle has single state and configuration
> + * across all the flow rules using it.
> + *
> + * @param[in] port_id
> + * The port identifier of the Ethernet device.
> + * @param[in] queue_id
> + * Flow queue which is used to update the rule.
> + * @param[in] attr
> + * Indirect action update operation attributes.
> + * @param[in] conf
> + * Action configuration for the indirect action list creation.
> + * @param[in] actions
> + * Specific configuration of the indirect action list.
> + * @param[in] user_data
> + * The user data that will be returned on async completion event.
> + * @param[out] error
> + * Perform verbose error reporting if not NULL. PMDs initialize this
> + * structure in case of error only.
> + * @return
> + * A valid handle in case of success, NULL otherwise and rte_errno is set
> + * to one of the error codes defined:
> + * - (-ENODEV) if *port_id* invalid.
> + * - (-ENOSYS) if underlying device does not support this functionality.
> + * - (-EIO) if underlying device is removed.
> + * - (-EINVAL) if *actions* list invalid.
> + * - (-ENOTSUP) if *action* list element valid but unsupported.
> + */
> +__rte_experimental
> +struct rte_flow_action_list_handle *
> +rte_flow_async_action_list_handle_create(uint16_t port_id, uint32_t
> queue_id,
> + const struct rte_flow_op_attr *attr,
> + const struct
> + rte_flow_indir_action_conf *conf,
> + const struct rte_flow_action
> *actions,
> + void *user_data,
> + struct rte_flow_error *error);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Destroy indirect actions list by handle.
> + *
> + * @param[in] port_id
> + * The port identifier of the Ethernet device.
> + * @param[in] handle
> + * Handle for the indirect actions list to be destroyed.
> + * @param[out] error
> + * Perform verbose error reporting if not NULL. PMDs initialize this
> + * structure in case of error only.
> + * @return
> + * - (0) if success.
> + * - (-ENODEV) if *port_id* invalid.
> + * - (-ENOSYS) if underlying device does not support this functionality.
> + * - (-EIO) if underlying device is removed.
> + * - (-ENOENT) if actions list pointed by *action* handle was not found.
> + * - (-EBUSY) if actions list pointed by *action* handle still used
> + */
> +__rte_experimental
> +int
> +rte_flow_action_list_handle_destroy(uint16_t port_id,
> + struct rte_flow_action_list_handle
> *handle,
> + struct rte_flow_error *error);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Enqueue indirect action list destruction operation.
> + * The destroy queue must be the same
> + * as the queue on which the action was created.
> + *
> + * @param[in] port_id
> + * Port identifier of Ethernet device.
> + * @param[in] queue_id
> + * Flow queue which is used to destroy the rule.
> + * @param[in] op_attr
> + * Indirect action destruction operation attributes.
> + * @param[in] handle
> + * Handle for the indirect action object to be destroyed.
> + * @param[in] user_data
> + * The user data that will be returned on the completion events.
> + * @param[out] error
> + * Perform verbose error reporting if not NULL.
> + * PMDs initialize this structure in case of error only.
> + *
> + * @return
> + * - (0) if success.
> + * - (-ENODEV) if *port_id* invalid.
> + * - (-ENOSYS) if underlying device does not support this functionality.
> + * - (-EIO) if underlying device is removed.
> + * - (-ENOENT) if actions list pointed by *action* handle was not found.
> + * - (-EBUSY) if actions list pointed by *action* handle still used
> + */
> +__rte_experimental
> +int
> +rte_flow_async_action_list_handle_destroy
> + (uint16_t port_id, uint32_t queue_id,
> + const struct rte_flow_op_attr *op_attr,
> + struct rte_flow_action_list_handle *handle,
> + void *user_data, struct rte_flow_error *error);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Query and/or update indirect flow actions list.
> + * If both query and update not NULL, the function atomically
> + * queries and updates indirect action. Query and update are carried in
> order
> + * specified in the mode parameter.
> + * If ether query or update is NULL, the function executes
> + * complementing operation.
> + *
> + * @param port_id
> + * Port identifier of Ethernet device.
> + * @param handle
> + * Handle for the indirect actions list object to be updated.
> + * @param update
> + * If not NULL, update profile specification used to modify the action
It should be explained that the upate/query points always to array with the size
of number of actions, the the query/update query/upate all the actions at the
same time
This comment is for all such parameters in async and synced functions.
> + * pointed by handle.
> + * @see struct rte_flow_action_indirect_list
> + * @param query
> + * If not NULL pointer to storage for the associated query data type.
> + * @see struct rte_flow_action_indirect_list
> + * @param mode
> + * Operational mode.
> + * @param error
> + * Perform verbose error reporting if not NULL.
> + * PMDs initialize this structure in case of error only.
> + *
> + * @return
> + * - (0) if success.
> + * - (-ENODEV) if *port_id* invalid.
> + * - (-ENOTSUP) if underlying device does not support this functionality.
> + * - (-EINVAL) if *handle* or *mode* invalid or
> + * both *query* and *update* are NULL.
> + */
> +__rte_experimental
> +int
> +rte_flow_action_list_handle_query_update(uint16_t port_id,
> + const struct
> + rte_flow_action_list_handle
> *handle,
> + const void **update, void **query,
> + enum
> rte_flow_query_update_mode mode,
> + struct rte_flow_error *error);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Enqueue async indirect flow actions list query and/or update
> + *
> + * @param port_id
> + * Port identifier of Ethernet device.
> + * @param queue_id
> + * Flow queue which is used to update the rule.
> + * @param attr
> + * Indirect action update operation attributes.
> + * @param handle
> + * Handle for the indirect actions list object to be updated.
> + * @param update
> + * If not NULL, update profile specification used to modify the action
> + * pointed by handle.
> + * @see struct rte_flow_action_indirect_list
> + * @param query
> + * If not NULL, pointer to storage for the associated query data type.
> + * Query result returned on async completion event.
> + * @see struct rte_flow_action_indirect_list
> + * @param mode
> + * Operational mode.
> + * @param user_data
> + * The user data that will be returned on async completion event.
> + * @param error
> + * Perform verbose error reporting if not NULL.
> + * PMDs initialize this structure in case of error only.
> + *
> + * @return
> + * - (0) if success.
> + * - (-ENODEV) if *port_id* invalid.
> + * - (-ENOTSUP) if underlying device does not support this functionality.
> + * - (-EINVAL) if *handle* or *mode* invalid or
> + * both *update* and *query* are NULL.
> + */
> +__rte_experimental
> +int
> +rte_flow_async_action_list_handle_query_update(uint16_t port_id,
> uint32_t queue_id,
> + const struct rte_flow_op_attr *attr,
> + const struct
> + rte_flow_action_list_handle
> *handle,
> + const void **update, void **query,
> + enum
> rte_flow_query_update_mode mode,
> + void *user_data,
> + struct rte_flow_error *error);
> +
> +
> #ifdef __cplusplus
> }
> #endif
> diff --git a/lib/ethdev/rte_flow_driver.h b/lib/ethdev/rte_flow_driver.h
> index a129a4605d..af63ef9b5c 100644
> --- a/lib/ethdev/rte_flow_driver.h
> +++ b/lib/ethdev/rte_flow_driver.h
> @@ -121,6 +121,17 @@ struct rte_flow_ops {
> const void *update, void *query,
> enum rte_flow_query_update_mode qu_mode,
> struct rte_flow_error *error);
> + /** @see rte_flow_action_list_handle_create() */
> + struct rte_flow_action_list_handle *(*action_list_handle_create)
> + (struct rte_eth_dev *dev,
> + const struct rte_flow_indir_action_conf *conf,
> + const struct rte_flow_action actions[],
> + struct rte_flow_error *error);
> + /** @see rte_flow_action_list_handle_destroy() */
> + int (*action_list_handle_destroy)
> + (struct rte_eth_dev *dev,
> + struct rte_flow_action_list_handle *handle,
> + struct rte_flow_error *error);
> /** See rte_flow_tunnel_decap_set() */
> int (*tunnel_decap_set)
> (struct rte_eth_dev *dev,
> @@ -302,6 +313,36 @@ struct rte_flow_ops {
> const void *update, void *query,
> enum rte_flow_query_update_mode qu_mode,
> void *user_data, struct rte_flow_error *error);
> + /** @see rte_flow_async_action_list_handle_create() */
> + struct rte_flow_action_list_handle *
> + (*async_action_list_handle_create)
> + (struct rte_eth_dev *dev, uint32_t queue_id,
> + const struct rte_flow_op_attr *attr,
> + const struct rte_flow_indir_action_conf *conf,
> + const struct rte_flow_action *actions,
> + void *user_data, struct rte_flow_error *error);
> + /** @see rte_flow_async_action_list_handle_destroy() */
> + int (*async_action_list_handle_destroy)
> + (struct rte_eth_dev *dev, uint32_t queue_id,
> + const struct rte_flow_op_attr *op_attr,
> + struct rte_flow_action_list_handle *action_handle,
> + void *user_data, struct rte_flow_error *error);
> + /** @see rte_flow_action_list_handle_query_update() */
> + int (*action_list_handle_query_update)
> + (struct rte_eth_dev *dev,
> + const struct rte_flow_action_list_handle *handle,
> + const void **update, void **query,
> + enum rte_flow_query_update_mode mode,
> + struct rte_flow_error *error);
> + /** @see rte_flow_async_action_list_handle_query_update() */
> + int (*async_action_list_handle_query_update)
> + (struct rte_eth_dev *dev, uint32_t queue_id,
> + const struct rte_flow_op_attr *attr,
> + const struct rte_flow_action_list_handle *handle,
> + const void **update, void **query,
> + enum rte_flow_query_update_mode mode,
> + void *user_data, struct rte_flow_error *error);
> +
> };
>
> /**
> diff --git a/lib/ethdev/version.map b/lib/ethdev/version.map
> index 357d1a88c0..02372b3a7e 100644
> --- a/lib/ethdev/version.map
> +++ b/lib/ethdev/version.map
> @@ -299,6 +299,14 @@ EXPERIMENTAL {
> rte_flow_action_handle_query_update;
> rte_flow_async_action_handle_query_update;
> rte_flow_async_create_by_index;
> +
> + # added in 23.07
> + rte_flow_action_list_handle_create;
> + rte_flow_action_list_handle_destroy;
> + rte_flow_action_list_handle_query_update;
> + rte_flow_async_action_list_handle_create;
> + rte_flow_async_action_list_handle_destroy;
> + rte_flow_async_action_list_handle_query_update;
> };
>
> INTERNAL {
> --
> 2.34.1
