Domain

mlx5dv_dr_domain_create() creates a DR domain object to be used with mlx5dv_dr_table_create() and mlx5dv_dr_action_create_*().

A domain should be destroyed by calling mlx5dv_dr_domain_destroy() once all depended resources are released.

The device support the following domains types:

MLX5DV_DR_DOMAIN_TYPE_NIC_RX Manage ethernet packets received on the NIC. Packets in this domain can be dropped, dispatched to QP`s, modified or redirected to additional tables inside the domain. Default behavior: Drop packet.

MLX5DV_DR_DOMAIN_TYPE_NIC_TX Manage ethernet packets transmit on the NIC. Packets in this domain can be dropped, modified or redirected to additional tables inside the domain. Default behavior: Forward packet to NIC vport (to eSwitch or wire).

MLX5DV_DR_DOMAIN_TYPE_FDB Manage ethernet packets in the eSwitch Forwarding Data Base for packets received from wire or from any other vport. Packets in this domain can be dropped, dispatched to vport, modified or redirected to additional tables inside the domain. Default behavior: Forward packet to eSwitch manager vport.

mlx5dv_dr_domain_sync() is used in order to flush the rule submission queue. By default, rules in a domain are updated in HW asynchronously. flags should be a set of type enum mlx5dv_dr_domain_sync_flags:

MLX5DV_DR_DOMAIN_SYNC_FLAGS_SW: block until completion of all software queued tasks.

MLX5DV_DR_DOMAIN_SYNC_FLAGS_HW: clear the steering HW cache to enforce next packet hits the latest rules, in addition to the SW SYNC handling.

MLX5DV_DR_DOMAIN_SYNC_FLAGS_MEM: sync device memory to free cached memory.

mlx5dv_dr_domain_set_reclaim_device_memory() is used to enable the reclaiming of device memory back to the system when not in use, by default this feature is disabled.

Table

mlx5dv_dr_table_create() creates a DR table in the domain, at the appropriate level, and can be used with mlx5dv_dr_matcher_create() and mlx5dv_dr_action_create_dest_table(). All packets start traversing the steering domain tree at table level zero (0). Using rule and action, packets can by redirected to other tables in the domain.

A table should be destroyed by calling mlx5dv_dr_table_destroy() once all depended resources are released.

Matcher

mlx5dv_dr_matcher_create() create a matcher object in table, at sorted priority (lower value is check first). A matcher can hold multiple rules, all with identical mask of type struct mlx5dv_flow_match_parameters which represents the exact attributes to be compared by HW steering. The match_criteria_enable and mask are defined in a device spec format. Only the fields that where masked in the matcher should be filled by the rule in mlx5dv_dr_rule_create().

A matcher should be destroyed by calling mlx5dv_dr_matcher_destroy() once all depended resources are released.

Actions

A set of action create API are defined by mlx5dv_dr_action_create_*(). All action are created as struct mlx5dv_dr_action. An action should be destroyed by calling mlx5dv_dr_action_destroy() once all depended rules are destroyed.

When an action handle is reused for multiple rules, the same action will be executed. e.g.: action `count' will count multiple flows rules on the same HW flow counter context. action `drop' will drop packets of different rule from any matcher.

Action: Drop mlx5dv_dr_action_create_drop create a terminating action which drops packets. Can not be mixed with Destination actions.

Action: Default miss mlx5dv_dr_action_create_default_miss create a terminating action which will execute the default behavior based on the domain type.

Action: Tag mlx5dv_dr_action_create_tag creates a non-terminating action which tags packets with tag_value. The tag_value is available in the CQE of the packet received. Valid only on domain type NIC_RX.

Action: Destination mlx5dv_dr_action_create_dest_ibv_qp creates a terminating action delivering the packet to a QP, defined by ibqp. Valid only on domain type NIC_RX. mlx5dv_dr_action_create_dest_table creates a forwarding action to another flow table, defined by table. The destination table must be from the same domain with a level higher than zero. mlx5dv_dr_action_create_dest_vport creates a forwarding action to a vport on the same domain. Valid only on domain type FDB. mlx5dv_dr_action_create_dest_devx_tir creates a terminating action delivering the packet to a TIR, defined by devx_obj. Valid only on domain type NIC_RX.

