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 - Manage flow domains
8 mlx5dv_dr_table_create, mlx5dv_dr_table_destroy - Manage flow tables
10 mlx5dv_dr_matcher_create, mlx5dv_dr_matcher_destroy - Manage flow
12 matchers
13 mlx5dv_dr_rule_create, mlx5dv_dr_rule_destroy - Manage flow rules
15 mlx5dv_dr_action_create_drop - Create drop action
17 mlx5dv_dr_action_create_default_miss - Create default miss action
19 mlx5dv_dr_action_create_tag - Create tag actions
21 mlx5dv_dr_action_create_dest_ibv_qp, mlx5dv_dr_action_create_dest_ta‐
23 ble, mlx5dv_dr_action_create_dest_vport, mlx5dv_dr_action_cre‐
24 ate_dest_devx_tir - Create packet destination actions
25 mlx5dv_dr_action_create_dest_array - Create destination array action
27 mlx5dv_dr_action_create_packet_reformat - Create packet reformat ac‐
29 tions
30 mlx5dv_dr_action_create_modify_header - Create modify header actions
32 mlx5dv_dr_action_create_flow_counter - Create devx flow counter actions
34 mlx5dv_dr_action_create_aso, mlx5dv_dr_action_modify_aso - Create and
36 modify ASO actions
37 mlx5dv_dr_action_create_flow_meter, mlx5dv_dr_action_modify_flow_meter
39 - Create and modify meter action
40 mlx5dv_dr_action_create_flow_sampler - Create flow sampler action
42 mlx5dv_dr_action_create_pop_vlan - Create pop vlan action
44 mlx5dv_dr_action_create_push_vlan- Create push vlan action
46 mlx5dv_dr_action_destroy - Destroy actions
48
50 #include <infiniband/mlx5dv.h>
51 struct mlx5dv_dr_domain *mlx5dv_dr_domain_create(
53 struct ibv_context *ctx,
54 enum mlx5dv_dr_domain_type type);
55 int mlx5dv_dr_domain_sync(
57 struct mlx5dv_dr_domain *domain,
58 uint32_t flags);
59 int mlx5dv_dr_domain_destroy(struct mlx5dv_dr_domain *domain);
61 void mlx5dv_dr_domain_set_reclaim_device_memory(
63 struct mlx5dv_dr_domain *dmn,
64 bool enable);
65 struct mlx5dv_dr_table *mlx5dv_dr_table_create(
67 struct mlx5dv_dr_domain *domain,
68 uint32_t level);
69 int mlx5dv_dr_table_destroy(struct mlx5dv_dr_table *table);
71 struct mlx5dv_dr_matcher *mlx5dv_dr_matcher_create(
73 struct mlx5dv_dr_table *table,
74 uint16_t priority,
75 uint8_t match_criteria_enable,
76 struct mlx5dv_flow_match_parameters *mask);
77 int mlx5dv_dr_matcher_destroy(struct mlx5dv_dr_matcher *matcher);
79 struct mlx5dv_dr_rule *mlx5dv_dr_rule_create(
81 struct mlx5dv_dr_matcher *matcher,
82 struct mlx5dv_flow_match_parameters *value,
83 size_t num_actions,
84 struct mlx5dv_dr_action *actions[]);
85 void mlx5dv_dr_rule_destroy(struct mlx5dv_dr_rule *rule);
87 struct mlx5dv_dr_action *mlx5dv_dr_action_create_drop(void);
89 struct mlx5dv_dr_action *mlx5dv_dr_action_create_default_miss(void);
91 struct mlx5dv_dr_action *mlx5dv_dr_action_create_tag(
93 uint32_t tag_value);
94 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_ibv_qp(
96 struct ibv_qp *ibqp);
97 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_table(
99 struct mlx5dv_dr_table *table);
100 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_vport(
102 struct mlx5dv_dr_domain *domain,
103 uint32_t vport);
104 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_devx_tir(
106 struct mlx5dv_devx_obj *devx_obj);
107 struct mlx5dv_dr_action *mlx5dv_dr_action_create_packet_reformat(
109 struct mlx5dv_dr_domain *domain,
110 uint32_t flags,
111 enum mlx5dv_flow_action_packet_reformat_type reformat_type,
112 size_t data_sz, void *data);
113 struct mlx5dv_dr_action *mlx5dv_dr_action_create_modify_header(
115 struct mlx5dv_dr_domain *domain,
116 uint32_t flags,
117 size_t actions_sz,
118 __be64 actions[]);
119 struct mlx5dv_dr_action *mlx5dv_dr_action_create_flow_counter(
121 struct mlx5dv_devx_obj *devx_obj,
122 uint32_t offset);
123 struct mlx5dv_dr_action *
125 mlx5dv_dr_action_create_aso(struct mlx5dv_dr_domain *domain,
126 struct mlx5dv_devx_obj *devx_obj,
127 uint32_t offset,
128 uint32_t flags,
129 uint8_t return_reg_c);
130 int mlx5dv_dr_action_modify_aso(struct mlx5dv_dr_action *action,
132 uint32_t offset,
133 uint32_t flags,
134 uint8_t return_reg_c);
135 struct mlx5dv_dr_action *
137 mlx5dv_dr_action_create_flow_meter(struct mlx5dv_dr_flow_meter_attr *attr);
138 int mlx5dv_dr_action_modify_flow_meter(struct mlx5dv_dr_action *action,
140 struct mlx5dv_dr_flow_meter_attr *attr,
141 __be64 modify_field_select);
142 struct mlx5dv_dr_action *
144 mlx5dv_dr_action_create_flow_sampler(struct mlx5dv_dr_flow_sampler_attr *attr);
145 struct mlx5dv_dr_action *
147 mlx5dv_dr_action_create_dest_array(struct mlx5dv_dr_domain *domain,
148 size_t num_dest,
149 struct mlx5dv_dr_action_dest_attr *dests[]);
150 struct mlx5dv_dr_action *mlx5dv_dr_action_create_pop_vlan(void);
152 struct mlx5dv_dr_action *mlx5dv_dr_action_create_push_vlan(
154 struct mlx5dv_dr_domain *dmn,
155 __be32 vlan_hdr)
156 int mlx5dv_dr_action_destroy(struct mlx5dv_dr_action *action);
158
160 The Direct Rule API (mlx5dv_dr_*) allows complete access by verbs ap‐
161 plication to the device`s packet steering functionality.
162 Steering flow rules are the combination of attributes with a match pat‐
164 tern and a list of actions. Rules can have several distinct actions
165 (such as counting, encapsulating, decapsulating before redirecting
166 packets to a particular queue or port, etc.). In order to manage the
167 rule execution order for the packet processing matching by HW, multiple
168 flow tables in an ordered chain and multiple flow matchers sorted by
169 priorities are defined.
170 Domain
172 mlx5dv_dr_domain_create() creates a DR domain object to be used with
173 mlx5dv_dr_table_create() and mlx5dv_dr_action_create_*().
174 A domain should be destroyed by calling mlx5dv_dr_domain_destroy() once
176 all depended resources are released.
177 The device support the following domains types:
179 MLX5DV_DR_DOMAIN_TYPE_NIC_RX Manage ethernet packets received on the
181 NIC. Packets in this domain can be dropped, dispatched to QP`s, modi‐
182 fied or redirected to additional tables inside the domain. Default be‐
183 havior: Drop packet.
184 MLX5DV_DR_DOMAIN_TYPE_NIC_TX Manage ethernet packets transmit on the
186 NIC. Packets in this domain can be dropped, modified or redirected to
187 additional tables inside the domain. Default behavior: Forward packet
188 to NIC vport (to eSwitch or wire).
189 MLX5DV_DR_DOMAIN_TYPE_FDB Manage ethernet packets in the eSwitch For‐
191 warding Data Base for packets received from wire or from any other
192 vport. Packets in this domain can be dropped, dispatched to vport,
193 modified or redirected to additional tables inside the domain. Default
194 behavior: Forward packet to eSwitch manager vport.
195 mlx5dv_dr_domain_sync() is used in order to flush the rule submission
197 queue. By default, rules in a domain are updated in HW asynchronously.
198 flags should be a set of type enum mlx5dv_dr_domain_sync_flags:
199 MLX5DV_DR_DOMAIN_SYNC_FLAGS_SW: block until completion of all software
201 queued tasks.
202 MLX5DV_DR_DOMAIN_SYNC_FLAGS_HW: clear the steering HW cache to enforce
204 next packet hits the latest rules, in addition to the SW SYNC handling.
205 MLX5DV_DR_DOMAIN_SYNC_FLAGS_MEM: sync device memory to free cached mem‐
207 ory.
208 mlx5dv_dr_domain_set_reclaim_device_memory() is used to enable the re‐
210 claiming of device memory back to the system when not in use, by de‐
211 fault this feature is disabled.
212 Table
214 mlx5dv_dr_table_create() creates a DR table in the domain, at the ap‐
215 propriate level, and can be used with mlx5dv_dr_matcher_create() and
216 mlx5dv_dr_action_create_dest_table(). All packets start traversing the
217 steering domain tree at table level [22mzero (0). Using rule and action,
218 packets can by redirected to other tables in the domain.
219 A table should be destroyed by calling mlx5dv_dr_table_destroy() once
221 all depended resources are released.
222 Matcher
224 mlx5dv_dr_matcher_create() create a matcher object in table, at sorted
225 priority (lower value is check first). A matcher can hold multiple
226 rules, all with identical mask of type struct mlx5dv_flow_match_parame‐
227 ters which represents the exact attributes to be compared by HW steer‐
228 ing. The match_criteria_enable and mask are defined in a device spec
229 format. Only the fields that where masked in the matcher should be
230 filled by the rule in mlx5dv_dr_rule_create().
231 A matcher should be destroyed by calling mlx5dv_dr_matcher_destroy()
233 once all depended resources are released.
234 Actions
236 A set of action create API are defined by mlx5dv_dr_action_create_*().
237 All action are created as struct mlx5dv_dr_action. An action should be
238 destroyed by calling mlx5dv_dr_action_destroy() once all depended rules
239 are destroyed.
240 When an action handle is reused for multiple rules, the same action
242 will be executed. e.g.: action `count' will count multiple flows rules
243 on the same HW flow counter context. action `drop' will drop packets
244 of different rule from any matcher.
245 Action: Drop mlx5dv_dr_action_create_drop create a terminating action
247 which drops packets. Can not be mixed with Destination actions.
248 Action: Default miss mlx5dv_dr_action_create_default_miss create a ter‐
250 minating action which will execute the default behavior based on the
251 domain type.
252 Action: Tag mlx5dv_dr_action_create_tag creates a non-terminating ac‐
254 tion which tags packets with tag_value. The tag_value is available in
255 the CQE of the packet received. Valid only on domain type NIC_RX.
256 Action: Destination mlx5dv_dr_action_create_dest_ibv_qp creates a ter‐
258 minating action delivering the packet to a QP, defined by ibqp. Valid
259 only on domain type NIC_RX. mlx5dv_dr_action_create_dest_table creates
260 a forwarding action to another flow table, defined by table. The des‐
261 tination table must be from the same domain with a level higher than
262 zero. mlx5dv_dr_action_create_dest_vport creates a forwarding action
263 to a vport on the same domain. Valid only on domain type FDB.
264 mlx5dv_dr_action_create_dest_devx_tir creates a terminating action de‐
265 livering the packet to a TIR, defined by devx_obj. Valid only on do‐
266 main type NIC_RX.
267 Action: Array mlx5dv_dr_action_create_dest_array creates an action
269 which replicates a packet to multiple destinations. num_dest defines
270 the number of replication destinations. Each dests destination array
271 entry can be of different type. Use type MLX5DV_DR_ACTION_DEST for di‐
272 rect forwarding to an action destination. Use type MLX5DV_DR_AC‐
273 TION_DEST_REFORMAT when reformat action should be performed on the
274 packet before it is forwarding to the destination action.
275 Action: Packet Reformat mlx5dv_dr_action_create_packet_reformat create
277 a packet reformat context and action in the domain. The reformat_type,
278 data_sz and data are defined in man mlx5dv_create_flow_action_pack‐
279 et_reformat.
280 Action: Modify Header mlx5dv_dr_action_create_modify_header create a
282 modify header context and action in the domain. The actions_sz and ac‐
283 tions are defined in man mlx5dv_create_flow_action_modify_header.
284 Action: Flow Count mlx5dv_dr_action_create_flow_counter creates a flow
286 counter action from a DEVX flow counter object, based on devx_obj and
287 specific counter index from offset in the counter bulk.
288 Action: ASO mlx5dv_dr_action_create_aso receives a domain pointer and
290 creates an ASO action from the DEVX ASO object, based on devx_obj. Use
291 offset to select the specific ASO object in the devx_obj bulk. DR
292 rules using this action can optionally update the ASO object value ac‐
293 cording to flags to choose the specific wanted behavior of this object.
294 After a packet hits the rule with the ASO object the value of the ASO
295 object will be copied into the chosen return_reg_c which can be used
296 for match in following DR rules.
297 mlx5dv_dr_action_modify_aso modifies ASO action action with new values
299 for offset, return_reg_c and flags. Only new DR rules using this ac‐
300 tion will use the modified values. Existing DR rules do not change the
301 HW action values stored.
302 flags can be set to one of the types of mlx5dv_dr_ac‐
304 tion_aso_first_hit_flags or mlx5dv_dr_action_aso_flow_meter_flags or
305 mlx5dv_dr_action_aso_ct_flags: MLX5DV_DR_AC‐
306 TION_ASO_FIRST_HIT_FLAGS_SET: is used to set the ASO first hit object
307 context, else the context is only copied to the return_reg_c.
308 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_RED: is used to indicate to up‐
309 date the initial color in ASO flow meter object value to red.
310 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_YELLOW: is used to indicate to
311 update the initial color in ASO flow meter object value to yellow.
312 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_GREEN: is used to indicate to up‐
313 date the initial color in ASO flow meter object value to green.
314 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_UNDEFINED: is used to indicate to
315 update the initial color in ASO flow meter object value to undefined.
316 MLX5DV_DR_ACTION_FLAGS_ASO_CT_DIRECTION_INITIATOR: is used to indicate
317 the TCP connection direction the SYN packet was sent on. MLX5DV_DR_AC‐
318 TION_FLAGS_ASO_CT_DIRECTION_RESPONDER: is used to indicate the TCP con‐
319 nection direction the SYN-ACK packet was sent on.
320 Action: Meter mlx5dv_dr_action_create_flow_meter creates a meter action
322 based on the flow meter parameters. The paramertes are according to
323 the device specification. mlx5dv_dr_action_modify_flow_meter modifies
324 existing flow meter action based on modify_field_select. modi‐
325 fy_field_select is according to the device specification.
326 Action: Sampler mlx5dv_dr_action_create_flow_sampler creates a sampler
328 action, allowing us to duplicate and sample a portion of traffic.
329 Packets steered to the sampler action will be sampled with an approxi‐
330 mate probability of 1/sample_ratio provided in attr, and sample_actions
331 provided in attr will be executed over them. All original packets will
332 be steered to default_next_table in attr. A modify header format
333 SET_ACTION data can be provided in action of attr, which can be execut‐
334 ed on packets before going to default flow table. On some devices,
335 this is required to set register value.
336 Action Flags: action flags can be set to one of the types of enum
338 mlx5dv_dr_action_flags:
339 Action: Pop Vlan mlx5dv_dr_action_create_pop_vlan creates a pop vlan
341 action which removes VLAN tags from packets layer 2.
342 Action: Push Vlan mlx5dv_dr_action_create_push_vlan creates a push vlan
344 action which adds VLAN tags to packets layer 2.
345 MLX5DV_DR_ACTION_FLAGS_ROOT_LEVEL: is used to indicate the action is
347 targeted for flow table in level=0 (ROOT) of the specific domain.
348 Rule
350 mlx5dv_dr_rule_create() creates a HW steering rule entry in matcher.
351 The value of type struct mlx5dv_flow_match_parameters holds the exact
352 attribute values of the steering rule to be matched, in a device spec
353 format. Only the fields that where masked in the matcher should be
354 filled. HW will perform the set of num_actions from the action array
355 of type struct mlx5dv_dr_action, once a packet matches the exact value
356 of the rule (referred to as a `hit').
357 mlx5dv_dr_rule_destroy() destroys the rule.
359
361 The create API calls will return a pointer to the relevant object: ta‐
362 ble, matcher, action, rule. on failure, NULL will be returned and er‐
363 rno will be set.
364 The destroy API calls will returns 0 on success, or the value of errno
366 on failure (which indicates the failure reason).
367
369 Application can verify is a feature is supported by trail and error.
370 No capabilities are exposed, as the combination of all the options ex‐
371 posed are way to large to define.
372 Tables are size less by definition. They are expected to grow and
374 shrink to accommodate for all rules, according to driver capabilities.
375 Once reaching a limit, an error is returned.
376 Matchers in same priority, in the same table, will have undefined or‐
378 dered.
379 A rule with identical value pattern to another rule on a given matcher
381 are rejected.
382 IP version in matcher mask and rule should be equal and set to 4, 6 or
384 0. # SEE ALSO
385 mlx5dv_open_device(3), mlx5dv_create_flow_action_packet_reformat(3),
387 mlx5dv_create_flow_action_modify_header(3).
388
390 Alex Rosenbaum <alexr@mellanox.com> Alex Vesker <valex@mellanox.com>
391mlx5 2019-03-28 MLX5DV_DR API(3)