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:
305 MLX5DV_DR_ACTION_ASO_FIRST_HIT_FLAGS_SET: is used to set the ASO first
306 hit object context, else the context is only copied to the re‐
307 turn_reg_c. MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_RED: is used to in‐
308 dicate to update the initial color in ASO flow meter object value to
309 red. MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_YELLOW: is used to indicate
310 to update the initial color in ASO flow meter object value to yellow.
311 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_GREEN: is used to indicate to up‐
312 date the initial color in ASO flow meter object value to green.
313 MLX5DV_DR_ACTION_FLAGS_ASO_FLOW_METER_UNDEFINED: is used to indicate to
314 update the initial color in ASO flow meter object value to undefined.
315 Action: Meter mlx5dv_dr_action_create_flow_meter creates a meter action
317 based on the flow meter parameters. The paramertes are according to
318 the device specification. mlx5dv_dr_action_modify_flow_meter modifies
319 existing flow meter action based on modify_field_select. modi‐
320 fy_field_select is according to the device specification.
321 Action: Sampler mlx5dv_dr_action_create_flow_sampler creates a sampler
323 action, allowing us to duplicate and sample a portion of traffic.
324 Packets steered to the sampler action will be sampled with an approxi‐
325 mate probability of 1/sample_ratio provided in attr, and sample_actions
326 provided in attr will be executed over them. All original packets will
327 be steered to default_next_table in attr. A modify header format
328 SET_ACTION data can be provided in action of attr, which can be execut‐
329 ed on packets before going to default flow table. On some devices,
330 this is required to set register value.
331 Action Flags: action flags can be set to one of the types of enum
333 mlx5dv_dr_action_flags:
334 Action: Pop Vlan mlx5dv_dr_action_create_pop_vlan creates a pop vlan
336 action which removes VLAN tags from packets layer 2.
337 Action: Push Vlan mlx5dv_dr_action_create_push_vlan creates a push vlan
339 action which adds VLAN tags to packets layer 2.
340 MLX5DV_DR_ACTION_FLAGS_ROOT_LEVEL: is used to indicate the action is
342 targeted for flow table in level=0 (ROOT) of the specific domain.
343 Rule
345 mlx5dv_dr_rule_create() creates a HW steering rule entry in matcher.
346 The value of type struct mlx5dv_flow_match_parameters holds the exact
347 attribute values of the steering rule to be matched, in a device spec
348 format. Only the fields that where masked in the matcher should be
349 filled. HW will perform the set of num_actions from the action array
350 of type struct mlx5dv_dr_action, once a packet matches the exact value
351 of the rule (referred to as a `hit').
352 mlx5dv_dr_rule_destroy() destroys the rule.
354
356 The create API calls will return a pointer to the relevant object: ta‐
357 ble, matcher, action, rule. on failure, NULL will be returned and er‐
358 rno will be set.
359 The destroy API calls will returns 0 on success, or the value of errno
361 on failure (which indicates the failure reason).
362
364 Application can verify is a feature is supported by trail and error.
365 No capabilities are exposed, as the combination of all the options ex‐
366 posed are way to large to define.
367 Tables are size less by definition. They are expected to grow and
369 shrink to accommodate for all rules, according to driver capabilities.
370 Once reaching a limit, an error is returned.
371 Matchers in same priority, in the same table, will have undefined or‐
373 dered.
374 A rule with identical value pattern to another rule on a given matcher
376 are rejected.
377 IP version in matcher mask and rule should be equal and set to 4, 6 or
379 0. # SEE ALSO
380 mlx5dv_open_device(3), mlx5dv_create_flow_action_packet_reformat(3),
382 mlx5dv_create_flow_action_modify_header(3).
383
385 Alex Rosenbaum <alexr@mellanox.com> Alex Vesker <valex@mellanox.com>
386mlx5 2019-03-28 MLX5DV_DR API(3)