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 - 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_tag - Create tag actions
19 mlx5dv_dr_action_create_dest_ibv_qp, mlx5dv_dr_action_create_dest_ta‐
21 ble, mlx5dv_dr_action_create_dest_vport - Create packet destination ac‐
22 tions
23 mlx5dv_dr_action_create_packet_reformat - Create packet reformat ac‐
25 tions
26 mlx5dv_dr_action_create_modify_header - Create modify header actions
28 mlx5dv_dr_action_create_flow_counter - Create devx flow counter actions
30 mlx5dv_dr_action_create_flow_meter, mlx5dv_dr_action_modify_flow_meter
32 - Create and modify meter action
33 mlx5dv_dr_action_destroy - Destroy actions
35
37 #include <infiniband/mlx5dv.h>
38 struct mlx5dv_dr_domain *mlx5dv_dr_domain_create(
40 struct ibv_context *ctx,
41 enum mlx5dv_dr_domain_type type);
42 int mlx5dv_dr_domain_sync(
44 struct mlx5dv_dr_domain *domain,
45 uint32_t flags);
46 int mlx5dv_dr_domain_destroy(struct mlx5dv_dr_domain *domain);
48 struct mlx5dv_dr_table *mlx5dv_dr_table_create(
50 struct mlx5dv_dr_domain *domain,
51 uint32_t level);
52 int mlx5dv_dr_table_destroy(struct mlx5dv_dr_table *table);
54 struct mlx5dv_dr_matcher *mlx5dv_dr_matcher_create(
56 struct mlx5dv_dr_table *table,
57 uint16_t priority,
58 uint8_t match_criteria_enable,
59 struct mlx5dv_flow_match_parameters *mask);
60 int mlx5dv_dr_matcher_destroy(struct mlx5dv_dr_matcher *matcher);
62 struct mlx5dv_dr_rule *mlx5dv_dr_rule_create(
64 struct mlx5dv_dr_matcher *matcher,
65 struct mlx5dv_flow_match_parameters *value,
66 size_t num_actions,
67 struct mlx5dv_dr_action *actions[]);
68 void mlx5dv_dr_rule_destroy(struct mlx5dv_dr_rule *rule);
70 struct mlx5dv_dr_action *mlx5dv_dr_action_create_drop(void);
72 struct mlx5dv_dr_action *mlx5dv_dr_action_create_tag(
74 uint32_t tag_value);
75 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_ibv_qp(
77 struct ibv_qp *ibqp);
78 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_table(
80 struct mlx5dv_dr_table *table);
81 struct mlx5dv_dr_action *mlx5dv_dr_action_create_dest_vport(
83 struct mlx5dv_dr_domain *domain,
84 uint32_t vport);
85 struct mlx5dv_dr_action *mlx5dv_dr_action_create_packet_reformat(
87 struct mlx5dv_dr_domain *domain,
88 uint32_t flags,
89 enum mlx5dv_flow_action_packet_reformat_type reformat_type,
90 size_t data_sz, void *data);
91 struct mlx5dv_dr_action *mlx5dv_dr_action_create_modify_header(
93 struct mlx5dv_dr_domain *domain,
94 uint32_t flags,
95 size_t actions_sz,
96 __be64 actions[]);
97 struct mlx5dv_dr_action *mlx5dv_dr_action_create_flow_counter(
99 struct mlx5dv_devx_obj *devx_obj,
100 uint32_t offset);
101 struct mlx5dv_dr_action *
103 mlx5dv_dr_action_create_flow_meter(struct mlx5dv_dr_flow_meter_attr *attr);
104 int mlx5dv_dr_action_modify_flow_meter(struct mlx5dv_dr_action *action,
106 struct mlx5dv_dr_flow_meter_attr *attr,
107 __be64 modify_field_select);
108 int mlx5dv_dr_action_destroy(struct mlx5dv_dr_action *action);
110
112 The Direct Rule API (mlx5dv_dr_*) allows complete access by verbs ap‐
113 plication to the device`s packet steering functionality.
114 Steering flow rules are the combination of attributes with a match pat‐
116 tern and a list of actions. Rules can have several distinct actions
117 (such as counting, encapsulating, decapsulating before redirecting
118 packets to a particular queue or port, etc.). In order to manage the
119 rule execution order for the packet processing matching by HW, multiple
120 flow tables in an ordered chain and multiple flow matchers sorted by
121 priorities are defined.
122 Domain
124 mlx5dv_dr_domain_create() creates a DR domain object to be used with
125 mlx5dv_dr_table_create() and mlx5dv_dr_action_create_*().
126 A domain should be destroyed by calling mlx5dv_dr_domain_destroy() once
128 all depended resources are released.
129 The device support the following domains types:
131 MLX5DV_DR_DOMAIN_TYPE_NIC_RX Manage ethernet packets received on the
133 NIC. Packets in this domain can be dropped, dispatched to QP`s, modi‐
134 fied or redirected to additional tables inside the domain. Default be‐
135 havior: Drop packet.
136 MLX5DV_DR_DOMAIN_TYPE_NIC_TX Manage ethernet packets transmit on the
138 NIC. Packets in this domain can be dropped, modified or redirected to
139 additional tables inside the domain. Default behavior: Forward packet
140 to NIC vport (to eSwitch or wire).
141 MLX5DV_DR_DOMAIN_TYPE_FDB Manage ethernet packets in the eSwitch For‐
143 warding Data Base for packets received from wire or from any other
144 vport. Packets in this domain can be dropped, dispatched to vport,
145 modified or redirected to additional tables inside the domain. Default
146 behavior: Forward packet to eSwitch manager vport.
147 mlx5dv_dr_domain_sync() is used in order to flush the rule submission
149 queue. By default, rules in a domain are updated in HW asynchronously.
150 flags should be a set of type enum mlx5dv_dr_domain_sync_flags:
151 MLX5DV_DR_DOMAIN_SYNC_FLAGS_SW: block until completion of all software
153 queued tasks.
154 MLX5DV_DR_DOMAIN_SYNC_FLAGS_HW: clear the steering HW cache to enforce
156 next packet hits the latest rules, in addition to the SW SYNC handling.
157 Table
159 mlx5dv_dr_table_create() creates a DR table in the domain, at the ap‐
160 propriate level, and can be used with mlx5dv_dr_matcher_create() and
161 mlx5dv_dr_action_create_dest_table(). All packets start traversing the
162 steering domain tree at table level [22mzero (0). Using rule and action,
163 packets can by redirected to other tables in the domain.
164 A table should be destroyed by calling mlx5dv_dr_table_destroy() once
166 all depended resources are released.
167 Matcher
169 mlx5dv_dr_matcher_create() create a matcher object in table, at sorted
170 priority (lower value is check first). A matcher can hold multiple
171 rules, all with identical mask of type struct mlx5dv_flow_match_parame‐
172 ters which represents the exact attributes to be compared by HW steer‐
173 ing. The match_criteria_enable and mask are defined in a device spec
174 format. Only the fields that where masked in the matcher should be
175 filled by the rule in mlx5dv_dr_rule_create().
176 A matcher should be destroyed by calling mlx5dv_dr_matcher_destroy()
178 once all depended resources are released.
179 Actions
181 A set of action create API are defined by mlx5dv_dr_action_create_*().
182 All action are created as struct mlx5dv_dr_action. An action should be
183 destroyed by calling mlx5dv_dr_action_destroy() once all depended rules
184 are destroyed.
185 When an action handle is reused for multiple rules, the same action
187 will be executed. e.g.: action `count' will count multiple flows rules
188 on the same HW flow counter context. action `drop' will drop packets
189 of different rule from any matcher.
190 Action: Drop mlx5dv_dr_action_create_drop create a terminating action
192 which drops packets. Can not be mixed with Destination actions.
193 Action: Tag mlx5dv_dr_action_create_tag creates a non-terminating ac‐
195 tion which tags packets with tag_value. The tag_value is available in
196 the CQE of the packet received. Valid only on domain type NIC_RX.
197 Action: Destination mlx5dv_dr_action_create_dest_ibv_qp creates a ter‐
199 minating action delivering the packet to a QP, defined by ibqp. Valid
200 only on domain type NIC_RX. mlx5dv_dr_action_create_dest_table creates
201 a forwarding action to another flow table, defined by table. The des‐
202 tination table must be from the same domain with a level higher than
203 zero. mlx5dv_dr_action_create_dest_vport creates a forwarding action
204 to a vport on the same domain. Valid only on domain type FDB.
205 Action: Packet Reformat mlx5dv_dr_action_create_packet_reformat create
207 a packet reformat context and action in the domain. The reformat_type,
208 data_sz and data are defined in man mlx5dv_create_flow_action_pack‐
209 et_reformat.
210 Action: Modify Header mlx5dv_dr_action_create_modify_header create a
212 modify header context and action in the domain. The actions_sz and ac‐
213 tions are defined in man mlx5dv_create_flow_action_modify_header.
214 Action: Flow Count mlx5dv_dr_action_create_flow_counter creates a flow
216 counter action from a DEVX flow counter object, based on devx_obj and
217 specific counter index from offset in the counter bulk.
218 Action: Meter mlx5dv_dr_action_create_flow_meter creates a meter action
220 based on the flow meter parameters. The paramertes are according to
221 the device specification. mlx5dv_dr_action_modify_flow_meter modifies
222 existing flow meter action based on modify_field_select. modi‐
223 fy_field_select is according to the device specification.
224 Action Flags: action flags can be set to one of the types of enum
226 mlx5dv_dr_action_flags:
227 MLX5DV_DR_ACTION_FLAGS_ROOT_LEVEL: is used to indicate the action is
229 targeted for flow table in level=0 (ROOT) of the specific domain.
230 Rule
232 mlx5dv_dr_rule_create() creates a HW steering rule entry in matcher.
233 The value of type struct mlx5dv_flow_match_parameters holds the exact
234 attribute values of the steering rule to be matched, in a device spec
235 format. Only the fields that where masked in the matcher should be
236 filled. HW will perform the set of num_actions from the action array
237 of type struct mlx5dv_dr_action, once a packet matches the exact value
238 of the rule (referred to as a `hit').
239 mlx5dv_dr_rule_destroy() destroys the rule.
241
243 The create API calls will return a pointer to the relevant object: ta‐
244 ble, matcher, action, rule. on failure, NULL will be returned and er‐
245 rno will be set.
246 The destroy API calls will returns 0 on success, or the value of errno
248 on failure (which indicates the failure reason).
249
251 Application can verify is a feature is supported by trail and error.
252 No capabilities are exposed, as the combination of all the options ex‐
253 posed are way to large to define.
254 Tables are size less by definition. They are expected to grow and
256 shrink to accommodate for all rules, according to driver capabilities.
257 Once reaching a limit, an error is returned.
258 Matchers in same priority, in the same table, will have undefined or‐
260 dered.
261 A rule with identical value pattern to another rule on a given matcher
263 are rejected.
264 IP version in matcher mask and rule should be equal and set to 4, 6 or
266 0. # SEE ALSO
267 mlx5dv_open_device(3), mlx5dv_create_flow_action_packet_reformat(3),
269 mlx5dv_create_flow_action_modify_header(3).
270
272 Alex Rosenbaum <alexr@mellanox.com> Alex Vesker <valex@mellanox.com>
273mlx5 2019-03-28 MLX5DV_DR API(3)