[dpdk-dev] app/testpmd: [RFC] Create flex item object

[dpdk-dev] app/testpmd: [RFC] Create flex item object

[Gregory Etelson]

app/testpmd: [RFC] Create flex item object

RTE flex item infrastructure allows application to create a parser for
custom network header in port hardware and offload flow rules to match
the custom protocol elements. RTE flex item API was introduced in
https://patchwork.dpdk.org/project/dpdk/patch/20210806085624.16497-1-viacheslavo@nvidia.com/

Application must create RTE flex item object before it can offload
flow rules to match custom header elements.  RTE flex item object
references custom hardware parser. Custom flex parser object is built
according to configuration that describes the custom header.
Flex item configuration building blocks are:
- New header length, fixed or variable, depending on the protocol.
- Network headers that precede and follow the new header and
  transition conditions.
- Offset and size of header samples that can be referenced in flex
  flow item for match.

Testpmd could create a new flex item object in several ways.
The following examples will use fixed size IPv4 header.

1. External configuration file.
Flex item configuration is stored in external data file in JSON format.
Testpmd flex item `create` and `modify` commands read the configuration
file into JSON object, parse the object and assign
configuration structure members according to parsing results.
Assumed, that the test application will not modify file data.
Different data file will be used to modify existing flex item.

Example:
Configuration:
{
  "next_header": { "field_mode": "FIELD_MODE_FIXED", "field_size": 20},
  "next_protocol": {"field_size": 8, "field_base": 72},
  "sample_data": [
    { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 0},
    { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 32},
    { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 64},
    { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 96}
  ],
  "input_link": [
   {"item": "eth type is 0x0800"},
   {"item": "vlan inner_type is 0x0800"}
  ],
  "output_link": [
   {"item": "udp", "next": 17},
   {"item": "tcp", "next": 6},
   {"item": "icmp", "next": 1}
  ]
}

testpmd> flow flex_item create <port> <flex_id> <config filename>
testpmd> flow flex_item {modify|destroy} <port> <flex_id>

Flex item ID is selected and maintained by testpmd operator,
like TOKEN in raw_decap/raw_encap commands.

Pros:
- One configuration file can be used by different ports to create flex
  items.
- Single CLI command creates flex item.
- JSON input file format can be parsed with existing jansson library.

Cons:
- Flex item configuration is in external file.

2. CLI commands with JSON data.
General testpmd flex command syntax is:
testpmd> flow flex_item <command>  <port_id> <flex_id> [optional args]
<port_id> - port index to operate on
<flex_id> - flex_item index to operate on (per port, the same index on
            diff ports means diff objects).
            Flex ID index is selected and maintained by testpmd operator,
            like TOKEN in raw_decap/raw_encap commands.
<command>
  init - resets the configuration that will be used to create/update
         the object
  create - creates the flex_item object on specified port with
           specified config
  modify - updates the flex_item object on specified port with
           specified config
  release - destroys the flex_item object on port
  field - adds field desc to conf
  link - adds link desc to conf
Optional arguments describe flex field or link parameters in JSON
format.  JSON format was selected to restrict flex item tokens parsing
to flex module only.

Example:
testpmd> flow flex_item init <port_id> <flex_id>
testpmd> flow flex_item field <port_id> <flex_id> {"next_header": { "field_mode": "FIELD_MODE_FIXED", "field_size": 20}}
testpmd> flow flex_item field <port_id> <flex_id> {"next_protocol": {"field_size": 8, "field_base": 72}}
testpmd> flow flex_item field <port_id> <flex_id> {"index":0, "sample_data": { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 0  }}
testpmd> flow flex_item field <port_id> <flex_id> {"index":1, "sample_data": { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 32 }}
testpmd> flow flex_item field <port_id> <flex_id> {"index":2, "sample_data": { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 64 }}
testpmd> flow flex_item field <port_id> <flex_id> {"index":3, "sample_data": { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 96 }}
testpmd> flow flex_item link <port_id> <flex_id> {"index":0, "input_link": {"item": "eth type is 0x0800" }}
testpmd> flow flex_item link <port_id> <flex_id> {"index":1, "input_link": {"item": "vlan inner_type is 0x0800" }}
testpmd> flow flex_item link <port_id> <flex_id> {"index":0, "output_link": {"item": "udp", "next": 17 }}
testpmd> flow flex_item link <port_id> <flex_id> {"index":1, "output_link": {"item": "tcp", "next": 6 }}
testpmd> flow flex_item link <port_id> <flex_id> {"index":2, "output_link": {"item": "icmp", "next": 1 }}
testpmd> flow flex_item create <port_id> <flex_id>

Pros:
- No external configuration file.
- Flex data in JSON format does not add multiple tokens to global
  token_list array.

Cons:
- Multiple CLI commands to create flex item.
- Commands must be repeated for each port.
- Index key added to sample and link arrays.
- No completion for JSON data.

3. CLI commands, no JSON
This method works with built-in DPDK cmdline parser.

Example:
testpmd> set flex_field 0 field_mode FIELD_MODE_FIXED field_size 20
testpmd> set flex_field 1 field_size 8 field_base 72
testpmd> set flex_field 2 index 0 field_mode FIELD_MODE_FIXED field_size 32 field_base 0
testpmd> set flex_field 3 index 1 field_mode FIELD_MODE_FIXED field_size 32 field_base 32
testpmd> set flex_field 4 index 2 field_mode FIELD_MODE_FIXED field_size 32 field_base 64
testpmd> set flex_field 5 index 3 field_mode FIELD_MODE_FIXED field_size 32 field_base 96
testpmd> set flex_link 0 index 0 item "eth type is 0x0800"
testpmd> set flex_link 1 index 1 item "eth type is 0x0800"
testpmd> set flex_link 2 index 0 item "udp" next 17
testpmd> set flex_link 3 index 1 item "tcp" next 6
testpmd> set flex_link 3 index 1 item "icmp" next 1
testpmd> flow flex_item init <port> <flex_id>
testpmd> flow flex_item add <port> <flex_id> field 0
testpmd> flow flex_item add <port> <flex_id> field 1
testpmd> flow flex_item add <port> <flex_id> sample 2
testpmd> flow flex_item add <port> <flex_id> sample 3
testpmd> flow flex_item add <port> <flex_id> sample 4
testpmd> flow flex_item add <port> <flex_id> sample 5
testpmd> flow flex_item add <port> <flex_id> link in 0
testpmd> flow flex_item add <port> <flex_id> link in 1
testpmd> flow flex_item add <port> <flex_id> link out 2
testpmd> flow flex_item add <port> <flex_id> link out 3
testpmd> flow flex_item add <port> <flex_id> link out 4
testpmd> flow flex_item create <port_id> <flex_id>

Pros:
- cmdline parser only.
- Full command completion.

Cons:
- Even more CLI commands.
- `flow flex_item` commands must be repeated for each port.
- Multiple tokens required to maintain this structure.
- Multiple indirect index usage can lead to mistakes.

Method number 1 - External configuration file, requires less resources
and is preferable for implementation.

Testpmd can utilize additional patch to split flex item commands into
multiple lines.

Signed-off-by: Gregory Etelson getelson@nvidia.com<mailto:getelson@nvidia.com>