.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "MLX5DV_DR API" "3" "2019\-03\-28" "mlx5" "mlx5 Programmer's Manual"
.hy
.SH NAME
.PP
mlx5dv_dr_domain_create, mlx5dv_dr_domain_sync, mlx5dv_dr_domain_destroy
\- Manage flow domains
.PP
mlx5dv_dr_table_create, mlx5dv_dr_table_destroy \- Manage flow tables
.PP
mlx5dv_dr_matcher_create, mlx5dv_dr_matcher_destroy \- Manage flow
matchers
.PP
mlx5dv_dr_rule_create, mlx5dv_dr_rule_destroy \- Manage flow rules
.PP
mlx5dv_dr_action_create_drop \- Create drop action
.PP
mlx5dv_dr_action_create_tag \- Create tag actions
.PP
mlx5dv_dr_action_create_dest_ibv_qp, mlx5dv_dr_action_create_dest_table,
mlx5dv_dr_action_create_dest_vport \- Create packet destination actions
.PP
mlx5dv_dr_action_create_packet_reformat \- Create packet reformat
actions
.PP
mlx5dv_dr_action_create_modify_header \- Create modify header actions
.PP
mlx5dv_dr_action_create_flow_counter \- Create devx flow counter actions
.PP
mlx5dv_dr_action_destroy \- Destroy actions
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <infiniband/mlx5dv.h>

struct\ mlx5dv_dr_domain\ *mlx5dv_dr_domain_create(
\ \ \ \ \ \ \ \ struct\ ibv_context\ *ctx,
\ \ \ \ \ \ \ \ enum\ mlx5dv_dr_domain_type\ type);

int\ mlx5dv_dr_domain_sync(
\ \ \ \ \ \ \ \ struct\ mlx5dv_dr_domain\ *domain,
\ \ \ \ \ \ \ \ uint32_t\ flags);

int\ mlx5dv_dr_domain_destroy(struct\ mlx5dv_dr_domain\ *domain);

struct\ mlx5dv_dr_table\ *mlx5dv_dr_table_create(
\ \ \ \ \ \ \ \ struct\ mlx5dv_dr_domain\ *domain,
\ \ \ \ \ \ \ \ uint32_t\ level);

int\ mlx5dv_dr_table_destroy(struct\ mlx5dv_dr_table\ *table);

struct\ mlx5dv_dr_matcher\ *mlx5dv_dr_matcher_create(
\ \ \ \ \ \ \ \ struct\ mlx5dv_dr_table\ *table,
\ \ \ \ \ \ \ \ uint16_t\ priority,
\ \ \ \ \ \ \ \ uint8_t\ match_criteria_enable,
\ \ \ \ \ \ \ \ struct\ mlx5dv_flow_match_parameters\ *mask);

int\ mlx5dv_dr_matcher_destroy(struct\ mlx5dv_dr_matcher\ *matcher);

struct\ mlx5dv_dr_rule\ *mlx5dv_dr_rule_create(
\ \ \ \ \ \ \ \ struct\ mlx5dv_dr_matcher\ *matcher,
\ \ \ \ \ \ \ \ struct\ mlx5dv_flow_match_parameters\ *value,
\ \ \ \ \ \ \ \ size_t\ num_actions,
\ \ \ \ \ \ \ \ struct\ mlx5dv_dr_action\ *actions[]);

void\ mlx5dv_dr_rule_destroy(struct\ mlx5dv_dr_rule\ *rule);

struct\ mlx5dv_dr_action\ *mlx5dv_dr_action_create_drop(void);

struct\ mlx5dv_dr_action\ *mlx5dv_dr_action_create_tag(
\ \ \ \ \ \ \ \ uint32_t\ tag_value);

struct\ mlx5dv_dr_action\ *mlx5dv_dr_action_create_dest_ibv_qp(
\ \ \ \ \ \ \ \ struct\ ibv_qp\ *ibqp);

struct\ mlx5dv_dr_action\ *mlx5dv_dr_action_create_dest_table(
\ \ \ \ \ \ \ \ struct\ mlx5dv_dr_table\ *table);

struct\ mlx5dv_dr_action\ *mlx5dv_dr_action_create_dest_vport(
\ \ \ \ \ \ \ \ struct\ mlx5dv_dr_domain\ *domain,
\ \ \ \ \ \ \ \ uint32_t\ vport);

