| Message ID | 1588844756-10086-2-git-send-email-orika@mellanox.com (mailing list archive) |
|---|---|
| State | Superseded, archived |
| Delegated to: | Thomas Monjalon |
| Headers | show |
| Series | add RegEx class | expand |
| Context | Check | Description |
|---|---|---|
| ci/iol-testing | success | Testing PASS |
| ci/iol-testing | fail | Testing issues |
| ci/iol-mellanox-Performance | success | Performance Testing PASS |
| ci/Intel-compilation | fail | Compilation issues |
| ci/iol-nxp-Performance | success | Performance Testing PASS |
| ci/iol-intel-Performance | success | Performance Testing PASS |
| ci/checkpatch | success | coding style OK |
Hi All, This is the only patch that is missing an ack, I plan to submit the PMD code next week, so please review and ack this patch. Thanks, Ori > -----Original Message----- > From: dev <dev-bounces@dpdk.org> On Behalf Of Ori Kam > Sent: Thursday, May 7, 2020 12:46 PM > To: jerinj@marvell.com; xiang.w.wang@intel.com > Cc: guyk@marvell.com; dev@dpdk.org; pbhagavatula@marvell.com; Shahaf > Shuler <shahafs@mellanox.com>; hemant.agrawal@nxp.com; Opher Reviv > <opher@mellanox.com>; Alex Rosenbaum <alexr@mellanox.com>; > dovrat@marvell.com; pkapoor@marvell.com; nipun.gupta@nxp.com; > bruce.richardson@intel.com; yang.a.hong@intel.com; harry.chang@intel.com; > gu.jian1@zte.com.cn; shanjiangh@chinatelecom.cn; > zhangy.yun@chinatelecom.cn; lixingfu@huachentel.com; wushuai@inspur.com; > yuyingxia@yxlink.com; fanchenggang@sunyainfo.com; > davidfgao@tencent.com; liuzhong1@chinaunicom.cn; > zhaoyong11@huawei.com; oc@yunify.com; jim@netgate.com; > hongjun.ni@intel.com; j.bromhead@titan-ic.com; deri@ntop.org; > fc@napatech.com; arthur.su@lionic.com; Thomas Monjalon > <thomas@monjalon.net>; Ori Kam <orika@mellanox.com> > Subject: [dpdk-dev] [PATCH v3 1/4] regexdev: introduce regexdev subsystem > > From: Jerin Jacob <jerinj@marvell.com> > > As RegEx usage become more used by DPDK applications, for example: > * Next Generation Firewalls (NGFW) > * Deep Packet and Flow Inspection (DPI) > * Intrusion Prevention Systems (IPS) > * DDoS Mitigation > * Network Monitoring > * Data Loss Prevention (DLP) > * Smart NICs > * Grammar based content processing > * URL, spam and adware filtering > * Advanced auditing and policing of user/application security policies > * Financial data mining - parsing of streamed financial feeds > * Application recognition. > * Dmemory introspection. > * Natural Language Processing (NLP) > * Sentiment Analysis. > * Big data databse acceleration. > * Computational storage. > > Number of PMD providers started to work on HW implementation, > along side with SW implementations. > > This lib adds the support for those kind of devices. > > 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: > https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fregexkit.so > urceforge.net%2FDocumentation%2Fpcre%2Fpcrepattern.html&data=02% > 7C01%7Corika%40mellanox.com%7C39f5765e405c46b18ba308d7f26b8480%7C > a652971c7d2e4d9ba6a4d149256f461b%7C0%7C0%7C637244415961144968&a > mp;sdata=NWYja3g5nTerSe8vIFSHpTeK8ipKOhMnXmmNBuJtWqY%3D&res > erved=0 > > 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() > > Signed-off-by: Jerin Jacob <jerinj@marvell.com> > Signed-off-by: Pavan Nikhilesh <pbhagavatula@marvell.com> > Signed-off-by: Ori Kam <orika@mellanox.com> > --- > v3: > * No changes. > > v2: > * Move unused define to other patch. > --- > config/common_base | 6 + > doc/api/doxy-api-index.md | 1 + > doc/api/doxy-api.conf.in | 1 + > doc/guides/prog_guide/index.rst | 1 + > doc/guides/prog_guide/regexdev_lib.rst | 177 ++++ > lib/Makefile | 2 + > lib/librte_regexdev/Makefile | 31 + > lib/librte_regexdev/meson.build | 7 + > lib/librte_regexdev/rte_regexdev.c | 6 + > lib/librte_regexdev/rte_regexdev.h | 1473 > ++++++++++++++++++++++++++ > lib/librte_regexdev/rte_regexdev_version.map | 26 + > lib/meson.build | 2 +- > 12 files changed, 1732 insertions(+), 1 deletion(-) > create mode 100644 doc/guides/prog_guide/regexdev_lib.rst > create mode 100644 lib/librte_regexdev/Makefile > create mode 100644 lib/librte_regexdev/meson.build > create mode 100644 lib/librte_regexdev/rte_regexdev.c > create mode 100644 lib/librte_regexdev/rte_regexdev.h > create mode 100644 lib/librte_regexdev/rte_regexdev_version.map > > diff --git a/config/common_base b/config/common_base > index 14000ba..27fcab1 100644 > --- a/config/common_base > +++ b/config/common_base > @@ -832,6 +832,11 @@ > CONFIG_RTE_LIBRTE_PMD_OCTEONTX2_EP_RAWDEV=y > CONFIG_RTE_LIBRTE_PMD_NTB_RAWDEV=y > > # > +# Compile regex device support > +# > +CONFIG_RTE_LIBRTE_REGEXDEV=y > + > +# > # Compile librte_ring > # > CONFIG_RTE_LIBRTE_RING=y > @@ -1124,3 +1129,4 @@ CONFIG_RTE_APP_CRYPTO_PERF=y > # Compile the eventdev application > # > CONFIG_RTE_APP_EVENTDEV=y > + > diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md > index 845a534..702591b 100644 > --- a/doc/api/doxy-api-index.md > +++ b/doc/api/doxy-api-index.md > @@ -26,6 +26,7 @@ The public API headers are grouped by topics: > [event_timer_adapter] (@ref rte_event_timer_adapter.h), > [event_crypto_adapter] (@ref rte_event_crypto_adapter.h), > [rawdev] (@ref rte_rawdev.h), > + [regexdev] (@ref rte_regexdev.h), > [metrics] (@ref rte_metrics.h), > [bitrate] (@ref rte_bitrate.h), > [latency] (@ref rte_latencystats.h), > diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in > index 65e8146..84621ba 100644 > --- a/doc/api/doxy-api.conf.in > +++ b/doc/api/doxy-api.conf.in > @@ -58,6 +58,7 @@ INPUT = @TOPDIR@/doc/api/doxy-api- > index.md \ > @TOPDIR@/lib/librte_rcu \ > @TOPDIR@/lib/librte_reorder \ > @TOPDIR@/lib/librte_rib \ > + @TOPDIR@/lib/librte_regexdev \ > @TOPDIR@/lib/librte_ring \ > @TOPDIR@/lib/librte_sched \ > @TOPDIR@/lib/librte_security \ > diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst > index 1d0cd49..fa8536c 100644 > --- a/doc/guides/prog_guide/index.rst > +++ b/doc/guides/prog_guide/index.rst > @@ -71,3 +71,4 @@ Programmer's Guide > lto > profile_app > glossary > + regexdev_lib > diff --git a/doc/guides/prog_guide/regexdev_lib.rst > b/doc/guides/prog_guide/regexdev_lib.rst > new file mode 100644 > index 0000000..1ecbf1c > --- /dev/null > +++ b/doc/guides/prog_guide/regexdev_lib.rst > @@ -0,0 +1,177 @@ > +.. SPDX-License-Identifier: BSD-3-Clause > + Copyright(c) 2020 Mellanox Corporation. > + > +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/lib/Makefile b/lib/Makefile > index d0ec391..6a3d4e3 100644 > --- a/lib/Makefile > +++ b/lib/Makefile > @@ -44,6 +44,8 @@ DEPDIRS-librte_eventdev := librte_eal librte_ring > librte_ethdev librte_hash \ > librte_mempool librte_timer librte_cryptodev > DIRS-$(CONFIG_RTE_LIBRTE_RAWDEV) += librte_rawdev > DEPDIRS-librte_rawdev := librte_eal librte_ethdev > +DIRS-$(CONFIG_RTE_LIBRTE_REGEXDEV) += librte_regexdev > +DEPDIRS-librte_regexdev := librte_eal librte_mbuf > DIRS-$(CONFIG_RTE_LIBRTE_VHOST) += librte_vhost > DEPDIRS-librte_vhost := librte_eal librte_mempool librte_mbuf librte_ethdev \ > librte_net librte_hash librte_cryptodev > diff --git a/lib/librte_regexdev/Makefile b/lib/librte_regexdev/Makefile > new file mode 100644 > index 0000000..6f4cc63 > --- /dev/null > +++ b/lib/librte_regexdev/Makefile > @@ -0,0 +1,31 @@ > +# SPDX-License-Identifier: BSD-3-Clause > +# Copyright(C) 2019 Marvell International Ltd. > +# Copyright(C) 2020 Mellanox International 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 0000000..f4db748 > --- /dev/null > +++ b/lib/librte_regexdev/meson.build > @@ -0,0 +1,7 @@ > +# SPDX-License-Identifier: BSD-3-Clause > +# Copyright(c) 2020 Mellanox Corporation > + > +allow_experimental_apis = true > +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 0000000..b901877 > --- /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(C) 2020 Mellanox International 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 0000000..7e688d9 > --- /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(C) 2020 Mellanox International Ltd. > + * Copyright(C) 2020 Intel International Ltd. > + */ > + > +#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: > + * > https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fregexkit.so > urceforge.net%2FDocumentation%2Fpcre%2Fpcrepattern.html&data=02% > 7C01%7Corika%40mellanox.com%7C39f5765e405c46b18ba308d7f26b8480%7C > a652971c7d2e4d9ba6a4d149256f461b%7C0%7C0%7C637244415961144968&a > mp;sdata=NWYja3g5nTerSe8vIFSHpTeK8ipKOhMnXmmNBuJtWqY%3D&res > erved=0 > + * > + * 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 <rte_common.h> > +#include <rte_config.h> > +#include <rte_dev.h> > +#include <rte_errno.h> > +#include <rte_mbuf.h> > +#include <rte_memory.h> > + > +/** > + * @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. > + * > + * @see struct rte_regexdev_qp_conf::cb, rte_regexdev_queue_pair_setup() > + */ > +__rte_experimental > +void > +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 0000000..d400624 > --- /dev/null > +++ b/lib/librte_regexdev/rte_regexdev_version.map > @@ -0,0 +1,26 @@ > +EXPERIMENTAL { > + global: > + > + rte_regexdev_count; > + rte_regexdev_get_dev_id; > + rte_regexdev_info_get; > + rte_regexdev_configure; > + rte_regexdev_queue_pair_setup; > + rte_regexdev_start; > + rte_regexdev_stop; > + rte_regexdev_close; > + rte_regexdev_attr_get; > + rte_regexdev_attr_set; > + rte_regexdev_rule_db_update; > + rte_regexdev_rule_db_compile_activate; > + rte_regexdev_rule_db_import; > + rte_regexdev_rule_db_export; > + rte_regexdev_xstats_names_get; > + rte_regexdev_xstats_get; > + rte_regexdev_xstats_by_name_get; > + rte_regexdev_xstats_reset; > + rte_regexdev_selftest; > + rte_regexdev_dump; > + rte_regexdev_enqueue_burst; > + rte_regexdev_dequeue_burst; > +}; > diff --git a/lib/meson.build b/lib/meson.build > index 07a65a6..79ae5cb 100644 > --- a/lib/meson.build > +++ b/lib/meson.build > @@ -24,7 +24,7 @@ libraries = [ > 'gro', 'gso', 'ip_frag', 'jobstats', > 'kni', 'latencystats', 'lpm', 'member', > 'power', 'pdump', 'rawdev', > - 'rib', 'reorder', 'sched', 'security', 'stack', 'vhost', > + 'regexdev', 'rib', 'reorder', 'sched', 'security', 'stack', 'vhost', > # ipsec lib depends on net, crypto and security > 'ipsec', > #fib lib depends on rib > -- > 1.8.3.1
Hi all, Just a reminder for ack, Thanks, Ori > -----Original Message----- > From: Ori Kam <orika@mellanox.com> > Sent: Sunday, June 21, 2020 2:19 PM > To: Ori Kam <orika@mellanox.com>; jerinj@marvell.com; > xiang.w.wang@intel.com > Cc: guyk@marvell.com; dev@dpdk.org; pbhagavatula@marvell.com; Shahaf > Shuler <shahafs@mellanox.com>; hemant.agrawal@nxp.com; Opher Reviv > <opher@mellanox.com>; Alex Rosenbaum <alexr@mellanox.com>; > dovrat@marvell.com; pkapoor@marvell.com; nipun.gupta@nxp.com; > bruce.richardson@intel.com; yang.a.hong@intel.com; harry.chang@intel.com; > gu.jian1@zte.com.cn; shanjiangh@chinatelecom.cn; > zhangy.yun@chinatelecom.cn; lixingfu@huachentel.com; wushuai@inspur.com; > yuyingxia@yxlink.com; fanchenggang@sunyainfo.com; > davidfgao@tencent.com; liuzhong1@chinaunicom.cn; > zhaoyong11@huawei.com; oc@yunify.com; jim@netgate.com; > hongjun.ni@intel.com; j.bromhead@titan-ic.com; deri@ntop.org; > fc@napatech.com; arthur.su@lionic.com; Thomas Monjalon > <thomas@monjalon.net> > Subject: RE: [dpdk-dev] [PATCH v3 1/4] regexdev: introduce regexdev > subsystem > > Hi All, > > This is the only patch that is missing an ack, > > I plan to submit the PMD code next week, so please review and ack this patch. > > Thanks, > Ori > > > -----Original Message----- > > From: dev <dev-bounces@dpdk.org> On Behalf Of Ori Kam > > Sent: Thursday, May 7, 2020 12:46 PM > > To: jerinj@marvell.com; xiang.w.wang@intel.com > > Cc: guyk@marvell.com; dev@dpdk.org; pbhagavatula@marvell.com; Shahaf > > Shuler <shahafs@mellanox.com>; hemant.agrawal@nxp.com; Opher Reviv > > <opher@mellanox.com>; Alex Rosenbaum <alexr@mellanox.com>; > > dovrat@marvell.com; pkapoor@marvell.com; nipun.gupta@nxp.com; > > bruce.richardson@intel.com; yang.a.hong@intel.com; > harry.chang@intel.com; > > gu.jian1@zte.com.cn; shanjiangh@chinatelecom.cn; > > zhangy.yun@chinatelecom.cn; lixingfu@huachentel.com; > wushuai@inspur.com; > > yuyingxia@yxlink.com; fanchenggang@sunyainfo.com; > > davidfgao@tencent.com; liuzhong1@chinaunicom.cn; > > zhaoyong11@huawei.com; oc@yunify.com; jim@netgate.com; > > hongjun.ni@intel.com; j.bromhead@titan-ic.com; deri@ntop.org; > > fc@napatech.com; arthur.su@lionic.com; Thomas Monjalon > > <thomas@monjalon.net>; Ori Kam <orika@mellanox.com> > > Subject: [dpdk-dev] [PATCH v3 1/4] regexdev: introduce regexdev subsystem > > > > From: Jerin Jacob <jerinj@marvell.com> > > > > As RegEx usage become more used by DPDK applications, for example: > > * Next Generation Firewalls (NGFW) > > * Deep Packet and Flow Inspection (DPI) > > * Intrusion Prevention Systems (IPS) > > * DDoS Mitigation > > * Network Monitoring > > * Data Loss Prevention (DLP) > > * Smart NICs > > * Grammar based content processing > > * URL, spam and adware filtering > > * Advanced auditing and policing of user/application security policies > > * Financial data mining - parsing of streamed financial feeds > > * Application recognition. > > * Dmemory introspection. > > * Natural Language Processing (NLP) > > * Sentiment Analysis. > > * Big data databse acceleration. > > * Computational storage. > > > > Number of PMD providers started to work on HW implementation, > > along side with SW implementations. > > > > This lib adds the support for those kind of devices. > > > > 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: > > > https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fregexkit.so > > > urceforge.net%2FDocumentation%2Fpcre%2Fpcrepattern.html&data=02% > > > 7C01%7Corika%40mellanox.com%7C39f5765e405c46b18ba308d7f26b8480%7C > > > a652971c7d2e4d9ba6a4d149256f461b%7C0%7C0%7C637244415961144968&a > > > mp;sdata=NWYja3g5nTerSe8vIFSHpTeK8ipKOhMnXmmNBuJtWqY%3D&res > > erved=0 > > > > 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() > > > > Signed-off-by: Jerin Jacob <jerinj@marvell.com> > > Signed-off-by: Pavan Nikhilesh <pbhagavatula@marvell.com> > > Signed-off-by: Ori Kam <orika@mellanox.com> > > --- > > v3: > > * No changes. > > > > v2: > > * Move unused define to other patch. > > --- > > config/common_base | 6 + > > doc/api/doxy-api-index.md | 1 + > > doc/api/doxy-api.conf.in | 1 + > > doc/guides/prog_guide/index.rst | 1 + > > doc/guides/prog_guide/regexdev_lib.rst | 177 ++++ > > lib/Makefile | 2 + > > lib/librte_regexdev/Makefile | 31 + > > lib/librte_regexdev/meson.build | 7 + > > lib/librte_regexdev/rte_regexdev.c | 6 + > > lib/librte_regexdev/rte_regexdev.h | 1473 > > ++++++++++++++++++++++++++ > > lib/librte_regexdev/rte_regexdev_version.map | 26 + > > lib/meson.build | 2 +- > > 12 files changed, 1732 insertions(+), 1 deletion(-) > > create mode 100644 doc/guides/prog_guide/regexdev_lib.rst > > create mode 100644 lib/librte_regexdev/Makefile > > create mode 100644 lib/librte_regexdev/meson.build > > create mode 100644 lib/librte_regexdev/rte_regexdev.c > > create mode 100644 lib/librte_regexdev/rte_regexdev.h > > create mode 100644 lib/librte_regexdev/rte_regexdev_version.map > > > > diff --git a/config/common_base b/config/common_base > > index 14000ba..27fcab1 100644 > > --- a/config/common_base > > +++ b/config/common_base > > @@ -832,6 +832,11 @@ > > CONFIG_RTE_LIBRTE_PMD_OCTEONTX2_EP_RAWDEV=y > > CONFIG_RTE_LIBRTE_PMD_NTB_RAWDEV=y > > > > # > > +# Compile regex device support > > +# > > +CONFIG_RTE_LIBRTE_REGEXDEV=y > > + > > +# > > # Compile librte_ring > > # > > CONFIG_RTE_LIBRTE_RING=y > > @@ -1124,3 +1129,4 @@ CONFIG_RTE_APP_CRYPTO_PERF=y > > # Compile the eventdev application > > # > > CONFIG_RTE_APP_EVENTDEV=y > > + > > diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md > > index 845a534..702591b 100644 > > --- a/doc/api/doxy-api-index.md > > +++ b/doc/api/doxy-api-index.md > > @@ -26,6 +26,7 @@ The public API headers are grouped by topics: > > [event_timer_adapter] (@ref rte_event_timer_adapter.h), > > [event_crypto_adapter] (@ref rte_event_crypto_adapter.h), > > [rawdev] (@ref rte_rawdev.h), > > + [regexdev] (@ref rte_regexdev.h), > > [metrics] (@ref rte_metrics.h), > > [bitrate] (@ref rte_bitrate.h), > > [latency] (@ref rte_latencystats.h), > > diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in > > index 65e8146..84621ba 100644 > > --- a/doc/api/doxy-api.conf.in > > +++ b/doc/api/doxy-api.conf.in > > @@ -58,6 +58,7 @@ INPUT = @TOPDIR@/doc/api/doxy-api- > > index.md \ > > @TOPDIR@/lib/librte_rcu \ > > @TOPDIR@/lib/librte_reorder \ > > @TOPDIR@/lib/librte_rib \ > > + @TOPDIR@/lib/librte_regexdev \ > > @TOPDIR@/lib/librte_ring \ > > @TOPDIR@/lib/librte_sched \ > > @TOPDIR@/lib/librte_security \ > > diff --git a/doc/guides/prog_guide/index.rst > b/doc/guides/prog_guide/index.rst > > index 1d0cd49..fa8536c 100644 > > --- a/doc/guides/prog_guide/index.rst > > +++ b/doc/guides/prog_guide/index.rst > > @@ -71,3 +71,4 @@ Programmer's Guide > > lto > > profile_app > > glossary > > + regexdev_lib > > diff --git a/doc/guides/prog_guide/regexdev_lib.rst > > b/doc/guides/prog_guide/regexdev_lib.rst > > new file mode 100644 > > index 0000000..1ecbf1c > > --- /dev/null > > +++ b/doc/guides/prog_guide/regexdev_lib.rst > > @@ -0,0 +1,177 @@ > > +.. SPDX-License-Identifier: BSD-3-Clause > > + Copyright(c) 2020 Mellanox Corporation. > > + > > +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/lib/Makefile b/lib/Makefile > > index d0ec391..6a3d4e3 100644 > > --- a/lib/Makefile > > +++ b/lib/Makefile > > @@ -44,6 +44,8 @@ DEPDIRS-librte_eventdev := librte_eal librte_ring > > librte_ethdev librte_hash \ > > librte_mempool librte_timer librte_cryptodev > > DIRS-$(CONFIG_RTE_LIBRTE_RAWDEV) += librte_rawdev > > DEPDIRS-librte_rawdev := librte_eal librte_ethdev > > +DIRS-$(CONFIG_RTE_LIBRTE_REGEXDEV) += librte_regexdev > > +DEPDIRS-librte_regexdev := librte_eal librte_mbuf > > DIRS-$(CONFIG_RTE_LIBRTE_VHOST) += librte_vhost > > DEPDIRS-librte_vhost := librte_eal librte_mempool librte_mbuf librte_ethdev > \ > > librte_net librte_hash librte_cryptodev > > diff --git a/lib/librte_regexdev/Makefile b/lib/librte_regexdev/Makefile > > new file mode 100644 > > index 0000000..6f4cc63 > > --- /dev/null > > +++ b/lib/librte_regexdev/Makefile > > @@ -0,0 +1,31 @@ > > +# SPDX-License-Identifier: BSD-3-Clause > > +# Copyright(C) 2019 Marvell International Ltd. > > +# Copyright(C) 2020 Mellanox International 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 0000000..f4db748 > > --- /dev/null > > +++ b/lib/librte_regexdev/meson.build > > @@ -0,0 +1,7 @@ > > +# SPDX-License-Identifier: BSD-3-Clause > > +# Copyright(c) 2020 Mellanox Corporation > > + > > +allow_experimental_apis = true > > +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 0000000..b901877 > > --- /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(C) 2020 Mellanox International 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 0000000..7e688d9 > > --- /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(C) 2020 Mellanox International Ltd. > > + * Copyright(C) 2020 Intel International Ltd. > > + */ > > + > > +#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: > > + * > > > https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fregexkit.so > > > urceforge.net%2FDocumentation%2Fpcre%2Fpcrepattern.html&data=02% > > > 7C01%7Corika%40mellanox.com%7C39f5765e405c46b18ba308d7f26b8480%7C > > > a652971c7d2e4d9ba6a4d149256f461b%7C0%7C0%7C637244415961144968&a > > > mp;sdata=NWYja3g5nTerSe8vIFSHpTeK8ipKOhMnXmmNBuJtWqY%3D&res > > erved=0 > > + * > > + * 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 <rte_common.h> > > +#include <rte_config.h> > > +#include <rte_dev.h> > > +#include <rte_errno.h> > > +#include <rte_mbuf.h> > > +#include <rte_memory.h> > > + > > +/** > > + * @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. > > + * > > + * @see struct rte_regexdev_qp_conf::cb, rte_regexdev_queue_pair_setup() > > + */ > > +__rte_experimental > > +void > > +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 0000000..d400624 > > --- /dev/null > > +++ b/lib/librte_regexdev/rte_regexdev_version.map > > @@ -0,0 +1,26 @@ > > +EXPERIMENTAL { > > + global: > > + > > + rte_regexdev_count; > > + rte_regexdev_get_dev_id; > > + rte_regexdev_info_get; > > + rte_regexdev_configure; > > + rte_regexdev_queue_pair_setup; > > + rte_regexdev_start; > > + rte_regexdev_stop; > > + rte_regexdev_close; > > + rte_regexdev_attr_get; > > + rte_regexdev_attr_set; > > + rte_regexdev_rule_db_update; > > + rte_regexdev_rule_db_compile_activate; > > + rte_regexdev_rule_db_import; > > + rte_regexdev_rule_db_export; > > + rte_regexdev_xstats_names_get; > > + rte_regexdev_xstats_get; > > + rte_regexdev_xstats_by_name_get; > > + rte_regexdev_xstats_reset; > > + rte_regexdev_selftest; > > + rte_regexdev_dump; > > + rte_regexdev_enqueue_burst; > > + rte_regexdev_dequeue_burst; > > +}; > > diff --git a/lib/meson.build b/lib/meson.build > > index 07a65a6..79ae5cb 100644 > > --- a/lib/meson.build > > +++ b/lib/meson.build > > @@ -24,7 +24,7 @@ libraries = [ > > 'gro', 'gso', 'ip_frag', 'jobstats', > > 'kni', 'latencystats', 'lpm', 'member', > > 'power', 'pdump', 'rawdev', > > - 'rib', 'reorder', 'sched', 'security', 'stack', 'vhost', > > + 'regexdev', 'rib', 'reorder', 'sched', 'security', 'stack', 'vhost', > > # ipsec lib depends on net, crypto and security > > 'ipsec', > > #fib lib depends on rib > > -- > > 1.8.3.1
diff --git a/config/common_base b/config/common_base index 14000ba..27fcab1 100644 --- a/config/common_base +++ b/config/common_base @@ -832,6 +832,11 @@ CONFIG_RTE_LIBRTE_PMD_OCTEONTX2_EP_RAWDEV=y CONFIG_RTE_LIBRTE_PMD_NTB_RAWDEV=y # +# Compile regex device support +# +CONFIG_RTE_LIBRTE_REGEXDEV=y + +# # Compile librte_ring # CONFIG_RTE_LIBRTE_RING=y @@ -1124,3 +1129,4 @@ CONFIG_RTE_APP_CRYPTO_PERF=y # Compile the eventdev application # CONFIG_RTE_APP_EVENTDEV=y + diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index 845a534..702591b 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -26,6 +26,7 @@ The public API headers are grouped by topics: [event_timer_adapter] (@ref rte_event_timer_adapter.h), [event_crypto_adapter] (@ref rte_event_crypto_adapter.h), [rawdev] (@ref rte_rawdev.h), + [regexdev] (@ref rte_regexdev.h), [metrics] (@ref rte_metrics.h), [bitrate] (@ref rte_bitrate.h), [latency] (@ref rte_latencystats.h), diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in index 65e8146..84621ba 100644 --- a/doc/api/doxy-api.conf.in +++ b/doc/api/doxy-api.conf.in @@ -58,6 +58,7 @@ INPUT = @TOPDIR@/doc/api/doxy-api-index.md \ @TOPDIR@/lib/librte_rcu \ @TOPDIR@/lib/librte_reorder \ @TOPDIR@/lib/librte_rib \ + @TOPDIR@/lib/librte_regexdev \ @TOPDIR@/lib/librte_ring \ @TOPDIR@/lib/librte_sched \ @TOPDIR@/lib/librte_security \ diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 1d0cd49..fa8536c 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -71,3 +71,4 @@ Programmer's Guide lto profile_app glossary + regexdev_lib diff --git a/doc/guides/prog_guide/regexdev_lib.rst b/doc/guides/prog_guide/regexdev_lib.rst new file mode 100644 index 0000000..1ecbf1c --- /dev/null +++ b/doc/guides/prog_guide/regexdev_lib.rst @@ -0,0 +1,177 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2020 Mellanox Corporation. + +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/lib/Makefile b/lib/Makefile index d0ec391..6a3d4e3 100644 --- a/lib/Makefile +++ b/lib/Makefile @@ -44,6 +44,8 @@ DEPDIRS-librte_eventdev := librte_eal librte_ring librte_ethdev librte_hash \ librte_mempool librte_timer librte_cryptodev DIRS-$(CONFIG_RTE_LIBRTE_RAWDEV) += librte_rawdev DEPDIRS-librte_rawdev := librte_eal librte_ethdev +DIRS-$(CONFIG_RTE_LIBRTE_REGEXDEV) += librte_regexdev +DEPDIRS-librte_regexdev := librte_eal librte_mbuf DIRS-$(CONFIG_RTE_LIBRTE_VHOST) += librte_vhost DEPDIRS-librte_vhost := librte_eal librte_mempool librte_mbuf librte_ethdev \ librte_net librte_hash librte_cryptodev diff --git a/lib/librte_regexdev/Makefile b/lib/librte_regexdev/Makefile new file mode 100644 index 0000000..6f4cc63 --- /dev/null +++ b/lib/librte_regexdev/Makefile @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(C) 2019 Marvell International Ltd. +# Copyright(C) 2020 Mellanox International 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 0000000..f4db748 --- /dev/null +++ b/lib/librte_regexdev/meson.build @@ -0,0 +1,7 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2020 Mellanox Corporation + +allow_experimental_apis = true +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 0000000..b901877 --- /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(C) 2020 Mellanox International 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 0000000..7e688d9 --- /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(C) 2020 Mellanox International Ltd. + * Copyright(C) 2020 Intel International Ltd. + */ + +#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 <rte_common.h> +#include <rte_config.h> +#include <rte_dev.h> +#include <rte_errno.h> +#include <rte_mbuf.h> +#include <rte_memory.h> + +/** + * @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. + * + * @see struct rte_regexdev_qp_conf::cb, rte_regexdev_queue_pair_setup() + */ +__rte_experimental +void +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 0000000..d400624 --- /dev/null +++ b/lib/librte_regexdev/rte_regexdev_version.map @@ -0,0 +1,26 @@ +EXPERIMENTAL { + global: + + rte_regexdev_count; + rte_regexdev_get_dev_id; + rte_regexdev_info_get; + rte_regexdev_configure; + rte_regexdev_queue_pair_setup; + rte_regexdev_start; + rte_regexdev_stop; + rte_regexdev_close; + rte_regexdev_attr_get; + rte_regexdev_attr_set; + rte_regexdev_rule_db_update; + rte_regexdev_rule_db_compile_activate; + rte_regexdev_rule_db_import; + rte_regexdev_rule_db_export; + rte_regexdev_xstats_names_get; + rte_regexdev_xstats_get; + rte_regexdev_xstats_by_name_get; + rte_regexdev_xstats_reset; + rte_regexdev_selftest; + rte_regexdev_dump; + rte_regexdev_enqueue_burst; + rte_regexdev_dequeue_burst; +}; diff --git a/lib/meson.build b/lib/meson.build index 07a65a6..79ae5cb 100644 --- a/lib/meson.build +++ b/lib/meson.build @@ -24,7 +24,7 @@ libraries = [ 'gro', 'gso', 'ip_frag', 'jobstats', 'kni', 'latencystats', 'lpm', 'member', 'power', 'pdump', 'rawdev', - 'rib', 'reorder', 'sched', 'security', 'stack', 'vhost', + 'regexdev', 'rib', 'reorder', 'sched', 'security', 'stack', 'vhost', # ipsec lib depends on net, crypto and security 'ipsec', #fib lib depends on rib