1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448
|
.\" Automatically generated by Pandoc 2.5
.\"
.TH "MLX5DV_DR API" "3" "2019\-03\-28" "mlx5" "mlx5 Programmer\[cq]s Manual"
.hy
.SH NAME
.PP
mlx5dv_dr_domain_create, mlx5dv_dr_domain_sync,
mlx5dv_dr_domain_destroy, mlx5dv_dr_domain_set_reclaim_device_memory \-
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_default_miss \- Create default miss 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,
mlx5dv_dr_action_create_dest_devx_tir \- Create packet destination
actions
.PP
mlx5dv_dr_action_create_dest_array \- Create destination array action
.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_create_aso, mlx5dv_dr_action_modify_aso \- Create and
modify ASO actions
.PP
mlx5dv_dr_action_create_flow_meter, mlx5dv_dr_action_modify_flow_meter
\- Create and modify meter action
.PP
mlx5dv_dr_action_create_flow_sampler \- Create flow sampler action
.PP
mlx5dv_dr_action_create_pop_vlan \- Create pop vlan action
.PP
mlx5dv_dr_action_create_push_vlan\- Create push vlan action
.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);
void mlx5dv_dr_domain_set_reclaim_device_memory(
struct mlx5dv_dr_domain *dmn,
bool enable);
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_default_miss(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_dest_devx_tir(
struct mlx5dv_devx_obj *devx_obj);
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);
struct mlx5dv_dr_action *
mlx5dv_dr_action_create_aso(struct mlx5dv_dr_domain *domain,
struct mlx5dv_devx_obj *devx_obj,
uint32_t offset,
uint32_t flags,
uint8_t return_reg_c);
int mlx5dv_dr_action_modify_aso(struct mlx5dv_dr_action *action,
uint32_t offset,
uint32_t flags,
uint8_t return_reg_c);
struct mlx5dv_dr_action *
mlx5dv_dr_action_create_flow_meter(struct mlx5dv_dr_flow_meter_attr *attr);
int mlx5dv_dr_action_modify_flow_meter(struct mlx5dv_dr_action *action,
struct mlx5dv_dr_flow_meter_attr *attr,
__be64 modify_field_select);
struct mlx5dv_dr_action *
mlx5dv_dr_action_create_flow_sampler(struct mlx5dv_dr_flow_sampler_attr *attr);
struct mlx5dv_dr_action *
mlx5dv_dr_action_create_dest_array(struct mlx5dv_dr_domain *domain,
size_t num_dest,
struct mlx5dv_dr_action_dest_attr *dests[]);
struct mlx5dv_dr_action *mlx5dv_dr_action_create_pop_vlan(void);
struct mlx5dv_dr_action *mlx5dv_dr_action_create_push_vlan(
struct mlx5dv_dr_domain *dmn,
__be32 vlan_hdr)
int mlx5dv_dr_action_destroy(struct mlx5dv_dr_action *action);
\f[R]
.fi
.SH DESCRIPTION
.PP
The Direct Rule API (mlx5dv_dr_*) allows complete access by verbs
application to the device\[ga]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[R] creates a DR domain object to be
used with \f[I]mlx5dv_dr_table_create()\f[R] and
\f[I]mlx5dv_dr_action_create_*()\f[R].
.PP
A domain should be destroyed by calling
\f[I]mlx5dv_dr_domain_destroy()\f[R] once all depended resources are
released.
.PP
The device support the following domains types:
.PP
\f[B]MLX5DV_DR_DOMAIN_TYPE_NIC_RX\f[R] Manage ethernet packets received
on the NIC.
Packets in this domain can be dropped, dispatched to QP\[ga]s, modified
or redirected to additional tables inside the domain.
Default behavior: Drop packet.
.PP
\f[B]MLX5DV_DR_DOMAIN_TYPE_NIC_TX\f[R] 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[R] 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[R] 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[R] should be a set of type \f[I]enum
mlx5dv_dr_domain_sync_flags\f[R]:
.PP
\f[B]MLX5DV_DR_DOMAIN_SYNC_FLAGS_SW\f[R]: block until completion of all
software queued tasks.
.PP
\f[B]MLX5DV_DR_DOMAIN_SYNC_FLAGS_HW\f[R]: clear the steering HW cache to
enforce next packet hits the latest rules, in addition to the SW SYNC
handling.
.PP
\f[B]MLX5DV_DR_DOMAIN_SYNC_FLAGS_MEM\f[R]: sync device memory to free
cached memory.
.PP
\f[I]mlx5dv_dr_domain_set_reclaim_device_memory()\f[R] is used to enable
the reclaiming of device memory back to the system when not in use, by
default this feature is disabled.
.SS Table
.PP
\f[I]mlx5dv_dr_table_create()\f[R] creates a DR table in the
\f[B]domain\f[R], at the appropriate \f[B]level\f[R], and can be used
with \f[I]mlx5dv_dr_matcher_create()\f[R] and
\f[I]mlx5dv_dr_action_create_dest_table()\f[R].
All packets start traversing the steering domain tree at table
\f[B]level\f[R] 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[R] once all depended resources are
released.
.SS Matcher
.PP
\f[I]mlx5dv_dr_matcher_create()\f[R] create a matcher object in
\f[B]table\f[R], at sorted \f[B]priority\f[R] (lower value is check
first).
A matcher can hold multiple rules, all with identical \f[B]mask\f[R] of
type \f[I]struct mlx5dv_flow_match_parameters\f[R] which represents the
exact attributes to be compared by HW steering.
The \f[B]match_criteria_enable\f[R] and \f[B]mask\f[R] are defined in a
device spec format.
Only the fields that where masked in the \f[I]matcher\f[R] should be
filled by the rule in \f[I]mlx5dv_dr_rule_create()\f[R].
.PP
A matcher should be destroyed by calling
\f[I]mlx5dv_dr_matcher_destroy()\f[R] 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[R].
All action are created as \f[I]struct mlx5dv_dr_action\f[R].
An action should be destroyed by calling
\f[I]mlx5dv_dr_action_destroy()\f[R] 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[R] create a terminating
action which drops packets.
Can not be mixed with Destination actions.
.PP
Action: Default miss \f[I]mlx5dv_dr_action_create_default_miss\f[R]
create a terminating action which will execute the default behavior
based on the domain type.
.PP
Action: Tag \f[I]mlx5dv_dr_action_create_tag\f[R] creates a
non\-terminating action which tags packets with \f[B]tag_value\f[R].
The \f[B]tag_value\f[R] 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[R]
creates a terminating action delivering the packet to a QP, defined by
\f[B]ibqp\f[R].
Valid only on domain type NIC_RX.
\f[I]mlx5dv_dr_action_create_dest_table\f[R] creates a forwarding action
to another flow table, defined by \f[B]table\f[R].
The destination \f[B]table\f[R] must be from the same domain with a
level higher than zero.
\f[I]mlx5dv_dr_action_create_dest_vport\f[R] creates a forwarding action
to a \f[B]vport\f[R] on the same \f[B]domain\f[R].
Valid only on domain type FDB.
\f[I]mlx5dv_dr_action_create_dest_devx_tir\f[R] creates a terminating
action delivering the packet to a TIR, defined by \f[B]devx_obj\f[R].
Valid only on domain type NIC_RX.
.PP
Action: Array \f[I]mlx5dv_dr_action_create_dest_array\f[R] creates an
action which replicates a packet to multiple destinations.
\f[B]num_dest\f[R] defines the number of replication destinations.
Each \f[B]dests\f[R] destination array entry can be of different
\f[B]type\f[R].
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.
.PP
Action: Packet Reformat
\f[I]mlx5dv_dr_action_create_packet_reformat\f[R] create a packet
reformat context and action in the \f[B]domain\f[R].
The \f[B]reformat_type\f[R], \f[B]data_sz\f[R] and \f[B]data\f[R] are
defined in \f[I]man mlx5dv_create_flow_action_packet_reformat\f[R].
.PP
Action: Modify Header \f[I]mlx5dv_dr_action_create_modify_header\f[R]
create a modify header context and action in the \f[B]domain\f[R].
The \f[B]actions_sz\f[R] and \f[B]actions\f[R] are defined in \f[I]man
mlx5dv_create_flow_action_modify_header\f[R].
.PP
Action: Flow Count \f[I]mlx5dv_dr_action_create_flow_counter\f[R]
creates a flow counter action from a DEVX flow counter object, based on
\f[B]devx_obj\f[R] and specific counter index from \f[B]offset\f[R] in
the counter bulk.
.PP
Action: ASO \f[I]mlx5dv_dr_action_create_aso\f[R] receives a
\f[B]domain\f[R] pointer and creates an ASO action from the DEVX ASO
object, based on \f[B]devx_obj\f[R].
Use \f[B]offset\f[R] to select the specific ASO object in the
\f[B]devx_obj\f[R] bulk.
DR rules using this action can optionally update the ASO object value
according to \f[B]flags\f[R] 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 \f[B]return_reg_c\f[R] which can
be used for match in following DR rules.
.PP
\f[I]mlx5dv_dr_action_modify_aso\f[R] modifies ASO action
\f[B]action\f[R] with new values for \f[B]offset\f[R],
\f[B]return_reg_c\f[R] and \f[B]flags\f[R].
Only new DR rules using this \f[B]action\f[R] will use the modified
values.
Existing DR rules do not change the HW action values stored.
.PP
\f[B]flags\f[R] can be set to one of the types of
\f[I]mlx5dv_dr_action_aso_first_hit_flags\f[R] or
\f[I]mlx5dv_dr_action_aso_flow_meter_flags\f[R]:
\f[B]MLX5DV_DR_ACTION_ASO_FIRST_HIT_FLAGS_SET\f[R]: is used to set the
ASO first hit object context, else the context is only copied to the
return_reg_c.
\f[B]MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_RED\f[R]: is used to indicate
to update the initial color in ASO flow meter object value to red.
\f[B]MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_YELLOW\f[R]: is used to
indicate to update the initial color in ASO flow meter object value to
yellow.
\f[B]MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_GREEN\f[R]: is used to
indicate to update the initial color in ASO flow meter object value to
green.
\f[B]MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_UNDEFINED\f[R]: is used to
indicate to update the initial color in ASO flow meter object value to
undefined.
.PP
Action: Meter \f[I]mlx5dv_dr_action_create_flow_meter\f[R] creates a
meter action based on the flow meter parameters.
The paramertes are according to the device specification.
\f[I]mlx5dv_dr_action_modify_flow_meter\f[R] modifies existing flow
meter \f[B]action\f[R] based on \f[B]modify_field_select\f[R].
\f[B]modify_field_select\f[R] is according to the device specification.
.PP
Action: Sampler \f[I]mlx5dv_dr_action_create_flow_sampler\f[R] 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 \f[B]attr\f[R],
and sample_actions provided in \f[B]attr\f[R] will be executed over
them.
All original packets will be steered to default_next_table in
\f[B]attr\f[R].
A modify header format SET_ACTION data can be provided in action of
\f[B]attr\f[R], which can be executed on packets before going to default
flow table.
On some devices, this is required to set register value.
.PP
Action Flags: action \f[B]flags\f[R] can be set to one of the types of
\f[I]enum mlx5dv_dr_action_flags\f[R]:
.PP
Action: Pop Vlan \f[I]mlx5dv_dr_action_create_pop_vlan\f[R] creates a
pop vlan action which removes VLAN tags from packets layer 2.
.PP
Action: Push Vlan \f[I]mlx5dv_dr_action_create_push_vlan\f[R] creates a
push vlan action which adds VLAN tags to packets layer 2.
.PP
\f[B]MLX5DV_DR_ACTION_FLAGS_ROOT_LEVEL\f[R]: 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[R] creates a HW steering rule entry in
\f[B]matcher\f[R].
The \f[B]value\f[R] of type \f[I]struct
mlx5dv_flow_match_parameters\f[R] 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[R] should be
filled.
HW will perform the set of \f[B]num_actions\f[R] from the
\f[B]action\f[R] array of type \f[I]struct mlx5dv_dr_action\f[R], once a
packet matches the exact \f[B]value\f[R] of the rule (referred to as a
`hit').
.PP
\f[I]mlx5dv_dr_rule_destroy()\f[R] 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[R].
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[R],
\f[B]mlx5dv_create_flow_action_packet_reformat(3)\f[R],
\f[B]mlx5dv_create_flow_action_modify_header(3)\f[R].
.SH AUTHOR
.PP
Alex Rosenbaum <alexr@mellanox.com> Alex Vesker <valex@mellanox.com>
|