Enhanced multiple sample application guides: eventdev_pipeline.rst: - Improved command-line option formatting and descriptions - Standardized terminology and fixed grammatical issues - Clarified pipeline stage descriptions
fips_validation.rst: - Restructured algorithm support sections for clarity - Fixed formatting inconsistencies - Improved readability of validation process descriptions flow_filtering.rst: - Enhanced code explanations and flow descriptions - Fixed formatting and indentation issues - Clarified API usage examples Signed-off-by: Stephen Hemminger <[email protected]> --- .../sample_app_ug/eventdev_pipeline.rst | 51 ++++++++------- doc/guides/sample_app_ug/fips_validation.rst | 63 +++++++++---------- doc/guides/sample_app_ug/flow_filtering.rst | 51 +++++++-------- 3 files changed, 82 insertions(+), 83 deletions(-) diff --git a/doc/guides/sample_app_ug/eventdev_pipeline.rst b/doc/guides/sample_app_ug/eventdev_pipeline.rst index 19ff53803e..343d3f46ec 100644 --- a/doc/guides/sample_app_ug/eventdev_pipeline.rst +++ b/doc/guides/sample_app_ug/eventdev_pipeline.rst @@ -4,41 +4,40 @@ Eventdev Pipeline Sample Application ==================================== -The eventdev pipeline sample application is a sample app that demonstrates +The eventdev pipeline sample application is an application that demonstrates the usage of the eventdev API using the software PMD. It shows how an application can configure a pipeline and assign a set of worker cores to perform the processing required. -The application has a range of command line arguments allowing it to be -configured for various numbers worker cores, stages,queue depths and cycles per -stage of work. This is useful for performance testing as well as quickly testing +The application has a range of command line arguments that allow it to be +configured for various numbers of worker cores, stages, queue depths, and cycles +per stage of work. This is useful for performance testing as well as quickly testing a particular pipeline configuration. Compiling the Application ------------------------- -To compile the sample application see :doc:`compiling`. - -The application is located in the ``examples`` sub-directory. +To compile the sample application, see :doc:`compiling`. +The application is located in the ``examples`` directory. Running the Application ----------------------- -The application has a lot of command line options. This allows specification of -the eventdev PMD to use, and a number of attributes of the processing pipeline +The application has a lot of command line options. This allows the specification of +the eventdev PMD to use and for a number of attributes of the processing pipeline options. An example eventdev pipeline running with the software eventdev PMD using these settings is shown below: - * ``-l 0,2,8-15``: lcore to use + * ``-l 0,2,8-15``: lcores to use * ``-r1``: core mask 0x1 for RX * ``-t1``: core mask 0x1 for TX * ``-e4``: core mask 0x4 for the software scheduler - * ``-w FF00``: core mask for worker cores, 8 cores from 8th to 16th + * ``-w FF00``: core mask for worker cores, 8 cores from 8th to 15th * ``-s4``: 4 atomic stages * ``-n0``: process infinite packets (run forever) * ``-c32``: worker dequeue depth of 32 @@ -50,8 +49,8 @@ these settings is shown below: ./<build_dir>/examples/dpdk-eventdev_pipeline -l 0,2,8-15 --vdev event_sw0 \ -- -r1 -t1 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D -The application has some sanity checking built-in, so if there is a function -(e.g.; the RX core) which doesn't have a cpu core mask assigned, the application +The application has sanity checking built-in, so if there is a function +(e.g., the RX core) which does not have a CPU core mask assigned, the application will print an error message: .. code-block:: console @@ -61,26 +60,26 @@ will print an error message: rx: 0 tx: 1 -Configuration of the eventdev is covered in detail in the programmers guide, -see the Event Device Library section. +Configuration of the eventdev is covered in detail in the programmer's guide. +See the Event Device Library section. Observing the Application -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ -At runtime the eventdev pipeline application prints out a summary of the -configuration, and some runtime statistics like packets per second. On exit the -worker statistics are printed, along with a full dump of the PMD statistics if +At runtime, the eventdev pipeline application prints out a summary of the +configuration, and some runtime statistics like packets per second. On exit, the +worker core statistics are printed, along with a full dump of the PMD statistics if required. The following sections show sample output for each of the output types. Configuration -~~~~~~~~~~~~~ +^^^^^^^^^^^^^ -This provides an overview of the pipeline, -scheduling type at each stage, and parameters to options such as how many -flows to use and what eventdev PMD is in use. See the following sample output -for details: +The configuration output provides an overview of the pipeline, the scheduling +type at each stage, +and parameters such as the number of flows and the eventdev PMD in use. +See the following sample output for details: .. code-block:: console @@ -101,7 +100,7 @@ for details: Stage 3, Type Atomic Priority = 128 Runtime -~~~~~~~ +^^^^^^^ At runtime, the statistics of the consumer are printed, stating the number of packets received, runtime in milliseconds, average mpps, and current mpps. @@ -111,7 +110,7 @@ packets received, runtime in milliseconds, average mpps, and current mpps. # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps] Shutdown -~~~~~~~~ +^^^^^^^^ At shutdown, the application prints the number of packets received and transmitted, and an overview of the distribution of work across worker cores. diff --git a/doc/guides/sample_app_ug/fips_validation.rst b/doc/guides/sample_app_ug/fips_validation.rst index 613c5afd19..732f47212a 100644 --- a/doc/guides/sample_app_ug/fips_validation.rst +++ b/doc/guides/sample_app_ug/fips_validation.rst @@ -7,13 +7,13 @@ Federal Information Processing Standards (FIPS) CryptoDev Validation Overview -------- +This application parses and performs symmetric cryptography computations +using test vectors from the NIST Cryptographic Algorithm Validation Program +(CAVP) and Automated Crypto Validation Protocol (ACVP). + Federal Information Processing Standards (FIPS) are publicly announced standards developed by the United States federal government for use in computer systems by -non-military government agencies and government contractors. - -This application is used to parse and perform symmetric cryptography -computation to the NIST Cryptographic Algorithm Validation Program (CAVP) and -Automated Crypto Validation Protocol (ACVP) test vectors. +non-military agencies and government contractors. For an algorithm implementation to be listed on a cryptographic module validation certificate as an Approved security function, the algorithm @@ -21,6 +21,7 @@ implementation must meet all the requirements of FIPS 140-2 (in case of CAVP) and FIPS 140-3 (in case of ACVP) and must successfully complete the cryptographic algorithm validation process. + Limitations ----------- @@ -28,17 +29,17 @@ CAVP ---- * The version of request file supported is ``CAVS 21.0``. -* If the header comment in a ``.req`` file does not contain a Algo tag - i.e ``AES,TDES,GCM`` you need to manually add it into the header comment for - example:: +* If the header comment in a ``.req`` file does not contain an algorithm tag + (i.e., ``AES``, ``TDES``, ``GCM``), you must manually add it to the header + comment, for example:: # VARIABLE KEY - KAT for CBC / # TDES VARIABLE KEY - KAT for CBC -* The application does not supply the test vectors. The user is expected to - obtain the test vector files from `CAVP +* The application does not supply the test vectors. Users must obtain the + test vector files from the `CAVP <https://csrc.nist.gov/projects/cryptographic-algorithm-validation- - program/block-ciphers>`_ website. To obtain the ``.req`` files you need to - email a person from the NIST website and pay for the ``.req`` files. + program/block-ciphers>`_ website. To obtain the ``.req`` files, you need to + contact a representative from the NIST website and pay for the ``.req`` files. The ``.rsp`` files from the site can be used to validate and compare with the ``.rsp`` files created by the FIPS application. @@ -54,7 +55,7 @@ CAVP ACVP ---- -* The application does not supply the test vectors. The user is expected to +* The application does not supply the test vectors. Users must obtain the test vector files from `ACVP <https://pages.nist.gov/ACVP>`_ website. * Supported test vectors @@ -78,19 +79,17 @@ ACVP Application Information ----------------------- -If a ``.req`` is used as the input file after the application is finished -running it will generate a response file or ``.rsp``. Differences between the -two files are, the ``.req`` file has missing information for instance if doing -encryption you will not have the cipher text and that will be generated in the -response file. Also if doing decryption it will not have the plain text until it -finished the work and in the response file it will be added onto the end of each -operation. - -The application can be run with a ``.rsp`` file and what the outcome of that -will be is it will add a extra line in the generated ``.rsp`` which should be -the same as the ``.rsp`` used to run the application, this is useful for -validating if the application has done the operation correctly. +If a ``.req`` file is used as input, the application generates a response +file (``.rsp``) after completion. The ``.req`` file has missing fields that +the application fills in. For example, when +performing encryption the cipher text is absent; when performing decryption +the plain text is absent. These are computed and added to the ``.rsp`` file +at the end of each operation. +The application can also run with a ``.rsp`` file as input. In this case, +it generates a new ``.rsp`` with an additional verification line. The output +should match the input ``.rsp``, which is useful for validating that the +application performed the operations correctly. Compiling the Application ------------------------- @@ -125,23 +124,23 @@ The application requires a number of command line options: --mbuf-dataroom DATAROOM_SIZE where, - * req-file: The path of the request file or folder, separated by + * req-file: The path of the request file or folder, indicated by ``path-is-folder`` option. - * rsp-file: The path that the response file or folder is stored. separated by + * rsp-file: The path where the response file or folder is stored, indicated by ``path-is-folder`` option. * cryptodev: The name of the target DPDK Crypto device to be validated. * cryptodev-id: The id of the target DPDK Crypto device to be validated. - * path-is-folder: If presented the application expects req-file and rsp-file - are folder paths. + * path-is-folder: If present, the application treats req-file and rsp-file + as folder paths. * mbuf-dataroom: By default the application creates mbuf pool with maximum - possible data room (65535 bytes). If the user wants to test scatter-gather - list feature of the PMD he or she may set this value to reduce the dataroom - size so that the input data may be divided into multiple chained mbufs. + possible data room (65535 bytes). To test the scatter-gather + list feature of a PMD, this value may be set to reduce the dataroom + size so that the input data is divided into multiple chained mbufs. To run the application in linux environment to test one AES FIPS test data diff --git a/doc/guides/sample_app_ug/flow_filtering.rst b/doc/guides/sample_app_ug/flow_filtering.rst index 179e978942..db5947d9e4 100644 --- a/doc/guides/sample_app_ug/flow_filtering.rst +++ b/doc/guides/sample_app_ug/flow_filtering.rst @@ -7,11 +7,11 @@ Flow Filtering Sample Application Overview -------- -The flow filtering sample application provides a simple example of creating flow rules. +The flow filtering sample application is a simple example of creating flow rules. It serves as a demonstration of the fundamental components of flow rules. -It demonstrates how to create rules and configure them, using both template and non template API. +It demonstrates how to create and configure rules using both template and non-template APIs. Compiling the Application @@ -25,7 +25,7 @@ The application is located in the ``flow_filtering`` sub-directory. Running the Application ----------------------- -To run the example in a ``linux`` environment: +To run the example in a Linux environment: .. code-block:: console @@ -34,7 +34,7 @@ To run the example in a ``linux`` environment: where, ``--[non-]template`` - Specify whether to use the template API (default is template API). + Specifies whether to use the template API (default is template API). For more details on template API please refer to :ref:`flow_template_api`. @@ -50,7 +50,7 @@ The example is built from 2 main files: - ``main.c``: Contains the application logic, including initializations and the main loop. - ``flow_skeleton.c``: Implements the creation of flow rules. -Additionally, the ``snippets`` directory includes code snippets showcasing various features +Additionally, the ``snippets`` directory contains code snippets showcasing various features that can override the basic ``flow_skeleton.c`` implementation. @@ -87,7 +87,7 @@ those configuration are defined in the snippet file. :end-before: >8 End of snippet-specific configuration. :dedent: 1 -Initialize the ports using the user-defined ``init_port()`` function, +Initialize the ports using the ``init_port()`` function, configuring Ethernet ports with default settings, including both Rx and Tx queues for a single port: .. literalinclude:: ../../../examples/flow_filtering/main.c @@ -96,7 +96,7 @@ configuring Ethernet ports with default settings, including both Rx and Tx queue :end-before: >8 End of Initializing the ports using user defined init_port(). :dedent: 1 -For template API, the flow API requires preallocating resources. +For the template API, the flow API requires preallocating resources. The function ``rte_flow_configure()`` should be called after configuring the Ethernet device and before creating any flow rules to set up flow queues for asynchronous operations. @@ -109,14 +109,14 @@ and before creating any flow rules to set up flow queues for asynchronous operat Creating the Flow Rule ~~~~~~~~~~~~~~~~~~~~~~ -This section is the core of the flow filtering functionality involves creating flow rules. -The flow rules are created using two primary approaches: template API and non-template API. -Both template and non-template API configure flow rules using attributes (like ingress or egress), -pattern items (for matching packet data), and actions (for operations on matched packets). -However, template API extend this by introducing pattern templates and actions templates, +This section covers the core of the flow filtering functionality: creating flow rules. +Flow rules are created using two primary approaches: template API and non-template API. +Both APIs configure flow rules using the same components: attributes (such as ingress or egress), +pattern items (for matching packet data), and actions (to perform operations on matched packets). +However, the template API extends this by introducing pattern templates and action templates, which define reusable matching criteria and action lists, respectively. -These templates are then combined in a template table to optimize resource allocation and management. -In contrast, non-template API handle each rule individually without such shared templates. +The pattern and action templates are combined in a template table to optimize resource allocation. +In contrast, the non-template API handles each rule individually without such shared templates. This is handled by the ``generate_flow_skeleton()`` function in ``flow_skeleton.c``. @@ -127,8 +127,8 @@ This is handled by the ``generate_flow_skeleton()`` function in ``flow_skeleton. :dedent: 1 This part of the code defines necessary data structures, -as well as configures action and pattern structures for the rule. -Common for both template and non-template API. +and configures action and pattern structures for the rule. +This is common to both template and non-template APIs. .. literalinclude:: ../../../examples/flow_filtering/flow_skeleton.c :language: c @@ -136,7 +136,7 @@ Common for both template and non-template API. :end-before: >8 End of setting the common action and pattern structures. :dedent: 1 -For template API, this part of the code creates the necessary template tables and finally create the rule. +For the template API, the code creates pattern and action templates, combines them in a template table, and creates the rule. .. literalinclude:: ../../../examples/flow_filtering/flow_skeleton.c :language: c @@ -144,7 +144,7 @@ For template API, this part of the code creates the necessary template tables an :end-before: >8 End of creating a flow rule using template API. :dedent: 1 -For non-template API, validate the rule and create it. +For the non-template API, the code validates and creates the rule directly. .. literalinclude:: ../../../examples/flow_filtering/flow_skeleton.c :language: c @@ -156,7 +156,7 @@ Main Loop Execution ~~~~~~~~~~~~~~~~~~~ Launch the ``main_loop()`` function from ``main.c``, -which reading the packets from all queues and printing for each packet the destination queue: +which reads packets from all queues and prints the destination queue for each packet: .. literalinclude:: ../../../examples/flow_filtering/main.c :language: c @@ -186,18 +186,19 @@ Using Snippets Developers can customize flow rules by modifying ``flow_skeleton.c`` and utilizing functions from ``snippets`` directory. -For example, within ``snippet_match_ipv4_flow.c``, developers can find the functions: +For example, ``snippet_match_ipv4_flow.c`` provides: - ``snippet_ipv4_flow_create_actions()`` for defining actions, - ``snippet_ipv4_flow_create_patterns()`` for setting packet matching patterns, - ``snippet_ipv4_flow_create_table()`` for creating the patterns and actions template table. -To use a different snippet, simply update the include statement in ``flow_skeleton.c`` -to point to the desired snippet file, this will change the default created flow. +To use a different snippet, update the include statement in ``flow_skeleton.c`` +to point to the desired snippet file. This will change the default flow rule created. -Some snippets may require different configuration, -those configuration are defined in the snippet file: +Some snippets require additional port or flow configuration. +These are defined in the snippet header file, for example: - ``snippet_init_ipv4`` for configuration of the port and flow attributes. -In order to use them the developer should include the snippet header file in main.c +To apply these configurations, include the snippet header file in ``main.c`` +so that the snippet-specific initialization is called during port setup. -- 2.53.0
