Branch data Line data Source code
1 : : /* SPDX-License-Identifier: BSD-3-Clause
2 : : * Copyright(C) 2019 Marvell International Ltd.
3 : : * Copyright 2020 Mellanox Technologies, Ltd
4 : : * Copyright(c) 2020 Intel Corporation
5 : : */
6 : :
7 : : #ifndef _RTE_REGEXDEV_H_
8 : : #define _RTE_REGEXDEV_H_
9 : :
10 : : /**
11 : : * @file
12 : : *
13 : : * RTE RegEx Device API
14 : : *
15 : : * Defines RTE RegEx Device APIs for RegEx operations and its provisioning.
16 : : *
17 : : * The RegEx Device API is composed of two parts:
18 : : *
19 : : * - The application-oriented RegEx API that includes functions to setup
20 : : * a RegEx device (configure it, setup its queue pairs and start it),
21 : : * update the rule database and so on.
22 : : *
23 : : * - The driver-oriented RegEx API that exports a function allowing
24 : : * a RegEx poll Mode Driver (PMD) to simultaneously register itself as
25 : : * a RegEx device driver.
26 : : *
27 : : * RegEx device components and definitions:
28 : : *
29 : : * +-----------------+
30 : : * | |
31 : : * | o---------+ rte_regexdev_[en|de]queue_burst()
32 : : * | PCRE based o------+ | |
33 : : * | RegEx pattern | | | +--------+ |
34 : : * | matching engine o------+--+--o | | +------+
35 : : * | | | | | queue |<==o===>|Core 0|
36 : : * | o----+ | | | pair 0 | | |
37 : : * | | | | | +--------+ +------+
38 : : * +-----------------+ | | |
39 : : * ^ | | | +--------+
40 : : * | | | | | | +------+
41 : : * | | +--+--o queue |<======>|Core 1|
42 : : * Rule|Database | | | pair 1 | | |
43 : : * +------+----------+ | | +--------+ +------+
44 : : * | Group 0 | | |
45 : : * | +-------------+ | | | +--------+ +------+
46 : : * | | Rules 0..n | | | | | | |Core 2|
47 : : * | +-------------+ | | +--o queue |<======>| |
48 : : * | Group 1 | | | pair 2 | +------+
49 : : * | +-------------+ | | +--------+
50 : : * | | Rules 0..n | | |
51 : : * | +-------------+ | | +--------+
52 : : * | Group 2 | | | | +------+
53 : : * | +-------------+ | | | queue |<======>|Core n|
54 : : * | | Rules 0..n | | +-------o pair n | | |
55 : : * | +-------------+ | +--------+ +------+
56 : : * | Group n |
57 : : * | +-------------+ |<-------rte_regexdev_rule_db_update()
58 : : * | | | |<-------rte_regexdev_rule_db_compile_activate()
59 : : * | | Rules 0..n | |<-------rte_regexdev_rule_db_import()
60 : : * | +-------------+ |------->rte_regexdev_rule_db_export()
61 : : * +-----------------+
62 : : *
63 : : * RegEx: A regular expression is a concise and flexible means for matching
64 : : * strings of text, such as particular characters, words, or patterns of
65 : : * characters. A common abbreviation for this is “RegEx”.
66 : : *
67 : : * RegEx device: A hardware or software-based implementation of RegEx
68 : : * device API for PCRE based pattern matching syntax and semantics.
69 : : *
70 : : * PCRE RegEx syntax and semantics specification:
71 : : * http://regexkit.sourceforge.net/Documentation/pcre/pcrepattern.html
72 : : *
73 : : * RegEx queue pair: Each RegEx device should have one or more queue pair to
74 : : * transmit a burst of pattern matching request and receive a burst of
75 : : * receive the pattern matching response. The pattern matching request/response
76 : : * embedded in *rte_regex_ops* structure.
77 : : *
78 : : * Rule: A pattern matching rule expressed in PCRE RegEx syntax along with
79 : : * Match ID and Group ID to identify the rule upon the match.
80 : : *
81 : : * Rule database: The RegEx device accepts regular expressions and converts them
82 : : * into a compiled rule database that can then be used to scan data.
83 : : * Compilation allows the device to analyze the given pattern(s) and
84 : : * pre-determine how to scan for these patterns in an optimized fashion that
85 : : * would be far too expensive to compute at run-time. A rule database contains
86 : : * a set of rules that compiled in device specific binary form.
87 : : *
88 : : * Match ID or Rule ID: A unique identifier provided at the time of rule
89 : : * creation for the application to identify the rule upon match.
90 : : *
91 : : * Group ID: Group of rules can be grouped under one group ID to enable
92 : : * rule isolation and effective pattern matching. A unique group identifier
93 : : * provided at the time of rule creation for the application to identify the
94 : : * rule upon match.
95 : : *
96 : : * Scan: A pattern matching request through *enqueue* API.
97 : : *
98 : : * It may possible that a given RegEx device may not support all the features
99 : : * of PCRE. The application may probe unsupported features through
100 : : * struct rte_regexdev_info::pcre_unsup_flags
101 : : *
102 : : * By default, all the functions of the RegEx Device API exported by a PMD
103 : : * are lock-free functions which assume to not be invoked in parallel on
104 : : * different logical cores to work on the same target object. For instance,
105 : : * the dequeue function of a PMD cannot be invoked in parallel on two logical
106 : : * cores to operates on same RegEx queue pair. Of course, this function
107 : : * can be invoked in parallel by different logical core on different queue pair.
108 : : * It is the responsibility of the upper level application to enforce this rule.
109 : : *
110 : : * In all functions of the RegEx API, the RegEx device is
111 : : * designated by an integer >= 0 named the device identifier *dev_id*
112 : : *
113 : : * At the RegEx driver level, RegEx devices are represented by a generic
114 : : * data structure of type *rte_regexdev*.
115 : : *
116 : : * RegEx devices are dynamically registered during the PCI/SoC device probing
117 : : * phase performed at EAL initialization time.
118 : : * When a RegEx device is being probed, a *rte_regexdev* structure and
119 : : * a new device identifier are allocated for that device. Then, the
120 : : * regexdev_init() function supplied by the RegEx driver matching the probed
121 : : * device is invoked to properly initialize the device.
122 : : *
123 : : * The role of the device init function consists of resetting the hardware or
124 : : * software RegEx driver implementations.
125 : : *
126 : : * If the device init operation is successful, the correspondence between
127 : : * the device identifier assigned to the new device and its associated
128 : : * *rte_regexdev* structure is effectively registered.
129 : : * Otherwise, both the *rte_regexdev* structure and the device identifier are
130 : : * freed.
131 : : *
132 : : * The functions exported by the application RegEx API to setup a device
133 : : * designated by its device identifier must be invoked in the following order:
134 : : * - rte_regexdev_configure()
135 : : * - rte_regexdev_queue_pair_setup()
136 : : * - rte_regexdev_start()
137 : : *
138 : : * Then, the application can invoke, in any order, the functions
139 : : * exported by the RegEx API to enqueue pattern matching job, dequeue pattern
140 : : * matching response, get the stats, update the rule database,
141 : : * get/set device attributes and so on
142 : : *
143 : : * If the application wants to change the configuration (i.e. call
144 : : * rte_regexdev_configure() or rte_regexdev_queue_pair_setup()), it must call
145 : : * rte_regexdev_stop() first to stop the device and then do the reconfiguration
146 : : * before calling rte_regexdev_start() again. The enqueue and dequeue
147 : : * functions should not be invoked when the device is stopped.
148 : : *
149 : : * Finally, an application can close a RegEx device by invoking the
150 : : * rte_regexdev_close() function.
151 : : *
152 : : * Each function of the application RegEx API invokes a specific function
153 : : * of the PMD that controls the target device designated by its device
154 : : * identifier.
155 : : *
156 : : * For this purpose, all device-specific functions of a RegEx driver are
157 : : * supplied through a set of pointers contained in a generic structure of type
158 : : * *regexdev_ops*.
159 : : * The address of the *regexdev_ops* structure is stored in the *rte_regexdev*
160 : : * structure by the device init function of the RegEx driver, which is
161 : : * invoked during the PCI/SoC device probing phase, as explained earlier.
162 : : *
163 : : * In other words, each function of the RegEx API simply retrieves the
164 : : * *rte_regexdev* structure associated with the device identifier and
165 : : * performs an indirect invocation of the corresponding driver function
166 : : * supplied in the *regexdev_ops* structure of the *rte_regexdev* structure.
167 : : *
168 : : * For performance reasons, the address of the fast-path functions of the
169 : : * RegEx driver is not contained in the *regexdev_ops* structure.
170 : : * Instead, they are directly stored at the beginning of the *rte_regexdev*
171 : : * structure to avoid an extra indirect memory access during their invocation.
172 : : *
173 : : * RTE RegEx device drivers do not use interrupts for enqueue or dequeue
174 : : * operation. Instead, RegEx drivers export Poll-Mode enqueue and dequeue
175 : : * functions to applications.
176 : : *
177 : : * The *enqueue* operation submits a burst of RegEx pattern matching request
178 : : * to the RegEx device and the *dequeue* operation gets a burst of pattern
179 : : * matching response for the ones submitted through *enqueue* operation.
180 : : *
181 : : * Typical application utilisation of the RegEx device API will follow the
182 : : * following programming flow.
183 : : *
184 : : * - rte_regexdev_configure()
185 : : * - rte_regexdev_queue_pair_setup()
186 : : * - rte_regexdev_rule_db_update() Needs to invoke if precompiled rule database
187 : : * not provided in rte_regexdev_config::rule_db for rte_regexdev_configure()
188 : : * and/or application needs to update rule database.
189 : : * - rte_regexdev_rule_db_compile_activate() Needs to invoke if
190 : : * rte_regexdev_rule_db_update function was used.
191 : : * - Create or reuse exiting mempool for *rte_regex_ops* objects.
192 : : * - rte_regexdev_start()
193 : : * - rte_regexdev_enqueue_burst()
194 : : * - rte_regexdev_dequeue_burst()
195 : : */
196 : :
197 : : #include <rte_compat.h>
198 : : #include <rte_common.h>
199 : : #include <rte_dev.h>
200 : : #include <rte_mbuf.h>
201 : :
202 : : #define RTE_REGEXDEV_NAME_MAX_LEN RTE_DEV_NAME_MAX_LEN
203 : :
204 : : extern int rte_regexdev_logtype;
205 : : #define RTE_LOGTYPE_REGEXDEV rte_regexdev_logtype
206 : :
207 : : #define RTE_REGEXDEV_LOG_LINE(level, ...) \
208 : : RTE_LOG_LINE(level, REGEXDEV, "" __VA_ARGS__)
209 : :
210 : : /* Macros to check for valid port */
211 : : #define RTE_REGEXDEV_VALID_DEV_ID_OR_ERR_RET(dev_id, retval) do { \
212 : : if (!rte_regexdev_is_valid_dev(dev_id)) { \
213 : : RTE_REGEXDEV_LOG_LINE(ERR, "Invalid dev_id=%u", dev_id); \
214 : : return retval; \
215 : : } \
216 : : } while (0)
217 : :
218 : : #define RTE_REGEXDEV_VALID_DEV_ID_OR_RET(dev_id) do { \
219 : : if (!rte_regexdev_is_valid_dev(dev_id)) { \
220 : : RTE_REGEXDEV_LOG_LINE(ERR, "Invalid dev_id=%u", dev_id); \
221 : : return; \
222 : : } \
223 : : } while (0)
224 : :
225 : : /**
226 : : * @warning
227 : : * @b EXPERIMENTAL: this API may change without prior notice.
228 : : *
229 : : * Check if dev_id is ready.
230 : : *
231 : : * @param dev_id
232 : : * The dev identifier of the RegEx device.
233 : : *
234 : : * @return
235 : : * - 0 if device state is not in ready state.
236 : : * - 1 if device state is ready state.
237 : : */
238 : : __rte_experimental
239 : : int rte_regexdev_is_valid_dev(uint16_t dev_id);
240 : :
241 : : /**
242 : : * @warning
243 : : * @b EXPERIMENTAL: this API may change without prior notice.
244 : : *
245 : : * Get the total number of RegEx devices that have been successfully
246 : : * initialised.
247 : : *
248 : : * @return
249 : : * The total number of usable RegEx devices.
250 : : */
251 : : __rte_experimental
252 : : uint8_t
253 : : rte_regexdev_count(void);
254 : :
255 : : /**
256 : : * @warning
257 : : * @b EXPERIMENTAL: this API may change without prior notice.
258 : : *
259 : : * Get the device identifier for the named RegEx device.
260 : : *
261 : : * @param name
262 : : * RegEx device name to select the RegEx device identifier.
263 : : *
264 : : * @return
265 : : * Returns RegEx device identifier on success.
266 : : * - <0: Failure to find named RegEx device.
267 : : */
268 : : __rte_experimental
269 : : int
270 : : rte_regexdev_get_dev_id(const char *name);
271 : :
272 : : /* Enumerates RegEx device capabilities */
273 : : #define RTE_REGEXDEV_CAPA_RUNTIME_COMPILATION_F (1ULL << 0)
274 : : /**< RegEx device does support compiling the rules at runtime unlike
275 : : * loading only the pre-built rule database using
276 : : * struct rte_regexdev_config::rule_db in rte_regexdev_configure()
277 : : *
278 : : * @see struct rte_regexdev_config::rule_db, rte_regexdev_configure()
279 : : * @see struct rte_regexdev_info::regexdev_capa
280 : : */
281 : :
282 : : #define RTE_REGEXDEV_CAPA_SUPP_PCRE_START_ANCHOR_F (1ULL << 1)
283 : : /**< RegEx device support PCRE Anchor to start of match flag.
284 : : * Example RegEx is `/\Gfoo\d/`. Here `\G` asserts position at the end of the
285 : : * previous match or the start of the string for the first match.
286 : : * This position will change each time the RegEx is applied to the subject
287 : : * string. If the RegEx is applied to `foo1foo2Zfoo3` the first two matches will
288 : : * be successful for `foo1foo2` and fail for `Zfoo3`.
289 : : *
290 : : * @see struct rte_regexdev_info::regexdev_capa
291 : : */
292 : :
293 : : #define RTE_REGEXDEV_CAPA_SUPP_PCRE_ATOMIC_GROUPING_F (1ULL << 2)
294 : : /**< RegEx device support PCRE Atomic grouping.
295 : : * Atomic groups are represented by `(?>)`. An atomic group is a group that,
296 : : * when the RegEx engine exits from it, automatically throws away all
297 : : * backtracking positions remembered by any tokens inside the group.
298 : : * Example RegEx is `a(?>bc|b)c` if the given patterns are `abc` and `abcc` then
299 : : * `a(bc|b)c` matches both where as `a(?>bc|b)c` matches only abcc because
300 : : * atomic groups don't allow backtracking back to `b`.
301 : : *
302 : : * @see struct rte_regexdev_info::regexdev_capa
303 : : */
304 : :
305 : : #define RTE_REGEXDEV_SUPP_PCRE_BACKTRACKING_CTRL_F (1ULL << 3)
306 : : /**< RegEx device support PCRE backtracking control verbs.
307 : : * Some examples of backtracking verbs are (*COMMIT), (*ACCEPT), (*FAIL),
308 : : * (*SKIP), (*PRUNE).
309 : : *
310 : : * @see struct rte_regexdev_info::regexdev_capa
311 : : */
312 : :
313 : : #define RTE_REGEXDEV_SUPP_PCRE_CALLOUTS_F (1ULL << 4)
314 : : /**< RegEx device support PCRE callouts.
315 : : * PCRE supports calling external function in between matches by using `(?C)`.
316 : : * Example RegEx `ABC(?C)D` if a given patter is `ABCD` then the RegEx engine
317 : : * will parse ABC perform a userdefined callout and return a successful match at
318 : : * D.
319 : : *
320 : : * @see struct rte_regexdev_info::regexdev_capa
321 : : */
322 : :
323 : : #define RTE_REGEXDEV_SUPP_PCRE_BACKREFERENCE_F (1ULL << 5)
324 : : /**< RegEx device support PCRE backreference.
325 : : * Example RegEx is `(\2ABC|(GHI))+` `\2` matches the same text as most recently
326 : : * matched by the 2nd capturing group i.e. `GHI`.
327 : : *
328 : : * @see struct rte_regexdev_info::regexdev_capa
329 : : */
330 : :
331 : : #define RTE_REGEXDEV_SUPP_PCRE_GREEDY_F (1ULL << 6)
332 : : /**< RegEx device support PCRE Greedy mode.
333 : : * For example if the RegEx is `AB\d*?` then `*?` represents zero or unlimited
334 : : * matches. In greedy mode the pattern `AB12345` will be matched completely
335 : : * where as the ungreedy mode `AB` will be returned as the match.
336 : : *
337 : : * @see struct rte_regexdev_info::regexdev_capa
338 : : */
339 : :
340 : : #define RTE_REGEXDEV_SUPP_PCRE_MATCH_ALL_F (1ULL << 7)
341 : : /**< RegEx device support match all mode.
342 : : * For example if the RegEx is `AB\d*?` then `*?` represents zero or unlimited
343 : : * matches. In match all mode the pattern `AB12345` will return 6 matches.
344 : : * AB, AB1, AB12, AB123, AB1234, AB12345.
345 : : *
346 : : * @see struct rte_regexdev_info::regexdev_capa
347 : : */
348 : :
349 : : #define RTE_REGEXDEV_SUPP_PCRE_LOOKAROUND_ASRT_F (1ULL << 8)
350 : : /**< RegEx device support PCRE Lookaround assertions
351 : : * (Zero-width assertions). Example RegEx is `[a-z]+\d+(?=!{3,})` if
352 : : * the given pattern is `dwad1234!` the RegEx engine doesn't report any matches
353 : : * because the assert `(?=!{3,})` fails. The pattern `dwad123!!!` would return a
354 : : * successful match.
355 : : *
356 : : * @see struct rte_regexdev_info::regexdev_capa
357 : : */
358 : :
359 : : #define RTE_REGEXDEV_SUPP_PCRE_MATCH_POINT_RST_F (1ULL << 9)
360 : : /**< RegEx device doesn't support PCRE match point reset directive.
361 : : * Example RegEx is `[a-z]+\K\d+` if the pattern is `dwad123`
362 : : * then even though the entire pattern matches only `123`
363 : : * is reported as a match.
364 : : *
365 : : * @see struct rte_regexdev_info::regexdev_capa
366 : : */
367 : :
368 : : #define RTE_REGEXDEV_SUPP_NEWLINE_CONVENTIONS_F (1ULL << 10)
369 : : /**< RegEx support PCRE newline convention.
370 : : * Newline conventions are represented as follows:
371 : : * (*CR) carriage return
372 : : * (*LF) linefeed
373 : : * (*CRLF) carriage return, followed by linefeed
374 : : * (*ANYCRLF) any of the three above
375 : : * (*ANY) all Unicode newline sequences
376 : : *
377 : : * @see struct rte_regexdev_info::regexdev_capa
378 : : */
379 : :
380 : : #define RTE_REGEXDEV_SUPP_PCRE_NEWLINE_SEQ_F (1ULL << 11)
381 : : /**< RegEx device support PCRE newline sequence.
382 : : * The escape sequence `\R` will match any newline sequence.
383 : : * It is equivalent to: `(?>\r\n|\n|\x0b|\f|\r|\x85)`.
384 : : *
385 : : * @see struct rte_regexdev_info::regexdev_capa
386 : : */
387 : :
388 : : #define RTE_REGEXDEV_SUPP_PCRE_POSSESSIVE_QUALIFIERS_F (1ULL << 12)
389 : : /**< RegEx device support PCRE possessive qualifiers.
390 : : * Example RegEx possessive qualifiers `*+`, `++`, `?+`, `{m,n}+`.
391 : : * Possessive quantifier repeats the token as many times as possible and it does
392 : : * not give up matches as the engine backtracks. With a possessive quantifier,
393 : : * the deal is all or nothing.
394 : : *
395 : : * @see struct rte_regexdev_info::regexdev_capa
396 : : */
397 : :
398 : : #define RTE_REGEXDEV_SUPP_PCRE_SUBROUTINE_REFERENCES_F (1ULL << 13)
399 : : /**< RegEx device support PCRE Subroutine references.
400 : : * PCRE Subroutine references allow for sub patterns to be assessed
401 : : * as part of the RegEx. Example RegEx is `(foo|fuzz)\g<1>+bar` matches the
402 : : * pattern `foofoofuzzfoofuzzbar`.
403 : : *
404 : : * @see struct rte_regexdev_info::regexdev_capa
405 : : */
406 : :
407 : : #define RTE_REGEXDEV_SUPP_PCRE_UTF_8_F (1ULL << 14)
408 : : /**< RegEx device support UTF-8 character encoding.
409 : : *
410 : : * @see struct rte_regexdev_info::pcre_unsup_flags
411 : : */
412 : :
413 : : #define RTE_REGEXDEV_SUPP_PCRE_UTF_16_F (1ULL << 15)
414 : : /**< RegEx device support UTF-16 character encoding.
415 : : *
416 : : * @see struct rte_regexdev_info::regexdev_capa
417 : : */
418 : :
419 : : #define RTE_REGEXDEV_SUPP_PCRE_UTF_32_F (1ULL << 16)
420 : : /**< RegEx device support UTF-32 character encoding.
421 : : *
422 : : * @see struct rte_regexdev_info::regexdev_capa
423 : : */
424 : :
425 : : #define RTE_REGEXDEV_SUPP_PCRE_WORD_BOUNDARY_F (1ULL << 17)
426 : : /**< RegEx device support word boundaries.
427 : : * The meta character `\b` represents word boundary anchor.
428 : : *
429 : : * @see struct rte_regexdev_info::regexdev_capa
430 : : */
431 : :
432 : : #define RTE_REGEXDEV_SUPP_PCRE_FORWARD_REFERENCES_F (1ULL << 18)
433 : : /**< RegEx device support Forward references.
434 : : * Forward references allow you to use a back reference to a group that appears
435 : : * later in the RegEx. Example RegEx is `(\3ABC|(DEF|(GHI)))+` matches the
436 : : * following string `GHIGHIABCDEF`.
437 : : *
438 : : * @see struct rte_regexdev_info::regexdev_capa
439 : : */
440 : :
441 : : #define RTE_REGEXDEV_SUPP_MATCH_AS_END_F (1ULL << 19)
442 : : /**< RegEx device support match as end.
443 : : * Match as end means that the match result holds the end offset of the
444 : : * detected match. No len value is set.
445 : : * If the device doesn't support this feature it means the match
446 : : * result holds the starting position of match and the length of the match.
447 : : *
448 : : * @see struct rte_regexdev_info::regexdev_capa
449 : : */
450 : :
451 : : #define RTE_REGEXDEV_SUPP_CROSS_BUFFER_F (1ULL << 20)
452 : : /**< RegEx device support cross buffer match.
453 : : * Cross buffer matching means that the match can be detected even if the
454 : : * string was started in previous buffer.
455 : : * In case the device is configured as RTE_REGEXDEV_CFG_MATCH_AS_END
456 : : * the end offset will be relative for the first packet.
457 : : * For example RegEx is ABC the first buffer is xxxx second buffer yyyA and
458 : : * the last buffer BCzz.
459 : : * In case the match as end is configured the end offset will be 10.
460 : : *
461 : : * @see RTE_REGEXDEV_CFG_MATCH_AS_END_F
462 : : * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F
463 : : * @see RTE_REGEX_OPS_RSP_PMI_SOJ_F
464 : : * @see RTE_REGEX_OPS_RSP_PMI_EOJ_F
465 : : */
466 : :
467 : : #define RTE_REGEXDEV_SUPP_MATCH_ALL_F (1ULL << 21)
468 : : /**< RegEx device support match all.
469 : : * Match all means that the RegEx engine will return all possible matches.
470 : : * For example, assume the RegEx is `A+b`, given the input AAAb the
471 : : * returned matches will be: Ab, AAb and AAAb.
472 : : *
473 : : * @see RTE_REGEXDEV_CFG_MATCH_ALL_F
474 : : */
475 : :
476 : : #define RTE_REGEXDEV_CAPA_QUEUE_PAIR_OOS_F (1ULL << 22)
477 : : /**< RegEx device supports out of order scan.
478 : : * Out of order scan means the response of a specific job can be returned as
479 : : * soon as it is ready even if previous jobs on the same queue didn't complete.
480 : : *
481 : : * @see RTE_REGEX_QUEUE_PAIR_CFG_OOS_F
482 : : * @see struct rte_regexdev_info::regexdev_capa
483 : : */
484 : :
485 : : /* Enumerates PCRE rule flags */
486 : : #define RTE_REGEX_PCRE_RULE_ALLOW_EMPTY_F (1ULL << 0)
487 : : /**< When this flag is set, the pattern that can match against an empty string,
488 : : * such as `.*` are allowed.
489 : : *
490 : : * @see struct rte_regexdev_info::rule_flags
491 : : * @see struct rte_regexdev_rule::rule_flags
492 : : */
493 : :
494 : : #define RTE_REGEX_PCRE_RULE_ANCHORED_F (1ULL << 1)
495 : : /**< When this flag is set, the pattern is forced to be "anchored", that is, it
496 : : * is constrained to match only at the first matching point in the string that
497 : : * is being searched. Similar to `^` and represented by `\A`.
498 : : *
499 : : * @see struct rte_regexdev_info::rule_flags
500 : : * @see struct rte_regexdev_rule::rule_flags
501 : : */
502 : :
503 : : #define RTE_REGEX_PCRE_RULE_CASELESS_F (1ULL << 2)
504 : : /**< When this flag is set, letters in the pattern match both upper and lower
505 : : * case letters in the subject.
506 : : *
507 : : * @see struct rte_regexdev_info::rule_flags
508 : : * @see struct rte_regexdev_rule::rule_flags
509 : : */
510 : :
511 : : #define RTE_REGEX_PCRE_RULE_DOTALL_F (1ULL << 3)
512 : : /**< When this flag is set, a dot metacharacter in the pattern matches any
513 : : * character, including one that indicates a newline.
514 : : *
515 : : * @see struct rte_regexdev_info::rule_flags
516 : : * @see struct rte_regexdev_rule::rule_flags
517 : : */
518 : :
519 : : #define RTE_REGEX_PCRE_RULE_DUPNAMES_F (1ULL << 4)
520 : : /**< When this flag is set, names used to identify capture groups need not be
521 : : * unique.
522 : : *
523 : : * @see struct rte_regexdev_info::rule_flags
524 : : * @see struct rte_regexdev_rule::rule_flags
525 : : */
526 : :
527 : : #define RTE_REGEX_PCRE_RULE_EXTENDED_F (1ULL << 5)
528 : : /**< When this flag is set, most white space characters in the pattern are
529 : : * totally ignored except when escaped or inside a character class.
530 : : *
531 : : * @see struct rte_regexdev_info::rule_flags
532 : : * @see struct rte_regexdev_rule::rule_flags
533 : : */
534 : :
535 : : #define RTE_REGEX_PCRE_RULE_MATCH_UNSET_BACKREF_F (1ULL << 6)
536 : : /**< When this flag is set, a backreference to an unset capture group matches an
537 : : * empty string.
538 : : *
539 : : * @see struct rte_regexdev_info::rule_flags
540 : : * @see struct rte_regexdev_rule::rule_flags
541 : : */
542 : :
543 : : #define RTE_REGEX_PCRE_RULE_MULTILINE_F (1ULL << 7)
544 : : /**< When this flag is set, the `^` and `$` constructs match immediately
545 : : * following or immediately before internal newlines in the subject string,
546 : : * respectively, as well as at the very start and end.
547 : : *
548 : : * @see struct rte_regexdev_info::rule_flags
549 : : * @see struct rte_regexdev_rule::rule_flags
550 : : */
551 : :
552 : : #define RTE_REGEX_PCRE_RULE_NO_AUTO_CAPTURE_F (1ULL << 8)
553 : : /**< When this Flag is set, it disables the use of numbered capturing
554 : : * parentheses in the pattern. References to capture groups (backreferences or
555 : : * recursion/subroutine calls) may only refer to named groups, though the
556 : : * reference can be by name or by number.
557 : : *
558 : : * @see struct rte_regexdev_info::rule_flags
559 : : * @see struct rte_regexdev_rule::rule_flags
560 : : */
561 : :
562 : : #define RTE_REGEX_PCRE_RULE_UCP_F (1ULL << 9)
563 : : /**< By default, only ASCII characters are recognized, When this flag is set,
564 : : * Unicode properties are used instead to classify characters.
565 : : *
566 : : * @see struct rte_regexdev_info::rule_flags
567 : : * @see struct rte_regexdev_rule::rule_flags
568 : : */
569 : :
570 : : #define RTE_REGEX_PCRE_RULE_UNGREEDY_F (1ULL << 10)
571 : : /**< When this flag is set, the "greediness" of the quantifiers is inverted
572 : : * so that they are not greedy by default, but become greedy if followed by
573 : : * `?`.
574 : : *
575 : : * @see struct rte_regexdev_info::rule_flags
576 : : * @see struct rte_regexdev_rule::rule_flags
577 : : */
578 : :
579 : : #define RTE_REGEX_PCRE_RULE_UTF_F (1ULL << 11)
580 : : /**< When this flag is set, RegEx engine has to regard both the pattern and the
581 : : * subject strings that are subsequently processed as strings of UTF characters
582 : : * instead of single-code-unit strings.
583 : : *
584 : : * @see struct rte_regexdev_info::rule_flags
585 : : * @see struct rte_regexdev_rule::rule_flags
586 : : */
587 : :
588 : : #define RTE_REGEX_PCRE_RULE_NEVER_BACKSLASH_C_F (1ULL << 12)
589 : : /**< This flag locks out the use of `\C` in the pattern that is being compiled.
590 : : * This escape matches one data unit, even in UTF mode which can cause
591 : : * unpredictable behavior in UTF-8 or UTF-16 modes, because it may leave the
592 : : * current matching point in the mi:set hlsearchddle of a multi-code-unit
593 : : * character.
594 : : *
595 : : * @see struct rte_regexdev_info::rule_flags
596 : : * @see struct rte_regexdev_rule::rule_flags
597 : : */
598 : :
599 : : /**
600 : : * RegEx device information
601 : : */
602 : : struct rte_regexdev_info {
603 : : const char *driver_name; /**< RegEx driver name. */
604 : : struct rte_device *dev; /**< Device information. */
605 : : uint16_t max_matches;
606 : : /**< Maximum matches per scan supported by this device. */
607 : : uint16_t max_queue_pairs;
608 : : /**< Maximum queue pairs supported by this device. */
609 : : uint16_t max_payload_size;
610 : : /**< Maximum payload size for a pattern match request or scan.
611 : : * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F
612 : : */
613 : : uint16_t max_segs;
614 : : /**< Maximum number of mbuf segments that can be chained together. */
615 : : uint32_t max_rules_per_group;
616 : : /**< Maximum rules supported per group by this device. */
617 : : uint16_t max_groups;
618 : : /**< Maximum groups supported by this device. */
619 : : uint32_t regexdev_capa;
620 : : /**< RegEx device capabilities. @see RTE_REGEXDEV_CAPA_* */
621 : : uint64_t rule_flags;
622 : : /**< Supported compiler rule flags.
623 : : * @see RTE_REGEX_PCRE_RULE_*, struct rte_regexdev_rule::rule_flags
624 : : */
625 : : };
626 : :
627 : : /**
628 : : * @warning
629 : : * @b EXPERIMENTAL: this API may change without prior notice.
630 : : *
631 : : * Retrieve the contextual information of a RegEx device.
632 : : *
633 : : * @param dev_id
634 : : * The identifier of the device.
635 : : *
636 : : * @param[out] dev_info
637 : : * A pointer to a structure of type *rte_regexdev_info* to be filled with the
638 : : * contextual information of the device.
639 : : *
640 : : * @return
641 : : * - 0: Success, driver updates the contextual information of the RegEx device
642 : : * - <0: Error code returned by the driver info get function.
643 : : */
644 : : __rte_experimental
645 : : int
646 : : rte_regexdev_info_get(uint8_t dev_id, struct rte_regexdev_info *dev_info);
647 : :
648 : : /* Enumerates RegEx device configuration flags */
649 : : #define RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F (1ULL << 0)
650 : : /**< Cross buffer scan refers to the ability to be able to detect
651 : : * matches that occur across buffer boundaries, where the buffers are related
652 : : * to each other in some way. Enable this flag when to scan payload size
653 : : * greater than struct rte_regexdev_info::max_payload_size and/or
654 : : * matches can present across scan buffer boundaries.
655 : : *
656 : : * @see struct rte_regexdev_info::max_payload_size
657 : : * @see struct rte_regexdev_config::dev_cfg_flags, rte_regexdev_configure()
658 : : * @see RTE_REGEX_OPS_RSP_PMI_SOJ_F
659 : : * @see RTE_REGEX_OPS_RSP_PMI_EOJ_F
660 : : */
661 : :
662 : : #define RTE_REGEXDEV_CFG_MATCH_AS_END_F (1ULL << 1)
663 : : /**< Match as end is the ability to return the result as ending offset.
664 : : * When this flag is set, the result for each match will hold the ending
665 : : * offset of the match in end_offset.
666 : : * If this flag is not set, then the match result will hold the starting offset
667 : : * in start_offset, and the length of the match in len.
668 : : *
669 : : * @see RTE_REGEXDEV_SUPP_MATCH_AS_END_F
670 : : */
671 : :
672 : : #define RTE_REGEXDEV_CFG_MATCH_ALL_F (1ULL << 2)
673 : : /**< Match all is the ability to return all possible results.
674 : : *
675 : : * @see RTE_REGEXDEV_SUPP_MATCH_ALL_F
676 : : */
677 : :
678 : : /** RegEx device configuration structure */
679 : : struct rte_regexdev_config {
680 : : uint16_t nb_max_matches;
681 : : /**< Maximum matches per scan configured on this device.
682 : : * This value cannot exceed the *max_matches*
683 : : * which previously provided in rte_regexdev_info_get().
684 : : * The value 0 is allowed, in which case, value 1 used.
685 : : * @see struct rte_regexdev_info::max_matches
686 : : */
687 : : uint16_t nb_queue_pairs;
688 : : /**< Number of RegEx queue pairs to configure on this device.
689 : : * This value cannot exceed the *max_queue_pairs* which previously
690 : : * provided in rte_regexdev_info_get().
691 : : * @see struct rte_regexdev_info::max_queue_pairs
692 : : */
693 : : uint32_t nb_rules_per_group;
694 : : /**< Number of rules per group to configure on this device.
695 : : * This value cannot exceed the *max_rules_per_group*
696 : : * which previously provided in rte_regexdev_info_get().
697 : : * The value 0 is allowed, in which case,
698 : : * struct rte_regexdev_info::max_rules_per_group used.
699 : : * @see struct rte_regexdev_info::max_rules_per_group
700 : : */
701 : : uint16_t nb_groups;
702 : : /**< Number of groups to configure on this device.
703 : : * This value cannot exceed the *max_groups*
704 : : * which previously provided in rte_regexdev_info_get().
705 : : * @see struct rte_regexdev_info::max_groups
706 : : */
707 : : const char *rule_db;
708 : : /**< Import initial set of prebuilt rule database on this device.
709 : : * The value NULL is allowed, in which case, the device will not
710 : : * be configured prebuilt rule database. Application may use
711 : : * rte_regexdev_rule_db_update() or rte_regexdev_rule_db_import() API
712 : : * to update or import rule database after the
713 : : * rte_regexdev_configure().
714 : : * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_import()
715 : : */
716 : : uint32_t rule_db_len;
717 : : /**< Length of *rule_db* buffer. */
718 : : uint32_t dev_cfg_flags;
719 : : /**< RegEx device configuration flags, See RTE_REGEXDEV_CFG_* */
720 : : };
721 : :
722 : : /**
723 : : * @warning
724 : : * @b EXPERIMENTAL: this API may change without prior notice.
725 : : *
726 : : * Configure a RegEx device.
727 : : *
728 : : * This function must be invoked first before any other function in the
729 : : * API. This function can also be re-invoked when a device is in the
730 : : * stopped state.
731 : : *
732 : : * The caller may use rte_regexdev_info_get() to get the capability of each
733 : : * resources available for this regex device.
734 : : *
735 : : * @param dev_id
736 : : * The identifier of the device to configure.
737 : : * @param cfg
738 : : * The RegEx device configuration structure.
739 : : *
740 : : * @return
741 : : * - 0: Success, device configured. Otherwise negative errno is returned.
742 : : */
743 : : __rte_experimental
744 : : int
745 : : rte_regexdev_configure(uint8_t dev_id, const struct rte_regexdev_config *cfg);
746 : :
747 : : /* Enumerates RegEx queue pair configuration flags */
748 : : #define RTE_REGEX_QUEUE_PAIR_CFG_OOS_F (1ULL << 0)
749 : : /**< Out of order scan, If not set, a scan must retire after previously issued
750 : : * in-order scans to this queue pair. If set, this scan can be retired as soon
751 : : * as device returns completion. Application should not set out of order scan
752 : : * flag if it needs to maintain the ingress order of scan request.
753 : : *
754 : : * @see struct rte_regexdev_qp_conf::qp_conf_flags
755 : : * @see rte_regexdev_queue_pair_setup()
756 : : */
757 : :
758 : : struct rte_regex_ops;
759 : : typedef void (*regexdev_stop_flush_t)(uint8_t dev_id, uint16_t qp_id,
760 : : struct rte_regex_ops *op);
761 : : /**< Callback function called during rte_regexdev_stop(), invoked once per
762 : : * flushed RegEx op.
763 : : */
764 : :
765 : : /** RegEx queue pair configuration structure */
766 : : struct rte_regexdev_qp_conf {
767 : : uint32_t qp_conf_flags;
768 : : /**< Queue pair config flags, See RTE_REGEX_QUEUE_PAIR_CFG_* */
769 : : uint16_t nb_desc;
770 : : /**< The number of descriptors to allocate for this queue pair. */
771 : : regexdev_stop_flush_t cb;
772 : : /**< Callback function called during rte_regexdev_stop(), invoked
773 : : * once per flushed regex op. Value NULL is allowed, in which case
774 : : * callback will not be invoked. This function can be used to properly
775 : : * dispose of outstanding regex ops from response queue,
776 : : * for example ops containing memory pointers.
777 : : * @see rte_regexdev_stop()
778 : : */
779 : : };
780 : :
781 : : /**
782 : : * @warning
783 : : * @b EXPERIMENTAL: this API may change without prior notice.
784 : : *
785 : : * Allocate and set up a RegEx queue pair for a RegEx device.
786 : : *
787 : : * @param dev_id
788 : : * The identifier of the device.
789 : : * @param queue_pair_id
790 : : * The index of the RegEx queue pair to setup. The value must be in the range
791 : : * [0, nb_queue_pairs - 1] previously supplied to rte_regexdev_configure().
792 : : * @param qp_conf
793 : : * The pointer to the configuration data to be used for the RegEx queue pair.
794 : : * NULL value is allowed, in which case default configuration used.
795 : : *
796 : : * @return
797 : : * 0 on success. Otherwise negative errno is returned.
798 : : */
799 : : __rte_experimental
800 : : int
801 : : rte_regexdev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id,
802 : : const struct rte_regexdev_qp_conf *qp_conf);
803 : :
804 : : /**
805 : : * @warning
806 : : * @b EXPERIMENTAL: this API may change without prior notice.
807 : : *
808 : : * Start a RegEx device.
809 : : *
810 : : * The device start step is the last one and consists of setting the RegEx
811 : : * queues to start accepting the pattern matching scan requests.
812 : : *
813 : : * On success, all basic functions exported by the API (RegEx enqueue,
814 : : * RegEx dequeue and so on) can be invoked.
815 : : *
816 : : * @param dev_id
817 : : * RegEx device identifier.
818 : : *
819 : : * @return
820 : : * 0 on success. Otherwise negative errno is returned.
821 : : */
822 : : __rte_experimental
823 : : int
824 : : rte_regexdev_start(uint8_t dev_id);
825 : :
826 : : /**
827 : : * @warning
828 : : * @b EXPERIMENTAL: this API may change without prior notice.
829 : : *
830 : : * Stop a RegEx device.
831 : : *
832 : : * Stop a RegEx device. The device can be restarted with a call to
833 : : * rte_regexdev_start().
834 : : *
835 : : * This function causes all queued response regex ops to be drained in the
836 : : * response queue. While draining ops out of the device,
837 : : * struct rte_regexdev_qp_conf::cb will be invoked for each ops.
838 : : *
839 : : * @param dev_id
840 : : * RegEx device identifier.
841 : : *
842 : : * @return
843 : : * 0 on success. Otherwise negative errno is returned.
844 : : */
845 : : __rte_experimental
846 : : int
847 : : rte_regexdev_stop(uint8_t dev_id);
848 : :
849 : : /**
850 : : * @warning
851 : : * @b EXPERIMENTAL: this API may change without prior notice.
852 : : *
853 : : * Close a RegEx device. The device cannot be restarted!
854 : : *
855 : : * @param dev_id
856 : : * RegEx device identifier
857 : : *
858 : : * @return
859 : : * 0 on success. Otherwise negative errno is returned.
860 : : */
861 : : __rte_experimental
862 : : int
863 : : rte_regexdev_close(uint8_t dev_id);
864 : :
865 : : /* Device get/set attributes */
866 : :
867 : : /** Enumerates RegEx device attribute identifier */
868 : : enum rte_regexdev_attr_id {
869 : : RTE_REGEXDEV_ATTR_SOCKET_ID,
870 : : /**< The NUMA socket id to which the device is connected or
871 : : * a default of zero if the socket could not be determined.
872 : : * datatype: *int*
873 : : * operation: *get*
874 : : */
875 : : RTE_REGEXDEV_ATTR_MAX_MATCHES,
876 : : /**< Maximum number of matches per scan.
877 : : * datatype: *uint8_t*
878 : : * operation: *get* and *set*
879 : : * @see RTE_REGEX_OPS_RSP_MAX_MATCH_F
880 : : */
881 : : RTE_REGEXDEV_ATTR_MAX_SCAN_TIMEOUT,
882 : : /**< Upper bound scan time in ns.
883 : : * datatype: *uint16_t*
884 : : * operation: *get* and *set*
885 : : * @see RTE_REGEX_OPS_RSP_MAX_SCAN_TIMEOUT_F
886 : : */
887 : : RTE_REGEXDEV_ATTR_MAX_PREFIX,
888 : : /**< Maximum number of prefix detected per scan.
889 : : * This would be useful for denial of service detection.
890 : : * datatype: *uint16_t*
891 : : * operation: *get* and *set*
892 : : * @see RTE_REGEX_OPS_RSP_MAX_PREFIX_F
893 : : */
894 : : };
895 : :
896 : : /**
897 : : * @warning
898 : : * @b EXPERIMENTAL: this API may change without prior notice.
899 : : *
900 : : * Get an attribute from a RegEx device.
901 : : *
902 : : * @param dev_id
903 : : * RegEx device identifier.
904 : : * @param attr_id
905 : : * The attribute ID to retrieve.
906 : : * @param attr_value
907 : : * A pointer that will be filled in with the attribute
908 : : * value if successful.
909 : : *
910 : : * @return
911 : : * - 0: Successfully retrieved attribute value.
912 : : * - -EINVAL: Invalid device or *attr_id* provided, or *attr_value* is NULL.
913 : : * - -ENOTSUP: if the device doesn't support specific *attr_id*.
914 : : */
915 : : __rte_experimental
916 : : int
917 : : rte_regexdev_attr_get(uint8_t dev_id, enum rte_regexdev_attr_id attr_id,
918 : : void *attr_value);
919 : :
920 : : /**
921 : : * @warning
922 : : * @b EXPERIMENTAL: this API may change without prior notice.
923 : : *
924 : : * Set an attribute to a RegEx device.
925 : : *
926 : : * @param dev_id
927 : : * RegEx device identifier.
928 : : * @param attr_id
929 : : * The attribute ID to retrieve.
930 : : * @param attr_value
931 : : * Pointer that will be filled in with the attribute value
932 : : * by the application.
933 : : *
934 : : * @return
935 : : * - 0: Successfully applied the attribute value.
936 : : * - -EINVAL: Invalid device or *attr_id* provided, or *attr_value* is NULL.
937 : : * - -ENOTSUP: if the device doesn't support specific *attr_id*.
938 : : */
939 : : __rte_experimental
940 : : int
941 : : rte_regexdev_attr_set(uint8_t dev_id, enum rte_regexdev_attr_id attr_id,
942 : : const void *attr_value);
943 : :
944 : : /* Rule related APIs */
945 : : /** Enumerates RegEx rule operation. */
946 : : enum rte_regexdev_rule_op {
947 : : RTE_REGEX_RULE_OP_ADD,
948 : : /**< Add RegEx rule to rule database. */
949 : : RTE_REGEX_RULE_OP_REMOVE
950 : : /**< Remove RegEx rule from rule database. */
951 : : };
952 : :
953 : : /** Structure to hold a RegEx rule attributes. */
954 : : struct rte_regexdev_rule {
955 : : enum rte_regexdev_rule_op op;
956 : : /**< OP type of the rule either a OP_ADD or OP_DELETE. */
957 : : uint16_t group_id;
958 : : /**< Group identifier to which the rule belongs to. */
959 : : uint32_t rule_id;
960 : : /**< Rule identifier which is returned on successful match. */
961 : : const char *pcre_rule;
962 : : /**< Buffer to hold the PCRE rule. */
963 : : uint16_t pcre_rule_len;
964 : : /**< Length of the PCRE rule. */
965 : : uint64_t rule_flags;
966 : : /* PCRE rule flags. Supported device specific PCRE rules enumerated
967 : : * in struct rte_regexdev_info::rule_flags. For successful rule
968 : : * database update, application needs to provide only supported
969 : : * rule flags.
970 : : * @See RTE_REGEX_PCRE_RULE_*, struct rte_regexdev_info::rule_flags
971 : : */
972 : : };
973 : :
974 : : /**
975 : : * @warning
976 : : * @b EXPERIMENTAL: this API may change without prior notice.
977 : : *
978 : : * Update the local rule set.
979 : : * This functions only modify the rule set in memory.
980 : : * In order for the changes to take effect, the function
981 : : * rte_regexdev_rule_db_compile_active must be called.
982 : : *
983 : : * @param dev_id
984 : : * RegEx device identifier.
985 : : * @param rules
986 : : * Points to an array of *nb_rules* objects of type *rte_regexdev_rule*
987 : : * structure which contain the regex rules attributes to be updated
988 : : * in rule database.
989 : : * @param nb_rules
990 : : * The number of PCRE rules to update the rule database.
991 : : *
992 : : * @return
993 : : * The number of regex rules actually updated on the regex device's rule
994 : : * database. The return value can be less than the value of the *nb_rules*
995 : : * parameter when the regex devices fails to update the rule database or
996 : : * if invalid parameters are specified in a *rte_regexdev_rule*.
997 : : * If the return value is less than *nb_rules*, the remaining PCRE rules
998 : : * at the end of *rules* are not consumed and the caller has to take
999 : : * care of them and rte_errno is set accordingly.
1000 : : * Possible errno values include:
1001 : : * - -EINVAL: Invalid device ID or rules is NULL
1002 : : * - -ENOTSUP: The last processed rule is not supported on this device.
1003 : : * - -ENOSPC: No space available in rule database.
1004 : : *
1005 : : * @see rte_regexdev_rule_db_import(), rte_regexdev_rule_db_export(),
1006 : : * rte_regexdev_rule_db_compile_activate()
1007 : : */
1008 : : __rte_experimental
1009 : : int
1010 : : rte_regexdev_rule_db_update(uint8_t dev_id,
1011 : : const struct rte_regexdev_rule *rules,
1012 : : uint32_t nb_rules);
1013 : :
1014 : : /**
1015 : : * @warning
1016 : : * @b EXPERIMENTAL: this API may change without prior notice.
1017 : : *
1018 : : * Compile local rule set and burn the complied result to the
1019 : : * RegEx device.
1020 : : *
1021 : : * @param dev_id
1022 : : * RegEx device identifier.
1023 : : *
1024 : : * @return
1025 : : * 0 on success, otherwise negative errno.
1026 : : *
1027 : : * @see rte_regexdev_rule_db_import(), rte_regexdev_rule_db_export(),
1028 : : * rte_regexdev_rule_db_update()
1029 : : */
1030 : : __rte_experimental
1031 : : int
1032 : : rte_regexdev_rule_db_compile_activate(uint8_t dev_id);
1033 : :
1034 : : /**
1035 : : * @warning
1036 : : * @b EXPERIMENTAL: this API may change without prior notice.
1037 : : *
1038 : : * Import a prebuilt rule database from a buffer to a RegEx device.
1039 : : *
1040 : : * @param dev_id
1041 : : * RegEx device identifier.
1042 : : * @param rule_db
1043 : : * Points to prebuilt rule database.
1044 : : * @param rule_db_len
1045 : : * Length of the rule database.
1046 : : *
1047 : : * @return
1048 : : * - 0: Successfully updated the prebuilt rule database.
1049 : : * - -EINVAL: Invalid device ID or rule_db is NULL
1050 : : * - -ENOTSUP: Rule database import is not supported on this device.
1051 : : * - -ENOSPC: No space available in rule database.
1052 : : *
1053 : : * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_export()
1054 : : */
1055 : : __rte_experimental
1056 : : int
1057 : : rte_regexdev_rule_db_import(uint8_t dev_id, const char *rule_db,
1058 : : uint32_t rule_db_len);
1059 : :
1060 : : /**
1061 : : * @warning
1062 : : * @b EXPERIMENTAL: this API may change without prior notice.
1063 : : *
1064 : : * Export the prebuilt rule database from a RegEx device to the buffer.
1065 : : *
1066 : : * @param dev_id
1067 : : * RegEx device identifier.
1068 : : * @param[out] rule_db
1069 : : * Block of memory to insert the rule database. Must be at least size in
1070 : : * capacity. If set to NULL, function returns required capacity.
1071 : : *
1072 : : * @return
1073 : : * - 0: Successfully exported the prebuilt rule database.
1074 : : * - size: If rule_db set to NULL then required capacity for *rule_db*
1075 : : * - -EINVAL: Invalid device ID
1076 : : * - -ENOTSUP: Rule database export is not supported on this device.
1077 : : *
1078 : : * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_import()
1079 : : */
1080 : : __rte_experimental
1081 : : int
1082 : : rte_regexdev_rule_db_export(uint8_t dev_id, char *rule_db);
1083 : :
1084 : : /* Extended statistics */
1085 : : /** Maximum name length for extended statistics counters */
1086 : : #define RTE_REGEXDEV_XSTATS_NAME_SIZE 64
1087 : :
1088 : : /**
1089 : : * A name-key lookup element for extended statistics.
1090 : : *
1091 : : * This structure is used to map between names and ID numbers
1092 : : * for extended RegEx device statistics.
1093 : : */
1094 : : struct rte_regexdev_xstats_map {
1095 : : uint16_t id;
1096 : : /**< xstat identifier */
1097 : : char name[RTE_REGEXDEV_XSTATS_NAME_SIZE];
1098 : : /**< xstat name */
1099 : : };
1100 : :
1101 : : /**
1102 : : * @warning
1103 : : * @b EXPERIMENTAL: this API may change without prior notice.
1104 : : *
1105 : : * Retrieve names of extended statistics of a regex device.
1106 : : *
1107 : : * @param dev_id
1108 : : * The identifier of the regex device.
1109 : : * @param[out] xstats_map
1110 : : * Block of memory to insert id and names into. Must be at least size in
1111 : : * capacity. If set to NULL, function returns required capacity.
1112 : : * @return
1113 : : * - Positive value on success:
1114 : : * -The return value is the number of entries filled in the stats map.
1115 : : * -If xstats_map set to NULL then required capacity for xstats_map.
1116 : : * - Negative value on error:
1117 : : * -ENODEV for invalid *dev_id*
1118 : : * -ENOTSUP if the device doesn't support this function.
1119 : : */
1120 : : __rte_experimental
1121 : : int
1122 : : rte_regexdev_xstats_names_get(uint8_t dev_id,
1123 : : struct rte_regexdev_xstats_map *xstats_map);
1124 : :
1125 : : /**
1126 : : * @warning
1127 : : * @b EXPERIMENTAL: this API may change without prior notice.
1128 : : *
1129 : : * Retrieve extended statistics of an regex device.
1130 : : *
1131 : : * @param dev_id
1132 : : * The identifier of the device.
1133 : : * @param ids
1134 : : * The id numbers of the stats to get. The ids can be got from the stat
1135 : : * position in the stat list from rte_regexdev_xstats_names_get(), or
1136 : : * by using rte_regexdev_xstats_by_name_get().
1137 : : * @param values
1138 : : * The values for each stats request by ID.
1139 : : * @param nb_values
1140 : : * The number of stats requested.
1141 : : * @return
1142 : : * - Positive value: number of stat entries filled into the values array
1143 : : * - Negative value on error:
1144 : : * -ENODEV for invalid *dev_id*
1145 : : * -ENOTSUP if the device doesn't support this function.
1146 : : */
1147 : : __rte_experimental
1148 : : int
1149 : : rte_regexdev_xstats_get(uint8_t dev_id, const uint16_t *ids,
1150 : : uint64_t *values, uint16_t nb_values);
1151 : :
1152 : : /**
1153 : : * @warning
1154 : : * @b EXPERIMENTAL: this API may change without prior notice.
1155 : : *
1156 : : * Retrieve the value of a single stat by requesting it by name.
1157 : : *
1158 : : * @param dev_id
1159 : : * The identifier of the device.
1160 : : * @param name
1161 : : * The stat name to retrieve.
1162 : : * @param id
1163 : : * If non-NULL, the numerical id of the stat will be returned, so that further
1164 : : * requests for the stat can be got using rte_regexdev_xstats_get, which will
1165 : : * be faster as it doesn't need to scan a list of names for the stat.
1166 : : * @param[out] value
1167 : : * Must be non-NULL, retrieved xstat value will be stored in this address.
1168 : : *
1169 : : * @return
1170 : : * - 0: Successfully retrieved xstat value.
1171 : : * - -EINVAL: invalid parameters
1172 : : * - -ENOTSUP: if not supported.
1173 : : */
1174 : : __rte_experimental
1175 : : int
1176 : : rte_regexdev_xstats_by_name_get(uint8_t dev_id, const char *name,
1177 : : uint16_t *id, uint64_t *value);
1178 : :
1179 : : /**
1180 : : * @warning
1181 : : * @b EXPERIMENTAL: this API may change without prior notice.
1182 : : *
1183 : : * Reset the values of the xstats of the selected component in the device.
1184 : : *
1185 : : * @param dev_id
1186 : : * The identifier of the device.
1187 : : * @param ids
1188 : : * Selects specific statistics to be reset. When NULL, all statistics will be
1189 : : * reset. If non-NULL, must point to array of at least *nb_ids* size.
1190 : : * @param nb_ids
1191 : : * The number of ids available from the *ids* array. Ignored when ids is NULL.
1192 : : *
1193 : : * @return
1194 : : * - 0: Successfully reset the statistics to zero.
1195 : : * - -EINVAL: invalid parameters.
1196 : : * - -ENOTSUP: if not supported.
1197 : : */
1198 : : __rte_experimental
1199 : : int
1200 : : rte_regexdev_xstats_reset(uint8_t dev_id, const uint16_t *ids,
1201 : : uint16_t nb_ids);
1202 : :
1203 : : /**
1204 : : * @warning
1205 : : * @b EXPERIMENTAL: this API may change without prior notice.
1206 : : *
1207 : : * Trigger the RegEx device self test.
1208 : : *
1209 : : * @param dev_id
1210 : : * The identifier of the device.
1211 : : * @return
1212 : : * - 0: Selftest successful.
1213 : : * - -ENOTSUP if the device doesn't support selftest.
1214 : : * - other values < 0 on failure.
1215 : : */
1216 : : __rte_experimental
1217 : : int
1218 : : rte_regexdev_selftest(uint8_t dev_id);
1219 : :
1220 : : /**
1221 : : * @warning
1222 : : * @b EXPERIMENTAL: this API may change without prior notice.
1223 : : *
1224 : : * Dump internal information about *dev_id* to the FILE* provided in *f*.
1225 : : *
1226 : : * @param dev_id
1227 : : * The identifier of the device.
1228 : : * @param f
1229 : : * A pointer to a file for output.
1230 : : *
1231 : : * @return
1232 : : * 0 on success, negative errno on failure.
1233 : : */
1234 : : __rte_experimental
1235 : : int
1236 : : rte_regexdev_dump(uint8_t dev_id, FILE *f);
1237 : :
1238 : : /* Fast path APIs */
1239 : :
1240 : : /**
1241 : : * The generic *rte_regexdev_match* structure to hold the RegEx match
1242 : : * attributes.
1243 : : * @see struct rte_regex_ops::matches
1244 : : */
1245 : : struct rte_regexdev_match {
1246 : : union {
1247 : : uint64_t u64;
1248 : : struct {
1249 : : uint32_t rule_id:20;
1250 : : /**< Rule identifier to which the pattern matched.
1251 : : * @see struct rte_regexdev_rule::rule_id
1252 : : */
1253 : : uint32_t group_id:12;
1254 : : /**< Group identifier of the rule which the pattern
1255 : : * matched. @see struct rte_regexdev_rule::group_id
1256 : : */
1257 : : uint16_t start_offset;
1258 : : /**< Starting Byte Position for matched rule. */
1259 : : union {
1260 : : uint16_t len;
1261 : : /**< Length of match in bytes */
1262 : : uint16_t end_offset;
1263 : : /**< The end offset of the match. In case
1264 : : * MATCH_AS_END configuration is enabled.
1265 : : * @see RTE_REGEXDEV_CFG_MATCH_AS_END
1266 : : */
1267 : : };
1268 : : };
1269 : : };
1270 : : };
1271 : :
1272 : : /* Enumerates RegEx request flags. */
1273 : : #define RTE_REGEX_OPS_REQ_GROUP_ID0_VALID_F (1 << 0)
1274 : : /**< Set when struct rte_regexdev_rule::group_id0 is valid. */
1275 : :
1276 : : #define RTE_REGEX_OPS_REQ_GROUP_ID1_VALID_F (1 << 1)
1277 : : /**< Set when struct rte_regexdev_rule::group_id1 is valid. */
1278 : :
1279 : : #define RTE_REGEX_OPS_REQ_GROUP_ID2_VALID_F (1 << 2)
1280 : : /**< Set when struct rte_regexdev_rule::group_id2 is valid. */
1281 : :
1282 : : #define RTE_REGEX_OPS_REQ_GROUP_ID3_VALID_F (1 << 3)
1283 : : /**< Set when struct rte_regexdev_rule::group_id3 is valid. */
1284 : :
1285 : : #define RTE_REGEX_OPS_REQ_STOP_ON_MATCH_F (1 << 4)
1286 : : /**< The RegEx engine will stop scanning and return the first match. */
1287 : :
1288 : : #define RTE_REGEX_OPS_REQ_MATCH_HIGH_PRIORITY_F (1 << 5)
1289 : : /**< In High Priority mode a maximum of one match will be returned per scan to
1290 : : * reduce the post-processing required by the application. The match with the
1291 : : * lowest Rule id, lowest start pointer and lowest match length will be
1292 : : * returned.
1293 : : *
1294 : : * @see struct rte_regex_ops::nb_actual_matches
1295 : : * @see struct rte_regex_ops::nb_matches
1296 : : */
1297 : :
1298 : :
1299 : : /* Enumerates RegEx response flags. */
1300 : : #define RTE_REGEX_OPS_RSP_PMI_SOJ_F (1 << 0)
1301 : : /**< Indicates that the RegEx device has encountered a partial match at the
1302 : : * start of scan in the given buffer.
1303 : : *
1304 : : * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F
1305 : : */
1306 : :
1307 : : #define RTE_REGEX_OPS_RSP_PMI_EOJ_F (1 << 1)
1308 : : /**< Indicates that the RegEx device has encountered a partial match at the
1309 : : * end of scan in the given buffer.
1310 : : *
1311 : : * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F
1312 : : */
1313 : :
1314 : : #define RTE_REGEX_OPS_RSP_MAX_SCAN_TIMEOUT_F (1 << 2)
1315 : : /**< Indicates that the RegEx device has exceeded the max timeout while
1316 : : * scanning the given buffer.
1317 : : *
1318 : : * @see RTE_REGEXDEV_ATTR_MAX_SCAN_TIMEOUT
1319 : : */
1320 : :
1321 : : #define RTE_REGEX_OPS_RSP_MAX_MATCH_F (1 << 3)
1322 : : /**< Indicates that the RegEx device has exceeded the max matches while
1323 : : * scanning the given buffer.
1324 : : *
1325 : : * @see RTE_REGEXDEV_ATTR_MAX_MATCHES
1326 : : */
1327 : :
1328 : : #define RTE_REGEX_OPS_RSP_MAX_PREFIX_F (1 << 4)
1329 : : /**< Indicates that the RegEx device has reached the max allowed prefix length
1330 : : * while scanning the given buffer.
1331 : : *
1332 : : * @see RTE_REGEXDEV_ATTR_MAX_PREFIX
1333 : : */
1334 : :
1335 : : #define RTE_REGEX_OPS_RSP_RESOURCE_LIMIT_REACHED_F (1 << 4)
1336 : : /**< Indicates that the RegEx device has reached the max allowed resource
1337 : : * allowed while scanning the given buffer.
1338 : : */
1339 : :
1340 : : /**
1341 : : * The generic *rte_regex_ops* structure to hold the RegEx attributes
1342 : : * for enqueue and dequeue operation.
1343 : : */
1344 : : struct rte_regex_ops {
1345 : : /* W0 */
1346 : : uint16_t req_flags;
1347 : : /**< Request flags for the RegEx ops.
1348 : : * @see RTE_REGEX_OPS_REQ_*
1349 : : */
1350 : : uint16_t rsp_flags;
1351 : : /**< Response flags for the RegEx ops.
1352 : : * @see RTE_REGEX_OPS_RSP_*
1353 : : */
1354 : : uint16_t nb_actual_matches;
1355 : : /**< The total number of actual matches detected by the Regex device.*/
1356 : : uint16_t nb_matches;
1357 : : /**< The total number of matches returned by the RegEx device for this
1358 : : * scan. The size of *rte_regex_ops::matches* zero length array will be
1359 : : * this value.
1360 : : *
1361 : : * @see struct rte_regex_ops::matches, struct rte_regexdev_match
1362 : : */
1363 : :
1364 : : /* W1 */
1365 : : struct rte_mbuf *mbuf; /**< source mbuf, to search in. */
1366 : :
1367 : : /* W2 */
1368 : : uint16_t group_id0;
1369 : : /**< First group_id to match the rule against. At minimum one group
1370 : : * should be valid. Behaviour is undefined non of the groups are valid.
1371 : : *
1372 : : * @see RTE_REGEX_OPS_REQ_GROUP_ID0_VALID_F
1373 : : */
1374 : : uint16_t group_id1;
1375 : : /**< Second group_id to match the rule against.
1376 : : *
1377 : : * @see RTE_REGEX_OPS_REQ_GROUP_ID1_VALID_F
1378 : : */
1379 : : uint16_t group_id2;
1380 : : /**< Third group_id to match the rule against.
1381 : : *
1382 : : * @see RTE_REGEX_OPS_REQ_GROUP_ID2_VALID_F
1383 : : */
1384 : : uint16_t group_id3;
1385 : : /**< Forth group_id to match the rule against.
1386 : : *
1387 : : * @see RTE_REGEX_OPS_REQ_GROUP_ID3_VALID_F
1388 : : */
1389 : :
1390 : : /* W3 */
1391 : : union {
1392 : : uint64_t user_id;
1393 : : /**< Application specific opaque value. An application may use
1394 : : * this field to hold application specific value to share
1395 : : * between dequeue and enqueue operation.
1396 : : * Implementation should not modify this field.
1397 : : */
1398 : : void *user_ptr;
1399 : : /**< Pointer representation of *user_id* */
1400 : : };
1401 : :
1402 : : /* W4 */
1403 : : union {
1404 : : uint64_t cross_buf_id;
1405 : : /**< ID used by the RegEx device in order to support cross
1406 : : * packet detection.
1407 : : * This ID is returned from the RegEx device on the dequeue
1408 : : * function. The application must send it back when calling
1409 : : * enqueue with the following packet.
1410 : : */
1411 : : void *cross_buf_ptr;
1412 : : /**< Pointer representation of *corss_buf_id* */
1413 : : };
1414 : :
1415 : : /* W5 */
1416 : : struct rte_regexdev_match matches[];
1417 : : /**< Zero length array to hold the match tuples.
1418 : : * The struct rte_regex_ops::nb_matches value holds the number of
1419 : : * elements in this array.
1420 : : *
1421 : : * @see struct rte_regex_ops::nb_matches
1422 : : */
1423 : : };
1424 : :
1425 : : #include "rte_regexdev_core.h"
1426 : :
1427 : : #ifdef __cplusplus
1428 : : extern "C" {
1429 : : #endif
1430 : :
1431 : : /**
1432 : : * @warning
1433 : : * @b EXPERIMENTAL: this API may change without prior notice.
1434 : : *
1435 : : * Enqueue a burst of scan request on a RegEx device.
1436 : : *
1437 : : * The rte_regexdev_enqueue_burst() function is invoked to place
1438 : : * regex operations on the queue *qp_id* of the device designated by
1439 : : * its *dev_id*.
1440 : : *
1441 : : * The *nb_ops* parameter is the number of operations to process which are
1442 : : * supplied in the *ops* array of *rte_regexdev_op* structures.
1443 : : *
1444 : : * The rte_regexdev_enqueue_burst() function returns the number of
1445 : : * operations it actually enqueued for processing. A return value equal to
1446 : : * *nb_ops* means that all packets have been enqueued.
1447 : : *
1448 : : * @param dev_id
1449 : : * The identifier of the device.
1450 : : * @param qp_id
1451 : : * The index of the queue pair which packets are to be enqueued for
1452 : : * processing. The value must be in the range [0, nb_queue_pairs - 1]
1453 : : * previously supplied to rte_regexdev_configure().
1454 : : * @param ops
1455 : : * The address of an array of *nb_ops* pointers to *rte_regexdev_op*
1456 : : * structures which contain the regex operations to be processed.
1457 : : * @param nb_ops
1458 : : * The number of operations to process.
1459 : : *
1460 : : * @return
1461 : : * The number of operations actually enqueued on the regex device. The return
1462 : : * value can be less than the value of the *nb_ops* parameter when the
1463 : : * regex devices queue is full or if invalid parameters are specified in
1464 : : * a *rte_regexdev_op*. If the return value is less than *nb_ops*, the
1465 : : * remaining ops at the end of *ops* are not consumed and the caller has
1466 : : * to take care of them.
1467 : : */
1468 : : __rte_experimental
1469 : : static inline uint16_t
1470 : : rte_regexdev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
1471 : : struct rte_regex_ops **ops, uint16_t nb_ops)
1472 : : {
1473 : : struct rte_regexdev *dev = &rte_regex_devices[dev_id];
1474 : : #ifdef RTE_LIBRTE_REGEXDEV_DEBUG
1475 : : RTE_REGEXDEV_VALID_DEV_ID_OR_ERR_RET(dev_id, -EINVAL);
1476 : : if (*dev->enqueue == NULL)
1477 : : return -ENOTSUP;
1478 : : if (qp_id >= dev->data->dev_conf.nb_queue_pairs) {
1479 : : RTE_REGEXDEV_LOG_LINE(ERR, "Invalid queue %d", qp_id);
1480 : : return -EINVAL;
1481 : : }
1482 : : #endif
1483 : 0 : return (*dev->enqueue)(dev, qp_id, ops, nb_ops);
1484 : : }
1485 : :
1486 : : /**
1487 : : * @warning
1488 : : * @b EXPERIMENTAL: this API may change without prior notice.
1489 : : *
1490 : : * Dequeue a burst of scan response from a queue on the RegEx device.
1491 : : * The dequeued operation are stored in *rte_regexdev_op* structures
1492 : : * whose pointers are supplied in the *ops* array.
1493 : : *
1494 : : * The rte_regexdev_dequeue_burst() function returns the number of ops
1495 : : * actually dequeued, which is the number of *rte_regexdev_op* data structures
1496 : : * effectively supplied into the *ops* array.
1497 : : *
1498 : : * A return value equal to *nb_ops* indicates that the queue contained
1499 : : * at least *nb_ops* operations, and this is likely to signify that other
1500 : : * processed operations remain in the devices output queue. Applications
1501 : : * implementing a "retrieve as many processed operations as possible" policy
1502 : : * can check this specific case and keep invoking the
1503 : : * rte_regexdev_dequeue_burst() function until a value less than
1504 : : * *nb_ops* is returned.
1505 : : *
1506 : : * The rte_regexdev_dequeue_burst() function does not provide any error
1507 : : * notification to avoid the corresponding overhead.
1508 : : *
1509 : : * @param dev_id
1510 : : * The RegEx device identifier
1511 : : * @param qp_id
1512 : : * The index of the queue pair from which to retrieve processed packets.
1513 : : * The value must be in the range [0, nb_queue_pairs - 1] previously
1514 : : * supplied to rte_regexdev_configure().
1515 : : * @param ops
1516 : : * The address of an array of pointers to *rte_regexdev_op* structures
1517 : : * that must be large enough to store *nb_ops* pointers in it.
1518 : : * @param nb_ops
1519 : : * The maximum number of operations to dequeue.
1520 : : *
1521 : : * @return
1522 : : * The number of operations actually dequeued, which is the number
1523 : : * of pointers to *rte_regexdev_op* structures effectively supplied to the
1524 : : * *ops* array. If the return value is less than *nb_ops*, the remaining
1525 : : * ops at the end of *ops* are not consumed and the caller has to take care
1526 : : * of them.
1527 : : */
1528 : : __rte_experimental
1529 : : static inline uint16_t
1530 : : rte_regexdev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
1531 : : struct rte_regex_ops **ops, uint16_t nb_ops)
1532 : : {
1533 : : struct rte_regexdev *dev = &rte_regex_devices[dev_id];
1534 : : #ifdef RTE_LIBRTE_REGEXDEV_DEBUG
1535 : : RTE_REGEXDEV_VALID_DEV_ID_OR_ERR_RET(dev_id, -EINVAL);
1536 : : if (*dev->dequeue == NULL)
1537 : : return -ENOTSUP;
1538 : : if (qp_id >= dev->data->dev_conf.nb_queue_pairs) {
1539 : : RTE_REGEXDEV_LOG_LINE(ERR, "Invalid queue %d", qp_id);
1540 : : return -EINVAL;
1541 : : }
1542 : : #endif
1543 : 0 : return (*dev->dequeue)(dev, qp_id, ops, nb_ops);
1544 : : }
1545 : :
1546 : : #ifdef __cplusplus
1547 : : }
1548 : : #endif
1549 : :
1550 : : #endif /* _RTE_REGEXDEV_H_ */
|
