Re: [PATCH v6] ethdev: add template table resize API

[Thomas Monjalon <thomas@monjalon.net>]

12/02/2024 19:12, Gregory Etelson:
> --- a/doc/guides/howto/rte_flow.rst
> +++ b/doc/guides/howto/rte_flow.rst
> +Template API resizable table
> +----------------------------
> +
> +Description
> +~~~~~~~~~~~
> +
> +The resizable template table API enables applications to dynamically adjust
> +capacity of template tables without disrupting the existing flows operation.
> +The resizable template table API allows applications to optimize the memory
> +usage and performance of template tables according to the traffic conditions
> +and requirements.
> +
> +A typical use case for the resizable template table API:
> +
> +  1. Create a resizable table with the initial capacity.
> +
> +  2. Change the table flows capacity.
> +
> +  3. Update table flows.

Isn't "flow rules" more appropriate than "flows"?

> +
> +  4. Complete the table resize.
> +
> +A resizable table can be ether in the normal or the resizable state.

s/ether/either/
drop "the"

> +When application begins to resize the table, it state is changed from

s/it/its/

> +the normal to resizable.

to resizable state. (no need from)

> +When application finishes resizing the table, the table state returns to
> +the normal state.

simpler:
until the application finishes the resize procedure.

> +Application can resize a table in the normal state only.
> +
> +Application needs to set the ``RTE_FLOW_TABLE_SPECIALIZE_RESIZABLE`` bit in
> +the table attributes when creating a template table that can be resized.
> +A table cannot be converted to resizable if it was created without the
> +``RTE_FLOW_TABLE_SPECIALIZE_RESIZABLE`` bit.

Redundant

> +A resizable table cannot be converted to non-resizable.
> +
> +Application triggers the table resize by calling
> +the ``rte_flow_template_table_resize()`` function. The resize process updates
> +the table configuration to fit the new flows capacity.

flows or flow rules?

> +Table resize does not change existing flows configuration.
> +Application can create new flows and modify or delete existing flows

flow rules

> +while the table is resizing, but the table performance might be
> +slower than usual.
> +
> +Flows that existed before table resize are fully functional after table resize.
> +However, application needs to update these flows to match the new table
> +configuration.

This part is not clear.
The rules are functional but needs to be updated. Why?

> +Application calls the ``rte_flow_async_update_resized()`` to update flow
> +resources for the new table configuration.
> +Flows created after table resize match new table configuration.
> +Application can track flows that need post-resize update or it can update all
> +existing flows. ``rte_flow_async_update_resized()`` returns success for flows
> +that were created after table resize.
> +
> +Application calls ``rte_flow_template_table_resize_complete()`` to return a
> +table to the normal state after it completed flows update.
> +
> +Testpmd commands (wrapped for clarity)::
> +
> +  # 1. Create resizable template table for 1 flow.
> +  testpmd> flow pattern_template 0 create ingress pattern_template_id 3
> +                template eth / ipv4 / udp src mask 0xffff / end
> +  testpmd> flow actions_template 0 create ingress actions_template_id 7
> +                template count  / rss / end
> +  testpmd> flow template_table 0 create table_id 101 resizable ingress
> +                group 1 priority 0 rules_number 1
> +                pattern_template 3 actions_template 7
> +
> +  # 2. Queue a flow rule.
> +  testpmd> flow queue 0 create 0 template_table 101
> +                pattern_template 0 actions_template 0 postpone no
> +                pattern eth / ipv4 / udp src spec 1 / end actions count / rss / end
> +
> +  # 3. Resize the template table
> +  #    The new table capacity is 32 rules
> +  testpmd> flow template_table 0 resize table_resize_id 101
> +                table_resize_rules_num 32
> +
> +  # 4. Queue more flow rules.
> +  testpmd> flow queue 0 create 0 template_table 101
> +                pattern_template 0 actions_template 0 postpone no
> +                pattern eth / ipv4 / udp src spec 2 / end actions count / rss / end
> +  testpmd> flow queue 0 create 0 template_table 101
> +                pattern_template 0 actions_template 0 postpone no
> +                pattern eth / ipv4 / udp src spec 3 / end actions count / rss / end
> +  testpmd> flow queue 0 create 0 template_table 101
> +                pattern_template 0 actions_template 0 postpone no
> +                pattern eth / ipv4 / udp src spec 4 / end actions count / rss / end
> +
> +  # 5. Queue the initial flow update.
> +  testpmd> flow queue 0 update_resized 0 rule 0
> +
> +  # 6. Complete the table resize.
> +  testpmd> flow template_table 0 resize_complete table 101
> diff --git a/doc/guides/rel_notes/release_24_03.rst b/doc/guides/rel_notes/release_24_03.rst
> index 6f8ad27808..9d5115ed96 100644
> --- a/doc/guides/rel_notes/release_24_03.rst
> +++ b/doc/guides/rel_notes/release_24_03.rst
> @@ -55,6 +55,18 @@ New Features
>       Also, make sure to start the actual text at the margin.
>       =======================================================
>  
> +* **Added  API to change template table flows capacity.**
> +
> +  * ``RTE_FLOW_TABLE_SPECIALIZE_RESIZABLE_TABLE`` table configuration bit.
> +    Set when template template must be created with the resizable property.
> +  * ``rte_flow_template_table_resizable()``.
> +    Query wheather template table can be resized.

whether

> +  * ``rte_flow_template_table_resize()``.
> +    Reconfigure template table for new flows capacity.
> +  * ``rte_flow_async_update_resized()``.
> +    Reconfigure flows for the updated table configuration.
> +  * ``rte_flow_template_table_resize_complete()``.
> +    Complete table resize.
[...]
> --- a/lib/ethdev/rte_flow.h
> +++ b/lib/ethdev/rte_flow.h
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Update flow for the new template table configuration after table resize.
> + * Can be called for *rule* created before and after *table* resize.

I feel we need to explain why it has to be called.

> + *
> + * @param port_id
> + *   Port identifier of Ethernet device.
> + * @param queue
> + *   Flow queue for async operation.
> + * @param attr
> + *   Async operation attributes.
> + * @param rule
> + *   Flow rule to update.
> + * @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 *table* was not resized.
> + *               If *rule* cannot be updated after *table* resize,
> + *               unrecoverable *table* error.
> + */
> +__rte_experimental
> +int
> +rte_flow_async_update_resized(uint16_t port_id, uint32_t queue,
> +			      const struct rte_flow_op_attr *attr,
> +			      struct rte_flow *rule, void *user_data,
> +			      struct rte_flow_error *error);
> +