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