From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id E590EA0471 for ; Thu, 15 Aug 2019 11:35:43 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id B64971BE8F; Thu, 15 Aug 2019 11:35:42 +0200 (CEST) Received: from new2-smtp.messagingengine.com (new2-smtp.messagingengine.com [66.111.4.224]) by dpdk.org (Postfix) with ESMTP id D51671BE8D for ; Thu, 15 Aug 2019 11:35:40 +0200 (CEST) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailnew.nyi.internal (Postfix) with ESMTP id 1790E22C1; Thu, 15 Aug 2019 05:35:40 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute1.internal (MEProxy); Thu, 15 Aug 2019 05:35:40 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:content-type; s=mesmtp; bh=F9cfIYrzQm1iT3kIMLXR6uZptTVbtjeYfkeYdTCwtuQ=; b=jSBIRNvsVPrx CtIIS5p3tmDJJN6plvKLHp4a7CXBjUfjxvt4Aj72tl+j9NC3yTO/f635bT4DpjTT 9Jqr7L3IhPRRMqH2m2d7YHzUT8UcZLzv8jk/0Ac51LghtYKJhGZNwlLIYq9EoAQy tB5X5KgZgMiPJuSjknFhfGSHg+l2h90= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm3; bh=F9cfIYrzQm1iT3kIMLXR6uZptTVbtjeYfkeYdTCwt uQ=; b=rqcWHqjHsPPWqS6OTG4AbKAZ2f4bq6vYZhkfwdZ3hDkPjPSNhKp06IgHL jyiHMecKMQNMUq6rW0COuQOSOwz+M5YgVpsGfSQkoLGqy1SvPZNQT65oBBpGuZNc WK3smqlH6I/LfelA+BaeF7oQFA7tX6Z7EJFo6jxXfA04oxLhSkLu352Ow1CWVV99 KRZY0qUb1nkDbDeRIi1LcdDY9zI26bGr84OTiYrZyreyOF2+qRReQRSnZYs1VIvG ROaQL4DeXHxHhyX5yuVaAWJ6viQ6pnRIgXFiWaOUMDVhIZ+jqd5b5rH0cuy0xT3I Za7X+TNTgUrcLPpc+25XIZO+AY3bw== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduvddrudefuddgudeiucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne goufhushhpvggtthffohhmrghinhculdegledmnecujfgurhephffvufffkfgjfhgggfgt sehtqhertddttdejnecuhfhrohhmpefvhhhomhgrshcuofhonhhjrghlohhnuceothhhoh hmrghssehmohhnjhgrlhhonhdrnhgvtheqnecuffhomhgrihhnpehvrghrshdrmhhkpdgt ohhnfhdrihhnpdhsohhurhgtvghfohhrghgvrdhnvghtpdhlihgsrdhmkhdpnhgvthhlih hfhidrtghomhenucfkphepjeejrddufeegrddvtdefrddukeegnecurfgrrhgrmhepmhgr ihhlfhhrohhmpehthhhomhgrshesmhhonhhjrghlohhnrdhnvghtnecuvehluhhsthgvrh fuihiivgeptd X-ME-Proxy: Received: from xps.localnet (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA id C1C1E8005C; Thu, 15 Aug 2019 05:35:26 -0400 (EDT) From: Thomas Monjalon To: jerinj@marvell.com Cc: dev@dpdk.org, Pavan Nikhilesh , Shahaf Shuler , Hemant Agrawal , Opher Reviv , Alex Rosenbaum , Dovrat Zifroni , Prasun Kapoor , Nipun Gupta , "Wang, Xiang W" , "Richardson, Bruce" , 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 Date: Thu, 15 Aug 2019 11:35:25 +0200 Message-ID: <8285913.8xKIzI91KM@xps> In-Reply-To: <20190627155036.56940-1-jerinj@marvell.com> References: <20190627155036.56940-1-jerinj@marvell.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="UTF-8" Subject: Re: [dpdk-dev] [RFC PATCH v1] regexdev: introduce regexdev subsystem X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" +Cc other interested vendors +Cc contributors to =C2=B5DPI project in fd.io 27/06/2019 17:50, jerinj@marvell.com: > From: Jerin Jacob >=20 > Even though there are some vendors which offer Regex HW offload, due to > lack of standard API, It is diffcult for DPDK consumer to use them > in a portable way. >=20 > This _RFC_ attempts to standardize the RegEx/DPI offload APIs for DPDK. >=20 > The Doxygen generated RFC API documentation available here: > https://dreamy-noether-22777e.netlify.com/rte__regexdev_8h.html >=20 > This RFC crafted based on SW Regex API frameworks such as libpcre and > hyperscan and a few of the RegEx HW IPs which I am aware of. >=20 > RegEx pattern matching applications: > =E2=80=A2 Next Generation Firewalls (NGFW) > =E2=80=A2 Deep Packet and Flow Inspection (DPI) > =E2=80=A2 Intrusion Prevention Systems (IPS) > =E2=80=A2 DDoS Mitigation > =E2=80=A2 Network Monitoring > =E2=80=A2 Data Loss Prevention (DLP) > =E2=80=A2 Smart NICs > =E2=80=A2 Grammar based content processing > =E2=80=A2 URL, spam and adware filtering > =E2=80=A2 Advanced auditing and policing of user/application security pol= icies > =E2=80=A2 Financial data mining - parsing of streamed financial feeds=20 >=20 > Request to review from HW and SW RegEx vendors and RegEx application users > to have portable DPDK API for RegEx. >=20 > The API schematics are based cryptodev, eventdev and ethdev existing devi= ce API. >=20 > Signed-off-by: Jerin Jacob > Signed-off-by: Pavan Nikhilesh > --- >=20 > RTE RegEx Device API > -------------------- >=20 > Defines RTE RegEx Device APIs for RegEx operations and its provisioning. >=20 > The RegEx Device API is composed of two parts: >=20 > - 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. >=20 > - 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. >=20 > RegEx device components and definitions: >=20 > +-----------------+ > | | > | o---------+ rte_regex_[en|de]queue_burst() > | PCRE based o------+ | | > | RegEx pattern | | | +--------+ | > | matching engine o------+--+--o | | +------+ > | | | | | queue |<=3D=3Do=3D=3D=3D>|Core 0| > | o----+ | | | pair 0 | | | > | | | | | +--------+ +------+ > +-----------------+ | | | > ^ | | | +--------+ > | | | | | | +------+ > | | +--+--o queue |<=3D=3D=3D=3D=3D=3D>|Core 1| > Rule|Database | | | pair 1 | | | > +------+----------+ | | +--------+ +------+ > | Group 0 | | | > | +-------------+ | | | +--------+ +------+ > | | Rules 0..n | | | | | | |Core 2| > | +-------------+ | | +--o queue |<=3D=3D=3D=3D=3D=3D>| | > | Group 1 | | | pair 2 | +------+ > | +-------------+ | | +--------+ > | | Rules 0..n | | | > | +-------------+ | | +--------+ > | Group 2 | | | | +------+ > | +-------------+ | | | queue |<=3D=3D=3D=3D=3D=3D>|Core n| > | | Rules 0..n | | +-------o pair n | | | > | +-------------+ | +--------+ +------+ > | Group n | > | +-------------+ |<-------rte_regex_rule_db_update() > | | Rules 0..n | |<-------rte_regex_rule_db_import() > | +-------------+ |------->rte_regex_rule_db_export() > +-----------------+ >=20 > 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 =E2=80=9CRegEx=E2=80=9D. >=20 > RegEx device: A hardware or software-based implementation of RegEx > device API for PCRE based pattern matching syntax and semantics. >=20 > PCRE RegEx syntax and semantics specification: > http://regexkit.sourceforge.net/Documentation/pcre/pcrepattern.html >=20 > 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/respo= nse > embedded in *rte_regex_ops* structure. >=20 > Rule: A pattern matching rule expressed in PCRE RegEx syntax along with > Match ID and Group ID to identify the rule upon the match. >=20 > 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 contai= ns > a set of rules that compiled in device specific binary form. >=20 > Match ID or Rule ID: A unique identifier provided at the time of rule > creation for the application to identify the rule upon match. >=20 > 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. >=20 > Scan: A pattern matching request through *enqueue* API. >=20 > 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_regex_dev_info::pcre_unsup_flags >=20 > 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 p= air. > It is the responsibility of the upper level application to enforce this r= ule. >=20 > In all functions of the RegEx API, the RegEx device is > designated by an integer >=3D 0 named the device identifier *dev_id* >=20 > At the RegEx driver level, RegEx devices are represented by a generic > data structure of type *rte_regex_dev*. >=20 > 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_regex_dev* structure and > a new device identifier are allocated for that device. Then, the > regex_dev_init() function supplied by the RegEx driver matching the probed > device is invoked to properly initialize the device. >=20 > The role of the device init function consists of resetting the hardware or > software RegEx driver implementations. >=20 > If the device init operation is successful, the correspondence between > the device identifier assigned to the new device and its associated > *rte_regex_dev* structure is effectively registered. > Otherwise, both the *rte_regex_dev* structure and the device identifier a= re > freed. >=20 > The functions exported by the application RegEx API to setup a device > designated by its device identifier must be invoked in the following orde= r: > - rte_regex_dev_configure() > - rte_regex_queue_pair_setup() > - rte_regex_dev_start() >=20 > 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 >=20 > If the application wants to change the configuration (i.e. call > rte_regex_dev_configure() or rte_regex_queue_pair_setup()), it must call > rte_regex_dev_stop() first to stop the device and then do the reconfigura= tion > before calling rte_regex_dev_start() again. The enqueue and dequeue > functions should not be invoked when the device is stopped. >=20 > Finally, an application can close a RegEx device by invoking the > rte_regex_dev_close() function. >=20 > Each function of the application RegEx API invokes a specific function > of the PMD that controls the target device designated by its device > identifier. >=20 > For this purpose, all device-specific functions of a RegEx driver are > supplied through a set of pointers contained in a generic structure of ty= pe > *regex_dev_ops*. > The address of the *regex_dev_ops* structure is stored in the *rte_regex_= dev* > structure by the device init function of the RegEx driver, which is > invoked during the PCI/SoC device probing phase, as explained earlier. >=20 > In other words, each function of the RegEx API simply retrieves the > *rte_regex_dev* structure associated with the device identifier and > performs an indirect invocation of the corresponding driver function > supplied in the *regex_dev_ops* structure of the *rte_regex_dev* structur= e. >=20 > For performance reasons, the address of the fast-path functions of the > RegEx driver is not contained in the *regex_dev_ops* structure. > Instead, they are directly stored at the beginning of the *rte_regex_dev* > structure to avoid an extra indirect memory access during their invocatio= n. >=20 > 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. >=20 > 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. >=20 > Typical application utilisation of the RegEx device API will follow the > following programming flow. >=20 > - rte_regex_dev_configure() > - rte_regex_queue_pair_setup() > - rte_regex_rule_db_update() Needs to invoke if precompiled rule database= not > provided in rte_regex_dev_config::rule_db for rte_regex_dev_configure() > and/or application needs to update rule database. > - Create or reuse exiting mempool for *rte_regex_ops* objects. > - rte_regex_dev_start() > - rte_regex_enqueue_burst() > - rte_regex_dequeue_burst() >=20 > --- >=20 > config/common_base | 5 + > doc/api/doxy-api-index.md | 1 + > doc/api/doxy-api.conf.in | 1 + > lib/Makefile | 2 + > lib/librte_regexdev/Makefile | 23 + > lib/librte_regexdev/rte_regexdev.c | 5 + > lib/librte_regexdev/rte_regexdev.h | 1247 ++++++++++++++++++++++++++++ > 7 files changed, 1284 insertions(+) > create mode 100644 lib/librte_regexdev/Makefile > create mode 100644 lib/librte_regexdev/rte_regexdev.c > create mode 100644 lib/librte_regexdev/rte_regexdev.h >=20 > diff --git a/config/common_base b/config/common_base > index e406e7836..986093d6e 100644 > --- a/config/common_base > +++ b/config/common_base > @@ -746,6 +746,11 @@ CONFIG_RTE_LIBRTE_PMD_DPAA2_QDMA_RAWDEV=3Dn > # > CONFIG_RTE_LIBRTE_PMD_IFPGA_RAWDEV=3Dy > =20 > +# > +# Compile regex device support > +# > +CONFIG_RTE_LIBRTE_REGEXDEV=3Dy > + > # > # Compile librte_ring > # > diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md > index 715248dd1..a0bc27ae4 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 b9896cb63..7adb821bb 100644 > --- a/doc/api/doxy-api.conf.in > +++ b/doc/api/doxy-api.conf.in > @@ -53,6 +53,7 @@ INPUT =3D @TOPDIR@/doc/api/doxy-api-i= ndex.md \ > @TOPDIR@/lib/librte_rawdev \ > @TOPDIR@/lib/librte_rcu \ > @TOPDIR@/lib/librte_reorder \ > + @TOPDIR@/lib/librte_regexdev \ > @TOPDIR@/lib/librte_ring \ > @TOPDIR@/lib/librte_sched \ > @TOPDIR@/lib/librte_security \ > diff --git a/lib/Makefile b/lib/Makefile > index 791e0d991..57de9691a 100644 > --- a/lib/Makefile > +++ b/lib/Makefile > @@ -44,6 +44,8 @@ DEPDIRS-librte_eventdev :=3D librte_eal librte_ring lib= rte_ethdev librte_hash \ > librte_mempool librte_timer librte_cryptodev > DIRS-$(CONFIG_RTE_LIBRTE_RAWDEV) +=3D librte_rawdev > DEPDIRS-librte_rawdev :=3D librte_eal librte_ethdev > +DIRS-$(CONFIG_RTE_LIBRTE_REGEXDEV) +=3D librte_regexdev > +DEPDIRS-librte_regexdev :=3D librte_eal > DIRS-$(CONFIG_RTE_LIBRTE_VHOST) +=3D librte_vhost > DEPDIRS-librte_vhost :=3D librte_eal librte_mempool librte_mbuf librte_e= thdev \ > librte_net > diff --git a/lib/librte_regexdev/Makefile b/lib/librte_regexdev/Makefile > new file mode 100644 > index 000000000..723b4b28c > --- /dev/null > +++ b/lib/librte_regexdev/Makefile > @@ -0,0 +1,23 @@ > +# SPDX-License-Identifier: BSD-3-Clause > +# Copyright(C) 2019 Marvell International Ltd. > +# > + > +include $(RTE_SDK)/mk/rte.vars.mk > + > +# library name > +LIB =3D librte_regexdev.a > + > +# library version > +LIBABIVER :=3D 1 > + > +# build flags > +CFLAGS +=3D -O3 > +CFLAGS +=3D $(WERROR_FLAGS) > + > +# library source files > +SRCS-y +=3D rte_regexdev.c > + > +# export include files > +SYMLINK-y-include +=3D rte_regexdev.h > + > +include $(RTE_SDK)/mk/rte.lib.mk > diff --git a/lib/librte_regexdev/rte_regexdev.c b/lib/librte_regexdev/rte= _regexdev.c > new file mode 100644 > index 000000000..e5be0f29c > --- /dev/null > +++ b/lib/librte_regexdev/rte_regexdev.c > @@ -0,0 +1,5 @@ > +/* SPDX-License-Identifier: BSD-3-Clause > + * Copyright(C) 2019 Marvell International Ltd. > + */ > + > +#include > diff --git a/lib/librte_regexdev/rte_regexdev.h b/lib/librte_regexdev/rte= _regexdev.h > new file mode 100644 > index 000000000..765da4aaa > --- /dev/null > +++ b/lib/librte_regexdev/rte_regexdev.h > @@ -0,0 +1,1247 @@ > +/* SPDX-License-Identifier: BSD-3-Clause > + * Copyright(C) 2019 Marvell 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 provisioni= ng. > + * > + * 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_regex_[en|de]queue_burst() > + * | PCRE based o------+ | | > + * | RegEx pattern | | | +--------+ | > + * | matching engine o------+--+--o | | +------+ > + * | | | | | queue |<=3D=3Do=3D=3D=3D>|Core = 0| > + * | o----+ | | | pair 0 | | | > + * | | | | | +--------+ +------+ > + * +-----------------+ | | | > + * ^ | | | +--------+ > + * | | | | | | +------+ > + * | | +--+--o queue |<=3D=3D=3D=3D=3D=3D>|Cor= e 1| > + * Rule|Database | | | pair 1 | | | > + * +------+----------+ | | +--------+ +------+ > + * | Group 0 | | | > + * | +-------------+ | | | +--------+ +------+ > + * | | Rules 0..n | | | | | | |Core 2| > + * | +-------------+ | | +--o queue |<=3D=3D=3D=3D=3D=3D>| = | > + * | Group 1 | | | pair 2 | +------+ > + * | +-------------+ | | +--------+ > + * | | Rules 0..n | | | > + * | +-------------+ | | +--------+ > + * | Group 2 | | | | +------+ > + * | +-------------+ | | | queue |<=3D=3D=3D=3D=3D=3D>|Cor= e n| > + * | | Rules 0..n | | +-------o pair n | | | > + * | +-------------+ | +--------+ +------+ > + * | Group n | > + * | +-------------+ |<-------rte_regex_rule_db_update() > + * | | Rules 0..n | |<-------rte_regex_rule_db_import() > + * | +-------------+ |------->rte_regex_rule_db_export() > + * +-----------------+ > + * > + * RegEx: A regular expression is a concise and flexible means for match= ing > + * strings of text, such as particular characters, words, or patterns of > + * characters. A common abbreviation for this is =E2=80=9CRegEx=E2=80=9D. > + * > + * 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 pai= r to > + * transmit a burst of pattern matching request and receive a burst of > + * receive the pattern matching response. The pattern matching request/r= esponse > + * embedded in *rte_regex_ops* structure. > + * > + * Rule: A pattern matching rule expressed in PCRE RegEx syntax along wi= th > + * Match ID and Group ID to identify the rule upon the match. > + * > + * Rule database: The RegEx device accepts regular expressions and conve= rts 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 co= ntains > + * 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 identif= ier > + * 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 fea= tures > + * of PCRE. The application may probe unsupported features through > + * struct rte_regex_dev_info::pcre_unsup_flags > + * > + * By default, all the functions of the RegEx Device API exported by a P= MD > + * are lock-free functions which assume to not be invoked in parallel on > + * different logical cores to work on the same target object. For instan= ce, > + * the dequeue function of a PMD cannot be invoked in parallel on two lo= gical > + * cores to operates on same RegEx queue pair. Of course, this function > + * can be invoked in parallel by different logical core on different que= ue pair. > + * It is the responsibility of the upper level application to enforce th= is rule. > + * > + * In all functions of the RegEx API, the RegEx device is > + * designated by an integer >=3D 0 named the device identifier *dev_id* > + * > + * At the RegEx driver level, RegEx devices are represented by a generic > + * data structure of type *rte_regex_dev*. > + * > + * RegEx devices are dynamically registered during the PCI/SoC device pr= obing > + * phase performed at EAL initialization time. > + * When a RegEx device is being probed, a *rte_regex_dev* structure and > + * a new device identifier are allocated for that device. Then, the > + * regex_dev_init() function supplied by the RegEx driver matching the p= robed > + * device is invoked to properly initialize the device. > + * > + * The role of the device init function consists of resetting the hardwa= re 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_regex_dev* structure is effectively registered. > + * Otherwise, both the *rte_regex_dev* structure and the device identifi= er 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_regex_dev_configure() > + * - rte_regex_queue_pair_setup() > + * - rte_regex_dev_start() > + * > + * Then, the application can invoke, in any order, the functions > + * exported by the RegEx API to enqueue pattern matching job, dequeue pa= ttern > + * 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_regex_dev_configure() or rte_regex_queue_pair_setup()), it must c= all > + * rte_regex_dev_stop() first to stop the device and then do the reconfi= guration > + * before calling rte_regex_dev_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_regex_dev_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 o= f type > + * *regex_dev_ops*. > + * The address of the *regex_dev_ops* structure is stored in the *rte_re= gex_dev* > + * 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_regex_dev* structure associated with the device identifier and > + * performs an indirect invocation of the corresponding driver function > + * supplied in the *regex_dev_ops* structure of the *rte_regex_dev* stru= cture. > + * > + * For performance reasons, the address of the fast-path functions of the > + * RegEx driver is not contained in the *regex_dev_ops* structure. > + * Instead, they are directly stored at the beginning of the *rte_regex_= dev* > + * structure to avoid an extra indirect memory access during their invoc= ation. > + * > + * 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 req= uest > + * to the RegEx device and the *dequeue* operation gets a burst of patte= rn > + * matching response for the ones submitted through *enqueue* operation. > + * > + * Typical application utilisation of the RegEx device API will follow t= he > + * following programming flow. > + * > + * - rte_regex_dev_configure() > + * - rte_regex_queue_pair_setup() > + * - rte_regex_rule_db_update() Needs to invoke if precompiled rule data= base not > + * provided in rte_regex_dev_config::rule_db for rte_regex_dev_configu= re() > + * and/or application needs to update rule database. > + * - Create or reuse exiting mempool for *rte_regex_ops* objects. > + * - rte_regex_dev_start() > + * - rte_regex_enqueue_burst() > + * - rte_regex_dequeue_burst() > + * > + */ > + > +#ifdef __cplusplus > +extern "C" { > +#endif > + > +#include > +#include > +#include > +#include > +#include > + > +/** > + * Get the total number of RegEx devices that have been successfully > + * initialised. > + * > + * @return > + * The total number of usable RegEx devices. > + */ > +uint8_t > +rte_regex_dev_count(void); > + > +/** > + * 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. > + */ > +int > +rte_regex_dev_get_dev_id(const char *name); > + > +/* Enumerates RegEx device capabilities */ > +#define RTE_REGEX_DEV_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_regex_dev_config::rule_db in rte_regex_dev_configure() > + * @see struct rte_regex_dev_config::rule_db, rte_regex_dev_configure() > + * @see struct rte_regex_dev_info::regex_dev_capa > + */ > + > + > +/* Enumerates unsupported PCRE features for the RegEx device */ > +#define RTE_REGEX_DEV_PCRE_UNSUP_START_ANCHOR_F (1ULL << 0) > +/**< RegEx device doesn't support PCRE Anchor to start of match flag. > + * Example RegEx is '/\Gfoo\d/'. Here '\G' asserts position at the end o= f 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 subje= ct > + * string. If the RegEx is applied to 'foo1foo2Zfoo3' the first two matc= hes will > + * be successful for 'foo1foo2' and fail for 'Zfoo3'. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_ATOMIC_GROUPING_F (1ULL << 1) > +/**< RegEx device doesn't support PCRE Atomic grouping. > + * Atomic groups are represented by '(?>)'. An atomic group is a group t= hat, > + * 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 'ab= cc' then > + * 'a(bc|b)c' matches both where as 'a(?>bc|b)c' matches only abcc becau= se > + * atomic groups don't allow backtracing back to 'b'. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_BACKTRACKING_CTRL_F (1ULL << 2) > +/**< RegEx device doesn't support PCRE backtracking control verbs. > + * Some examples of backtracing verbs are (*COMMIT), (*ACCEPT), (*FAIL), > + * (*SKIP), (*PRUNE). > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_CALLOUTS_F (1ULL << 3) > +/**< RegEx device doesn't 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 e= ngine > + * will parse ABC perform a userdefined callout and return a successful = match at > + * D. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_BACKREFERENCE_F (1ULL << 4) > +/**< RegEx device doesn't support PCRE backreference. > + * Example RegEx is '(\2ABC|(GHI))+' \2 matches the same text as most re= cently > + * matched by the 2nd capturing group i.e. 'GHI'. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_GREEDY_F (1ULL << 5) > +/**< RegEx device doesn't support PCRE Greedy mode. > + * For example if the RegEx is 'AB\d*?' then '*?' represents zero or unl= imited > + * matches. In greedy mode the pattern 'AB12345' will be matched complet= ely > + * where as the ungreedy mode 'AB' will be returned as the match. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_LOOKAROUND_ASRT_F (1ULL << 6) > +/**< RegEx device doesn't support PCRE Lookaround assertions > + * (Zero-width assertions). Example RegEx is '[a-z]+\d+(?=3D!{3,})' if > + * the given pattern is 'dwad1234!' the RegEx engine doesn't report any = matches > + * because the assert '(?=3D!{3,})' fails. The pattern 'dwad123!!!' woul= d return a > + * successful match. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_MATCH_POINT_RST_F (1ULL << 7) > +/**< 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_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_NEWLINE_CONVENTIONS_F (1ULL << 8) > +/**< RegEx device doesn't 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_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_NEWLINE_SEQ_F (1ULL << 9) > +/**< RegEx device doesn't 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_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_POSSESSIVE_QUALIFIERS_F (1ULL << 10) > +/**< RegEx device doesn't 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 quant= ifier, > + * the deal is all or nothing. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_SUBROUTINE_REFERENCES_F (1ULL << 11) > +/**< RegEx device doesn't 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_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_UTF_8_F (1ULL << 12) > +/**< RegEx device doesn't support UTF-8 character encoding. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_UTF_16_F (1ULL << 13) > +/**< RegEx device doesn't support UTF-16 character encoding. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_UTF_32_F (1ULL << 14) > +/**< RegEx device doesn't support UTF-32 character encoding. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_WORD_BOUNDARY_F (1ULL << 15) > +/**< RegEx device doesn't support word boundaries. > + * The meta character '\b' represents word boundary anchor. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +#define RTE_REGEX_DEV_PCRE_UNSUP_FORWARD_REFERENCES_F (1ULL << 16) > +/**< RegEx device doesn't 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 t= he > + * following string 'GHIGHIABCDEF'. > + * @see struct rte_regex_dev_info::pcre_unsup_flags > + */ > + > +/* 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_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_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 strin= g that > + * is being searched. Similar to '^' and represented by \A. > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_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_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_flags > + */ > + > +#define RTE_REGEX_PCRE_RULE_DOTALL_F (1ULL << 3) > +/**< When this flag is set, a dot metacharacter in the pattern matches a= ny > + * character, including one that indicates a newline. > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_flags > + */ > + > +#define RTE_REGEX_PCRE_RULE_DUPNAMES_F (1ULL << 4) > +/**< When this flag is set, names used to identify capture groups need n= ot be > + * unique. > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_flags > + */ > + > +#define RTE_REGEX_PCRE_RULE_EXTENDED_F (1ULL << 5) > +/**< When this flag is set, most white space characters in the pattern a= re > + * totally ignored except when escaped or inside a character class. > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_flags > + */ > + > +#define RTE_REGEX_PCRE_RULE_MATCH_UNSET_BACKREF_F (1ULL << 6) > +/**< When this flag is set, a backreference to an unset capture group ma= tches an > + * empty string. > + * @see RTE_REGEX_DEV_PCRE_UNSUP_FORWARD_REFERENCES_F > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_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 stri= ng, > + * respectively, as well as at the very start and end. > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_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 (backreferen= ces or > + * recursion/subroutine calls) may only refer to named groups, though the > + * reference can be by name or by number. > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_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_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_flags > + */ > + > +#define RTE_REGEX_PCRE_RULE_UNGREEDY_F (1ULL << 10) > +/**< When this flag is set, the "greediness" of the quantifiers is inver= ted > + * so that they are not greedy by default, but become greedy if followed= by > + * '?'. > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_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 cha= racters > + * instead of single-code-unit strings. > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_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 co= mpiled. > + * 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 middle of a multi-code-unit character. > + * @see struct rte_regex_dev_info::rule_flags, struct rte_regex_rule::ru= le_flags > + */ > + > + > +/** > + * RegEx device information > + */ > +struct rte_regex_dev_info { > + const char *driver_name; /**< RegEx driver name */ > + struct rte_device *dev; /**< Device information */ > + uint8_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_REGEX_DEV_CFG_CROSS_BUFFER_SCAN_F > + */ > + uint16_t max_rules_per_group; > + /**< Maximum rules supported per group by this device */ > + uint16_t max_groups; > + /**< Maximum group supported by this device */ > + uint32_t regex_dev_capa; > + /**< RegEx device capabilities. @see RTE_REGEX_DEV_CAPA_* */ > + uint64_t rule_flags; > + /**< Supported compiler rule flags. > + * @see RTE_REGEX_PCRE_RULE_*, struct rte_regex_rule::rule_flags > + */ > + uint64_t pcre_unsup_flags; > + /**< Unsupported PCRE features for this RegEx device. > + * @see RTE_REGEX_DEV_PCRE_UNSUP_* > + */ > +}; > + > +/** > + * 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_regex_dev_info* to be filled = with the > + * contextual information of the device. > + * > + * @return > + * - 0: Success, driver updates the contextual information of the RegE= x device > + * - <0: Error code returned by the driver info get function. > + * > + */ > +int > +rte_regex_dev_info_get(uint8_t dev_id, struct rte_regex_dev_info *dev_in= fo); > + > +/* Enumerates RegEx device configuration flags */ > +#define RTE_REGEX_DEV_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 re= lated > + * to each other in some way. Enable this flag when to scan payload size > + * greater struct struct rte_regex_dev_info::max_payload_size and/or > + * matches can present across scan buffer boundaries. > + * > + * @see struct rte_regex_dev_info::max_payload_size > + * @see struct rte_regex_dev_config::dev_cfg_flags, rte_regex_dev_config= ure() > + * @see RTE_REGEX_OPS_RSP_PMI_SOJ_F > + * @see RTE_REGEX_OPS_RSP_PMI_EOJ_F > + */ > + > +/** RegEx device configuration structure */ > +struct rte_regex_dev_config { > + uint8_t nb_max_matches; > + /**< Maximum matches per scan configured on this device. > + * This value cannot exceed the *max_matches* > + * which previously provided in rte_regex_dev_info_get(). > + * The value 0 is allowed, in which case, value 1 used. > + * @see struct rte_regex_dev_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_regex_dev_info_get(). > + * @see struct rte_regex_dev_info::max_queue_pairs > + */ > + uint16_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_regex_dev_info_get(). > + * The value 0 is allowed, in which case, > + * struct rte_regex_dev_info::max_rules_per_group used. > + * @see struct rte_regex_dev_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_regex_dev_info_get(). > + * @see struct rte_regex_dev_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_regex_rule_db_update() or rte_regex_rule_db_import() API > + * to update or import rule database after the > + * rte_regex_dev_configure(). > + * @see rte_regex_rule_db_update(), rte_regex_rule_db_import() > + */ > + uint32_t rule_db_len; > + /**< Length of *rule_db* buffer. */ > + uint32_t dev_cfg_flags; > + /**< RegEx device configuration flags, See RTE_REGEX_DEV_CFG_* */ > +}; > + > +/** > + * 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_regex_dev_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. > + * - <0: Error code returned by the driver configuration function. > + */ > +int > +rte_regex_dev_configure(uint8_t dev_id, const struct rte_regex_dev_confi= g *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 a= s 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_regex_qp_conf::qp_conf_flags, rte_regex_queue_pair_se= tup() > + */ > + > +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_regex_dev_stop(), invoked once = per > + * flushed RegEx op. > + */ > + > +/** RegEx queue pair configuration structure */ > +struct rte_regex_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_regex_dev_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_regex_dev_stop() > + */ > +}; > + > +/** > + * 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 th= e range > + * [0, nb_queue_pairs - 1] previously supplied to rte_regex_dev_config= ure(). > + * @param qp_conf > + * The pointer to the configuration data to be used for the RegEx queu= e pair. > + * NULL value is allowed, in which case default configuration used. > + * > + * @return > + * - 0: Success, RegEx queue pair correctly set up. > + * - <0: RegEx queue configuration failed > + */ > +int > +rte_regex_queue_pair_setup(uint8_t dev_id, uint8_t queue_pair_id, > + const struct rte_regex_qp_conf *qp_conf); > + > +/** > + * Start a RegEx device. > + * > + * The device start step is the last one and consists of setting the Reg= Ex > + * 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: Success, device started. > + * - <0: Device start failed. > + */ > +int > +rte_regex_dev_start(uint8_t dev_id); > + > +/** > + * Stop a RegEx device. > + * > + * Stop a RegEx device. The device can be restarted with a call to > + * rte_regex_dev_start(). > + * > + * This function causes all queued response regex ops to be drained in t= he > + * response queue. While draining ops out of the device, > + * struct rte_regex_qp_conf::cb will be invoked for each ops. > + * > + * @param dev_id > + * RegEx device identifier. > + * > + * @see struct rte_regex_qp_conf::cb, rte_regex_queue_pair_setup() > + */ > +void > +rte_regex_dev_stop(uint8_t dev_id); > + > +/** > + * Close a RegEx device. The device cannot be restarted! > + * > + * @param dev_id > + * RegEx device identifier > + * > + * @return > + * - 0 on successfully closed the device. > + * - <0 on failure to close the device. > + */ > +int > +rte_regex_dev_close(uint8_t dev_id); > + > +/* Device get/set attributes */ > + > +/** Enumerates RegEx device attribute identifier */ > +enum rte_regex_dev_attr_id { > + RTE_REGEX_DEV_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_REGEX_DEV_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_REGEX_DEV_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_REGEX_DEV_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 > + */ > +}; > + > +/** > + * Get an attribute from a RegEx device. > + * > + * @param dev_id RegEx device identifier > + * @param attr_id The attribute ID to retrieve > + * @param[out] attr_value A pointer that will be filled in with the attr= ibute > + * value if successful. > + * > + * @return > + * - 0: Successfully retrieved attribute value. > + * - -EINVAL: Invalid device or *attr_id* provided, or *attr_value* i= s NULL. > + * - -ENOTSUP: if the device doesn't support specific *attr_id*. > + */ > +int > +rte_regex_dev_attr_get(uint8_t dev_id, enum rte_regex_dev_attr_id attr_i= d, > + void *attr_value); > + > +/** > + * Set an attribute to 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 > + * by the application > + * > + * @return > + * - 0: Successfully applied the attribute value. > + * - -EINVAL: Invalid device or *attr_id* provided, or *attr_value* i= s NULL. > + * - -ENOTSUP: if the device doesn't support specific *attr_id*. > + */ > +int > +rte_regex_dev_attr_set(uint8_t dev_id, enum rte_regex_dev_attr_id attr_i= d, > + const void *attr_value); > + > +/* Rule related APIs */ > +/** Enumerates RegEx rule operation */ > +enum rte_regex_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_regex_rule { > + enum rte_regex_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_regex_dev_info::rule_flags. For successful rule > + * database update, application needs to provide only supported > + * rule flags. > + * @See RTE_REGEX_PCRE_RULE_*, struct rte_regex_dev_info::rule_flags > + */ > +}; > + > +/** > + * Update the rule database of a RegEx device. > + * > + * @param dev_id RegEx device identifier > + * @param rules > + * Points to an array of *nb_rules* objects of type *rte_regex_rule* s= tructure > + * which contain the regex rules attributes to be updated in rule data= base. > + * @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 ru= le > + * database. The return value can be less than the value of the *nb_ru= les* > + * parameter when the regex devices fails to update the rule database = or > + * if invalid parameters are specified in a *rte_regex_rule*. > + * If the return value is less than *nb_rules*, the remaining PCRE rul= es > + * 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_regex_rule_db_import(), rte_regex_rule_db_export() > + */ > +uint16_t > +rte_regex_rule_db_update(uint8_t dev_id, const struct rte_regex_rule *ru= les, > + uint16_t nb_rules); > + > +/** > + * 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_regex_rule_db_update(), rte_regex_rule_db_export() > + */ > +int > +rte_regex_rule_db_import(uint8_t dev_id, const char *rule_db, > + uint32_t rule_db_len); > + > +/** > + * 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_regex_rule_db_update(), rte_regex_rule_db_import() > + */ > +int > +rte_regex_rule_db_export(uint8_t dev_id, char *rule_db); > + > +/* Extended statistics */ > +/** Maximum name length for extended statistics counters */ > +#define RTE_REGEX_DEV_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_regex_dev_xstats_map { > + uint16_t id; > + /**< xstat identifier */ > + char name[RTE_REGEX_DEV_XSTATS_NAME_SIZE]; > + /**< xstat name */ > +}; > + > +/** > + * 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_m= ap. > + * - negative value on error: > + * -ENODEV for invalid *dev_id* > + * -ENOTSUP if the device doesn't support this function. > + */ > +int > +rte_regex_dev_xstats_names_get(uint8_t dev_id, > + struct rte_regex_dev_xstats_map *xstats_map); > + > +/** > + * 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_regex_dev_xstats_names_get(), or > + * by using rte_regex_dev_xstats_by_name_get(). > + * @param[out] values > + * The values for each stats request by ID. > + * @param n > + * The number of stats requested > + * @return > + * - positive value: number of stat entries filled into the values arr= ay > + * - negative value on error: > + * -ENODEV for invalid *dev_id* > + * -ENOTSUP if the device doesn't support this function. > + */ > +int > +rte_regex_dev_xstats_get(uint8_t dev_id, const uint16_t ids[], > + uint64_t values[], uint16_t n); > + > +/** > + * 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[out] 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_regex_dev_xstats_get, wh= ich 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 addr= ess. > + * > + * @return > + * - 0: Successfully retrieved xstat value. > + * - -EINVAL: invalid parameters > + * - -ENOTSUP: if not supported. > + */ > +int > +rte_regex_dev_xstats_by_name_get(uint8_t dev_id, const char *name, > + uint16_t *id, uint64_t *value); > + > +/** > + * Reset the values of the xstats of the selected component in the devic= e. > + * > + * @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. > + */ > +int > +rte_regex_dev_xstats_reset(uint8_t dev_id, const uint16_t ids[], > + uint16_t nb_ids); > + > +/** > + * 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. > + */ > +int rte_regex_dev_selftest(uint8_t dev_id); > + > +/** > + * 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 > + * - <0: on failure. > + */ > +int > +rte_regex_dev_dump(uint8_t dev_id, FILE *f); > + > +/* Fast path APIs */ > + > +/** > + * The generic *rte_regex_match* structure to hold the RegEx match attri= butes. > + * @see struct rte_regex_ops::matches > + */ > +struct rte_regex_match { > + RTE_STD_C11 > + union { > + uint64_t u64; > + struct { > + uint32_t rule_id:20; > + /**< Rule identifier to which the pattern matched. > + * @see struct rte_regex_rule::rule_id > + */ > + uint32_t group_id:12; > + /**< Group identifier of the rule which the pattern > + * matched. @see struct rte_regex_rule::group_id > + */ > + uint16_t offset; > + /**< Starting Byte Position for matched rule. */ > + uint16_t len; > + /**< Length of match in bytes */ > + }; > + }; > +}; > + > +/* Enumerates RegEx request flags. */ > +#define RTE_REGEX_OPS_REQ_GROUP_ID1_VALID_F (1 << 0) > +/**< Set when struct rte_regex_rule::group_id1 valid */ > + > +#define RTE_REGEX_OPS_REQ_GROUP_ID2_VALID_F (1 << 1) > +/**< Set when struct rte_regex_rule::group_id2 valid */ > + > +#define RTE_REGEX_OPS_REQ_GROUP_ID3_VALID_F (1 << 2) > +/**< Set when struct rte_regex_rule::group_id3 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 s= can to > + * reduce the post-processing required by the application. The match wit= h 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_REGEX_DEV_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_REGEX_DEV_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_REGEX_DEV_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_REGEX_DEV_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_REGEX_DEV_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 scan_size; > + /**< Scan size of the buffer to be scanned in bytes. */ > + uint16_t rsp_flags; > + /**< Response flags for the RegEx ops. > + * @see RTE_REGEX_OPS_RSP_* > + */ > + uint8_t nb_actual_matches; > + /**< The total number of actual matches detected by the Regex device.*/ > + uint8_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_regex_match > + */ > + > + /* W1 */ > + RTE_STD_C11 > + union { > + uint64_t u64; > + /**< Allow 8-byte reserved on 32-bit system */ > + void *buf_addr; > + /**< Virtual address of the pattern to be matched. */ > + }; > + > + /* W2 */ > + rte_iova_t buf_iova; > + /**< IOVA address of the pattern to be matched. */ > + > + /* W3 */ > + uint16_t group_id0; > + /**< First group_id to match the rule against. Minimum one group id > + * must be provided by application. > + * When RTE_REGEX_OPS_REQ_GROUP_ID1_VALID_F set then group_id1 > + * is valid, respectively similar flags for group_id2 and group_id3. > + * Upon the match, struct rte_regex_match::group_id shall be updated > + * with matching group ID by the device. Group ID scheme provides > + * rule isolation and effective pattern matching. > + */ > + 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 > + */ > + > + /* W4 */ > + 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* */ > + }; > + > + /* W5 */ > + struct rte_regex_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 > + */ > +}; > + > +/** > + * Enqueue a burst of scan request on a RegEx device. > + * > + * The rte_regex_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 a= re > + * supplied in the *ops* array of *rte_regex_op* structures. > + * > + * The rte_regex_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_regex_dev_configure(). > + * @param ops > + * The address of an array of *nb_ops* pointers to *rte_regex_op* stru= ctures > + * 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_regex_op*. If the return value is less than *nb_ops*, the re= maining > + * ops at the end of *ops* are not consumed and the caller has to take= care > + * of them. > + */ > +uint16_t > +rte_regex_enqueue_burst(uint8_t dev_id, uint16_t qp_id, > + struct rte_regex_ops **ops, uint16_t nb_ops); > + > +/** > + * > + * Dequeue a burst of scan response from a queue on the RegEx device. > + * The dequeued operation are stored in *rte_regex_op* structures > + * whose pointers are supplied in the *ops* array. > + * > + * The rte_regex_dequeue_burst() function returns the number of ops > + * actually dequeued, which is the number of *rte_regex_op* data structu= res > + * 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" po= licy > + * can check this specific case and keep invoking the > + * rte_regex_dequeue_burst() function until a value less than > + * *nb_ops* is returned. > + * > + * The rte_regex_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 packet= s. > + * The value must be in the range [0, nb_queue_pairs - 1] previously > + * supplied to rte_regex_dev_configure(). > + * @param ops > + * The address of an array of pointers to *rte_regex_op* structures th= at 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_regex_op* structures effectively supplied to the > + * *ops* array. If the return value is less than *nb_ops*, the remaini= ng > + * ops at the end of *ops* are not consumed and the caller has to take= care > + * of them. > + */ > +uint16_t > +rte_regex_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_ */