Action: Array mlx5dv_dr_action_create_dest_array creates an action which replicates a packet to multiple destinations. num_dest defines the number of replication destinations. Each dests destination array entry can be of different type. Use type MLX5DV_DR_ACTION_DEST for direct forwarding to an action destination. Use type MLX5DV_DR_ACTION_DEST_REFORMAT when reformat action should be performed on the packet before it is forwarding to the destination action.

Action: Packet Reformat mlx5dv_dr_action_create_packet_reformat create a packet reformat context and action in the domain. The reformat_type, data_sz and data are defined in man mlx5dv_create_flow_action_packet_reformat.

Action: Modify Header mlx5dv_dr_action_create_modify_header create a modify header context and action in the domain. The actions_sz and actions are defined in man mlx5dv_create_flow_action_modify_header.

Action: Flow Count mlx5dv_dr_action_create_flow_counter creates a flow counter action from a DEVX flow counter object, based on devx_obj and specific counter index from offset in the counter bulk.

Action: ASO mlx5dv_dr_action_create_aso receives a domain pointer and creates an ASO action from the DEVX ASO object, based on devx_obj. Use offset to select the specific ASO object in the devx_obj bulk. DR rules using this action can optionally update the ASO object value according to flags to choose the specific wanted behavior of this object. After a packet hits the rule with the ASO object the value of the ASO object will be copied into the chosen return_reg_c which can be used for match in following DR rules.

mlx5dv_dr_action_modify_aso modifies ASO action action with new values for offset, return_reg_c and flags. Only new DR rules using this action will use the modified values. Existing DR rules do not change the HW action values stored.

flags can be set to one of the types of mlx5dv_dr_action_aso_first_hit_flags or mlx5dv_dr_action_aso_flow_meter_flags: MLX5DV_DR_ACTION_ASO_FIRST_HIT_FLAGS_SET: is used to set the ASO first hit object context, else the context is only copied to the return_reg_c. MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_RED: is used to indicate to update the initial color in ASO flow meter object value to red. MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_YELLOW: is used to indicate to update the initial color in ASO flow meter object value to yellow. MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_GREEN: is used to indicate to update the initial color in ASO flow meter object value to green. MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_UNDEFINED: is used to indicate to update the initial color in ASO flow meter object value to undefined.

Action: Meter mlx5dv_dr_action_create_flow_meter creates a meter action based on the flow meter parameters. The paramertes are according to the device specification. mlx5dv_dr_action_modify_flow_meter modifies existing flow meter action based on modify_field_select. modify_field_select is according to the device specification.

Action: Sampler mlx5dv_dr_action_create_flow_sampler creates a sampler action, allowing us to duplicate and sample a portion of traffic. Packets steered to the sampler action will be sampled with an approximate probability of 1/sample_ratio provided in attr, and sample_actions provided in attr will be executed over them. All original packets will be steered to default_next_table in attr. A modify header format SET_ACTION data can be provided in action of attr, which can be executed on packets before going to default flow table. On some devices, this is required to set register value.

Action Flags: action flags can be set to one of the types of enum mlx5dv_dr_action_flags:

Action: Pop Vlan mlx5dv_dr_action_create_pop_vlan creates a pop vlan action which removes VLAN tags from packets layer 2.

Action: Push Vlan mlx5dv_dr_action_create_push_vlan creates a push vlan action which adds VLAN tags to packets layer 2.

MLX5DV_DR_ACTION_FLAGS_ROOT_LEVEL: is used to indicate the action is targeted for flow table in level=0 (ROOT) of the specific domain.

Rule

mlx5dv_dr_rule_create() creates a HW steering rule entry in matcher. The value of type struct mlx5dv_flow_match_parameters holds the exact attribute values of the steering rule to be matched, in a device spec format. Only the fields that where masked in the matcher should be filled. HW will perform the set of num_actions from the action array of type struct mlx5dv_dr_action, once a packet matches the exact value of the rule (referred to as a `hit').

mlx5dv_dr_rule_destroy() destroys the rule.