From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id BC3EF4687B; Wed, 4 Jun 2025 17:30:47 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A9E2242E70; Wed, 4 Jun 2025 17:30:39 +0200 (CEST) Received: from mx0b-0016f401.pphosted.com (mx0a-0016f401.pphosted.com [67.231.148.174]) by mails.dpdk.org (Postfix) with ESMTP id 98DC042E6E for ; Wed, 4 Jun 2025 17:30:37 +0200 (CEST) Received: from pps.filterd (m0045849.ppops.net [127.0.0.1]) by mx0a-0016f401.pphosted.com (8.18.1.2/8.18.1.2) with ESMTP id 5543PTPK010531; Wed, 4 Jun 2025 08:30:33 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=marvell.com; h= cc:content-transfer-encoding:content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to; s=pfpt0220; bh=l 5BW2URu/ufOZ+PAjLlT7svnRG804KKMybPW6j6wYLI=; b=MPUOTbIqOFaqnGopD 3DKxbVY/EGtkVtGvIIWxmkZxtGDtddBAmJB54nQMj4upz8tHkPNkTrCchCBtX/Kl 93r2ZrJFGJBr/NBmZBotal2Pc4KavE/q1ghmFQRdLyjwNMC6pY6aEl8koaV0ncno VDQWfh98g23mQz4oygnaqdCz8ftJ33MOFYARAs8SfCaNVoBpVZWUeqID4u6s3N8D n+DV9fttJSdhcLnAKilc5mWDwuon3chnf+EPpW3XTVDcB8rr69xKe9sYDo1UOB4l tAF07KMWFtVes9SzXff1BRv+eLS9pBOPePwr4STUp19jZRSTD+JecUgg3q0CWXce z+kDg== Received: from dc5-exch05.marvell.com ([199.233.59.128]) by mx0a-0016f401.pphosted.com (PPS) with ESMTPS id 472e7n9f43-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Wed, 04 Jun 2025 08:30:32 -0700 (PDT) Received: from DC5-EXCH05.marvell.com (10.69.176.209) by DC5-EXCH05.marvell.com (10.69.176.209) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.1544.4; Wed, 4 Jun 2025 08:30:31 -0700 Received: from maili.marvell.com (10.69.176.80) by DC5-EXCH05.marvell.com (10.69.176.209) with Microsoft SMTP Server id 15.2.1544.4 via Frontend Transport; Wed, 4 Jun 2025 08:30:31 -0700 Received: from cavium-PowerEdge-R640.. (unknown [10.28.36.207]) by maili.marvell.com (Postfix) with ESMTP id B13B73F7040; Wed, 4 Jun 2025 08:30:28 -0700 (PDT) From: Nitin Saxena To: Jerin Jacob , Kiran Kumar K , Nithin Dabilpuram , Zhirun Yan , Robin Jarry , Christophe Fontaine CC: , Nitin Saxena Subject: [PATCH v11 2/7] graph: add feature arc registrations Date: Wed, 4 Jun 2025 21:00:03 +0530 Message-ID: <20250604153020.92712-3-nsaxena@marvell.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250604153020.92712-1-nsaxena@marvell.com> References: <20250103060612.2671836-1-nsaxena@marvell.com> <20250604153020.92712-1-nsaxena@marvell.com> MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Authority-Analysis: v=2.4 cv=CJkqXQrD c=1 sm=1 tr=0 ts=68406698 cx=c_pps a=rEv8fa4AjpPjGxpoe8rlIQ==:117 a=rEv8fa4AjpPjGxpoe8rlIQ==:17 a=IkcTkHD0fZMA:10 a=6IFa9wvqVegA:10 a=VQ9ene8lAAAA:8 a=L3Y5zZzAAAAA:8 a=GqZI9gvVAAAA:8 a=SSmOFEACAAAA:8 a=M5GUcnROAAAA:8 a=Hf6uRemhBz85_QEdVXwA:9 a=QEXdDO2ut3YA:10 a=5kMfGx23w8a0v5ansn-_:22 a=OBjm3rFKGHvpk9ecZwUJ:22 X-Proofpoint-GUID: eqHgJ6iD_E8wjH9YLw8ddPfJj4OrWmJs X-Proofpoint-Spam-Details-Enc: AW1haW4tMjUwNjA0MDExNyBTYWx0ZWRfX/kE0yeijEUvy vwGbE9SQvY8GhMkByrUzmuBKP7nMBFnVNXH0VYADB6GDMTpiKchMXyXWvxP5SCvgDiYdnVBuXqA Rt8bYYSdfZN4D1yRzJpoCek9exrhhAXyC3ZiYwOrWo4niyuMJyasUy4gZF6+UylOmxmf2pSbp7w mTzFyakx6ezNm5nYvHiZzxb/OmsRk7fHn2zzfDh9dUUUBHVADKnFGgil9eRS2b4CcJTl/5F/4y9 z2bfTOT6/AvIlin/HWRsGL459A7TBdqfzLj+82pu4jW+TiAC1odb/11iIAVdDTA6PsKKEpS/lbV fqxfy1zusKGV3RdM4qI3DU5V8UPQ1Tp674eALh0GyDxBJ6nVLqHiDvYR1Jx4TvWZtEtP++0TFgV kcaXee8EQljqvRZyKLsxv6TGqtfTUMJLF1I+4lVFrRfWImk5c/ZkfL+LARhC6AgmmK94dKzl X-Proofpoint-ORIG-GUID: eqHgJ6iD_E8wjH9YLw8ddPfJj4OrWmJs X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1099,Hydra:6.0.736,FMLib:17.12.80.40 definitions=2025-06-04_03,2025-06-03_02,2025-03-28_01 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org This patch defines RTE_GRAPH_FEATURE_ARC_REGISTER() and RTE_GRAPH_FEATURE_REGISTER() constructors and associated APIs with programming guide. Signed-off-by: Nitin Saxena --- doc/api/doxy-api-index.md | 1 + doc/guides/prog_guide/graph_lib.rst | 289 +++++++++++ doc/guides/prog_guide/img/feature_arc-1.svg | 269 +++++++++++ doc/guides/prog_guide/img/feature_arc-2.svg | 511 ++++++++++++++++++++ doc/guides/rel_notes/release_25_07.rst | 7 + lib/graph/graph_feature_arc.c | 36 ++ lib/graph/meson.build | 2 + lib/graph/rte_graph_feature_arc.h | 270 +++++++++++ 8 files changed, 1385 insertions(+) create mode 100644 doc/guides/prog_guide/img/feature_arc-1.svg create mode 100644 doc/guides/prog_guide/img/feature_arc-2.svg create mode 100644 lib/graph/graph_feature_arc.c create mode 100644 lib/graph/rte_graph_feature_arc.h diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index 5c425a2cb9..a7bdbf892c 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -214,6 +214,7 @@ The public API headers are grouped by topics: [table_wm](@ref rte_swx_table_wm.h) * [graph](@ref rte_graph.h): [graph_worker](@ref rte_graph_worker.h) + [graph_feature_arc](@ref rte_graph_feature_arc.h) * graph_nodes: [eth_node](@ref rte_node_eth_api.h), [ip4_node](@ref rte_node_ip4_api.h), diff --git a/doc/guides/prog_guide/graph_lib.rst b/doc/guides/prog_guide/gr= aph_lib.rst index dc6c8c0712..191c8e8a0b 100644 --- a/doc/guides/prog_guide/graph_lib.rst +++ b/doc/guides/prog_guide/graph_lib.rst @@ -559,3 +559,292 @@ on success packet is enqueued to ``udp4_input`` node. Hash lookup is performed in ``udp4_input`` node with registered destinatio= n port and destination port in UDP packet , on success packet is handed to ``udp_= user_node``. + +Graph feature arc +----------------- +Introduction +~~~~~~~~~~~~ +Graph feature arc is an abstraction to manage more than one network protoc= ols(or +features) in a graph application with + +* Runtime network configurability +* Overloading of default node packet path +* Control/Data plane synchronization + +.. note:: + + Feature arc abstraction is introduced as an optional functionality to t= he + graph library. Feature arc is a ``NOP`` to application which skips + :ref:`feature arc initialization` + +Runtime network configurability +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Feature arc facilitates to enable/disable protocols at runtime from control +thread. In fast path, it provides APIs to steer packets across nodes of t= hose +protocols which are enabled from control thread. + +Feature arc uses ``index`` object to enable/disable a protocol which is ge= neric +to cater all the possibilities of configuring a protocol. Examples of ``in= dex`` +object are interface index, route index, flow index, classification index = etc. + +Runtime configuration of one ``index`` is independent of another ``index`` +configuration. In other words, packet received on an interface0 are steered +independent from packets received on interface1. Both interface0 and inter= face1 +can have separate sets of protocols enabled at the same time. + +Feature arc also provides mechanism to express ``protocol sequencing order= `` +for packets. If more than one protocols are active in a network layer, pac= kets +may be required to be steered among protocol nodes in a specific order. For +example: in a typical firewall IPv4, IPsec and IP tables may be enabled at= the +same time in IP layer. Feature arc provides mechanism to express sequence +order in which protocol nodes are to be traversed by packets received/sent= on +an interface. + +Default node packet path overloading +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Each network function has defined node packet path. As an example, IPv4 ro= uter +as a forwarder includes nodes performing - packet ingress, ethernet recept= ion, +IPv4 reception, IPv4 lookup, ethernet rewrite and packet egress. Feature a= rc +provides application to overload default node path by providing hook +points(like netfilter) to insert out-of-tree or another protocol nodes in +packet path. + +Control/Data plane synchronization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Feature arc does not stop worker cores for any runtime control plane updat= es. +i.e. any feature(protocol) enable/disable at runtime does not stop worker +cores. Control plane feature enable/disable APIs also provides RCU mechani= sm, +if needed. + +When a feature is enabled in control plane, certain resources may be alloc= ated +by application specific to ``[feature, index]``. For example when IPsec is +enabled either on an interface(policy based IPsec) or route(route based IP= sec), +a security association(SA) would be allocated/initialized and attached to +interface/route. Feature arc APIs are provided to pass SA from control thr= ead +to worker threads for applying it(SA) on packets received/sent via +interface or SA tunnel route. + +Furthermore, when IPsec gets disabled for same ``[feature, index]`` in lat= er +point of time, cleanup would be required to free resources associated with= SA. +Cleanup can only be done in control thread when it ensures that no worker +thread is using the SA. For this usecase, application can use RCU mechanism +provided with enable/disable APIs. See :ref:`notifier_cb`. + +Objects +~~~~~~~ +Feature +^^^^^^^ +Feature is analogous to a protocol. + +.. _Feature_Nodes: + +Features nodes +^^^^^^^^^^^^^^ +A feature node is a node which performs specific feature processing in a g= iven +network layer. Feature nodes incorporates fast path feature arc APIs in th= eir +``process()`` function and are part of a unique arc. + +Not all nodes in graph required to be made feature nodes. + +.. _Start_Node: + +Start node +^^^^^^^^^^ +A node through which packets enters feature arc path is called ``Start nod= e``. +It is a node which provides a hook point to overload node packet path. Each +feature arc object has unique ``start node``. It can be a new node or any +existing node in a graph. Start node is not counted as a feature node in a= n arc. + +.. _End_Feature_Node: + +End feature node +^^^^^^^^^^^^^^^^ +An end feature node is a feature node through which packets exits feature = arc +path. It is required for exiting packets, from feature arc path, which are +getting processed by feature node which is getting disabled at runtime in +control thread. It is always the last feature node in an arc. As an except= ion +to other feature nodes, this node does not uses any feature arc fast path = APIs + +Feature arc +^^^^^^^^^^^ + +.. _Figure_Arc_1: + +.. figure:: img/feature_arc-1.* + :alt: feature-arc-1 + :width: 350px + :align: center + + Feature arc representation + +A ordered list of feature nodes in a given network layer is called as feat= ure arc. +It consists of three objects: + +- :ref:`Start node` +- :ref:`End feature node` +- :ref:`Zero or more feature nodes` + +In order to :ref:`create` a feature arc object o= nly +``start node`` and ``end feature node`` is required. Once created, feature +nodes can be :ref:`added` to the arc. + +Feature data +^^^^^^^^^^^^ +It is a fast path object which hold information to steer packets across no= des. + +Programming model +~~~~~~~~~~~~~~~~~ + +Arc/Feature Registrations +^^^^^^^^^^^^^^^^^^^^^^^^^ +Feature arc and feature registrations happens using constructor based macr= os. +While feature arc registration creates a feature arc object, the feature +registration adds provided node to a feature arc object. + +.. note:: + + During registration, no memory is allocated associated with any feature= arc. + Actual memory allocation, object creation and connecting of nodes via e= dges + corresponding to all registered feature arcs happens as part of + :ref:`feature arc initialization`. + +.. _Feature_Arc_Registration: + +Feature arc registration +************************ +A feature arc object creation require ``feature arc registration``. Once +registered, feature arc is created as part of +:ref:`initialization`. A feature arc is regist= ered +via ``RTE_GRAPH_FEATURE_ARC_REGISTER()``. An arc shown in +:ref:`figure` can be registered as follows: + +.. code-block:: c + + /* Existing nodes */ + RTE_NODE_REGISTER(Node-A); + RTE_NODE_REGISTER(Node-B); + + /* Define End feature node: Node-B*/ + struct rte_graph_feature_register Node-B-feature =3D { + .feature_name =3D "Node-B-feature", + .arc_name =3D "Arc1", + .feature_process_fn =3D nodeB_process_fn(), + .feature_node =3D &Node-B, + }; + + /* Arc1 registration */ + struct rte_graph_feature_arc_register arc1 =3D { + .arc_name =3D "Arc1", + .max_indexes =3D RTE_MAX_ETHPORTS, + .start_node =3D &Node-A, + .start_node_feature_process_fn =3D nodeA_feature_process_fn(), + .end_feature_node =3D &Node-B-feature, + }; + + /* Call constructor */ + RTE_GRAPH_FEATURE_ARC_REGISTER(arc1); + +.. note:: + + Feature arc can also be created using ``rte_graph_feature_arc_create()`= ` API as well + +.. _Feature_Registration: + +Feature registration +******************** +A feature registration means defining a feature node which would be added = to a +unique ``arc``. A feature nodes needs to know ``arc name`` to which it wan= ts to +connect to. Registration happens via ``RTE_GRAPH_FEATURE_REGISTER()``. + +A ``Feature-1`` shown in :ref:`figure` can be registered as = follows: + +.. code-block:: c + + /* Existing node */ + RTE_NODE_REGISTER(Feature-1); + + /* Define feature node: Feature-1 */ + struct rte_graph_feature_register Feature-1 =3D { + .feature_name =3D "Feature-1", + .arc_name =3D "Arc1", + .feature_process_fn =3D feature1_process_fn(), + .feature_node =3D &Feature-1, + }; + + /* Call constructor */ + RTE_GRAPH_FEATURE_REGISTER(Feature-1); + +.. note:: + + A feature node can be out-of-tree application node which is willing to + connect to an arc defined by DPDK in-built nodes. This way application = can + hook it's node to standard node packet path. + +Advance parameters +`````````````````` +.. _Figure_Arc_2: + +.. figure:: img/feature_arc-2.* + :alt: feature-arc-2 + :width: 550px + :align: center + + Feature registration advance parameters + +Feature registration have some advance parameters to control the feature n= ode. +As shown in above figure, ``Custom Feature`` and ``Feature-2`` nodes can be +added to existing arc as follows: + +.. code-block:: c + + /* Define feature node: Custom-Feature */ + struct rte_graph_feature_register Custom-Feature =3D { + .feature_name =3D "Custom-Feature", + .arc_name =3D "Arc1", + ... + ... + ... + .notifier_cb =3D Custom-Feature_notifier_fn(), /* Optional notifi= er function */ + .runs_after =3D "Feature-1", + }; + + /* Define feature node: Feature-2 */ + struct rte_graph_feature_register Feature-2 =3D { + .feature_name =3D "Feature-2", + .arc_name =3D "Arc1", + ... + ... + ... + .override_index_cb =3D Feature-3_override_index_cb(), + .runs_after =3D "Feature-1", + .runs_before =3D "Custom-Feature", + }; + +runs_after/runs_before +...................... +These parameters are used to express the sequencing order of feature nodes= . If +``Custome Feature`` needs to run after ``Feature-1`` it can be defined as = shown +above. Similarly, if ``Feature-2`` needs to run before ``Custome-Feature``= but +after ``Feature-1`` it can be done as shown above. + +.. _Feature_Notifier_Cb: + +notifier_cb() +............. +If non-NULL, every feature enable/disable in control plane will invoke the +notifier callback on control thread. This notifier callback can be used to +destroy resources for ``[feature, index]`` pair during ``feature disable`` +which might have allocated during feature enable. + +notifier_cb() is called, at runtime, for every enable/disable of ``[featur= e, +index]`` from control thread. + +override_index_cb() +.................... +A feature arc is :ref:`registered` to operate on +certain number of ``max_indexes``. If particular feature like to overload = this +``max_indexes`` with a larger value it can do so by returning larger value= in +this callback. In case of multiple features, largest value returned by any +feature would be selected for creating feature arc. + +.. _Feature_Arc_Initialization: diff --git a/doc/guides/prog_guide/img/feature_arc-1.svg b/doc/guides/prog_= guide/img/feature_arc-1.svg new file mode 100644 index 0000000000..1c6b83f18f --- /dev/null +++ b/doc/guides/prog_guide/img/feature_arc-1.svg @@ -0,0 +1,269 @@ + + + + +image/svg+xmlNode +- +A +Node +- +B +Feature +- +1 +Static Packet Path +edge =3D=3D 0 +edge =3D=3D 1 +Start Node +End Feature +Node +Feature +Node +Packet path gets activated in +Node +- +A +when Feature +- +1 is +enabled on +an interface + diff --git a/doc/guides/prog_guide/img/feature_arc-2.svg b/doc/guides/prog_= guide/img/feature_arc-2.svg new file mode 100644 index 0000000000..990c96f306 --- /dev/null +++ b/doc/guides/prog_guide/img/feature_arc-2.svg @@ -0,0 +1,511 @@ + + + + +image/svg+xmlNode +- +A +Node +- +B +Feature +- +1 +Static Packet +Path +edge =3D=3D 0 +edge =3D=3D 1 +Custom +=E2=80=93 +Feature +edge =3D=3D 3 +Feature +- +2 +edge =3D=3D 2 +First Feature +For Interface +=E2=80=93 +0,1 +edge =3D=3D 1 +Next Feature to Feature +- +1 +for Interface +- +0 +edge =3D=3D 0 +Next Feature to Feature +- +1 +for Interface +- +1 +edge =3D=3D 0 +Interface +- +0 +Enabled Features +Interface +- +1 +Enabled Features +edge =3D=3D 2 +edge =3D=3D 0 +edge =3D=3D 0 + diff --git a/doc/guides/rel_notes/release_25_07.rst b/doc/guides/rel_notes/= release_25_07.rst index a4962e46d6..3164957964 100644 --- a/doc/guides/rel_notes/release_25_07.rst +++ b/doc/guides/rel_notes/release_25_07.rst @@ -87,6 +87,13 @@ New Features See the :doc:`../cryptodevs/zsda` guide for more details on the new driv= er. +* **Added feature arc abstraction in graph library.** + + Feature arc helps ``rte_graph`` based applications to manage multiple ne= twork + protocols/features with runtime configurability, in-built node-reusabili= ty + and optimized control/data plane synchronization. + + See section ``Graph feature arc`` in :doc:`../prog_guide/graph_lib` for = more details. Removed Items ------------- diff --git a/lib/graph/graph_feature_arc.c b/lib/graph/graph_feature_arc.c new file mode 100644 index 0000000000..6135b262d5 --- /dev/null +++ b/lib/graph/graph_feature_arc.c @@ -0,0 +1,36 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright(C) 2025 Marvell International Ltd. + */ + +#include +#include +#include "graph_private.h" + +/* global feature arc list */ +static STAILQ_HEAD(, rte_graph_feature_arc_register) feature_arc_list =3D + STAILQ_HEAD_INITIALIZER(feature_arc_list); + +/* global feature arc list */ +static STAILQ_HEAD(, rte_graph_feature_register) feature_list =3D + STAILQ_HEAD_INITIALIZER(feature_list); + +RTE_EXPORT_EXPERIMENTAL_SYMBOL(__rte_graph_feature_arc_register, 25.07); +void __rte_graph_feature_arc_register(struct rte_graph_feature_arc_registe= r *reg, + const char *caller_name, int lineno) +{ + RTE_SET_USED(caller_name); + RTE_SET_USED(lineno); + /* Do not validate arc registration here but as part of rte_graph_feature= _arc_init() */ + STAILQ_INSERT_TAIL(&feature_arc_list, reg, next_arc); +} + +RTE_EXPORT_EXPERIMENTAL_SYMBOL(__rte_graph_feature_register, 25.07); +void __rte_graph_feature_register(struct rte_graph_feature_register *reg, + const char *caller_name, int lineno) +{ + RTE_SET_USED(caller_name); + RTE_SET_USED(lineno); + + /* Add to the feature_list*/ + STAILQ_INSERT_TAIL(&feature_list, reg, next_feature); +} diff --git a/lib/graph/meson.build b/lib/graph/meson.build index 0cb15442ab..1b2f493037 100644 --- a/lib/graph/meson.build +++ b/lib/graph/meson.build @@ -17,8 +17,10 @@ sources =3D files( 'graph_pcap.c', 'rte_graph_worker.c', 'rte_graph_model_mcore_dispatch.c', + 'graph_feature_arc.c', ) headers =3D files('rte_graph.h', 'rte_graph_worker.h') +headers +=3D files('rte_graph_feature_arc.h') indirect_headers +=3D files( 'rte_graph_model_mcore_dispatch.h', 'rte_graph_model_rtc.h', diff --git a/lib/graph/rte_graph_feature_arc.h b/lib/graph/rte_graph_featur= e_arc.h new file mode 100644 index 0000000000..56d8f2f34c --- /dev/null +++ b/lib/graph/rte_graph_feature_arc.h @@ -0,0 +1,270 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright(C) 2025 Marvell International Ltd. + */ + +#ifndef _RTE_GRAPH_FEATURE_ARC_H_ +#define _RTE_GRAPH_FEATURE_ARC_H_ + +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @file + * + * rte_graph_feature_arc.h + * + * Define APIs and structures/variables with respect to feature arc + * + * - Feature arc(s) + * - Feature(s) + * + * In a typical network stack, often a protocol must be first enabled in + * control plane before any packet is steered for its processing in the + * dataplane. For eg: incoming IPv4 packets are routed only after a valid = IPv4 + * address is assigned to the received interface. In other words, often pa= ckets + * received on an interface need to be steered to protocol not based on the + * packet content but based on whether the protocol is configured on the + * interface or not. + * + * Protocols can be enabled/disabled multiple times at runtime in the cont= rol + * plane. Protocols enabled on one interface may not be enabled on another + * interface. + * + * When more than one protocols are present at a networking layer (say IPv= 4, + * IP tables, IPsec etc), it becomes imperative to steer packets (in datap= lane) + * across each protocol processing in a defined sequential order. In ingre= ss + * direction, stack decides to perform IPsec decryption first before IP + * validation while in egress direction IPsec encryption is performed afte= r IP + * forwarding. In the case of IP tables, users can enable rules in any + * protocol order i.e. pre-routing or post-routing etc. This implies that + * protocols are configured differently at each networking layer and in ea= ch + * traffic direction. + * + * A feature arc represents an ordered list of features/protocols nodes at= the + * given networking layer and in a given direction. It provides a high lev= el + * abstraction to enable/disable features on an index at runtime and provi= de a + * mechanism to steer packets across these feature nodes in a generic mann= er. + * Here index corresponds to either interface index, route index, flow ind= ex or + * classification index etc. as it is deemed suitable to configure protoco= ls at + * the networking layer. Some typical examples of protocols which are + * configured based on + * + * - Interface Index (like IPv4 VRF, Port mirroring, Port based IPsec etc) + * - Routes Index (like Route based IPsec etc) + * - Flow index (like SDN) + * - Classification Index (like ACL based protocol steering) + * + * Feature arc also provides a way to steer packets from in-built DPDK *fe= ature + * nodes* to out-of-tree *feature nodes* and vice-versa without any code + * changes required in DPDK in-built node's fast path functions. This way = it + * allows application to override default packet path defined by in-built = DPDK + * nodes. + * + * Features enabled on one index may not be enabled on another index hence + * packets received on an interface "X" should be treated independently fr= om + * packets received on interface "Y". + * + * A given feature might consume packet (if it's configured to consume) or= may + * forward it to next enabled feature. For instance, "IPsec input" feature= may + * consume/drop all packets with "Protect" policy action while all packets= with + * policy action as "Bypass" may be forwarded to next enabled feature (wit= h in + * same feature arc) + * + * A feature arc in a graph is represented via *start_node* and *end_node*. + * Feature nodes are added between start_node and end_node. Packets enter + * feature arc traversal via start_node while they exits from end_node. Pa= ckets + * steering from start_node to feature nodes are controlled in control pla= ne + * via rte_graph_feature_enable()/rte_graph_feature_disable(). + * + * This library facilitates rte graph based applications to implement stack + * functionalities described above by providing "edge" to the next enabled + * feature node in fast path + * + */ + +/** feature notifier callback called when feature is enabled/disabled */ +typedef void (*rte_graph_feature_change_notifier_cb_t)(const char *arc_nam= e, + const char *feature_name, + rte_node_t feature_node_id, + uint32_t index, + bool enable_disable, + uint16_t app_cookie); + +/** cb for overriding arc->max_indexes via RTE_GRAPH_FEATURE_REGISTER() */ +typedef uint16_t (*rte_graph_feature_override_index_cb_t)(void); + +/** + * Feature registration structure provided to + * RTE_GRAPH_FEATURE_REGISTER() + */ +struct rte_graph_feature_register { + /** + * Pointer to next registered feature in the same arc. + */ + STAILQ_ENTRY(rte_graph_feature_register) next_feature; + + /** Name of the arc which is registered either via + * RTE_GRAPH_FEATURE_ARC_REGISTER() or via + * rte_graph_feature_arc_create() + */ + const char *arc_name; + + /** Name of the feature */ + const char *feature_name; + + /** + * Node id of feature_node. + * + * Setting this field can be skipped if registering feature via + * RTE_GRAPH_FEATURE_REGISTER() + */ + rte_node_t feature_node_id; + + /** + * Feature node process() function calling feature fast path APIs. + * + * If application calls rte_graph_feature_arc_init(), node->process() + * provided in RTE_NODE_REGISTER() is overwritten by this + * function. + */ + rte_node_process_t feature_process_fn; + + /** + * Pointer to Feature node registration + * + * Used when features are registered via + * RTE_GRAPH_FEATURE_REGISTER(). + */ + struct rte_node_register *feature_node; + + /** Feature ordering constraints + * runs_after: Name of the feature which must run before "this feature" + * runs_before: Name of the feature which must run after "this feature" + */ + const char *runs_after; + const char *runs_before; + + /** + * Allow each feature registration to override arc->max_indexes + * + * If set, struct rte_graph_feature_arc_register::max_indexes is + * calculated as follows (before calling rte_graph_feature_arc_create()) + * + * max_indexes =3D rte_graph_feature_arc_register:max_indexes + * FOR_EACH_FEATURE_REGISTER(arc, feat) { + * rte_graph_feature_arc_register:max_indexes =3D max(feat->override_in= dex_cb(), + * max_indexes) + */ + rte_graph_feature_override_index_cb_t override_index_cb; + + /** + * Callback for notifying any change in feature enable/disable state + */ + rte_graph_feature_change_notifier_cb_t notifier_cb; +}; + +/** Feature arc registration structure */ +struct rte_graph_feature_arc_register { + STAILQ_ENTRY(rte_graph_feature_arc_register) next_arc; + + /** Name of the feature arc */ + const char *arc_name; + + /** + * Maximum number of features supported in this feature arc. + * + * This field can be skipped for feature arc registration via + * RTE_GRAPH_FEATURE_ARC_REGISTER(). + * + * API internally sets this field by calculating number of + * RTE_GRAPH_FEATURE_REGISTER() for every arc registration via + * RTE_GRAPH_FEATURE_ARC_REGISTER() + */ + uint16_t max_features; + + /** + * Maximum number of indexes supported in this feature arc + * Memory is allocated based on this field + */ + uint16_t max_indexes; + + /** Start node of this arc */ + struct rte_node_register *start_node; + + /** + * Feature arc specific process() function for Start node. + * If application calls rte_graph_feature_arc_init(), + * start_node->process() is replaced by this function + */ + rte_node_process_t start_node_feature_process_fn; + + /** End feature node registration */ + struct rte_graph_feature_register *end_feature; +}; + +/** constructor to register feature to an arc */ +#define RTE_GRAPH_FEATURE_REGISTER(reg) = \ + RTE_INIT(__rte_graph_feature_register_##reg) = \ + { = \ + __rte_graph_feature_register(®, __func__, __LINE__); \ + } + +/** constructor to register a feature arc */ +#define RTE_GRAPH_FEATURE_ARC_REGISTER(reg) = \ + RTE_INIT(__rte_graph_feature_arc_register_##reg) = \ + { = \ + __rte_graph_feature_arc_register(®, __func__, __LINE__); \ + } + +/** + * @internal + * + * function declaration for registering arc + * + * @param reg + * Pointer to struct rte_graph_feature_arc_register + * @param caller_name + * Name of the function which is calling this API + * @param lineno + * Line number of the function which is calling this API + */ +__rte_experimental +void __rte_graph_feature_arc_register(struct rte_graph_feature_arc_registe= r *reg, + const char *caller_name, int lineno); + +/** + * @internal + * + * function declaration for registering feature + * + * @param reg + * Pointer to struct rte_graph_feature_register + * @param caller_name + * Name of the function which is calling this API + * @param lineno + * Line number of the function which is calling this API + */ +__rte_experimental +void __rte_graph_feature_register(struct rte_graph_feature_register *reg, + const char *caller_name, int lineno); + +#ifdef __cplusplus +} +#endif + +#endif -- 2.43.0