struct\ mlx5dv_dr_action\ *mlx5dv_dr_action_create_packet_reformat(
\ \ \ \ \ \ \ \ struct\ mlx5dv_dr_domain\ *domain,
\ \ \ \ \ \ \ \ uint32_t\ flags,
\ \ \ \ \ \ \ \ enum\ mlx5dv_flow_action_packet_reformat_type\ reformat_type,
\ \ \ \ \ \ \ \ size_t\ data_sz,\ void\ *data);

struct\ mlx5dv_dr_action\ *mlx5dv_dr_action_create_modify_header(
\ \ \ \ \ \ \ \ struct\ mlx5dv_dr_domain\ *domain,
\ \ \ \ \ \ \ \ uint32_t\ flags,
\ \ \ \ \ \ \ \ size_t\ actions_sz,
\ \ \ \ \ \ \ \ __be64\ actions[]);

struct\ mlx5dv_dr_action\ *mlx5dv_dr_action_create_flow_counter(
\ \ \ \ \ \ \ \ struct\ mlx5dv_devx_obj\ *devx_obj,
\ \ \ \ \ \ \ \ uint32_t\ offset);

int\ mlx5dv_dr_action_destroy(struct\ mlx5dv_dr_action\ *action);
\f[]
.fi
.SH DESCRIPTION
.PP
The Direct Rule API (mlx5dv_dr_*) allows complete access by verbs
application to the device`s packet steering functionality.
.PP
Steering flow rules are the combination of attributes with a match
pattern and a list of actions.
Rules can have several distinct actions (such as counting,
encapsulating, decapsulating before redirecting packets to a particular
queue or port, etc.).
In order to manage the rule execution order for the packet processing
matching by HW, multiple flow tables in an ordered chain and multiple
flow matchers sorted by priorities are defined.
.SS Domain
.PP
\f[I]mlx5dv_dr_domain_create()\f[] creates a DR domain object to be used
with \f[I]mlx5dv_dr_table_create()\f[] and
\f[I]mlx5dv_dr_action_create_*()\f[].
.PP
A domain should be destroyed by calling
\f[I]mlx5dv_dr_domain_destroy()\f[] once all depended resources are
released.
.PP
The device support the following domains types:
.PP
\f[B]MLX5DV_DR_DOMAIN_TYPE_NIC_RX\f[] 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.
.PP
\f[B]MLX5DV_DR_DOMAIN_TYPE_NIC_TX\f[] 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).
.PP
\f[B]MLX5DV_DR_DOMAIN_TYPE_FDB\f[] 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.
.PP
\f[I]mlx5dv_dr_domain_sync()\f[] is used in order to flush the rule
submission queue.
By default, rules in a domain are updated in HW asynchronously.
\f[B]flags\f[] should be a set of type \f[I]enum
mlx5dv_dr_domain_sync_flags\f[]:
.PP
\f[B]MLX5DV_DR_DOMAIN_SYNC_FLAGS_SW\f[]: block until completion of all
software queued tasks.
.PP
\f[B]MLX5DV_DR_DOMAIN_SYNC_FLAGS_HW\f[]: clear the steering HW cache to
enforce next packet hits the latest rules, in addition to the SW SYNC
handling.
.SS Table
.PP
\f[I]mlx5dv_dr_table_create()\f[] creates a DR table in the
\f[B]domain\f[], at the appropriate \f[B]level\f[], and can be used with
\f[I]mlx5dv_dr_matcher_create()\f[] and
\f[I]mlx5dv_dr_action_create_dest_table()\f[].
All packets start traversing the steering domain tree at table
\f[B]level\f[] zero (0).
Using rule and action, packets can by redirected to other tables in the
domain.
.PP
A table should be destroyed by calling
\f[I]mlx5dv_dr_table_destroy()\f[] once all depended resources are
released.
.SS Matcher
.PP
\f[I]mlx5dv_dr_matcher_create()\f[] create a matcher object in
\f[B]table\f[], at sorted \f[B]priority\f[] (lower value is check
first).
A matcher can hold multiple rules, all with identical \f[B]mask\f[] of
type \f[I]struct mlx5dv_flow_match_parameters\f[] which represents the
exact attributes to be compared by HW steering.
The \f[B]match_criteria_enable\f[] and \f[B]mask\f[] are defined in a
device spec format.
Only the fields that where masked in the \f[I]matcher\f[] should be
filled by the rule in \f[I]mlx5dv_dr_rule_create()\f[].
.PP
A matcher should be destroyed by calling
\f[I]mlx5dv_dr_matcher_destroy()\f[] once all depended resources are
released.
.SS Actions
.PP
A set of action create API are defined by
\f[I]mlx5dv_dr_action_create_*()\f[].
All action are created as \f[I]struct mlx5dv_dr_action\f[].
An action should be destroyed by calling
\f[I]mlx5dv_dr_action_destroy()\f[] once all depended rules are
destroyed.
.PP
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.
.PP
Action: Drop \f[I]mlx5dv_dr_action_create_drop\f[] create a terminating
action which drops packets.
Can not be mixed with Destination actions.
.PP
Action: Tag \f[I]mlx5dv_dr_action_create_tag\f[] creates a
non\-terminating action which tags packets with \f[B]tag_value\f[].
The \f[B]tag_value\f[] is available in the CQE of the packet received.
Valid only on domain type NIC_RX.
.PP
Action: Destination \f[I]mlx5dv_dr_action_create_dest_ibv_qp\f[] creates
a terminating action delivering the packet to a QP, defined by
\f[B]ibqp\f[].
Valid only on domain type NIC_RX.
\f[I]mlx5dv_dr_action_create_dest_table\f[] creates a forwarding action
to another flow table, defined by \f[B]table\f[].
The destination \f[B]table\f[] must be from the same domain with a level
higher than zero.
\f[I]mlx5dv_dr_action_create_dest_vport\f[] creates a forwarding action
to a \f[B]vport\f[] on the same \f[B]domain\f[].
Valid only on domain type FDB.
.PP
Action: Packet Reformat \f[I]mlx5dv_dr_action_create_packet_reformat\f[]
create a packet reformat context and action in the \f[B]domain\f[].
The \f[B]reformat_type\f[], \f[B]data_sz\f[] and \f[B]data\f[] are
defined in \f[I]man mlx5dv_create_flow_action_packet_reformat\f[].
.PP
Action: Modify Header \f[I]mlx5dv_dr_action_create_modify_header\f[]
create a modify header context and action in the \f[B]domain\f[].
The \f[B]actions_sz\f[] and \f[B]actions\f[] are defined in \f[I]man
mlx5dv_create_flow_action_modify_header\f[].
.PP
Action: Flow Count \f[I]mlx5dv_dr_action_create_flow_counter\f[] creates
a flow counter action from a DEVX flow counter object, based on
\f[B]devx_obj\f[] and specific counter index from \f[B]offset\f[] in the
counter bulk.
.PP
Action Flags: action \f[B]flags\f[] can be set to one of the types of
\f[I]enum mlx5dv_dr_action_flags\f[]:
.PP
\f[B]MLX5DV_DR_ACTION_FLAGS_ROOT_LEVEL\f[]: is used to indicate the
action is targeted for flow table in level=0 (ROOT) of the specific
domain.
.SS Rule
.PP
\f[I]mlx5dv_dr_rule_create()\f[] creates a HW steering rule entry in
\f[B]matcher\f[].
The \f[B]value\f[] of type \f[I]struct mlx5dv_flow_match_parameters\f[]
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 \f[I]matcher\f[] should be
filled.
HW will perform the set of \f[B]num_actions\f[] from the \f[B]action\f[]
array of type \f[I]struct mlx5dv_dr_action\f[], once a packet matches
the exact \f[B]value\f[] of the rule (referred to as a `hit').
.PP
\f[I]mlx5dv_dr_rule_destroy()\f[] destroys the rule.
.SH RETURN VALUE
.PP
The create API calls will return a pointer to the relevant object:
table, matcher, action, rule.
on failure, NULL will be returned and errno will be set.
.PP
The destroy API calls will returns 0 on success, or the value of errno
on failure (which indicates the failure reason).
.SH LIMITATIONS
.PP
Application can verify is a feature is supported by \f[I]trail and
error\f[].
No capabilities are exposed, as the combination of all the options
exposed are way to large to define.
.PP
Tables are size less by definition.
They are expected to grow and shrink to accommodate for all rules,
according to driver capabilities.
Once reaching a limit, an error is returned.
.PP
Matchers in same priority, in the same table, will have undefined
ordered.
.PP
A rule with identical value pattern to another rule on a given matcher
are rejected.
.PP
IP version in matcher mask and rule should be equal and set to 4, 6 or
0.
# SEE ALSO
.PP
\f[B]mlx5dv_open_device(3)\f[],
\f[B]mlx5dv_create_flow_action_packet_reformat(3)\f[],
\f[B]mlx5dv_create_flow_action_modify_header(3)\f[].
.SH AUTHOR
.PP
Alex Rosenbaum <alexr@mellanox.com> Alex Vesker <valex@mellanox.com>