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 C5F194688E; Thu, 5 Jun 2025 19:33:43 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 240D540608; Thu, 5 Jun 2025 19:33:35 +0200 (CEST) Received: from mx0b-0016f401.pphosted.com (mx0b-0016f401.pphosted.com [67.231.156.173]) by mails.dpdk.org (Postfix) with ESMTP id BE11940150 for ; Thu, 5 Jun 2025 19:33:32 +0200 (CEST) Received: from pps.filterd (m0045851.ppops.net [127.0.0.1]) by mx0b-0016f401.pphosted.com (8.18.1.2/8.18.1.2) with ESMTP id 555H0RRN020512; Thu, 5 Jun 2025 10:33:27 -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=Q 6utgXaCBgH4gH/hkwObz9QSiuU66xVSqnrOtWmi/XQ=; b=QYUblAIm7F7XKfRKI 0owOGx1Gv+S5FfRGUKMi0JajpgceKn0mFtbWSASJwOt/+dXJmKMDsUz2eeilT6U2 f+xZElYvcpOQ+WIiMY0jkn9LoeOmNmSdtFK2/ydYuVnZV2F0Z8HNkaG35QsM2o7B lwl2jOxK66zIhIkaZweVLWm6s07uJ/ToAR581PjVuzkq85K56AGiBquttInjzSu3 DKfZ3A4yeIxiMPH5n/7yNHV6Y8BLDPVZMDcmn0iHPXo0FS9+VE/GVLRZKLhfnaHU 6G1LhSQWaNnYOfxktygUBqJXDliUnuMZsmvBwRt5K6AveIoFnCWBLzqA19fw+DTB rY5UA== Received: from dc6wp-exch02.marvell.com ([4.21.29.225]) by mx0b-0016f401.pphosted.com (PPS) with ESMTPS id 472as454ww-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Thu, 05 Jun 2025 10:33:27 -0700 (PDT) Received: from DC6WP-EXCH02.marvell.com (10.76.176.209) by DC6WP-EXCH02.marvell.com (10.76.176.209) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.1544.4; Thu, 5 Jun 2025 10:33:26 -0700 Received: from maili.marvell.com (10.69.176.80) by DC6WP-EXCH02.marvell.com (10.76.176.209) with Microsoft SMTP Server id 15.2.1544.4 via Frontend Transport; Thu, 5 Jun 2025 10:33:26 -0700 Received: from cavium-PowerEdge-R640.. (unknown [10.28.36.207]) by maili.marvell.com (Postfix) with ESMTP id 1414A3F7044; Thu, 5 Jun 2025 10:33:22 -0700 (PDT) From: Nitin Saxena To: Jerin Jacob , Kiran Kumar K , Nithin Dabilpuram , Zhirun Yan , Robin Jarry , Christophe Fontaine CC: , Nitin Saxena Subject: [PATCH v12 2/7] graph: add feature arc registrations Date: Thu, 5 Jun 2025 23:03:07 +0530 Message-ID: <20250605173315.1447003-3-nsaxena@marvell.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250605173315.1447003-1-nsaxena@marvell.com> References: <20250103060612.2671836-1-nsaxena@marvell.com> <20250605173315.1447003-1-nsaxena@marvell.com> MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Proofpoint-Spam-Details-Enc: AW1haW4tMjUwNjA1MDE1NSBTYWx0ZWRfX+xDYWr7Cdf57 2O/pEceKXtCecmOsASLU6re0PxlzxLylug8ochD7stwiNus08rgJbkwy5FB6Q2Od2B9+fZ1ieEM Sa0x/nkr4CpTY9PjzZrb/rzsWulO1TSJpG5Ft7IXO3MK4MCQ+b7hNEk0Ssbr/076E2ttd3dbYKI zfPAz3oR7fkCqSfSCDf4+hC4qTGJpaXkI5zlOPWkWellOHrhPAx3qvoSIMCzFBeIR8pRD5ctxX2 7/AR67DGp49s6F5qcL4Fgr/S5QV1ilTuFYAouDLFZPw0iA7bMCs+cpNR5jW6OCDin74gYOFnYpJ kKA+OVQ29JSE8QZU4IXFQDNDfUHD8oJFwLWPCMz9T36ZvWiAlr4hcFRiZaISZeTaLNNhSWRNRqk tNYPqCIZyRhISyWGkhPSZV0brJKjh1C8p1UEfV6J3N/gyZtQShyPbd2zlHO34IeunFRq0Lfw X-Proofpoint-GUID: Vh4sX23jsGoKZQD3s3GRMlHHYpVoItUj X-Proofpoint-ORIG-GUID: Vh4sX23jsGoKZQD3s3GRMlHHYpVoItUj X-Authority-Analysis: v=2.4 cv=It4ecK/g c=1 sm=1 tr=0 ts=6841d4e7 cx=c_pps a=gIfcoYsirJbf48DBMSPrZA==:117 a=gIfcoYsirJbf48DBMSPrZA==: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-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-05_04,2025-06-05_01,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 | 3 +- doc/guides/prog_guide/graph_lib.rst | 291 +++++++++++ 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 | 272 +++++++++++ 8 files changed, 1390 insertions(+), 1 deletion(-) 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..2d55c7fe01 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -213,7 +213,8 @@ The public API headers are grouped by topics: [table_em](@ref rte_swx_table_em.h) [table_wm](@ref rte_swx_table_wm.h) * [graph](@ref rte_graph.h): - [graph_worker](@ref rte_graph_worker.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..2f64f32c6c 100644 --- a/doc/guides/prog_guide/graph_lib.rst +++ b/doc/guides/prog_guide/graph_lib.rst @@ -404,6 +404,295 @@ The graph_nodes_mem_create() creates and populate thi= s memory. The functions such as ``rte_graph_walk()`` and ``rte_node_enqueue_*`` use this memory to enable fastpath services. +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 +``Custom Feature`` needs to run after ``Feature-1`` it can be defined as s= hown +above. Similarly, if ``Feature-2`` needs to run before ``Custom-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: + Inbuilt Nodes ------------- @@ -559,3 +848,5 @@ 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``. + + 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..f50f82f001 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 support 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..65066f06dd --- /dev/null +++ b/lib/graph/rte_graph_feature_arc.h @@ -0,0 +1,272 @@ +/* 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 + * + * @warning + * @b EXPERIMENTAL: + * All functions in this file may be changed or removed without prior noti= ce. + * + * Graph Feature Arc API + * + * 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 path via start_node while they exits from end_node. + * + * 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