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
7 #ifndef _RTE_REGEXDEV_H_
8 #define _RTE_REGEXDEV_H_
13 * RTE RegEx Device API
15 * Defines RTE RegEx Device APIs for RegEx operations and its provisioning.
17 * The RegEx Device API is composed of two parts:
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.
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.
27 * RegEx device components and definitions:
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 * +-----------------+ | | |
40 * | | | | | | +------+
41 * | | +--+--o queue |<======>|Core 1|
42 * Rule|Database | | | pair 1 | | |
43 * +------+----------+ | | +--------+ +------+
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 * | +-------------+ | +--------+ +------+
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()
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”.
67 * RegEx device: A hardware or software-based implementation of RegEx
68 * device API for PCRE based pattern matching syntax and semantics.
70 * PCRE RegEx syntax and semantics specification:
71 * http://regexkit.sourceforge.net/Documentation/pcre/pcrepattern.html
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.
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.
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.
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.
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
96 * Scan: A pattern matching request through *enqueue* API.
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
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.
110 * In all functions of the RegEx API, the RegEx device is
111 * designated by an integer >= 0 named the device identifier *dev_id*
113 * At the RegEx driver level, RegEx devices are represented by a generic
114 * data structure of type *rte_regexdev*.
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.
123 * The role of the device init function consists of resetting the hardware or
124 * software RegEx driver implementations.
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
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()
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
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.
149 * Finally, an application can close a RegEx device by invoking the
150 * rte_regexdev_close() function.
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
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
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.
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.
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.
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.
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.
181 * Typical application utilisation of the RegEx device API will follow the
182 * following programming flow.
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()
201 #include <rte_common.h>
202 #include <rte_config.h>
204 #include <rte_errno.h>
205 #include <rte_mbuf.h>
206 #include <rte_memory.h>
208 #define RTE_REGEXDEV_NAME_MAX_LEN RTE_DEV_NAME_MAX_LEN
210 extern int rte_regexdev_logtype;
212 #define RTE_REGEXDEV_LOG(level, ...) \
213 rte_log(RTE_LOG_ ## level, rte_regexdev_logtype, "" __VA_ARGS__)
215 /* Macros to check for valid port */
216 #define RTE_REGEXDEV_VALID_DEV_ID_OR_ERR_RET(dev_id, retval) do { \
217 if (!rte_regexdev_is_valid_dev(dev_id)) { \
218 RTE_REGEXDEV_LOG(ERR, "Invalid dev_id=%u\n", dev_id); \
223 #define RTE_REGEXDEV_VALID_DEV_ID_OR_RET(dev_id) do { \
224 if (!rte_regexdev_is_valid_dev(dev_id)) { \
225 RTE_REGEXDEV_LOG(ERR, "Invalid dev_id=%u\n", dev_id); \
231 * Check if dev_id is ready.
234 * The dev identifier of the RegEx device.
237 * - 0 if device state is not in ready state.
238 * - 1 if device state is ready state.
240 int rte_regexdev_is_valid_dev(uint16_t dev_id);
244 * @b EXPERIMENTAL: this API may change without prior notice.
246 * Get the total number of RegEx devices that have been successfully
250 * The total number of usable RegEx devices.
254 rte_regexdev_count(void);
258 * @b EXPERIMENTAL: this API may change without prior notice.
260 * Get the device identifier for the named RegEx device.
263 * RegEx device name to select the RegEx device identifier.
266 * Returns RegEx device identifier on success.
267 * - <0: Failure to find named RegEx device.
271 rte_regexdev_get_dev_id(const char *name);
273 /* Enumerates RegEx device capabilities */
274 #define RTE_REGEXDEV_CAPA_RUNTIME_COMPILATION_F (1ULL << 0)
275 /**< RegEx device does support compiling the rules at runtime unlike
276 * loading only the pre-built rule database using
277 * struct rte_regexdev_config::rule_db in rte_regexdev_configure()
279 * @see struct rte_regexdev_config::rule_db, rte_regexdev_configure()
280 * @see struct rte_regexdev_info::regexdev_capa
283 #define RTE_REGEXDEV_CAPA_SUPP_PCRE_START_ANCHOR_F (1ULL << 1)
284 /**< RegEx device support PCRE Anchor to start of match flag.
285 * Example RegEx is `/\Gfoo\d/`. Here `\G` asserts position at the end of the
286 * previous match or the start of the string for the first match.
287 * This position will change each time the RegEx is applied to the subject
288 * string. If the RegEx is applied to `foo1foo2Zfoo3` the first two matches will
289 * be successful for `foo1foo2` and fail for `Zfoo3`.
291 * @see struct rte_regexdev_info::regexdev_capa
294 #define RTE_REGEXDEV_CAPA_SUPP_PCRE_ATOMIC_GROUPING_F (1ULL << 2)
295 /**< RegEx device support PCRE Atomic grouping.
296 * Atomic groups are represented by `(?>)`. An atomic group is a group that,
297 * when the RegEx engine exits from it, automatically throws away all
298 * backtracking positions remembered by any tokens inside the group.
299 * Example RegEx is `a(?>bc|b)c` if the given patterns are `abc` and `abcc` then
300 * `a(bc|b)c` matches both where as `a(?>bc|b)c` matches only abcc because
301 * atomic groups don't allow backtracking back to `b`.
303 * @see struct rte_regexdev_info::regexdev_capa
306 #define RTE_REGEXDEV_SUPP_PCRE_BACKTRACKING_CTRL_F (1ULL << 3)
307 /**< RegEx device support PCRE backtracking control verbs.
308 * Some examples of backtracking verbs are (*COMMIT), (*ACCEPT), (*FAIL),
311 * @see struct rte_regexdev_info::regexdev_capa
314 #define RTE_REGEXDEV_SUPP_PCRE_CALLOUTS_F (1ULL << 4)
315 /**< RegEx device support PCRE callouts.
316 * PCRE supports calling external function in between matches by using `(?C)`.
317 * Example RegEx `ABC(?C)D` if a given patter is `ABCD` then the RegEx engine
318 * will parse ABC perform a userdefined callout and return a successful match at
321 * @see struct rte_regexdev_info::regexdev_capa
324 #define RTE_REGEXDEV_SUPP_PCRE_BACKREFERENCE_F (1ULL << 5)
325 /**< RegEx device support PCRE backreference.
326 * Example RegEx is `(\2ABC|(GHI))+` `\2` matches the same text as most recently
327 * matched by the 2nd capturing group i.e. `GHI`.
329 * @see struct rte_regexdev_info::regexdev_capa
332 #define RTE_REGEXDEV_SUPP_PCRE_GREEDY_F (1ULL << 6)
333 /**< RegEx device support PCRE Greedy mode.
334 * For example if the RegEx is `AB\d*?` then `*?` represents zero or unlimited
335 * matches. In greedy mode the pattern `AB12345` will be matched completely
336 * where as the ungreedy mode `AB` will be returned as the match.
338 * @see struct rte_regexdev_info::regexdev_capa
341 #define RTE_REGEXDEV_SUPP_PCRE_MATCH_ALL_F (1ULL << 7)
342 /**< RegEx device support match all mode.
343 * For example if the RegEx is `AB\d*?` then `*?` represents zero or unlimited
344 * matches. In match all mode the pattern `AB12345` will return 6 matches.
345 * AB, AB1, AB12, AB123, AB1234, AB12345.
347 * @see struct rte_regexdev_info::regexdev_capa
350 #define RTE_REGEXDEV_SUPP_PCRE_LOOKAROUND_ASRT_F (1ULL << 8)
351 /**< RegEx device support PCRE Lookaround assertions
352 * (Zero-width assertions). Example RegEx is `[a-z]+\d+(?=!{3,})` if
353 * the given pattern is `dwad1234!` the RegEx engine doesn't report any matches
354 * because the assert `(?=!{3,})` fails. The pattern `dwad123!!!` would return a
357 * @see struct rte_regexdev_info::regexdev_capa
360 #define RTE_REGEXDEV_SUPP_PCRE_MATCH_POINT_RST_F (1ULL << 9)
361 /**< RegEx device doesn't support PCRE match point reset directive.
362 * Example RegEx is `[a-z]+\K\d+` if the pattern is `dwad123`
363 * then even though the entire pattern matches only `123`
364 * is reported as a match.
366 * @see struct rte_regexdev_info::regexdev_capa
369 #define RTE_REGEXDEV_SUPP_NEWLINE_CONVENTIONS_F (1ULL << 10)
370 /**< RegEx support PCRE newline convention.
371 * Newline conventions are represented as follows:
372 * (*CR) carriage return
374 * (*CRLF) carriage return, followed by linefeed
375 * (*ANYCRLF) any of the three above
376 * (*ANY) all Unicode newline sequences
378 * @see struct rte_regexdev_info::regexdev_capa
381 #define RTE_REGEXDEV_SUPP_PCRE_NEWLINE_SEQ_F (1ULL << 11)
382 /**< RegEx device support PCRE newline sequence.
383 * The escape sequence `\R` will match any newline sequence.
384 * It is equivalent to: `(?>\r\n|\n|\x0b|\f|\r|\x85)`.
386 * @see struct rte_regexdev_info::regexdev_capa
389 #define RTE_REGEXDEV_SUPP_PCRE_POSSESSIVE_QUALIFIERS_F (1ULL << 12)
390 /**< RegEx device support PCRE possessive qualifiers.
391 * Example RegEx possessive qualifiers `*+`, `++`, `?+`, `{m,n}+`.
392 * Possessive quantifier repeats the token as many times as possible and it does
393 * not give up matches as the engine backtracks. With a possessive quantifier,
394 * the deal is all or nothing.
396 * @see struct rte_regexdev_info::regexdev_capa
399 #define RTE_REGEXDEV_SUPP_PCRE_SUBROUTINE_REFERENCES_F (1ULL << 13)
400 /**< RegEx device support PCRE Subroutine references.
401 * PCRE Subroutine references allow for sub patterns to be assessed
402 * as part of the RegEx. Example RegEx is `(foo|fuzz)\g<1>+bar` matches the
403 * pattern `foofoofuzzfoofuzzbar`.
405 * @see struct rte_regexdev_info::regexdev_capa
408 #define RTE_REGEXDEV_SUPP_PCRE_UTF_8_F (1ULL << 14)
409 /**< RegEx device support UTF-8 character encoding.
411 * @see struct rte_regexdev_info::pcre_unsup_flags
414 #define RTE_REGEXDEV_SUPP_PCRE_UTF_16_F (1ULL << 15)
415 /**< RegEx device support UTF-16 character encoding.
417 * @see struct rte_regexdev_info::regexdev_capa
420 #define RTE_REGEXDEV_SUPP_PCRE_UTF_32_F (1ULL << 16)
421 /**< RegEx device support UTF-32 character encoding.
423 * @see struct rte_regexdev_info::regexdev_capa
426 #define RTE_REGEXDEV_SUPP_PCRE_WORD_BOUNDARY_F (1ULL << 17)
427 /**< RegEx device support word boundaries.
428 * The meta character `\b` represents word boundary anchor.
430 * @see struct rte_regexdev_info::regexdev_capa
433 #define RTE_REGEXDEV_SUPP_PCRE_FORWARD_REFERENCES_F (1ULL << 18)
434 /**< RegEx device support Forward references.
435 * Forward references allow you to use a back reference to a group that appears
436 * later in the RegEx. Example RegEx is `(\3ABC|(DEF|(GHI)))+` matches the
437 * following string `GHIGHIABCDEF`.
439 * @see struct rte_regexdev_info::regexdev_capa
442 #define RTE_REGEXDEV_SUPP_MATCH_AS_END_F (1ULL << 19)
443 /**< RegEx device support match as end.
444 * Match as end means that the match result holds the end offset of the
445 * detected match. No len value is set.
446 * If the device doesn't support this feature it means the match
447 * result holds the starting position of match and the length of the match.
449 * @see struct rte_regexdev_info::regexdev_capa
452 #define RTE_REGEXDEV_SUPP_CROSS_BUFFER_F (1ULL << 20)
453 /**< RegEx device support cross buffer match.
454 * Cross buffer matching means that the match can be detected even if the
455 * string was started in previous buffer.
456 * In case the device is configured as RTE_REGEXDEV_CFG_MATCH_AS_END
457 * the end offset will be relative for the first packet.
458 * For example RegEx is ABC the first buffer is xxxx second buffer yyyA and
459 * the last buffer BCzz.
460 * In case the match as end is configured the end offset will be 10.
462 * @see RTE_REGEXDEV_CFG_MATCH_AS_END_F
463 * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F
464 * @see RTE_REGEX_OPS_RSP_PMI_SOJ_F
465 * @see RTE_REGEX_OPS_RSP_PMI_EOJ_F
468 #define RTE_REGEXDEV_SUPP_MATCH_ALL_F (1ULL << 21)
469 /**< RegEx device support match all.
470 * Match all means that the RegEx engine will return all possible matches.
471 * For example, assume the RegEx is `A+b`, given the input AAAb the
472 * returned matches will be: Ab, AAb and AAAb.
474 * @see RTE_REGEXDEV_CFG_MATCH_ALL_F
477 #define RTE_REGEXDEV_CAPA_QUEUE_PAIR_OOS_F (1ULL << 22)
478 /**< RegEx device supports out of order scan.
479 * Out of order scan means the response of a specific job can be returned as
480 * soon as it is ready even if previous jobs on the same queue didn't complete.
482 * @see RTE_REGEX_QUEUE_PAIR_CFG_OOS_F
483 * @see struct rte_regexdev_info::regexdev_capa
486 /* Enumerates PCRE rule flags */
487 #define RTE_REGEX_PCRE_RULE_ALLOW_EMPTY_F (1ULL << 0)
488 /**< When this flag is set, the pattern that can match against an empty string,
489 * such as `.*` are allowed.
491 * @see struct rte_regexdev_info::rule_flags
492 * @see struct rte_regexdev_rule::rule_flags
495 #define RTE_REGEX_PCRE_RULE_ANCHORED_F (1ULL << 1)
496 /**< When this flag is set, the pattern is forced to be "anchored", that is, it
497 * is constrained to match only at the first matching point in the string that
498 * is being searched. Similar to `^` and represented by `\A`.
500 * @see struct rte_regexdev_info::rule_flags
501 * @see struct rte_regexdev_rule::rule_flags
504 #define RTE_REGEX_PCRE_RULE_CASELESS_F (1ULL << 2)
505 /**< When this flag is set, letters in the pattern match both upper and lower
506 * case letters in the subject.
508 * @see struct rte_regexdev_info::rule_flags
509 * @see struct rte_regexdev_rule::rule_flags
512 #define RTE_REGEX_PCRE_RULE_DOTALL_F (1ULL << 3)
513 /**< When this flag is set, a dot metacharacter in the pattern matches any
514 * character, including one that indicates a newline.
516 * @see struct rte_regexdev_info::rule_flags
517 * @see struct rte_regexdev_rule::rule_flags
520 #define RTE_REGEX_PCRE_RULE_DUPNAMES_F (1ULL << 4)
521 /**< When this flag is set, names used to identify capture groups need not be
524 * @see struct rte_regexdev_info::rule_flags
525 * @see struct rte_regexdev_rule::rule_flags
528 #define RTE_REGEX_PCRE_RULE_EXTENDED_F (1ULL << 5)
529 /**< When this flag is set, most white space characters in the pattern are
530 * totally ignored except when escaped or inside a character class.
532 * @see struct rte_regexdev_info::rule_flags
533 * @see struct rte_regexdev_rule::rule_flags
536 #define RTE_REGEX_PCRE_RULE_MATCH_UNSET_BACKREF_F (1ULL << 6)
537 /**< When this flag is set, a backreference to an unset capture group matches an
540 * @see struct rte_regexdev_info::rule_flags
541 * @see struct rte_regexdev_rule::rule_flags
544 #define RTE_REGEX_PCRE_RULE_MULTILINE_F (1ULL << 7)
545 /**< When this flag is set, the `^` and `$` constructs match immediately
546 * following or immediately before internal newlines in the subject string,
547 * respectively, as well as at the very start and end.
549 * @see struct rte_regexdev_info::rule_flags
550 * @see struct rte_regexdev_rule::rule_flags
553 #define RTE_REGEX_PCRE_RULE_NO_AUTO_CAPTURE_F (1ULL << 8)
554 /**< When this Flag is set, it disables the use of numbered capturing
555 * parentheses in the pattern. References to capture groups (backreferences or
556 * recursion/subroutine calls) may only refer to named groups, though the
557 * reference can be by name or by number.
559 * @see struct rte_regexdev_info::rule_flags
560 * @see struct rte_regexdev_rule::rule_flags
563 #define RTE_REGEX_PCRE_RULE_UCP_F (1ULL << 9)
564 /**< By default, only ASCII characters are recognized, When this flag is set,
565 * Unicode properties are used instead to classify characters.
567 * @see struct rte_regexdev_info::rule_flags
568 * @see struct rte_regexdev_rule::rule_flags
571 #define RTE_REGEX_PCRE_RULE_UNGREEDY_F (1ULL << 10)
572 /**< When this flag is set, the "greediness" of the quantifiers is inverted
573 * so that they are not greedy by default, but become greedy if followed by
576 * @see struct rte_regexdev_info::rule_flags
577 * @see struct rte_regexdev_rule::rule_flags
580 #define RTE_REGEX_PCRE_RULE_UTF_F (1ULL << 11)
581 /**< When this flag is set, RegEx engine has to regard both the pattern and the
582 * subject strings that are subsequently processed as strings of UTF characters
583 * instead of single-code-unit strings.
585 * @see struct rte_regexdev_info::rule_flags
586 * @see struct rte_regexdev_rule::rule_flags
589 #define RTE_REGEX_PCRE_RULE_NEVER_BACKSLASH_C_F (1ULL << 12)
590 /**< This flag locks out the use of `\C` in the pattern that is being compiled.
591 * This escape matches one data unit, even in UTF mode which can cause
592 * unpredictable behavior in UTF-8 or UTF-16 modes, because it may leave the
593 * current matching point in the mi:set hlsearchddle of a multi-code-unit
596 * @see struct rte_regexdev_info::rule_flags
597 * @see struct rte_regexdev_rule::rule_flags
601 * RegEx device information
603 struct rte_regexdev_info {
604 const char *driver_name; /**< RegEx driver name. */
605 struct rte_device *dev; /**< Device information. */
606 uint16_t max_matches;
607 /**< Maximum matches per scan supported by this device. */
608 uint16_t max_queue_pairs;
609 /**< Maximum queue pairs supported by this device. */
610 uint16_t max_payload_size;
611 /**< Maximum payload size for a pattern match request or scan.
612 * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F
614 uint32_t max_rules_per_group;
615 /**< Maximum rules supported per group by this device. */
617 /**< Maximum groups supported by this device. */
618 uint32_t regexdev_capa;
619 /**< RegEx device capabilities. @see RTE_REGEXDEV_CAPA_* */
621 /**< Supported compiler rule flags.
622 * @see RTE_REGEX_PCRE_RULE_*, struct rte_regexdev_rule::rule_flags
628 * @b EXPERIMENTAL: this API may change without prior notice.
630 * Retrieve the contextual information of a RegEx device.
633 * The identifier of the device.
635 * @param[out] dev_info
636 * A pointer to a structure of type *rte_regexdev_info* to be filled with the
637 * contextual information of the device.
640 * - 0: Success, driver updates the contextual information of the RegEx device
641 * - <0: Error code returned by the driver info get function.
645 rte_regexdev_info_get(uint8_t dev_id, struct rte_regexdev_info *dev_info);
647 /* Enumerates RegEx device configuration flags */
648 #define RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F (1ULL << 0)
649 /**< Cross buffer scan refers to the ability to be able to detect
650 * matches that occur across buffer boundaries, where the buffers are related
651 * to each other in some way. Enable this flag when to scan payload size
652 * greater than struct rte_regexdev_info::max_payload_size and/or
653 * matches can present across scan buffer boundaries.
655 * @see struct rte_regexdev_info::max_payload_size
656 * @see struct rte_regexdev_config::dev_cfg_flags, rte_regexdev_configure()
657 * @see RTE_REGEX_OPS_RSP_PMI_SOJ_F
658 * @see RTE_REGEX_OPS_RSP_PMI_EOJ_F
661 #define RTE_REGEXDEV_CFG_MATCH_AS_END_F (1ULL << 1)
662 /**< Match as end is the ability to return the result as ending offset.
663 * When this flag is set, the result for each match will hold the ending
664 * offset of the match in end_offset.
665 * If this flag is not set, then the match result will hold the starting offset
666 * in start_offset, and the length of the match in len.
668 * @see RTE_REGEXDEV_SUPP_MATCH_AS_END_F
671 #define RTE_REGEXDEV_CFG_MATCH_ALL_F (1ULL << 2)
672 /**< Match all is the ability to return all possible results.
674 * @see RTE_REGEXDEV_SUPP_MATCH_ALL_F
677 /** RegEx device configuration structure */
678 struct rte_regexdev_config {
679 uint16_t nb_max_matches;
680 /**< Maximum matches per scan configured on this device.
681 * This value cannot exceed the *max_matches*
682 * which previously provided in rte_regexdev_info_get().
683 * The value 0 is allowed, in which case, value 1 used.
684 * @see struct rte_regexdev_info::max_matches
686 uint16_t nb_queue_pairs;
687 /**< Number of RegEx queue pairs to configure on this device.
688 * This value cannot exceed the *max_queue_pairs* which previously
689 * provided in rte_regexdev_info_get().
690 * @see struct rte_regexdev_info::max_queue_pairs
692 uint32_t nb_rules_per_group;
693 /**< Number of rules per group to configure on this device.
694 * This value cannot exceed the *max_rules_per_group*
695 * which previously provided in rte_regexdev_info_get().
696 * The value 0 is allowed, in which case,
697 * struct rte_regexdev_info::max_rules_per_group used.
698 * @see struct rte_regexdev_info::max_rules_per_group
701 /**< Number of groups to configure on this device.
702 * This value cannot exceed the *max_groups*
703 * which previously provided in rte_regexdev_info_get().
704 * @see struct rte_regexdev_info::max_groups
707 /**< Import initial set of prebuilt rule database on this device.
708 * The value NULL is allowed, in which case, the device will not
709 * be configured prebuilt rule database. Application may use
710 * rte_regexdev_rule_db_update() or rte_regexdev_rule_db_import() API
711 * to update or import rule database after the
712 * rte_regexdev_configure().
713 * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_import()
715 uint32_t rule_db_len;
716 /**< Length of *rule_db* buffer. */
717 uint32_t dev_cfg_flags;
718 /**< RegEx device configuration flags, See RTE_REGEXDEV_CFG_* */
723 * @b EXPERIMENTAL: this API may change without prior notice.
725 * Configure a RegEx device.
727 * This function must be invoked first before any other function in the
728 * API. This function can also be re-invoked when a device is in the
731 * The caller may use rte_regexdev_info_get() to get the capability of each
732 * resources available for this regex device.
735 * The identifier of the device to configure.
737 * The RegEx device configuration structure.
740 * - 0: Success, device configured. Otherwise negative errno is returned.
744 rte_regexdev_configure(uint8_t dev_id, const struct rte_regexdev_config *cfg);
746 /* Enumerates RegEx queue pair configuration flags */
747 #define RTE_REGEX_QUEUE_PAIR_CFG_OOS_F (1ULL << 0)
748 /**< Out of order scan, If not set, a scan must retire after previously issued
749 * in-order scans to this queue pair. If set, this scan can be retired as soon
750 * as device returns completion. Application should not set out of order scan
751 * flag if it needs to maintain the ingress order of scan request.
753 * @see struct rte_regexdev_qp_conf::qp_conf_flags
754 * @see rte_regexdev_queue_pair_setup()
757 struct rte_regex_ops;
758 typedef void (*regexdev_stop_flush_t)(uint8_t dev_id, uint16_t qp_id,
759 struct rte_regex_ops *op);
760 /**< Callback function called during rte_regexdev_stop(), invoked once per
764 /** RegEx queue pair configuration structure */
765 struct rte_regexdev_qp_conf {
766 uint32_t qp_conf_flags;
767 /**< Queue pair config flags, See RTE_REGEX_QUEUE_PAIR_CFG_* */
769 /**< The number of descriptors to allocate for this queue pair. */
770 regexdev_stop_flush_t cb;
771 /**< Callback function called during rte_regexdev_stop(), invoked
772 * once per flushed regex op. Value NULL is allowed, in which case
773 * callback will not be invoked. This function can be used to properly
774 * dispose of outstanding regex ops from response queue,
775 * for example ops containing memory pointers.
776 * @see rte_regexdev_stop()
782 * @b EXPERIMENTAL: this API may change without prior notice.
784 * Allocate and set up a RegEx queue pair for a RegEx device.
787 * The identifier of the device.
788 * @param queue_pair_id
789 * The index of the RegEx queue pair to setup. The value must be in the range
790 * [0, nb_queue_pairs - 1] previously supplied to rte_regexdev_configure().
792 * The pointer to the configuration data to be used for the RegEx queue pair.
793 * NULL value is allowed, in which case default configuration used.
796 * 0 on success. Otherwise negative errno is returned.
800 rte_regexdev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id,
801 const struct rte_regexdev_qp_conf *qp_conf);
805 * @b EXPERIMENTAL: this API may change without prior notice.
807 * Start a RegEx device.
809 * The device start step is the last one and consists of setting the RegEx
810 * queues to start accepting the pattern matching scan requests.
812 * On success, all basic functions exported by the API (RegEx enqueue,
813 * RegEx dequeue and so on) can be invoked.
816 * RegEx device identifier.
819 * 0 on success. Otherwise negative errno is returned.
823 rte_regexdev_start(uint8_t dev_id);
827 * @b EXPERIMENTAL: this API may change without prior notice.
829 * Stop a RegEx device.
831 * Stop a RegEx device. The device can be restarted with a call to
832 * rte_regexdev_start().
834 * This function causes all queued response regex ops to be drained in the
835 * response queue. While draining ops out of the device,
836 * struct rte_regexdev_qp_conf::cb will be invoked for each ops.
839 * RegEx device identifier.
842 * 0 on success. Otherwise negative errno is returned.
846 rte_regexdev_stop(uint8_t dev_id);
850 * @b EXPERIMENTAL: this API may change without prior notice.
852 * Close a RegEx device. The device cannot be restarted!
855 * RegEx device identifier
858 * 0 on success. Otherwise negative errno is returned.
862 rte_regexdev_close(uint8_t dev_id);
864 /* Device get/set attributes */
866 /** Enumerates RegEx device attribute identifier */
867 enum rte_regexdev_attr_id {
868 RTE_REGEXDEV_ATTR_SOCKET_ID,
869 /**< The NUMA socket id to which the device is connected or
870 * a default of zero if the socket could not be determined.
874 RTE_REGEXDEV_ATTR_MAX_MATCHES,
875 /**< Maximum number of matches per scan.
876 * datatype: *uint8_t*
877 * operation: *get* and *set*
878 * @see RTE_REGEX_OPS_RSP_MAX_MATCH_F
880 RTE_REGEXDEV_ATTR_MAX_SCAN_TIMEOUT,
881 /**< Upper bound scan time in ns.
882 * datatype: *uint16_t*
883 * operation: *get* and *set*
884 * @see RTE_REGEX_OPS_RSP_MAX_SCAN_TIMEOUT_F
886 RTE_REGEXDEV_ATTR_MAX_PREFIX,
887 /**< Maximum number of prefix detected per scan.
888 * This would be useful for denial of service detection.
889 * datatype: *uint16_t*
890 * operation: *get* and *set*
891 * @see RTE_REGEX_OPS_RSP_MAX_PREFIX_F
897 * @b EXPERIMENTAL: this API may change without prior notice.
899 * Get an attribute from a RegEx device.
902 * RegEx device identifier.
904 * The attribute ID to retrieve.
906 * A pointer that will be filled in with the attribute
907 * value if successful.
910 * - 0: Successfully retrieved attribute value.
911 * - -EINVAL: Invalid device or *attr_id* provided, or *attr_value* is NULL.
912 * - -ENOTSUP: if the device doesn't support specific *attr_id*.
916 rte_regexdev_attr_get(uint8_t dev_id, enum rte_regexdev_attr_id attr_id,
921 * @b EXPERIMENTAL: this API may change without prior notice.
923 * Set an attribute to a RegEx device.
926 * RegEx device identifier.
928 * The attribute ID to retrieve.
930 * Pointer that will be filled in with the attribute value
931 * by the application.
934 * - 0: Successfully applied the attribute value.
935 * - -EINVAL: Invalid device or *attr_id* provided, or *attr_value* is NULL.
936 * - -ENOTSUP: if the device doesn't support specific *attr_id*.
940 rte_regexdev_attr_set(uint8_t dev_id, enum rte_regexdev_attr_id attr_id,
941 const void *attr_value);
943 /* Rule related APIs */
944 /** Enumerates RegEx rule operation. */
945 enum rte_regexdev_rule_op {
946 RTE_REGEX_RULE_OP_ADD,
947 /**< Add RegEx rule to rule database. */
948 RTE_REGEX_RULE_OP_REMOVE
949 /**< Remove RegEx rule from rule database. */
952 /** Structure to hold a RegEx rule attributes. */
953 struct rte_regexdev_rule {
954 enum rte_regexdev_rule_op op;
955 /**< OP type of the rule either a OP_ADD or OP_DELETE. */
957 /**< Group identifier to which the rule belongs to. */
959 /**< Rule identifier which is returned on successful match. */
960 const char *pcre_rule;
961 /**< Buffer to hold the PCRE rule. */
962 uint16_t pcre_rule_len;
963 /**< Length of the PCRE rule. */
965 /* PCRE rule flags. Supported device specific PCRE rules enumerated
966 * in struct rte_regexdev_info::rule_flags. For successful rule
967 * database update, application needs to provide only supported
969 * @See RTE_REGEX_PCRE_RULE_*, struct rte_regexdev_info::rule_flags
975 * @b EXPERIMENTAL: this API may change without prior notice.
977 * Update the local rule set.
978 * This functions only modify the rule set in memory.
979 * In order for the changes to take effect, the function
980 * rte_regexdev_rule_db_compile_active must be called.
983 * RegEx device identifier.
985 * Points to an array of *nb_rules* objects of type *rte_regexdev_rule*
986 * structure which contain the regex rules attributes to be updated
989 * The number of PCRE rules to update the rule database.
992 * The number of regex rules actually updated on the regex device's rule
993 * database. The return value can be less than the value of the *nb_rules*
994 * parameter when the regex devices fails to update the rule database or
995 * if invalid parameters are specified in a *rte_regexdev_rule*.
996 * If the return value is less than *nb_rules*, the remaining PCRE rules
997 * at the end of *rules* are not consumed and the caller has to take
998 * care of them and rte_errno is set accordingly.
999 * Possible errno values include:
1000 * - -EINVAL: Invalid device ID or rules is NULL
1001 * - -ENOTSUP: The last processed rule is not supported on this device.
1002 * - -ENOSPC: No space available in rule database.
1004 * @see rte_regexdev_rule_db_import(), rte_regexdev_rule_db_export(),
1005 * rte_regexdev_rule_db_compile_activate()
1009 rte_regexdev_rule_db_update(uint8_t dev_id,
1010 const struct rte_regexdev_rule *rules,
1015 * @b EXPERIMENTAL: this API may change without prior notice.
1017 * Compile local rule set and burn the complied result to the
1021 * RegEx device identifier.
1024 * 0 on success, otherwise negative errno.
1026 * @see rte_regexdev_rule_db_import(), rte_regexdev_rule_db_export(),
1027 * rte_regexdev_rule_db_update()
1031 rte_regexdev_rule_db_compile_activate(uint8_t dev_id);
1035 * @b EXPERIMENTAL: this API may change without prior notice.
1037 * Import a prebuilt rule database from a buffer to a RegEx device.
1040 * RegEx device identifier.
1042 * Points to prebuilt rule database.
1043 * @param rule_db_len
1044 * Length of the rule database.
1047 * - 0: Successfully updated the prebuilt rule database.
1048 * - -EINVAL: Invalid device ID or rule_db is NULL
1049 * - -ENOTSUP: Rule database import is not supported on this device.
1050 * - -ENOSPC: No space available in rule database.
1052 * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_export()
1056 rte_regexdev_rule_db_import(uint8_t dev_id, const char *rule_db,
1057 uint32_t rule_db_len);
1061 * @b EXPERIMENTAL: this API may change without prior notice.
1063 * Export the prebuilt rule database from a RegEx device to the buffer.
1066 * RegEx device identifier.
1067 * @param[out] rule_db
1068 * Block of memory to insert the rule database. Must be at least size in
1069 * capacity. If set to NULL, function returns required capacity.
1072 * - 0: Successfully exported the prebuilt rule database.
1073 * - size: If rule_db set to NULL then required capacity for *rule_db*
1074 * - -EINVAL: Invalid device ID
1075 * - -ENOTSUP: Rule database export is not supported on this device.
1077 * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_import()
1081 rte_regexdev_rule_db_export(uint8_t dev_id, char *rule_db);
1083 /* Extended statistics */
1084 /** Maximum name length for extended statistics counters */
1085 #define RTE_REGEXDEV_XSTATS_NAME_SIZE 64
1088 * A name-key lookup element for extended statistics.
1090 * This structure is used to map between names and ID numbers
1091 * for extended RegEx device statistics.
1093 struct rte_regexdev_xstats_map {
1095 /**< xstat identifier */
1096 char name[RTE_REGEXDEV_XSTATS_NAME_SIZE];
1102 * @b EXPERIMENTAL: this API may change without prior notice.
1104 * Retrieve names of extended statistics of a regex device.
1107 * The identifier of the regex device.
1108 * @param[out] xstats_map
1109 * Block of memory to insert id and names into. Must be at least size in
1110 * capacity. If set to NULL, function returns required capacity.
1112 * - Positive value on success:
1113 * -The return value is the number of entries filled in the stats map.
1114 * -If xstats_map set to NULL then required capacity for xstats_map.
1115 * - Negative value on error:
1116 * -ENODEV for invalid *dev_id*
1117 * -ENOTSUP if the device doesn't support this function.
1121 rte_regexdev_xstats_names_get(uint8_t dev_id,
1122 struct rte_regexdev_xstats_map *xstats_map);
1126 * @b EXPERIMENTAL: this API may change without prior notice.
1128 * Retrieve extended statistics of an regex device.
1131 * The identifier of the device.
1133 * The id numbers of the stats to get. The ids can be got from the stat
1134 * position in the stat list from rte_regexdev_xstats_names_get(), or
1135 * by using rte_regexdev_xstats_by_name_get().
1137 * The values for each stats request by ID.
1139 * The number of stats requested.
1141 * - Positive value: number of stat entries filled into the values array
1142 * - Negative value on error:
1143 * -ENODEV for invalid *dev_id*
1144 * -ENOTSUP if the device doesn't support this function.
1148 rte_regexdev_xstats_get(uint8_t dev_id, const uint16_t *ids,
1149 uint64_t *values, uint16_t nb_values);
1153 * @b EXPERIMENTAL: this API may change without prior notice.
1155 * Retrieve the value of a single stat by requesting it by name.
1158 * The identifier of the device.
1160 * The stat name to retrieve.
1162 * If non-NULL, the numerical id of the stat will be returned, so that further
1163 * requests for the stat can be got using rte_regexdev_xstats_get, which will
1164 * be faster as it doesn't need to scan a list of names for the stat.
1166 * Must be non-NULL, retrieved xstat value will be stored in this address.
1169 * - 0: Successfully retrieved xstat value.
1170 * - -EINVAL: invalid parameters
1171 * - -ENOTSUP: if not supported.
1175 rte_regexdev_xstats_by_name_get(uint8_t dev_id, const char *name,
1176 uint16_t *id, uint64_t *value);
1180 * @b EXPERIMENTAL: this API may change without prior notice.
1182 * Reset the values of the xstats of the selected component in the device.
1185 * The identifier of the device.
1187 * Selects specific statistics to be reset. When NULL, all statistics will be
1188 * reset. If non-NULL, must point to array of at least *nb_ids* size.
1190 * The number of ids available from the *ids* array. Ignored when ids is NULL.
1193 * - 0: Successfully reset the statistics to zero.
1194 * - -EINVAL: invalid parameters.
1195 * - -ENOTSUP: if not supported.
1199 rte_regexdev_xstats_reset(uint8_t dev_id, const uint16_t *ids,
1204 * @b EXPERIMENTAL: this API may change without prior notice.
1206 * Trigger the RegEx device self test.
1209 * The identifier of the device.
1211 * - 0: Selftest successful.
1212 * - -ENOTSUP if the device doesn't support selftest.
1213 * - other values < 0 on failure.
1217 rte_regexdev_selftest(uint8_t dev_id);
1221 * @b EXPERIMENTAL: this API may change without prior notice.
1223 * Dump internal information about *dev_id* to the FILE* provided in *f*.
1226 * The identifier of the device.
1228 * A pointer to a file for output.
1231 * 0 on success, negative errno on failure.
1235 rte_regexdev_dump(uint8_t dev_id, FILE *f);
1237 /* Fast path APIs */
1240 * The generic *rte_regexdev_match* structure to hold the RegEx match
1242 * @see struct rte_regex_ops::matches
1244 struct rte_regexdev_match {
1249 uint32_t rule_id:20;
1250 /**< Rule identifier to which the pattern matched.
1251 * @see struct rte_regexdev_rule::rule_id
1253 uint32_t group_id:12;
1254 /**< Group identifier of the rule which the pattern
1255 * matched. @see struct rte_regexdev_rule::group_id
1257 uint16_t start_offset;
1258 /**< Starting Byte Position for matched rule. */
1262 /**< Length of match in bytes */
1263 uint16_t end_offset;
1264 /**< The end offset of the match. In case
1265 * MATCH_AS_END configuration is enabled.
1266 * @see RTE_REGEXDEV_CFG_MATCH_AS_END
1273 /* Enumerates RegEx request flags. */
1274 #define RTE_REGEX_OPS_REQ_GROUP_ID0_VALID_F (1 << 0)
1275 /**< Set when struct rte_regexdev_rule::group_id0 is valid. */
1277 #define RTE_REGEX_OPS_REQ_GROUP_ID1_VALID_F (1 << 1)
1278 /**< Set when struct rte_regexdev_rule::group_id1 is valid. */
1280 #define RTE_REGEX_OPS_REQ_GROUP_ID2_VALID_F (1 << 2)
1281 /**< Set when struct rte_regexdev_rule::group_id2 is valid. */
1283 #define RTE_REGEX_OPS_REQ_GROUP_ID3_VALID_F (1 << 3)
1284 /**< Set when struct rte_regexdev_rule::group_id3 is valid. */
1286 #define RTE_REGEX_OPS_REQ_STOP_ON_MATCH_F (1 << 4)
1287 /**< The RegEx engine will stop scanning and return the first match. */
1289 #define RTE_REGEX_OPS_REQ_MATCH_HIGH_PRIORITY_F (1 << 5)
1290 /**< In High Priority mode a maximum of one match will be returned per scan to
1291 * reduce the post-processing required by the application. The match with the
1292 * lowest Rule id, lowest start pointer and lowest match length will be
1295 * @see struct rte_regex_ops::nb_actual_matches
1296 * @see struct rte_regex_ops::nb_matches
1300 /* Enumerates RegEx response flags. */
1301 #define RTE_REGEX_OPS_RSP_PMI_SOJ_F (1 << 0)
1302 /**< Indicates that the RegEx device has encountered a partial match at the
1303 * start of scan in the given buffer.
1305 * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F
1308 #define RTE_REGEX_OPS_RSP_PMI_EOJ_F (1 << 1)
1309 /**< Indicates that the RegEx device has encountered a partial match at the
1310 * end of scan in the given buffer.
1312 * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F
1315 #define RTE_REGEX_OPS_RSP_MAX_SCAN_TIMEOUT_F (1 << 2)
1316 /**< Indicates that the RegEx device has exceeded the max timeout while
1317 * scanning the given buffer.
1319 * @see RTE_REGEXDEV_ATTR_MAX_SCAN_TIMEOUT
1322 #define RTE_REGEX_OPS_RSP_MAX_MATCH_F (1 << 3)
1323 /**< Indicates that the RegEx device has exceeded the max matches while
1324 * scanning the given buffer.
1326 * @see RTE_REGEXDEV_ATTR_MAX_MATCHES
1329 #define RTE_REGEX_OPS_RSP_MAX_PREFIX_F (1 << 4)
1330 /**< Indicates that the RegEx device has reached the max allowed prefix length
1331 * while scanning the given buffer.
1333 * @see RTE_REGEXDEV_ATTR_MAX_PREFIX
1336 #define RTE_REGEX_OPS_RSP_RESOURCE_LIMIT_REACHED_F (1 << 4)
1337 /**< Indicates that the RegEx device has reached the max allowed resource
1338 * allowed while scanning the given buffer.
1342 * The generic *rte_regex_ops* structure to hold the RegEx attributes
1343 * for enqueue and dequeue operation.
1345 struct rte_regex_ops {
1348 /**< Request flags for the RegEx ops.
1349 * @see RTE_REGEX_OPS_REQ_*
1352 /**< Response flags for the RegEx ops.
1353 * @see RTE_REGEX_OPS_RSP_*
1355 uint16_t nb_actual_matches;
1356 /**< The total number of actual matches detected by the Regex device.*/
1357 uint16_t nb_matches;
1358 /**< The total number of matches returned by the RegEx device for this
1359 * scan. The size of *rte_regex_ops::matches* zero length array will be
1362 * @see struct rte_regex_ops::matches, struct rte_regexdev_match
1366 struct rte_mbuf *mbuf; /**< source mbuf, to search in. */
1370 /**< First group_id to match the rule against. At minimum one group
1371 * should be valid. Behaviour is undefined non of the groups are valid.
1373 * @see RTE_REGEX_OPS_REQ_GROUP_ID0_VALID_F
1376 /**< Second group_id to match the rule against.
1378 * @see RTE_REGEX_OPS_REQ_GROUP_ID1_VALID_F
1381 /**< Third group_id to match the rule against.
1383 * @see RTE_REGEX_OPS_REQ_GROUP_ID2_VALID_F
1386 /**< Forth group_id to match the rule against.
1388 * @see RTE_REGEX_OPS_REQ_GROUP_ID3_VALID_F
1395 /**< Application specific opaque value. An application may use
1396 * this field to hold application specific value to share
1397 * between dequeue and enqueue operation.
1398 * Implementation should not modify this field.
1401 /**< Pointer representation of *user_id* */
1407 uint64_t cross_buf_id;
1408 /**< ID used by the RegEx device in order to support cross
1410 * This ID is returned from the RegEx device on the dequeue
1411 * function. The application must send it back when calling
1412 * enqueue with the following packet.
1414 void *cross_buf_ptr;
1415 /**< Pointer representation of *corss_buf_id* */
1419 struct rte_regexdev_match matches[];
1420 /**< Zero length array to hold the match tuples.
1421 * The struct rte_regex_ops::nb_matches value holds the number of
1422 * elements in this array.
1424 * @see struct rte_regex_ops::nb_matches
1428 #include "rte_regexdev_core.h"
1432 * @b EXPERIMENTAL: this API may change without prior notice.
1434 * Enqueue a burst of scan request on a RegEx device.
1436 * The rte_regexdev_enqueue_burst() function is invoked to place
1437 * regex operations on the queue *qp_id* of the device designated by
1440 * The *nb_ops* parameter is the number of operations to process which are
1441 * supplied in the *ops* array of *rte_regexdev_op* structures.
1443 * The rte_regexdev_enqueue_burst() function returns the number of
1444 * operations it actually enqueued for processing. A return value equal to
1445 * *nb_ops* means that all packets have been enqueued.
1448 * The identifier of the device.
1450 * The index of the queue pair which packets are to be enqueued for
1451 * processing. The value must be in the range [0, nb_queue_pairs - 1]
1452 * previously supplied to rte_regexdev_configure().
1454 * The address of an array of *nb_ops* pointers to *rte_regexdev_op*
1455 * structures which contain the regex operations to be processed.
1457 * The number of operations to process.
1460 * The number of operations actually enqueued on the regex device. The return
1461 * value can be less than the value of the *nb_ops* parameter when the
1462 * regex devices queue is full or if invalid parameters are specified in
1463 * a *rte_regexdev_op*. If the return value is less than *nb_ops*, the
1464 * remaining ops at the end of *ops* are not consumed and the caller has
1465 * to take care of them.
1468 static inline uint16_t
1469 rte_regexdev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
1470 struct rte_regex_ops **ops, uint16_t nb_ops)
1472 struct rte_regexdev *dev = &rte_regex_devices[dev_id];
1473 #ifdef RTE_LIBRTE_REGEXDEV_DEBUG
1474 RTE_REGEXDEV_VALID_DEV_ID_OR_ERR_RET(dev_id, -EINVAL);
1475 RTE_FUNC_PTR_OR_ERR_RET(*dev->enqueue, -ENOTSUP);
1476 if (qp_id >= dev->data->dev_conf.nb_queue_pairs) {
1477 RTE_REGEXDEV_LOG(ERR, "Invalid queue %d\n", qp_id);
1481 return (*dev->enqueue)(dev, qp_id, ops, nb_ops);
1486 * @b EXPERIMENTAL: this API may change without prior notice.
1488 * Dequeue a burst of scan response from a queue on the RegEx device.
1489 * The dequeued operation are stored in *rte_regexdev_op* structures
1490 * whose pointers are supplied in the *ops* array.
1492 * The rte_regexdev_dequeue_burst() function returns the number of ops
1493 * actually dequeued, which is the number of *rte_regexdev_op* data structures
1494 * effectively supplied into the *ops* array.
1496 * A return value equal to *nb_ops* indicates that the queue contained
1497 * at least *nb_ops* operations, and this is likely to signify that other
1498 * processed operations remain in the devices output queue. Applications
1499 * implementing a "retrieve as many processed operations as possible" policy
1500 * can check this specific case and keep invoking the
1501 * rte_regexdev_dequeue_burst() function until a value less than
1502 * *nb_ops* is returned.
1504 * The rte_regexdev_dequeue_burst() function does not provide any error
1505 * notification to avoid the corresponding overhead.
1508 * The RegEx device identifier
1510 * The index of the queue pair from which to retrieve processed packets.
1511 * The value must be in the range [0, nb_queue_pairs - 1] previously
1512 * supplied to rte_regexdev_configure().
1514 * The address of an array of pointers to *rte_regexdev_op* structures
1515 * that must be large enough to store *nb_ops* pointers in it.
1517 * The maximum number of operations to dequeue.
1520 * The number of operations actually dequeued, which is the number
1521 * of pointers to *rte_regexdev_op* structures effectively supplied to the
1522 * *ops* array. If the return value is less than *nb_ops*, the remaining
1523 * ops at the end of *ops* are not consumed and the caller has to take care
1527 static inline uint16_t
1528 rte_regexdev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
1529 struct rte_regex_ops **ops, uint16_t nb_ops)
1531 struct rte_regexdev *dev = &rte_regex_devices[dev_id];
1532 #ifdef RTE_LIBRTE_REGEXDEV_DEBUG
1533 RTE_REGEXDEV_VALID_DEV_ID_OR_ERR_RET(dev_id, -EINVAL);
1534 RTE_FUNC_PTR_OR_ERR_RET(*dev->dequeue, -ENOTSUP);
1535 if (qp_id >= dev->data->dev_conf.nb_queue_pairs) {
1536 RTE_REGEXDEV_LOG(ERR, "Invalid queue %d\n", qp_id);
1540 return (*dev->dequeue)(dev, qp_id, ops, nb_ops);
1547 #endif /* _RTE_REGEXDEV_H_ */