1MLX5DV_DR API(3) mlx5 Programmer’s Manual MLX5DV_DR API(3)
2
6 mlx5dv_dr_domain_create, mlx5dv_dr_domain_sync, mlx5dv_dr_domain_de‐
7 stroy, mlx5dv_dr_domain_set_reclaim_device_memory, mlx5dv_dr_domain_al‐
8 low_duplicate_rules - Manage flow domains
9 mlx5dv_dr_table_create, mlx5dv_dr_table_destroy - Manage flow tables
11 mlx5dv_dr_matcher_create, mlx5dv_dr_matcher_destroy, mlx5dv_dr_match‐
13 er_set_layout - Manage flow matchers
14 mlx5dv_dr_rule_create, mlx5dv_dr_rule_destroy - Manage flow rules
16 mlx5dv_dr_action_create_drop - Create drop action
18 mlx5dv_dr_action_create_default_miss - Create default miss action
20 mlx5dv_dr_action_create_tag - Create tag actions
22 mlx5dv_dr_action_create_dest_ibv_qp - Create packet destination QP ac‐
24 tion
25 mlx5dv_dr_action_create_dest_table - Create packet destination dr table
27 action
28 mlx5dv_dr_action_create_dest_root_table - Create packet destination
30 root table action
31 mlx5dv_dr_action_create_dest_vport - Create packet destination vport
33 action
34 mlx5dv_dr_action_create_dest_ib_port - Create packet destination IB
36 port action
37 mlx5dv_dr_action_create_dest_devx_tir - Create packet destination TIR
39 action
40 mlx5dv_dr_action_create_dest_array - Create destination array action
42 mlx5dv_dr_action_create_packet_reformat - Create packet reformat ac‐
44 tions
45 mlx5dv_dr_action_create_modify_header - Create modify header actions
47 mlx5dv_dr_action_create_flow_counter - Create devx flow counter actions
49 mlx5dv_dr_action_create_aso, mlx5dv_dr_action_modify_aso - Create and
51 modify ASO actions
52 mlx5dv_dr_action_create_flow_meter, mlx5dv_dr_action_modify_flow_meter
54 - Create and modify meter action
55 mlx5dv_dr_action_create_flow_sampler - Create flow sampler action
57 mlx5dv_dr_action_create_pop_vlan - Create pop vlan action
59 mlx5dv_dr_action_create_push_vlan- Create push vlan action
61 mlx5dv_dr_action_destroy - Destroy actions
63 mlx5dv_dr_aso_other_domain_link, mlx5dv_dr_aso_other_domain_unlink -
65 link/unlink ASO devx object to work with different domains
66
68 #include <infiniband/mlx5dv.h>
69 struct mlx5dv_dr_domain *mlx5dv_dr_domain_create(
71 struct ibv_context *ctx,
72 enum mlx5dv_dr_domain_type type);
73 int mlx5dv_dr_domain_sync(
75 struct mlx5dv_dr_domain *domain,
76 uint32_t flags);
77 int mlx5dv_dr_domain_destroy(struct mlx5dv_dr_domain *domain);
79 void mlx5dv_dr_domain_set_reclaim_device_memory(
81 struct mlx5dv_dr_domain *dmn,
82 bool enable);
83 void mlx5dv_dr_domain_allow_duplicate_rules(struct mlx5dv_dr_domain *dmn, bool allow);
85 struct mlx5dv_dr_table *mlx5dv_dr_table_create(
87 struct mlx5dv_dr_domain *domain,
88 uint32_t level);
89 int mlx5dv_dr_table_destroy(struct mlx5dv_dr_table *table);
91 struct mlx5dv_dr_matcher *mlx5dv_dr_matcher_create(
93 struct mlx5dv_dr_table *table,
94 uint16_t priority,
95 uint8_t match_criteria_enable,
96 struct mlx5dv_flow_match_parameters *mask);
97 int mlx5dv_dr_matcher_destroy(struct mlx5dv_dr_matcher *matcher);
99 int mlx5dv_dr_matcher_set_layout(struct mlx5dv_dr_matcher *matcher, struct mlx5dv_dr_matcher_layout *matcher_layout);
102 struct mlx5dv_dr_rule *mlx5dv_dr_rule_create(
104 struct mlx5dv_dr_matcher *matcher,
105 struct mlx5dv_flow_match_parameters *value,
106 size_t num_actions,
107 struct mlx5dv_dr_action *actions[]);
108 void mlx5dv_dr_rule_destroy(struct mlx5dv_dr_rule *rule);
110 struct mlx5dv_dr_action *mlx5dv_dr_action_create_drop(void);
112 struct mlx5dv_dr_action *mlx5dv_dr_action_create_default_miss(void);
114 struct mlx5dv_dr_action *mlx5dv_dr_action_create_tag(
116 uint32_t tag_value);
117 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_ibv_qp(
119 struct ibv_qp *ibqp);
120 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_table(
122 struct mlx5dv_dr_table *table);
123 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_root_table(
125 struct mlx5dv_dr_table *table, uint16_t priority);
126 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_vport(
128 struct mlx5dv_dr_domain *domain,
129 uint32_t vport);
130 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_ib_port(
132 struct mlx5dv_dr_domain *domain,
133 uint32_t ib_port);
134 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_devx_tir(
136 struct mlx5dv_devx_obj *devx_obj);
137 struct mlx5dv_dr_action *mlx5dv_dr_action_create_packet_reformat(
139 struct mlx5dv_dr_domain *domain,
140 uint32_t flags,
141 enum mlx5dv_flow_action_packet_reformat_type reformat_type,
142 size_t data_sz, void *data);
143 struct mlx5dv_dr_action *mlx5dv_dr_action_create_modify_header(
145 struct mlx5dv_dr_domain *domain,
146 uint32_t flags,
147 size_t actions_sz,
148 __be64 actions[]);
149 struct mlx5dv_dr_action *mlx5dv_dr_action_create_flow_counter(
151 struct mlx5dv_devx_obj *devx_obj,
152 uint32_t offset);
153 struct mlx5dv_dr_action *
155 mlx5dv_dr_action_create_aso(struct mlx5dv_dr_domain *domain,
156 struct mlx5dv_devx_obj *devx_obj,
157 uint32_t offset,
158 uint32_t flags,
159 uint8_t return_reg_c);
160 int mlx5dv_dr_action_modify_aso(struct mlx5dv_dr_action *action,
162 uint32_t offset,
163 uint32_t flags,
164 uint8_t return_reg_c);
165 struct mlx5dv_dr_action *
167 mlx5dv_dr_action_create_flow_meter(struct mlx5dv_dr_flow_meter_attr *attr);
168 int mlx5dv_dr_action_modify_flow_meter(struct mlx5dv_dr_action *action,
170 struct mlx5dv_dr_flow_meter_attr *attr,
171 __be64 modify_field_select);
172 struct mlx5dv_dr_action *
174 mlx5dv_dr_action_create_flow_sampler(struct mlx5dv_dr_flow_sampler_attr *attr);
175 struct mlx5dv_dr_action *
177 mlx5dv_dr_action_create_dest_array(struct mlx5dv_dr_domain *domain,
178 size_t num_dest,
179 struct mlx5dv_dr_action_dest_attr *dests[]);
180 struct mlx5dv_dr_action *mlx5dv_dr_action_create_pop_vlan(void);
182 struct mlx5dv_dr_action *mlx5dv_dr_action_create_push_vlan(
184 struct mlx5dv_dr_domain *dmn,
185 __be32 vlan_hdr)
186 int mlx5dv_dr_action_destroy(struct mlx5dv_dr_action *action);
188 int mlx5dv_dr_aso_other_domain_link(struct mlx5dv_devx_obj *devx_obj,
190 struct mlx5dv_dr_domain *peer_dmn,
191 struct mlx5dv_dr_domain *dmn,
192 uint32_t flags,
193 uint8_t return_reg_c);
194 int mlx5dv_dr_aso_other_domain_unlink(struct mlx5dv_devx_obj *devx_obj,
196 struct mlx5dv_dr_domain *dmn);
197
199 The Direct Rule API (mlx5dv_dr_*) allows complete access by verbs ap‐
200 plication to the device`s packet steering functionality.
201 Steering flow rules are the combination of attributes with a match pat‐
203 tern and a list of actions. Rules can have several distinct actions
204 (such as counting, encapsulating, decapsulating before redirecting
205 packets to a particular queue or port, etc.). In order to manage the
206 rule execution order for the packet processing matching by HW, multiple
207 flow tables in an ordered chain and multiple flow matchers sorted by
208 priorities are defined.
209 Domain
211 mlx5dv_dr_domain_create() creates a DR domain object to be used with
212 mlx5dv_dr_table_create() and mlx5dv_dr_action_create_*().
213 A domain should be destroyed by calling mlx5dv_dr_domain_destroy() once
215 all depended resources are released.
216 The device support the following domains types:
218 MLX5DV_DR_DOMAIN_TYPE_NIC_RX Manage ethernet packets received on the
220 NIC. Packets in this domain can be dropped, dispatched to QP`s, modi‐
221 fied or redirected to additional tables inside the domain. Default be‐
222 havior: Drop packet.
223 MLX5DV_DR_DOMAIN_TYPE_NIC_TX Manage ethernet packets transmit on the
225 NIC. Packets in this domain can be dropped, modified or redirected to
226 additional tables inside the domain. Default behavior: Forward packet
227 to NIC vport (to eSwitch or wire).
228 MLX5DV_DR_DOMAIN_TYPE_FDB Manage ethernet packets in the eSwitch For‐
230 warding Data Base for packets received from wire or from any other
231 vport. Packets in this domain can be dropped, dispatched to vport,
232 modified or redirected to additional tables inside the domain. Default
233 behavior: Forward packet to eSwitch manager vport.
234 mlx5dv_dr_domain_sync() is used in order to flush the rule submission
236 queue. By default, rules in a domain are updated in HW asynchronously.
237 flags should be a set of type enum mlx5dv_dr_domain_sync_flags:
238 MLX5DV_DR_DOMAIN_SYNC_FLAGS_SW: block until completion of all software
240 queued tasks.
241 MLX5DV_DR_DOMAIN_SYNC_FLAGS_HW: clear the steering HW cache to enforce
243 next packet hits the latest rules, in addition to the SW SYNC handling.
244 MLX5DV_DR_DOMAIN_SYNC_FLAGS_MEM: sync device memory to free cached mem‐
246 ory.
247 mlx5dv_dr_domain_set_reclaim_device_memory() is used to enable the re‐
249 claiming of device memory back to the system when not in use, by de‐
250 fault this feature is disabled.
251 mlx5dv_dr_domain_allow_duplicate_rules() is used to allow or prevent
253 insertion of rules matching on same fields(duplicates) on non root ta‐
254 bles, by default this feature is allowed.
255 Table
257 mlx5dv_dr_table_create() creates a DR table in the domain, at the ap‐
258 propriate level, and can be used with mlx5dv_dr_matcher_create(),
259 mlx5dv_dr_action_create_dest_table() and mlx5dv_dr_action_cre‐
260 ate_dest_root_table. All packets start traversing the steering domain
261 tree at table level [22mzero (0). Using rule and action, packets can by
262 redirected to other tables in the domain.
263 A table should be destroyed by calling mlx5dv_dr_table_destroy() once
265 all depended resources are released.
266 Matcher
268 mlx5dv_dr_matcher_create() create a matcher object in table, at sorted
269 priority (lower value is check first). A matcher can hold multiple
270 rules, all with identical mask of type struct mlx5dv_flow_match_parame‐
271 ters which represents the exact attributes to be compared by HW steer‐
272 ing. The match_criteria_enable and mask are defined in a device spec
273 format. Only the fields that where masked in the matcher should be
274 filled by the rule in mlx5dv_dr_rule_create().
275 A matcher should be destroyed by calling mlx5dv_dr_matcher_destroy()
277 once all depended resources are released.
278 mlx5dv_dr_matcher_set_layout() is used to set specific layout parame‐
280 ters of a matcher, on some conditions setting some attributes might not
281 be supported, in such cases ENOTSUP will be returned. flags should be
282 a set of type enum mlx5dv_dr_matcher_layout_flags:
283 MLX5DV_DR_MATCHER_LAYOUT_RESIZABLE: The matcher can resize its scale
285 and resources according to the rules that are inserted or removed.
286 MLX5DV_DR_MATCHER_LAYOUT_NUM_RULE: Indicates a hint from the applica‐
288 tion about the number of the rules the matcher is expected to handle.
289 This allows preallocation of matcher resources for faster rule updates
290 when using with non-resizable layout mode.
291 Actions
293 A set of action create API are defined by mlx5dv_dr_action_create_*().
294 All action are created as struct mlx5dv_dr_action. An action should be
295 destroyed by calling mlx5dv_dr_action_destroy() once all depended rules
296 are destroyed.
297 When an action handle is reused for multiple rules, the same action
299 will be executed. e.g.: action `count' will count multiple flows rules
300 on the same HW flow counter context. action `drop' will drop packets
301 of different rule from any matcher.
302 Action: Drop mlx5dv_dr_action_create_drop create a terminating action
304 which drops packets. Can not be mixed with Destination actions.
305 Action: Default miss mlx5dv_dr_action_create_default_miss create a ter‐
307 minating action which will execute the default behavior based on the
308 domain type.
309 Action: Tag mlx5dv_dr_action_create_tag creates a non-terminating ac‐
311 tion which tags packets with tag_value. The tag_value is available in
312 the CQE of the packet received. Valid only on domain type NIC_RX.
313 Action: Destination mlx5dv_dr_action_create_dest_ibv_qp creates a ter‐
315 minating action delivering the packet to a QP, defined by ibqp. Valid
316 only on domain type NIC_RX. mlx5dv_dr_action_create_dest_table creates
317 a forwarding action to another flow table, defined by table. The des‐
318 tination table must be from the same domain with a level higher than
319 zero. mlx5dv_dr_action_create_dest_root_table creates a forwarding ac‐
320 tion to another priority inside a root flow table, defined by table and
321 priority. mlx5dv_dr_action_create_dest_vport creates a forwarding ac‐
322 tion to a vport on the same domain. Valid only on domain type FDB.
323 mlx5dv_dr_action_create_dest_ib_port creates a forwarding action to a
324 ib_port on the same domain. The valid range of ports is a based on the
325 capability phys_port_cnt_ex provided by ibq_query_device_ex and it is
326 possible to query the ports details using mlx5dv_query_port. Action is
327 supported only on domain type FDB. mlx5dv_dr_action_create_dest_de‐
328 vx_tir creates a terminating action delivering the packet to a TIR, de‐
329 fined by devx_obj. Valid only on domain type NIC_RX.
330 Action: Array mlx5dv_dr_action_create_dest_array creates an action
332 which replicates a packet to multiple destinations. num_dest defines
333 the number of replication destinations. Each dests destination array
334 entry can be of different type. Use type MLX5DV_DR_ACTION_DEST for di‐
335 rect forwarding to an action destination. Use type MLX5DV_DR_AC‐
336 TION_DEST_REFORMAT when reformat action should be performed on the
337 packet before it is forwarding to the destination action.
338 Action: Packet Reformat mlx5dv_dr_action_create_packet_reformat create
340 a packet reformat context and action in the domain. The reformat_type,
341 data_sz and data are defined in man mlx5dv_create_flow_action_pack‐
342 et_reformat.
343 Action: Modify Header mlx5dv_dr_action_create_modify_header create a
345 modify header context and action in the domain. The actions_sz and ac‐
346 tions are defined in man mlx5dv_create_flow_action_modify_header.
347 Action: Flow Count mlx5dv_dr_action_create_flow_counter creates a flow
349 counter action from a DEVX flow counter object, based on devx_obj and
350 specific counter index from offset in the counter bulk.
351 Action: ASO mlx5dv_dr_action_create_aso receives a domain pointer and
353 creates an ASO action from the DEVX ASO object, based on devx_obj. Use
354 offset to select the specific ASO object in the devx_obj bulk. DR
355 rules using this action can optionally update the ASO object value ac‐
356 cording to flags to choose the specific wanted behavior of this object.
357 After a packet hits the rule with the ASO object the value of the ASO
358 object will be copied into the chosen return_reg_c which can be used
359 for match in following DR rules.
360 mlx5dv_dr_action_modify_aso modifies ASO action action with new values
362 for offset, return_reg_c and flags. Only new DR rules using this ac‐
363 tion will use the modified values. Existing DR rules do not change the
364 HW action values stored.
365 flags can be set to one of the types of mlx5dv_dr_ac‐
367 tion_aso_first_hit_flags or mlx5dv_dr_action_aso_flow_meter_flags or
368 mlx5dv_dr_action_aso_ct_flags: MLX5DV_DR_AC‐
369 TION_ASO_FIRST_HIT_FLAGS_SET: is used to set the ASO first hit object
370 context, else the context is only copied to the return_reg_c.
371 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_RED: is used to indicate to up‐
372 date the initial color in ASO flow meter object value to red.
373 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_YELLOW: is used to indicate to
374 update the initial color in ASO flow meter object value to yellow.
375 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_GREEN: is used to indicate to up‐
376 date the initial color in ASO flow meter object value to green.
377 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_UNDEFINED: is used to indicate to
378 update the initial color in ASO flow meter object value to undefined.
379 MLX5DV_DR_ACTION_FLAGS_ASO_CT_DIRECTION_INITIATOR: is used to indicate
380 the TCP connection direction the SYN packet was sent on. MLX5DV_DR_AC‐
381 TION_FLAGS_ASO_CT_DIRECTION_RESPONDER: is used to indicate the TCP con‐
382 nection direction the SYN-ACK packet was sent on.
383 Action: Meter mlx5dv_dr_action_create_flow_meter creates a meter action
385 based on the flow meter parameters. The paramertes are according to
386 the device specification. mlx5dv_dr_action_modify_flow_meter modifies
387 existing flow meter action based on modify_field_select. modi‐
388 fy_field_select is according to the device specification.
389 Action: Sampler mlx5dv_dr_action_create_flow_sampler creates a sampler
391 action, allowing us to duplicate and sample a portion of traffic.
392 Packets steered to the sampler action will be sampled with an approxi‐
393 mate probability of 1/sample_ratio provided in attr, and sample_actions
394 provided in attr will be executed over them. All original packets will
395 be steered to default_next_table in attr. A modify header format
396 SET_ACTION data can be provided in action of attr, which can be execut‐
397 ed on packets before going to default flow table. On some devices,
398 this is required to set register value.
399 Action Flags: action flags can be set to one of the types of enum
401 mlx5dv_dr_action_flags:
402 Action: Pop Vlan mlx5dv_dr_action_create_pop_vlan creates a pop vlan
404 action which removes VLAN tags from packets layer 2.
405 Action: Push Vlan mlx5dv_dr_action_create_push_vlan creates a push vlan
407 action which adds VLAN tags to packets layer 2.
408 MLX5DV_DR_ACTION_FLAGS_ROOT_LEVEL: is used to indicate the action is
410 targeted for flow table in level=0 (ROOT) of the specific domain.
411 Rule
413 mlx5dv_dr_rule_create() creates a HW steering rule entry in matcher.
414 The value of type struct mlx5dv_flow_match_parameters holds the exact
415 attribute values of the steering rule to be matched, in a device spec
416 format. Only the fields that where masked in the matcher should be
417 filled. HW will perform the set of num_actions from the action array
418 of type struct mlx5dv_dr_action, once a packet matches the exact value
419 of the rule (referred to as a `hit').
420 mlx5dv_dr_rule_destroy() destroys the rule.
422 Other
424 mlx5dv_dr_aso_other_domain_link() links the ASO devx object, devx_obj
425 to a domain dmn, this will allow creating a rule with ASO action using
426 the given object on the linked domain dmn. peer_dmn is the domain that
427 the ASO devx object was created on. dmn is the domain that ASO devx
428 object will be linked to. flags choose the specific wanted behavior of
429 this object according to the flags, same as for ASO action creation
430 flags. regc_index After a packet hits the rule with the ASO object the
431 value of the ASO object will be copied into the regc register indicated
432 by this param, and then we can use the value for matching in the fol‐
433 lowing DR rules.
434 mlx5dv_dr_aso_other_domain_unlink() will unlink the devx_obj from the
436 linked dmn. dmn is the domain that ASO devx object is linked to.
437
439 The create API calls will return a pointer to the relevant object: ta‐
440 ble, matcher, action, rule. on failure, NULL will be returned and er‐
441 rno will be set.
442 The destroy API calls will returns 0 on success, or the value of errno
444 on failure (which indicates the failure reason).
445
447 Application can verify is a feature is supported by trail and error.
448 No capabilities are exposed, as the combination of all the options ex‐
449 posed are way to large to define.
450 Tables are size less by definition. They are expected to grow and
452 shrink to accommodate for all rules, according to driver capabilities.
453 Once reaching a limit, an error is returned.
454 Matchers in same priority, in the same table, will have undefined or‐
456 dered.
457 A rule with identical value pattern to another rule on a given matcher
459 are rejected.
460 IP version in matcher mask and rule should be equal and set to 4, 6 or
462 0. # SEE ALSO
463 mlx5dv_open_device(3), mlx5dv_create_flow_action_packet_reformat(3),
465 mlx5dv_create_flow_action_modify_header(3).
466
468 Alex Rosenbaum <alexr@mellanox.com> Alex Vesker <valex@mellanox.com>
469mlx5 2019-03-28 MLX5DV_DR API(3)