diff --git a/MAINTAINERS b/MAINTAINERS index 27a7be8e64..27fcd6d648 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -449,6 +449,11 @@ F: app/test/test_compressdev* F: doc/guides/prog_guide/compressdev.rst F: doc/guides/compressdevs/features/default.ini +RegEx API - EXPERIMENTAL +M: Ori Kam +F: lib/librte_regexdev/ +F: doc/guides/prog_guide/regexdev.rst + Eventdev API M: Jerin Jacob T: git://dpdk.org/next/dpdk-next-eventdev diff --git a/config/common_base b/config/common_base index fe30c515e5..5ba283957c 100644 --- a/config/common_base +++ b/config/common_base @@ -735,6 +735,11 @@ CONFIG_RTE_LIBRTE_PMD_ISAL=n # CONFIG_RTE_LIBRTE_PMD_ZLIB=n +# +# Compile RegEx device support +# +CONFIG_RTE_LIBRTE_REGEXDEV=y + # # Compile generic event device library # diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index 5a48789b5d..766c79dbed 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -20,6 +20,7 @@ The public API headers are grouped by topics: [security] (@ref rte_security.h), [compressdev] (@ref rte_compressdev.h), [compress] (@ref rte_comp.h), + [regexdev] (@ref rte_regexdev.h), [eventdev] (@ref rte_eventdev.h), [event_eth_rx_adapter] (@ref rte_event_eth_rx_adapter.h), [event_eth_tx_adapter] (@ref rte_event_eth_tx_adapter.h), diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in index 9b55b7500c..42d38919d3 100644 --- a/doc/api/doxy-api.conf.in +++ b/doc/api/doxy-api.conf.in @@ -59,6 +59,7 @@ INPUT = @TOPDIR@/doc/api/doxy-api-index.md \ @TOPDIR@/lib/librte_power \ @TOPDIR@/lib/librte_rawdev \ @TOPDIR@/lib/librte_rcu \ + @TOPDIR@/lib/librte_regexdev \ @TOPDIR@/lib/librte_reorder \ @TOPDIR@/lib/librte_rib \ @TOPDIR@/lib/librte_ring \ diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 8838ffb9ae..0454768de3 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -26,6 +26,7 @@ Programmer's Guide bbdev cryptodev_lib compressdev + regexdev rte_security rawdev link_bonding_poll_mode_drv_lib diff --git a/doc/guides/prog_guide/regexdev.rst b/doc/guides/prog_guide/regexdev.rst new file mode 100644 index 0000000000..b8ae9c0cc9 --- /dev/null +++ b/doc/guides/prog_guide/regexdev.rst @@ -0,0 +1,177 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2020 Mellanox Technologies, Ltd + +RegEx Device Library +==================== + +The RegEx library provides a RegEx device framework for management and +provisioning of hardware and software RegEx poll mode drivers, defining generic +APIs which support a number of different RegEx operations. + + +Design Principles +----------------- + +The RegEx library follows the same basic principles as those used in DPDK's +Ethernet Device framework and the Crypto framework. The RegEx framework provides +a generic Crypto device framework which supports both physical (hardware) +and virtual (software) RegEx devices as well as a generic RegEx API which allows +RegEx devices to be managed and configured and supports RegEx operations to be +provisioned on RegEx poll mode driver. + + +Device Management +----------------- + +Device Creation +~~~~~~~~~~~~~~~ + +Physical RegEx devices are discovered during the PCI probe/enumeration of the +EAL function which is executed at DPDK initialization, based on +their PCI device identifier, each unique PCI BDF (bus/bridge, device, +function). Specific physical ReEx devices, like other physical devices in DPDK +can be white-listed or black-listed using the EAL command line options. + + +Device Identification +~~~~~~~~~~~~~~~~~~~~~ + +Each device, whether virtual or physical is uniquely designated by two +identifiers: + +- A unique device index used to designate the RegEx device in all functions + exported by the regexdev API. + +- A device name used to designate the RegEx device in console messages, for + administration or debugging purposes. + + +Device Configuration +~~~~~~~~~~~~~~~~~~~~ + +The configuration of each RegEx device includes the following operations: + +- Allocation of resources, including hardware resources if a physical device. +- Resetting the device into a well-known default state. +- Initialization of statistics counters. + +The rte_regexdev_configure API is used to configure a RegEx device. + +.. code-block:: c + + int rte_regexdev_configure(uint8_t dev_id, + const struct rte_regexdev_config *cfg); + +The ``rte_regexdev_config`` structure is used to pass the configuration +parameters for the RegEx device for example number of queue pairs, number of +groups, max number of matches and so on. + +.. code-block:: c + + struct rte_regexdev_config { + uint16_t nb_max_matches; + /**< Maximum matches per scan configured on this device. + * This value cannot exceed the *max_matches* + * which previously provided in rte_regexdev_info_get(). + * The value 0 is allowed, in which case, value 1 used. + * @see struct rte_regexdev_info::max_matches + */ + uint16_t nb_queue_pairs; + /**< Number of RegEx queue pairs to configure on this device. + * This value cannot exceed the *max_queue_pairs* which previously + * provided in rte_regexdev_info_get(). + * @see struct rte_regexdev_info::max_queue_pairs + */ + uint32_t nb_rules_per_group; + /**< Number of rules per group to configure on this device. + * This value cannot exceed the *max_rules_per_group* + * which previously provided in rte_regexdev_info_get(). + * The value 0 is allowed, in which case, + * struct rte_regexdev_info::max_rules_per_group used. + * @see struct rte_regexdev_info::max_rules_per_group + */ + uint16_t nb_groups; + /**< Number of groups to configure on this device. + * This value cannot exceed the *max_groups* + * which previously provided in rte_regexdev_info_get(). + * @see struct rte_regexdev_info::max_groups + */ + const char *rule_db; + /**< Import initial set of prebuilt rule database on this device. + * The value NULL is allowed, in which case, the device will not + * be configured prebuilt rule database. Application may use + * rte_regexdev_rule_db_update() or rte_regexdev_rule_db_import() API + * to update or import rule database after the + * rte_regexdev_configure(). + * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_import() + */ + uint32_t rule_db_len; + /**< Length of *rule_db* buffer. */ + uint32_t dev_cfg_flags; + /**< RegEx device configuration flags, See RTE_REGEXDEV_CFG_* */ + }; + + +Configuration of Rules Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each Regex device should be configured with the rule database. +There are two modes of setting the rule database, online or offline. +The online mode means, that the rule database in being compiled by the +RegEx PMD while in the offline mode the rule database is compiled by external +compiler, and is being loaded to the PMD as a buffer. +The configuration mode is depended on the PMD capabilities. + +Online rule configuration is done using the following API functions: +``rte_regexdev_rule_db_update`` which add / remove rules from the rules +precomplied list, and ``rte_regexdev_rule_db_compile_activate`` +which compile the rules and loads them to the RegEx HW. + +Offline rule configuration can be done by adding a pointer to the compiled +rule database in the configuration step, or by using +``rte_regexdev_rule_db_import`` API. + + +Configuration of Queue Pairs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each RegEx device can be configured with number of queue pairs. +Each queue pair is configured using ``rte_regexdev_queue_pair_setup`` + + +Logical Cores, Memory and Queues Pair Relationships +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Multiple logical cores should never share the same queue pair for enqueuing +operations or dequeuing operations on the same RegEx device since this would +require global locks and hinder performance. + + +Device Features and Capabilities +--------------------------------- + +RegEx devices may support different feature set. +In order to get the supported PMD feature ``rte_regexdev_info_get`` +API which return the info of the device and it's supported features. + + +Enqueue / Dequeue Burst APIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The burst enqueue API uses a RegEx device identifier and a queue pair +identifier to specify the device queue pair to schedule the processing on. +The ``nb_ops`` parameter is the number of operations to process which are +supplied in the ``ops`` array of ``rte_regex_ops`` structures. +The enqueue function returns the number of operations it actually enqueued for +processing, a return value equal to ``nb_ops`` means that all packets have been +enqueued. + +Data pointed in each op, should not be released until the dequeue of for that +op. + +The dequeue API uses the same format as the enqueue API of processed but +the ``nb_ops`` and ``ops`` parameters are now used to specify the max processed +operations the user wishes to retrieve and the location in which to store them. +The API call returns the actual number of processed operations returned, this +can never be larger than ``nb_ops``. + diff --git a/doc/guides/rel_notes/release_20_08.rst b/doc/guides/rel_notes/release_20_08.rst index c0f81d8d40..ffae463f45 100644 --- a/doc/guides/rel_notes/release_20_08.rst +++ b/doc/guides/rel_notes/release_20_08.rst @@ -56,6 +56,11 @@ New Features Also, make sure to start the actual text at the margin. ========================================================= +* **Added the RegEx Library, a generic RegEx service library.** + + Added the RegEx library which provides an API for offload of regular + expressions search operations to hardware or software accelerator devices. + * **Updated PCAP driver.** Updated PCAP driver with new features and improvements, including: diff --git a/lib/Makefile b/lib/Makefile index e0e5eb4d8d..4b981f505e 100644 --- a/lib/Makefile +++ b/lib/Makefile @@ -40,6 +40,8 @@ DEPDIRS-librte_security += librte_cryptodev DIRS-$(CONFIG_RTE_LIBRTE_COMPRESSDEV) += librte_compressdev DEPDIRS-librte_compressdev := librte_eal librte_mempool librte_ring librte_mbuf DEPDIRS-librte_compressdev += librte_kvargs +DIRS-$(CONFIG_RTE_LIBRTE_REGEXDEV) += librte_regexdev +DEPDIRS-librte_regexdev := librte_eal librte_mbuf DIRS-$(CONFIG_RTE_LIBRTE_EVENTDEV) += librte_eventdev DEPDIRS-librte_eventdev := librte_eal librte_ring librte_ethdev librte_hash \ librte_mempool librte_timer librte_cryptodev diff --git a/lib/librte_regexdev/Makefile b/lib/librte_regexdev/Makefile new file mode 100644 index 0000000000..5da4d00260 --- /dev/null +++ b/lib/librte_regexdev/Makefile @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(C) 2019 Marvell International Ltd. +# Copyright 2020 Mellanox Technologies, Ltd + +include $(RTE_SDK)/mk/rte.vars.mk + +# library name +LIB = librte_regexdev.a + +EXPORT_MAP := rte_regex_version.map + +# library version +LIBABIVER := 1 + +# build flags +CFLAGS += -O3 +CFLAGS += $(WERROR_FLAGS) +LDLIBS += -lrte_eal -lrte_mbuf + +# library source files +# all source are stored in SRCS-y +SRCS-$(CONFIG_RTE_LIBRTE_REGEXDEV) := rte_regexdev.c + +# export include files +SYMLINK-$(CONFIG_RTE_LIBRTE_REGEXDEV)-include += rte_regexdev.h + +# versioning export map +EXPORT_MAP := rte_regexdev_version.map + +include $(RTE_SDK)/mk/rte.lib.mk diff --git a/lib/librte_regexdev/meson.build b/lib/librte_regexdev/meson.build new file mode 100644 index 0000000000..3484ec5a11 --- /dev/null +++ b/lib/librte_regexdev/meson.build @@ -0,0 +1,6 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2020 Mellanox Technologies, Ltd + +sources = files('rte_regexdev.c') +headers = files('rte_regexdev.h') +deps += ['mbuf'] diff --git a/lib/librte_regexdev/rte_regexdev.c b/lib/librte_regexdev/rte_regexdev.c new file mode 100644 index 0000000000..b18deeeb42 --- /dev/null +++ b/lib/librte_regexdev/rte_regexdev.c @@ -0,0 +1,6 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright(C) 2019 Marvell International Ltd. + * Copyright 2020 Mellanox Technologies, Ltd + */ + +#include "rte_regexdev.h" diff --git a/lib/librte_regexdev/rte_regexdev.h b/lib/librte_regexdev/rte_regexdev.h new file mode 100644 index 0000000000..09bf8865f3 --- /dev/null +++ b/lib/librte_regexdev/rte_regexdev.h @@ -0,0 +1,1473 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright(C) 2019 Marvell International Ltd. + * Copyright 2020 Mellanox Technologies, Ltd + * Copyright(c) 2020 Intel Corporation + */ + +#ifndef _RTE_REGEXDEV_H_ +#define _RTE_REGEXDEV_H_ + +/** + * @file + * + * RTE RegEx Device API + * + * Defines RTE RegEx Device APIs for RegEx operations and its provisioning. + * + * The RegEx Device API is composed of two parts: + * + * - The application-oriented RegEx API that includes functions to setup + * a RegEx device (configure it, setup its queue pairs and start it), + * update the rule database and so on. + * + * - The driver-oriented RegEx API that exports a function allowing + * a RegEx poll Mode Driver (PMD) to simultaneously register itself as + * a RegEx device driver. + * + * RegEx device components and definitions: + * + * +-----------------+ + * | | + * | o---------+ rte_regexdev_[en|de]queue_burst() + * | PCRE based o------+ | | + * | RegEx pattern | | | +--------+ | + * | matching engine o------+--+--o | | +------+ + * | | | | | queue |<==o===>|Core 0| + * | o----+ | | | pair 0 | | | + * | | | | | +--------+ +------+ + * +-----------------+ | | | + * ^ | | | +--------+ + * | | | | | | +------+ + * | | +--+--o queue |<======>|Core 1| + * Rule|Database | | | pair 1 | | | + * +------+----------+ | | +--------+ +------+ + * | Group 0 | | | + * | +-------------+ | | | +--------+ +------+ + * | | Rules 0..n | | | | | | |Core 2| + * | +-------------+ | | +--o queue |<======>| | + * | Group 1 | | | pair 2 | +------+ + * | +-------------+ | | +--------+ + * | | Rules 0..n | | | + * | +-------------+ | | +--------+ + * | Group 2 | | | | +------+ + * | +-------------+ | | | queue |<======>|Core n| + * | | Rules 0..n | | +-------o pair n | | | + * | +-------------+ | +--------+ +------+ + * | Group n | + * | +-------------+ |<-------rte_regexdev_rule_db_update() + * | | | |<-------rte_regexdev_rule_db_compile_activate() + * | | Rules 0..n | |<-------rte_regexdev_rule_db_import() + * | +-------------+ |------->rte_regexdev_rule_db_export() + * +-----------------+ + * + * RegEx: A regular expression is a concise and flexible means for matching + * strings of text, such as particular characters, words, or patterns of + * characters. A common abbreviation for this is “RegEx”. + * + * RegEx device: A hardware or software-based implementation of RegEx + * device API for PCRE based pattern matching syntax and semantics. + * + * PCRE RegEx syntax and semantics specification: + * http://regexkit.sourceforge.net/Documentation/pcre/pcrepattern.html + * + * RegEx queue pair: Each RegEx device should have one or more queue pair to + * transmit a burst of pattern matching request and receive a burst of + * receive the pattern matching response. The pattern matching request/response + * embedded in *rte_regex_ops* structure. + * + * Rule: A pattern matching rule expressed in PCRE RegEx syntax along with + * Match ID and Group ID to identify the rule upon the match. + * + * Rule database: The RegEx device accepts regular expressions and converts them + * into a compiled rule database that can then be used to scan data. + * Compilation allows the device to analyze the given pattern(s) and + * pre-determine how to scan for these patterns in an optimized fashion that + * would be far too expensive to compute at run-time. A rule database contains + * a set of rules that compiled in device specific binary form. + * + * Match ID or Rule ID: A unique identifier provided at the time of rule + * creation for the application to identify the rule upon match. + * + * Group ID: Group of rules can be grouped under one group ID to enable + * rule isolation and effective pattern matching. A unique group identifier + * provided at the time of rule creation for the application to identify the + * rule upon match. + * + * Scan: A pattern matching request through *enqueue* API. + * + * It may possible that a given RegEx device may not support all the features + * of PCRE. The application may probe unsupported features through + * struct rte_regexdev_info::pcre_unsup_flags + * + * By default, all the functions of the RegEx Device API exported by a PMD + * are lock-free functions which assume to not be invoked in parallel on + * different logical cores to work on the same target object. For instance, + * the dequeue function of a PMD cannot be invoked in parallel on two logical + * cores to operates on same RegEx queue pair. Of course, this function + * can be invoked in parallel by different logical core on different queue pair. + * It is the responsibility of the upper level application to enforce this rule. + * + * In all functions of the RegEx API, the RegEx device is + * designated by an integer >= 0 named the device identifier *dev_id* + * + * At the RegEx driver level, RegEx devices are represented by a generic + * data structure of type *rte_regexdev*. + * + * RegEx devices are dynamically registered during the PCI/SoC device probing + * phase performed at EAL initialization time. + * When a RegEx device is being probed, a *rte_regexdev* structure and + * a new device identifier are allocated for that device. Then, the + * regexdev_init() function supplied by the RegEx driver matching the probed + * device is invoked to properly initialize the device. + * + * The role of the device init function consists of resetting the hardware or + * software RegEx driver implementations. + * + * If the device init operation is successful, the correspondence between + * the device identifier assigned to the new device and its associated + * *rte_regexdev* structure is effectively registered. + * Otherwise, both the *rte_regexdev* structure and the device identifier are + * freed. + * + * The functions exported by the application RegEx API to setup a device + * designated by its device identifier must be invoked in the following order: + * - rte_regexdev_configure() + * - rte_regexdev_queue_pair_setup() + * - rte_regexdev_start() + * + * Then, the application can invoke, in any order, the functions + * exported by the RegEx API to enqueue pattern matching job, dequeue pattern + * matching response, get the stats, update the rule database, + * get/set device attributes and so on + * + * If the application wants to change the configuration (i.e. call + * rte_regexdev_configure() or rte_regexdev_queue_pair_setup()), it must call + * rte_regexdev_stop() first to stop the device and then do the reconfiguration + * before calling rte_regexdev_start() again. The enqueue and dequeue + * functions should not be invoked when the device is stopped. + * + * Finally, an application can close a RegEx device by invoking the + * rte_regexdev_close() function. + * + * Each function of the application RegEx API invokes a specific function + * of the PMD that controls the target device designated by its device + * identifier. + * + * For this purpose, all device-specific functions of a RegEx driver are + * supplied through a set of pointers contained in a generic structure of type + * *regexdev_ops*. + * The address of the *regexdev_ops* structure is stored in the *rte_regexdev* + * structure by the device init function of the RegEx driver, which is + * invoked during the PCI/SoC device probing phase, as explained earlier. + * + * In other words, each function of the RegEx API simply retrieves the + * *rte_regexdev* structure associated with the device identifier and + * performs an indirect invocation of the corresponding driver function + * supplied in the *regexdev_ops* structure of the *rte_regexdev* structure. + * + * For performance reasons, the address of the fast-path functions of the + * RegEx driver is not contained in the *regexdev_ops* structure. + * Instead, they are directly stored at the beginning of the *rte_regexdev* + * structure to avoid an extra indirect memory access during their invocation. + * + * RTE RegEx device drivers do not use interrupts for enqueue or dequeue + * operation. Instead, RegEx drivers export Poll-Mode enqueue and dequeue + * functions to applications. + * + * The *enqueue* operation submits a burst of RegEx pattern matching request + * to the RegEx device and the *dequeue* operation gets a burst of pattern + * matching response for the ones submitted through *enqueue* operation. + * + * Typical application utilisation of the RegEx device API will follow the + * following programming flow. + * + * - rte_regexdev_configure() + * - rte_regexdev_queue_pair_setup() + * - rte_regexdev_rule_db_update() Needs to invoke if precompiled rule database + * not provided in rte_regexdev_config::rule_db for rte_regexdev_configure() + * and/or application needs to update rule database. + * - rte_regexdev_rule_db_compile_activate() Needs to invoke if + * rte_regexdev_rule_db_update function was used. + * - Create or reuse exiting mempool for *rte_regex_ops* objects. + * - rte_regexdev_start() + * - rte_regexdev_enqueue_burst() + * - rte_regexdev_dequeue_burst() + */ + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include +#include +#include +#include +#include + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Get the total number of RegEx devices that have been successfully + * initialised. + * + * @return + * The total number of usable RegEx devices. + */ +__rte_experimental +uint8_t +rte_regexdev_count(void); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Get the device identifier for the named RegEx device. + * + * @param name + * RegEx device name to select the RegEx device identifier. + * + * @return + * Returns RegEx device identifier on success. + * - <0: Failure to find named RegEx device. + */ +__rte_experimental +int +rte_regexdev_get_dev_id(const char *name); + +/* Enumerates RegEx device capabilities */ +#define RTE_REGEXDEV_CAPA_RUNTIME_COMPILATION_F (1ULL << 0) +/**< RegEx device does support compiling the rules at runtime unlike + * loading only the pre-built rule database using + * struct rte_regexdev_config::rule_db in rte_regexdev_configure() + * + * @see struct rte_regexdev_config::rule_db, rte_regexdev_configure() + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_CAPA_SUPP_PCRE_START_ANCHOR_F (1ULL << 1) +/**< RegEx device support PCRE Anchor to start of match flag. + * Example RegEx is `/\Gfoo\d/`. Here `\G` asserts position at the end of the + * previous match or the start of the string for the first match. + * This position will change each time the RegEx is applied to the subject + * string. If the RegEx is applied to `foo1foo2Zfoo3` the first two matches will + * be successful for `foo1foo2` and fail for `Zfoo3`. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_CAPA_SUPP_PCRE_ATOMIC_GROUPING_F (1ULL << 2) +/**< RegEx device support PCRE Atomic grouping. + * Atomic groups are represented by `(?>)`. An atomic group is a group that, + * when the RegEx engine exits from it, automatically throws away all + * backtracking positions remembered by any tokens inside the group. + * Example RegEx is `a(?>bc|b)c` if the given patterns are `abc` and `abcc` then + * `a(bc|b)c` matches both where as `a(?>bc|b)c` matches only abcc because + * atomic groups don't allow backtracing back to `b`. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_BACKTRACKING_CTRL_F (1ULL << 3) +/**< RegEx device support PCRE backtracking control verbs. + * Some examples of backtracing verbs are (*COMMIT), (*ACCEPT), (*FAIL), + * (*SKIP), (*PRUNE). + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_CALLOUTS_F (1ULL << 4) +/**< RegEx device support PCRE callouts. + * PCRE supports calling external function in between matches by using `(?C)`. + * Example RegEx `ABC(?C)D` if a given patter is `ABCD` then the RegEx engine + * will parse ABC perform a userdefined callout and return a successful match at + * D. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_BACKREFERENCE_F (1ULL << 5) +/**< RegEx device support PCRE backreference. + * Example RegEx is `(\2ABC|(GHI))+` `\2` matches the same text as most recently + * matched by the 2nd capturing group i.e. `GHI`. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_GREEDY_F (1ULL << 6) +/**< RegEx device support PCRE Greedy mode. + * For example if the RegEx is `AB\d*?` then `*?` represents zero or unlimited + * matches. In greedy mode the pattern `AB12345` will be matched completely + * where as the ungreedy mode `AB` will be returned as the match. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_MATCH_ALL_F (1ULL << 7) +/**< RegEx device support match all mode. + * For example if the RegEx is `AB\d*?` then `*?` represents zero or unlimited + * matches. In match all mode the pattern `AB12345` will return 6 matches. + * AB, AB1, AB12, AB123, AB1234, AB12345. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_LOOKAROUND_ASRT_F (1ULL << 8) +/**< RegEx device support PCRE Lookaround assertions + * (Zero-width assertions). Example RegEx is `[a-z]+\d+(?=!{3,})` if + * the given pattern is `dwad1234!` the RegEx engine doesn't report any matches + * because the assert `(?=!{3,})` fails. The pattern `dwad123!!!` would return a + * successful match. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_MATCH_POINT_RST_F (1ULL << 9) +/**< RegEx device doesn't support PCRE match point reset directive. + * Example RegEx is `[a-z]+\K\d+` if the pattern is `dwad123` + * then even though the entire pattern matches only `123` + * is reported as a match. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_NEWLINE_CONVENTIONS_F (1ULL << 10) +/**< RegEx support PCRE newline convention. + * Newline conventions are represented as follows: + * (*CR) carriage return + * (*LF) linefeed + * (*CRLF) carriage return, followed by linefeed + * (*ANYCRLF) any of the three above + * (*ANY) all Unicode newline sequences + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_NEWLINE_SEQ_F (1ULL << 11) +/**< RegEx device support PCRE newline sequence. + * The escape sequence `\R` will match any newline sequence. + * It is equivalent to: `(?>\r\n|\n|\x0b|\f|\r|\x85)`. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_POSSESSIVE_QUALIFIERS_F (1ULL << 12) +/**< RegEx device support PCRE possessive qualifiers. + * Example RegEx possessive qualifiers `*+`, `++`, `?+`, `{m,n}+`. + * Possessive quantifier repeats the token as many times as possible and it does + * not give up matches as the engine backtracks. With a possessive quantifier, + * the deal is all or nothing. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_SUBROUTINE_REFERENCES_F (1ULL << 13) +/**< RegEx device support PCRE Subroutine references. + * PCRE Subroutine references allow for sub patterns to be assessed + * as part of the RegEx. Example RegEx is `(foo|fuzz)\g<1>+bar` matches the + * pattern `foofoofuzzfoofuzzbar`. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_UTF_8_F (1ULL << 14) +/**< RegEx device support UTF-8 character encoding. + * + * @see struct rte_regexdev_info::pcre_unsup_flags + */ + +#define RTE_REGEXDEV_SUPP_PCRE_UTF_16_F (1ULL << 15) +/**< RegEx device support UTF-16 character encoding. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_UTF_32_F (1ULL << 16) +/**< RegEx device support UTF-32 character encoding. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_WORD_BOUNDARY_F (1ULL << 17) +/**< RegEx device support word boundaries. + * The meta character `\b` represents word boundary anchor. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_PCRE_FORWARD_REFERENCES_F (1ULL << 18) +/**< RegEx device support Forward references. + * Forward references allow you to use a back reference to a group that appears + * later in the RegEx. Example RegEx is `(\3ABC|(DEF|(GHI)))+` matches the + * following string `GHIGHIABCDEF`. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_MATCH_AS_END_F (1ULL << 19) +/**< RegEx device support match as end. + * Match as end means that the match result holds the end offset of the + * detected match. No len value is set. + * If the device doesn't support this feature it means the match + * result holds the starting position of match and the length of the match. + * + * @see struct rte_regexdev_info::regexdev_capa + */ + +#define RTE_REGEXDEV_SUPP_CROSS_BUFFER_F (1ULL << 20) +/**< RegEx device support cross buffer match. + * Cross buffer matching means that the match can be detected even if the + * string was started in previous buffer. + * In case the device is configured as RTE_REGEXDEV_CFG_MATCH_AS_END + * the end offset will be relative for the first packet. + * For example RegEx is ABC the first buffer is xxxx second buffer yyyA and + * the last buffer BCzz. + * In case the match as end is configured the end offset will be 10. + * + * @see RTE_REGEXDEV_CFG_MATCH_AS_END_F + * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F + * @see RTE_REGEX_OPS_RSP_PMI_SOJ_F + * @see RTE_REGEX_OPS_RSP_PMI_EOJ_F + */ + +#define RTE_REGEXDEV_SUPP_MATCH_ALL_F (1ULL << 21) +/**< RegEx device support match all. + * Match all means that the RegEx engine will return all possible matches. + * For example, assume the RegEx is `A+b`, given the input AAAb the + * returned matches will be: Ab, AAb and AAAb. + * + * @see RTE_REGEXDEV_CFG_MATCH_ALL_F + */ + +/* Enumerates PCRE rule flags */ +#define RTE_REGEX_PCRE_RULE_ALLOW_EMPTY_F (1ULL << 0) +/**< When this flag is set, the pattern that can match against an empty string, + * such as `.*` are allowed. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_ANCHORED_F (1ULL << 1) +/**< When this flag is set, the pattern is forced to be "anchored", that is, it + * is constrained to match only at the first matching point in the string that + * is being searched. Similar to `^` and represented by `\A`. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_CASELESS_F (1ULL << 2) +/**< When this flag is set, letters in the pattern match both upper and lower + * case letters in the subject. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_DOTALL_F (1ULL << 3) +/**< When this flag is set, a dot metacharacter in the pattern matches any + * character, including one that indicates a newline. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_DUPNAMES_F (1ULL << 4) +/**< When this flag is set, names used to identify capture groups need not be + * unique. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_EXTENDED_F (1ULL << 5) +/**< When this flag is set, most white space characters in the pattern are + * totally ignored except when escaped or inside a character class. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_MATCH_UNSET_BACKREF_F (1ULL << 6) +/**< When this flag is set, a backreference to an unset capture group matches an + * empty string. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_MULTILINE_F (1ULL << 7) +/**< When this flag is set, the `^` and `$` constructs match immediately + * following or immediately before internal newlines in the subject string, + * respectively, as well as at the very start and end. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_NO_AUTO_CAPTURE_F (1ULL << 8) +/**< When this Flag is set, it disables the use of numbered capturing + * parentheses in the pattern. References to capture groups (backreferences or + * recursion/subroutine calls) may only refer to named groups, though the + * reference can be by name or by number. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_UCP_F (1ULL << 9) +/**< By default, only ASCII characters are recognized, When this flag is set, + * Unicode properties are used instead to classify characters. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_UNGREEDY_F (1ULL << 10) +/**< When this flag is set, the "greediness" of the quantifiers is inverted + * so that they are not greedy by default, but become greedy if followed by + * `?`. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_UTF_F (1ULL << 11) +/**< When this flag is set, RegEx engine has to regard both the pattern and the + * subject strings that are subsequently processed as strings of UTF characters + * instead of single-code-unit strings. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +#define RTE_REGEX_PCRE_RULE_NEVER_BACKSLASH_C_F (1ULL << 12) +/**< This flag locks out the use of `\C` in the pattern that is being compiled. + * This escape matches one data unit, even in UTF mode which can cause + * unpredictable behavior in UTF-8 or UTF-16 modes, because it may leave the + * current matching point in the mi:set hlsearchddle of a multi-code-unit + * character. + * + * @see struct rte_regexdev_info::rule_flags + * @see struct rte_regexdev_rule::rule_flags + */ + +/** + * RegEx device information + */ +struct rte_regexdev_info { + const char *driver_name; /**< RegEx driver name. */ + struct rte_device *dev; /**< Device information. */ + uint16_t max_matches; + /**< Maximum matches per scan supported by this device. */ + uint16_t max_queue_pairs; + /**< Maximum queue pairs supported by this device. */ + uint16_t max_payload_size; + /**< Maximum payload size for a pattern match request or scan. + * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F + */ + uint32_t max_rules_per_group; + /**< Maximum rules supported per group by this device. */ + uint16_t max_groups; + /**< Maximum groups supported by this device. */ + uint32_t regexdev_capa; + /**< RegEx device capabilities. @see RTE_REGEXDEV_CAPA_* */ + uint64_t rule_flags; + /**< Supported compiler rule flags. + * @see RTE_REGEX_PCRE_RULE_*, struct rte_regexdev_rule::rule_flags + */ +}; + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Retrieve the contextual information of a RegEx device. + * + * @param dev_id + * The identifier of the device. + * + * @param[out] dev_info + * A pointer to a structure of type *rte_regexdev_info* to be filled with the + * contextual information of the device. + * + * @return + * - 0: Success, driver updates the contextual information of the RegEx device + * - <0: Error code returned by the driver info get function. + */ +__rte_experimental +int +rte_regexdev_info_get(uint8_t dev_id, struct rte_regexdev_info *dev_info); + +/* Enumerates RegEx device configuration flags */ +#define RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F (1ULL << 0) +/**< Cross buffer scan refers to the ability to be able to detect + * matches that occur across buffer boundaries, where the buffers are related + * to each other in some way. Enable this flag when to scan payload size + * greater than struct rte_regexdev_info::max_payload_size and/or + * matches can present across scan buffer boundaries. + * + * @see struct rte_regexdev_info::max_payload_size + * @see struct rte_regexdev_config::dev_cfg_flags, rte_regexdev_configure() + * @see RTE_REGEX_OPS_RSP_PMI_SOJ_F + * @see RTE_REGEX_OPS_RSP_PMI_EOJ_F + */ + +#define RTE_REGEXDEV_CFG_MATCH_AS_END_F (1ULL << 1) +/**< Match as end is the ability to return the result as ending offset. + * When this flag is set, the result for each match will hold the ending + * offset of the match in end_offset. + * If this flag is not set, then the match result will hold the starting offset + * in start_offset, and the length of the match in len. + * + * @see RTE_REGEXDEV_SUPP_MATCH_AS_END_F + */ + +#define RTE_REGEXDEV_CFG_MATCH_ALL_F (1ULL << 2) +/**< Match all is the ability to return all possible results. + * + * @see RTE_REGEXDEV_SUPP_MATCH_ALL_F + */ + +/** RegEx device configuration structure */ +struct rte_regexdev_config { + uint16_t nb_max_matches; + /**< Maximum matches per scan configured on this device. + * This value cannot exceed the *max_matches* + * which previously provided in rte_regexdev_info_get(). + * The value 0 is allowed, in which case, value 1 used. + * @see struct rte_regexdev_info::max_matches + */ + uint16_t nb_queue_pairs; + /**< Number of RegEx queue pairs to configure on this device. + * This value cannot exceed the *max_queue_pairs* which previously + * provided in rte_regexdev_info_get(). + * @see struct rte_regexdev_info::max_queue_pairs + */ + uint32_t nb_rules_per_group; + /**< Number of rules per group to configure on this device. + * This value cannot exceed the *max_rules_per_group* + * which previously provided in rte_regexdev_info_get(). + * The value 0 is allowed, in which case, + * struct rte_regexdev_info::max_rules_per_group used. + * @see struct rte_regexdev_info::max_rules_per_group + */ + uint16_t nb_groups; + /**< Number of groups to configure on this device. + * This value cannot exceed the *max_groups* + * which previously provided in rte_regexdev_info_get(). + * @see struct rte_regexdev_info::max_groups + */ + const char *rule_db; + /**< Import initial set of prebuilt rule database on this device. + * The value NULL is allowed, in which case, the device will not + * be configured prebuilt rule database. Application may use + * rte_regexdev_rule_db_update() or rte_regexdev_rule_db_import() API + * to update or import rule database after the + * rte_regexdev_configure(). + * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_import() + */ + uint32_t rule_db_len; + /**< Length of *rule_db* buffer. */ + uint32_t dev_cfg_flags; + /**< RegEx device configuration flags, See RTE_REGEXDEV_CFG_* */ +}; + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Configure a RegEx device. + * + * This function must be invoked first before any other function in the + * API. This function can also be re-invoked when a device is in the + * stopped state. + * + * The caller may use rte_regexdev_info_get() to get the capability of each + * resources available for this regex device. + * + * @param dev_id + * The identifier of the device to configure. + * @param cfg + * The RegEx device configuration structure. + * + * @return + * - 0: Success, device configured. Otherwise negative errno is returned. + */ +__rte_experimental +int +rte_regexdev_configure(uint8_t dev_id, const struct rte_regexdev_config *cfg); + +/* Enumerates RegEx queue pair configuration flags */ +#define RTE_REGEX_QUEUE_PAIR_CFG_OOS_F (1ULL << 0) +/**< Out of order scan, If not set, a scan must retire after previously issued + * in-order scans to this queue pair. If set, this scan can be retired as soon + * as device returns completion. Application should not set out of order scan + * flag if it needs to maintain the ingress order of scan request. + * + * @see struct rte_regexdev_qp_conf::qp_conf_flags + * @see rte_regexdev_queue_pair_setup() + */ + +struct rte_regex_ops; +typedef void (*regexdev_stop_flush_t)(uint8_t dev_id, uint16_t qp_id, + struct rte_regex_ops *op); +/**< Callback function called during rte_regexdev_stop(), invoked once per + * flushed RegEx op. + */ + +/** RegEx queue pair configuration structure */ +struct rte_regexdev_qp_conf { + uint32_t qp_conf_flags; + /**< Queue pair config flags, See RTE_REGEX_QUEUE_PAIR_CFG_* */ + uint16_t nb_desc; + /**< The number of descriptors to allocate for this queue pair. */ + regexdev_stop_flush_t cb; + /**< Callback function called during rte_regexdev_stop(), invoked + * once per flushed regex op. Value NULL is allowed, in which case + * callback will not be invoked. This function can be used to properly + * dispose of outstanding regex ops from response queue, + * for example ops containing memory pointers. + * @see rte_regexdev_stop() + */ +}; + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Allocate and set up a RegEx queue pair for a RegEx device. + * + * @param dev_id + * The identifier of the device. + * @param queue_pair_id + * The index of the RegEx queue pair to setup. The value must be in the range + * [0, nb_queue_pairs - 1] previously supplied to rte_regexdev_configure(). + * @param qp_conf + * The pointer to the configuration data to be used for the RegEx queue pair. + * NULL value is allowed, in which case default configuration used. + * + * @return + * 0 on success. Otherwise negative errno is returned. + */ +__rte_experimental +int +rte_regexdev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id, + const struct rte_regexdev_qp_conf *qp_conf); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Start a RegEx device. + * + * The device start step is the last one and consists of setting the RegEx + * queues to start accepting the pattern matching scan requests. + * + * On success, all basic functions exported by the API (RegEx enqueue, + * RegEx dequeue and so on) can be invoked. + * + * @param dev_id + * RegEx device identifier. + * + * @return + * 0 on success. Otherwise negative errno is returned. + */ +__rte_experimental +int +rte_regexdev_start(uint8_t dev_id); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Stop a RegEx device. + * + * Stop a RegEx device. The device can be restarted with a call to + * rte_regexdev_start(). + * + * This function causes all queued response regex ops to be drained in the + * response queue. While draining ops out of the device, + * struct rte_regexdev_qp_conf::cb will be invoked for each ops. + * + * @param dev_id + * RegEx device identifier. + * + * @return + * 0 on success. Otherwise negative errno is returned. + */ +__rte_experimental +int +rte_regexdev_stop(uint8_t dev_id); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Close a RegEx device. The device cannot be restarted! + * + * @param dev_id + * RegEx device identifier + * + * @return + * 0 on success. Otherwise negative errno is returned. + */ +__rte_experimental +int +rte_regexdev_close(uint8_t dev_id); + +/* Device get/set attributes */ + +/** Enumerates RegEx device attribute identifier */ +enum rte_regexdev_attr_id { + RTE_REGEXDEV_ATTR_SOCKET_ID, + /**< The NUMA socket id to which the device is connected or + * a default of zero if the socket could not be determined. + * datatype: *int* + * operation: *get* + */ + RTE_REGEXDEV_ATTR_MAX_MATCHES, + /**< Maximum number of matches per scan. + * datatype: *uint8_t* + * operation: *get* and *set* + * @see RTE_REGEX_OPS_RSP_MAX_MATCH_F + */ + RTE_REGEXDEV_ATTR_MAX_SCAN_TIMEOUT, + /**< Upper bound scan time in ns. + * datatype: *uint16_t* + * operation: *get* and *set* + * @see RTE_REGEX_OPS_RSP_MAX_SCAN_TIMEOUT_F + */ + RTE_REGEXDEV_ATTR_MAX_PREFIX, + /**< Maximum number of prefix detected per scan. + * This would be useful for denial of service detection. + * datatype: *uint16_t* + * operation: *get* and *set* + * @see RTE_REGEX_OPS_RSP_MAX_PREFIX_F + */ +}; + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Get an attribute from a RegEx device. + * + * @param dev_id + * RegEx device identifier. + * @param attr_id + * The attribute ID to retrieve. + * @param attr_value + * A pointer that will be filled in with the attribute + * value if successful. + * + * @return + * - 0: Successfully retrieved attribute value. + * - -EINVAL: Invalid device or *attr_id* provided, or *attr_value* is NULL. + * - -ENOTSUP: if the device doesn't support specific *attr_id*. + */ +__rte_experimental +int +rte_regexdev_attr_get(uint8_t dev_id, enum rte_regexdev_attr_id attr_id, + void *attr_value); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Set an attribute to a RegEx device. + * + * @param dev_id + * RegEx device identifier. + * @param attr_id + * The attribute ID to retrieve. + * @param attr_value + * Pointer that will be filled in with the attribute value + * by the application. + * + * @return + * - 0: Successfully applied the attribute value. + * - -EINVAL: Invalid device or *attr_id* provided, or *attr_value* is NULL. + * - -ENOTSUP: if the device doesn't support specific *attr_id*. + */ +__rte_experimental +int +rte_regexdev_attr_set(uint8_t dev_id, enum rte_regexdev_attr_id attr_id, + const void *attr_value); + +/* Rule related APIs */ +/** Enumerates RegEx rule operation. */ +enum rte_regexdev_rule_op { + RTE_REGEX_RULE_OP_ADD, + /**< Add RegEx rule to rule database. */ + RTE_REGEX_RULE_OP_REMOVE + /**< Remove RegEx rule from rule database. */ +}; + +/** Structure to hold a RegEx rule attributes. */ +struct rte_regexdev_rule { + enum rte_regexdev_rule_op op; + /**< OP type of the rule either a OP_ADD or OP_DELETE. */ + uint16_t group_id; + /**< Group identifier to which the rule belongs to. */ + uint32_t rule_id; + /**< Rule identifier which is returned on successful match. */ + const char *pcre_rule; + /**< Buffer to hold the PCRE rule. */ + uint16_t pcre_rule_len; + /**< Length of the PCRE rule. */ + uint64_t rule_flags; + /* PCRE rule flags. Supported device specific PCRE rules enumerated + * in struct rte_regexdev_info::rule_flags. For successful rule + * database update, application needs to provide only supported + * rule flags. + * @See RTE_REGEX_PCRE_RULE_*, struct rte_regexdev_info::rule_flags + */ +}; + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Update the local rule set. + * This functions only modify the rule set in memory. + * In order for the changes to take effect, the function + * rte_regexdev_rule_db_compile_active must be called. + * + * @param dev_id + * RegEx device identifier. + * @param rules + * Points to an array of *nb_rules* objects of type *rte_regexdev_rule* + * structure which contain the regex rules attributes to be updated + * in rule database. + * @param nb_rules + * The number of PCRE rules to update the rule database. + * + * @return + * The number of regex rules actually updated on the regex device's rule + * database. The return value can be less than the value of the *nb_rules* + * parameter when the regex devices fails to update the rule database or + * if invalid parameters are specified in a *rte_regexdev_rule*. + * If the return value is less than *nb_rules*, the remaining PCRE rules + * at the end of *rules* are not consumed and the caller has to take + * care of them and rte_errno is set accordingly. + * Possible errno values include: + * - -EINVAL: Invalid device ID or rules is NULL + * - -ENOTSUP: The last processed rule is not supported on this device. + * - -ENOSPC: No space available in rule database. + * + * @see rte_regexdev_rule_db_import(), rte_regexdev_rule_db_export(), + * rte_regexdev_rule_db_compile_activate() + */ +__rte_experimental +int +rte_regexdev_rule_db_update(uint8_t dev_id, + const struct rte_regexdev_rule *rules, + uint32_t nb_rules); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Compile local rule set and burn the complied result to the + * RegEx deive. + * + * @param dev_id + * RegEx device identifier. + * + * @return + * 0 on success, otherwise negative errno. + * + * @see rte_regexdev_rule_db_import(), rte_regexdev_rule_db_export(), + * rte_regexdev_rule_db_update() + */ +__rte_experimental +int +rte_regexdev_rule_db_compile_activate(uint8_t dev_id); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Import a prebuilt rule database from a buffer to a RegEx device. + * + * @param dev_id + * RegEx device identifier. + * @param rule_db + * Points to prebuilt rule database. + * @param rule_db_len + * Length of the rule database. + * + * @return + * - 0: Successfully updated the prebuilt rule database. + * - -EINVAL: Invalid device ID or rule_db is NULL + * - -ENOTSUP: Rule database import is not supported on this device. + * - -ENOSPC: No space available in rule database. + * + * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_export() + */ +__rte_experimental +int +rte_regexdev_rule_db_import(uint8_t dev_id, const char *rule_db, + uint32_t rule_db_len); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Export the prebuilt rule database from a RegEx device to the buffer. + * + * @param dev_id + * RegEx device identifier. + * @param[out] rule_db + * Block of memory to insert the rule database. Must be at least size in + * capacity. If set to NULL, function returns required capacity. + * + * @return + * - 0: Successfully exported the prebuilt rule database. + * - size: If rule_db set to NULL then required capacity for *rule_db* + * - -EINVAL: Invalid device ID + * - -ENOTSUP: Rule database export is not supported on this device. + * + * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_import() + */ +__rte_experimental +int +rte_regexdev_rule_db_export(uint8_t dev_id, char *rule_db); + +/* Extended statistics */ +/** Maximum name length for extended statistics counters */ +#define RTE_REGEXDEV_XSTATS_NAME_SIZE 64 + +/** + * A name-key lookup element for extended statistics. + * + * This structure is used to map between names and ID numbers + * for extended RegEx device statistics. + */ +struct rte_regexdev_xstats_map { + uint16_t id; + /**< xstat identifier */ + char name[RTE_REGEXDEV_XSTATS_NAME_SIZE]; + /**< xstat name */ +}; + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Retrieve names of extended statistics of a regex device. + * + * @param dev_id + * The identifier of the regex device. + * @param[out] xstats_map + * Block of memory to insert id and names into. Must be at least size in + * capacity. If set to NULL, function returns required capacity. + * @return + * - Positive value on success: + * -The return value is the number of entries filled in the stats map. + * -If xstats_map set to NULL then required capacity for xstats_map. + * - Negative value on error: + * -ENODEV for invalid *dev_id* + * -ENOTSUP if the device doesn't support this function. + */ +__rte_experimental +int +rte_regexdev_xstats_names_get(uint8_t dev_id, + struct rte_regexdev_xstats_map *xstats_map); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Retrieve extended statistics of an regex device. + * + * @param dev_id + * The identifier of the device. + * @param ids + * The id numbers of the stats to get. The ids can be got from the stat + * position in the stat list from rte_regexdev_xstats_names_get(), or + * by using rte_regexdev_xstats_by_name_get(). + * @param values + * The values for each stats request by ID. + * @param nb_values + * The number of stats requested. + * @return + * - Positive value: number of stat entries filled into the values array + * - Negative value on error: + * -ENODEV for invalid *dev_id* + * -ENOTSUP if the device doesn't support this function. + */ +__rte_experimental +int +rte_regexdev_xstats_get(uint8_t dev_id, const uint16_t *ids, + uint64_t *values, uint16_t nb_values); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Retrieve the value of a single stat by requesting it by name. + * + * @param dev_id + * The identifier of the device. + * @param name + * The stat name to retrieve. + * @param id + * If non-NULL, the numerical id of the stat will be returned, so that further + * requests for the stat can be got using rte_regexdev_xstats_get, which will + * be faster as it doesn't need to scan a list of names for the stat. + * @param[out] value + * Must be non-NULL, retrieved xstat value will be stored in this address. + * + * @return + * - 0: Successfully retrieved xstat value. + * - -EINVAL: invalid parameters + * - -ENOTSUP: if not supported. + */ +__rte_experimental +int +rte_regexdev_xstats_by_name_get(uint8_t dev_id, const char *name, + uint16_t *id, uint64_t *value); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Reset the values of the xstats of the selected component in the device. + * + * @param dev_id + * The identifier of the device. + * @param ids + * Selects specific statistics to be reset. When NULL, all statistics will be + * reset. If non-NULL, must point to array of at least *nb_ids* size. + * @param nb_ids + * The number of ids available from the *ids* array. Ignored when ids is NULL. + * + * @return + * - 0: Successfully reset the statistics to zero. + * - -EINVAL: invalid parameters. + * - -ENOTSUP: if not supported. + */ +__rte_experimental +int +rte_regexdev_xstats_reset(uint8_t dev_id, const uint16_t *ids, + uint16_t nb_ids); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Trigger the RegEx device self test. + * + * @param dev_id + * The identifier of the device. + * @return + * - 0: Selftest successful. + * - -ENOTSUP if the device doesn't support selftest. + * - other values < 0 on failure. + */ +__rte_experimental +int +rte_regexdev_selftest(uint8_t dev_id); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Dump internal information about *dev_id* to the FILE* provided in *f*. + * + * @param dev_id + * The identifier of the device. + * @param f + * A pointer to a file for output. + * + * @return + * 0 on success, negative errno on failure. + */ +__rte_experimental +int +rte_regexdev_dump(uint8_t dev_id, FILE *f); + +/* Fast path APIs */ + +/** + * The generic *rte_regexdev_match* structure to hold the RegEx match + * attributes. + * @see struct rte_regex_ops::matches + */ +struct rte_regexdev_match { + RTE_STD_C11 + union { + uint64_t u64; + struct { + uint32_t rule_id:20; + /**< Rule identifier to which the pattern matched. + * @see struct rte_regexdev_rule::rule_id + */ + uint32_t group_id:12; + /**< Group identifier of the rule which the pattern + * matched. @see struct rte_regexdev_rule::group_id + */ + uint16_t start_offset; + /**< Starting Byte Position for matched rule. */ + RTE_STD_C11 + union { + uint16_t len; + /**< Length of match in bytes */ + uint16_t end_offset; + /**< The end offset of the match. In case + * MATCH_AS_END configuration is enabled. + * @see RTE_REGEXDEV_CFG_MATCH_AS_END + */ + }; + }; + }; +}; + +/* Enumerates RegEx request flags. */ +#define RTE_REGEX_OPS_REQ_GROUP_ID0_VALID_F (1 << 0) +/**< Set when struct rte_regexdev_rule::group_id0 is valid. */ + +#define RTE_REGEX_OPS_REQ_GROUP_ID1_VALID_F (1 << 1) +/**< Set when struct rte_regexdev_rule::group_id1 is valid. */ + +#define RTE_REGEX_OPS_REQ_GROUP_ID2_VALID_F (1 << 2) +/**< Set when struct rte_regexdev_rule::group_id2 is valid. */ + +#define RTE_REGEX_OPS_REQ_GROUP_ID3_VALID_F (1 << 3) +/**< Set when struct rte_regexdev_rule::group_id3 is valid. */ + +#define RTE_REGEX_OPS_REQ_STOP_ON_MATCH_F (1 << 4) +/**< The RegEx engine will stop scanning and return the first match. */ + +#define RTE_REGEX_OPS_REQ_MATCH_HIGH_PRIORITY_F (1 << 5) +/**< In High Priority mode a maximum of one match will be returned per scan to + * reduce the post-processing required by the application. The match with the + * lowest Rule id, lowest start pointer and lowest match length will be + * returned. + * + * @see struct rte_regex_ops::nb_actual_matches + * @see struct rte_regex_ops::nb_matches + */ + + +/* Enumerates RegEx response flags. */ +#define RTE_REGEX_OPS_RSP_PMI_SOJ_F (1 << 0) +/**< Indicates that the RegEx device has encountered a partial match at the + * start of scan in the given buffer. + * + * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F + */ + +#define RTE_REGEX_OPS_RSP_PMI_EOJ_F (1 << 1) +/**< Indicates that the RegEx device has encountered a partial match at the + * end of scan in the given buffer. + * + * @see RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F + */ + +#define RTE_REGEX_OPS_RSP_MAX_SCAN_TIMEOUT_F (1 << 2) +/**< Indicates that the RegEx device has exceeded the max timeout while + * scanning the given buffer. + * + * @see RTE_REGEXDEV_ATTR_MAX_SCAN_TIMEOUT + */ + +#define RTE_REGEX_OPS_RSP_MAX_MATCH_F (1 << 3) +/**< Indicates that the RegEx device has exceeded the max matches while + * scanning the given buffer. + * + * @see RTE_REGEXDEV_ATTR_MAX_MATCHES + */ + +#define RTE_REGEX_OPS_RSP_MAX_PREFIX_F (1 << 4) +/**< Indicates that the RegEx device has reached the max allowed prefix length + * while scanning the given buffer. + * + * @see RTE_REGEXDEV_ATTR_MAX_PREFIX + */ + +/** + * The generic *rte_regex_ops* structure to hold the RegEx attributes + * for enqueue and dequeue operation. + */ +struct rte_regex_ops { + /* W0 */ + uint16_t req_flags; + /**< Request flags for the RegEx ops. + * @see RTE_REGEX_OPS_REQ_* + */ + uint16_t rsp_flags; + /**< Response flags for the RegEx ops. + * @see RTE_REGEX_OPS_RSP_* + */ + uint16_t nb_actual_matches; + /**< The total number of actual matches detected by the Regex device.*/ + uint16_t nb_matches; + /**< The total number of matches returned by the RegEx device for this + * scan. The size of *rte_regex_ops::matches* zero length array will be + * this value. + * + * @see struct rte_regex_ops::matches, struct rte_regexdev_match + */ + + /* W1 */ + struct rte_mbuf *mbuf; /**< source mbuf, to search in. */ + + /* W2 */ + uint16_t group_id0; + /**< First group_id to match the rule against. At minimum one group + * should be valid. Behaviour is undefined non of the groups are valid. + * + * @see RTE_REGEX_OPS_REQ_GROUP_ID0_VALID_F + */ + uint16_t group_id1; + /**< Second group_id to match the rule against. + * + * @see RTE_REGEX_OPS_REQ_GROUP_ID1_VALID_F + */ + uint16_t group_id2; + /**< Third group_id to match the rule against. + * + * @see RTE_REGEX_OPS_REQ_GROUP_ID2_VALID_F + */ + uint16_t group_id3; + /**< Forth group_id to match the rule against. + * + * @see RTE_REGEX_OPS_REQ_GROUP_ID3_VALID_F + */ + + /* W3 */ + RTE_STD_C11 + union { + uint64_t user_id; + /**< Application specific opaque value. An application may use + * this field to hold application specific value to share + * between dequeue and enqueue operation. + * Implementation should not modify this field. + */ + void *user_ptr; + /**< Pointer representation of *user_id* */ + }; + + /* W4 */ + RTE_STD_C11 + union { + uint64_t cross_buf_id; + /**< ID used by the RegEx device in order to support cross + * packet detection. + * This ID is returned from the RegEx device on the dequeue + * function. The application must send it back when calling + * enqueue with the following packet. + */ + void *cross_buf_ptr; + /**< Pointer representation of *corss_buf_id* */ + }; + + /* W5 */ + struct rte_regexdev_match matches[]; + /**< Zero length array to hold the match tuples. + * The struct rte_regex_ops::nb_matches value holds the number of + * elements in this array. + * + * @see struct rte_regex_ops::nb_matches + */ +}; + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Enqueue a burst of scan request on a RegEx device. + * + * The rte_regexdev_enqueue_burst() function is invoked to place + * regex operations on the queue *qp_id* of the device designated by + * its *dev_id*. + * + * The *nb_ops* parameter is the number of operations to process which are + * supplied in the *ops* array of *rte_regexdev_op* structures. + * + * The rte_regexdev_enqueue_burst() function returns the number of + * operations it actually enqueued for processing. A return value equal to + * *nb_ops* means that all packets have been enqueued. + * + * @param dev_id + * The identifier of the device. + * @param qp_id + * The index of the queue pair which packets are to be enqueued for + * processing. The value must be in the range [0, nb_queue_pairs - 1] + * previously supplied to rte_regexdev_configure(). + * @param ops + * The address of an array of *nb_ops* pointers to *rte_regexdev_op* + * structures which contain the regex operations to be processed. + * @param nb_ops + * The number of operations to process. + * + * @return + * The number of operations actually enqueued on the regex device. The return + * value can be less than the value of the *nb_ops* parameter when the + * regex devices queue is full or if invalid parameters are specified in + * a *rte_regexdev_op*. If the return value is less than *nb_ops*, the + * remaining ops at the end of *ops* are not consumed and the caller has + * to take care of them. + */ +__rte_experimental +uint16_t +rte_regexdev_enqueue_burst(uint8_t dev_id, uint16_t qp_id, + struct rte_regex_ops **ops, uint16_t nb_ops); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Dequeue a burst of scan response from a queue on the RegEx device. + * The dequeued operation are stored in *rte_regexdev_op* structures + * whose pointers are supplied in the *ops* array. + * + * The rte_regexdev_dequeue_burst() function returns the number of ops + * actually dequeued, which is the number of *rte_regexdev_op* data structures + * effectively supplied into the *ops* array. + * + * A return value equal to *nb_ops* indicates that the queue contained + * at least *nb_ops* operations, and this is likely to signify that other + * processed operations remain in the devices output queue. Applications + * implementing a "retrieve as many processed operations as possible" policy + * can check this specific case and keep invoking the + * rte_regexdev_dequeue_burst() function until a value less than + * *nb_ops* is returned. + * + * The rte_regexdev_dequeue_burst() function does not provide any error + * notification to avoid the corresponding overhead. + * + * @param dev_id + * The RegEx device identifier + * @param qp_id + * The index of the queue pair from which to retrieve processed packets. + * The value must be in the range [0, nb_queue_pairs - 1] previously + * supplied to rte_regexdev_configure(). + * @param ops + * The address of an array of pointers to *rte_regexdev_op* structures + * that must be large enough to store *nb_ops* pointers in it. + * @param nb_ops + * The maximum number of operations to dequeue. + * + * @return + * The number of operations actually dequeued, which is the number + * of pointers to *rte_regexdev_op* structures effectively supplied to the + * *ops* array. If the return value is less than *nb_ops*, the remaining + * ops at the end of *ops* are not consumed and the caller has to take care + * of them. + */ +__rte_experimental +uint16_t +rte_regexdev_dequeue_burst(uint8_t dev_id, uint16_t qp_id, + struct rte_regex_ops **ops, uint16_t nb_ops); + +#ifdef __cplusplus +} +#endif + +#endif /* _RTE_REGEXDEV_H_ */ diff --git a/lib/librte_regexdev/rte_regexdev_version.map b/lib/librte_regexdev/rte_regexdev_version.map new file mode 100644 index 0000000000..8db9b17018 --- /dev/null +++ b/lib/librte_regexdev/rte_regexdev_version.map @@ -0,0 +1,26 @@ +EXPERIMENTAL { + global: + + rte_regexdev_attr_get; + rte_regexdev_attr_set; + rte_regexdev_close; + rte_regexdev_configure; + rte_regexdev_count; + rte_regexdev_dequeue_burst; + rte_regexdev_dump; + rte_regexdev_enqueue_burst; + rte_regexdev_get_dev_id; + rte_regexdev_info_get; + rte_regexdev_queue_pair_setup; + rte_regexdev_rule_db_compile_activate; + rte_regexdev_rule_db_export; + rte_regexdev_rule_db_import; + rte_regexdev_rule_db_update; + rte_regexdev_selftest; + rte_regexdev_start; + rte_regexdev_stop; + rte_regexdev_xstats_by_name_get; + rte_regexdev_xstats_get; + rte_regexdev_xstats_names_get; + rte_regexdev_xstats_reset; +}; diff --git a/lib/meson.build b/lib/meson.build index 8ca25172c3..80c37afa8f 100644 --- a/lib/meson.build +++ b/lib/meson.build @@ -24,7 +24,7 @@ libraries = [ 'distributor', 'efd', 'eventdev', 'gro', 'gso', 'ip_frag', 'jobstats', 'kni', 'latencystats', 'lpm', 'member', - 'power', 'pdump', 'rawdev', + 'power', 'pdump', 'rawdev', 'regexdev', 'rib', 'reorder', 'sched', 'security', 'stack', 'vhost', # ipsec lib depends on net, crypto and security 'ipsec',