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