patches for DPDK stable branches
 help / color / mirror / Atom feed
From: Xueming Li <xuemingl@nvidia.com>
To: Ciara Power <ciara.power@intel.com>
Cc: <xuemingl@nvidia.com>, Fan Zhang <roy.fan.zhang@intel.com>,
	dpdk stable <stable@dpdk.org>
Subject: patch 'doc: fix grammar and formatting in compressdev guide' has been queued to stable release 20.11.6
Date: Wed, 20 Jul 2022 11:21:21 +0300	[thread overview]
Message-ID: <20220720082132.3954126-52-xuemingl@nvidia.com> (raw)
In-Reply-To: <20220720082132.3954126-1-xuemingl@nvidia.com>

Hi,

FYI, your patch has been queued to stable release 20.11.6

Note it hasn't been pushed to http://dpdk.org/browse/dpdk-stable yet.
It will be pushed if I get no objections before 07/22/22. So please
shout if anyone has objections.

Also note that after the patch there's a diff of the upstream commit vs the
patch applied to the branch. This will indicate if there was any rebasing
needed to apply to the stable branch. If there were code changes for rebasing
(ie: not only metadata diffs), please double check that the rebase was
correctly done.

Queued patches are on a temporary branch at:
https://github.com/steevenlee/dpdk

This queued commit can be viewed at:
https://github.com/steevenlee/dpdk/commit/92962694e870727efa84358a3323c58ee1c2d8a0

Thanks.

Xueming Li <xuemingl@nvidia.com>

---
From 92962694e870727efa84358a3323c58ee1c2d8a0 Mon Sep 17 00:00:00 2001
From: Ciara Power <ciara.power@intel.com>
Date: Mon, 30 May 2022 16:03:42 +0000
Subject: [PATCH] doc: fix grammar and formatting in compressdev guide
Cc: Xueming Li <xuemingl@nvidia.com>

[ upstream commit 4c9484373fcd0aa4a240fdb2e797269eb2f26b9b ]

Small improvements made to the compressdev programmer's guide.
This includes rephrasing some sentences, fixing grammar,
and aligning formatting.

Fixes: a584d3bea902 ("doc: add compressdev library guide")
Fixes: f7095d41bba6 ("doc: clarify data plane error handling in compressdev")

Signed-off-by: Ciara Power <ciara.power@intel.com>
Acked-by: Fan Zhang <roy.fan.zhang@intel.com>
---
 doc/guides/prog_guide/compressdev.rst | 283 ++++++++++++++------------
 1 file changed, 148 insertions(+), 135 deletions(-)

diff --git a/doc/guides/prog_guide/compressdev.rst b/doc/guides/prog_guide/compressdev.rst
index 07d1a62a63..2a59c434c1 100644
--- a/doc/guides/prog_guide/compressdev.rst
+++ b/doc/guides/prog_guide/compressdev.rst
@@ -2,7 +2,7 @@
     Copyright(c) 2017-2018 Cavium Networks.
 
 Compression Device Library
-===========================
+==========================
 
 The compression framework provides a generic set of APIs to perform compression services
 as well as to query and configure compression devices both physical(hardware) and virtual(software)
@@ -32,10 +32,10 @@ From the command line using the --vdev EAL option
 
 .. Note::
 
-   * If DPDK application requires multiple software compression PMD devices then required
-     number of ``--vdev`` with appropriate libraries are to be added.
+   * If a DPDK application requires multiple software compression PMD devices then the
+     required number of ``--vdev`` args with appropriate libraries are to be added.
 
-   * An Application with multiple compression device instances exposed by the same PMD must
+   * An application with multiple compression device instances exposed by the same PMD must
      specify a unique name for each device.
 
    Example: ``--vdev  'pmd0' --vdev  'pmd1'``
@@ -53,7 +53,7 @@ All virtual compression devices support the following initialization parameters:
 Device Identification
 ~~~~~~~~~~~~~~~~~~~~~
 
-Each device, whether virtual or physical is uniquely designated by two
+Each device, whether virtual or physical, is uniquely designated by two
 identifiers:
 
 - A unique device index used to designate the compression device in all functions
@@ -76,7 +76,7 @@ The ``rte_compressdev_configure`` API is used to configure a compression device.
 The ``rte_compressdev_config`` structure is used to pass the configuration
 parameters.
 
-See *DPDK API Reference* for details.
+See the `DPDK API Reference <https://doc.dpdk.org/api/rte__compressdev_8h.html>`_ for details.
 
 Configuration of Queue Pairs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -85,87 +85,88 @@ Each compression device queue pair is individually configured through the
 ``rte_compressdev_queue_pair_setup`` API.
 
 The ``max_inflight_ops`` is used to pass maximum number of
-rte_comp_op that could be present in a queue at-a-time.
-PMD then can allocate resources accordingly on a specified socket.
+``rte_comp_op`` that could be present in a queue at a time.
+The PMD can then allocate resources accordingly on a specified socket.
 
-See *DPDK API Reference* for details.
+See the `DPDK API Reference <https://doc.dpdk.org/api/rte__compressdev_8h.html>`_ for details.
 
-Logical Cores, Memory and Queues Pair Relationships
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Logical Cores, Memory and Queue Pair Relationships
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Library supports NUMA similarly as described in Cryptodev library section.
+The Compressdev library supports NUMA similarly as described in Cryptodev library section.
 
-A queue pair cannot be shared and should be exclusively used by a single processing
-context for enqueuing operations or dequeuing operations on the same compression device
+A queue pair cannot be shared, and should be exclusively used by a single processing
+context for enqueuing operations or dequeuing operations on the same compression device,
 since sharing would require global locks and hinder performance. It is however possible
 to use a different logical core to dequeue an operation on a queue pair from the logical
-core on which it was enqueued. This means that a compression burst enqueue/dequeue
+core on which it was enqueued. This means that for a compression burst, enqueue/dequeue
 APIs are a logical place to transition from one logical core to another in a
 data processing pipeline.
 
 Device Features and Capabilities
----------------------------------
+--------------------------------
 
 Compression devices define their functionality through two mechanisms, global device
-features and algorithm features. Global devices features identify device
-wide level features which are applicable to the whole device such as supported hardware
+features and algorithm features. Global device features identify device
+wide level features which are applicable to the whole device, such as supported hardware
 acceleration and CPU features. List of compression device features can be seen in the
 RTE_COMPDEV_FF_XXX macros.
 
-The algorithm features lists individual algo feature which device supports per-algorithm,
-such as a stateful compression/decompression, checksums operation etc. List of algorithm
-features can be seen in the RTE_COMP_FF_XXX macros.
+The algorithm features are features which the device supports per-algorithm,
+such as a stateful compression/decompression, checksums operation etc.
+The list of algorithm features can be seen in the RTE_COMP_FF_XXX macros.
 
 Capabilities
 ~~~~~~~~~~~~
 Each PMD has a list of capabilities, including algorithms listed in
-enum ``rte_comp_algorithm`` and its associated feature flag and
-sliding window range in log base 2 value. Sliding window tells
-the minimum and maximum size of lookup window that algorithm uses
+the enum ``rte_comp_algorithm``, its associated feature flag, and
+sliding window range in log base 2 value. The sliding window range
+defines the minimum and maximum size of a lookup window that an algorithm uses
 to find duplicates.
 
-See *DPDK API Reference* for details.
+See the `DPDK API Reference <https://doc.dpdk.org/api/rte__compressdev_8h.html>`_ for details.
 
 Each Compression poll mode driver defines its array of capabilities
-for each algorithm it supports. See PMD implementation for capability
+for each algorithm it supports. See the PMD implementation for capability
 initialization.
 
 Capabilities Discovery
 ~~~~~~~~~~~~~~~~~~~~~~
 
-PMD capability and features are discovered via ``rte_compressdev_info_get`` function.
+PMD capability and features are discovered via the ``rte_compressdev_info_get`` function.
 
 The ``rte_compressdev_info`` structure contains all the relevant information for the device.
 
-See *DPDK API Reference* for details.
+See the `DPDK API Reference <https://doc.dpdk.org/api/rte__compressdev_8h.html>`_ for details.
 
 Compression Operation
-----------------------
+---------------------
 
 DPDK compression supports two types of compression methodologies:
 
-- Stateless, data associated to a compression operation is compressed without any reference
+- Stateless - data associated with a compression operation is compressed without any reference
   to another compression operation.
 
-- Stateful, data in each compression operation is compressed with reference to previous compression
+- Stateful - data in each compression operation is compressed with reference to previous compression
   operations in the same data stream i.e. history of data is maintained between the operations.
 
-For more explanation, please refer RFC https://www.ietf.org/rfc/rfc1951.txt
+For more explanation, please refer to the RFC https://www.ietf.org/rfc/rfc1951.txt
 
 Operation Representation
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Compression operation is described via ``struct rte_comp_op``, which contains both input and
+A compression operation is described via ``struct rte_comp_op``, which contains both input and
 output data. The operation structure includes the operation type (stateless or stateful),
-the operation status and the priv_xform/stream handle, source, destination and checksum buffer
+the operation status, the priv_xform/stream handle, source, destination and checksum buffer
 pointers. It also contains the source mempool from which the operation is allocated.
-PMD updates consumed field with amount of data read from source buffer and produced
-field with amount of data of written into destination buffer along with status of
-operation. See section *Produced, Consumed And Operation Status* for more details.
-
-Compression operations mempool also has an ability to allocate private memory with the
-operation for application's purposes. Application software is responsible for specifying
-all the operation specific fields in the ``rte_comp_op`` structure which are then used
+The PMD updates the consumed field with the amount of data read from the source buffer,
+and the produced field with the amount of data written into the destination buffer,
+along with status of operation.
+See the section :ref:`compressdev_prod_cons_op_status`: for more details.
+
+The compression operations mempool also has the ability to allocate private memory with the
+operation for the application's use. The application software is responsible for specifying
+all the operation specific fields in the ``rte_comp_op`` structure, which are then used
 by the compression PMD to process the requested operation.
 
 
@@ -181,27 +182,27 @@ A ``rte_comp_op`` contains a field indicating the pool it originated from.
 
 ``rte_comp_op_alloc()`` and ``rte_comp_op_bulk_alloc()`` are used to allocate
 compression operations from a given compression operation mempool.
-The operation gets reset before being returned to a user so that operation
+The operation gets reset before being returned to a user so that the operation
 is always in a good known state before use by the application.
 
 ``rte_comp_op_free()`` is called by the application to return an operation to
 its allocating pool.
 
-See *DPDK API Reference* for details.
+See the `DPDK API Reference <https://doc.dpdk.org/api/rte__compressdev_8h.html>`_ for details.
 
 Passing source data as mbuf-chain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If input data is scattered across several different buffers, then
-Application can either parse through all such buffers and make one
+the application can either parse through all such buffers and make one
 mbuf-chain and enqueue it for processing or, alternatively, it can
-make multiple sequential enqueue_burst() calls for each of them
-processing them statefully. See *Compression API Stateful Operation*
+make multiple sequential enqueue_burst() calls for each of them,
+processing them statefully. See :ref:`compressdev_stateful_op`:
 for stateful processing of ops.
 
 Operation Status
 ~~~~~~~~~~~~~~~~
-Each operation carries a status information updated by PMD after it is processed.
-Following are currently supported:
+Each operation carries status information updated by the PMD after it is processed.
+The following are currently supported:
 
 - RTE_COMP_OP_STATUS_SUCCESS,
     Operation is successfully completed
@@ -225,22 +226,25 @@ Following are currently supported:
 - RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE,
     Output buffer ran out of space before operation completed, but this
     is not an error case. Output data up to op.produced can be used and
-    next op in the stream should continue on from op.consumed+1.
+    the next op in the stream should continue on from op.consumed+1.
 
 Operation status after enqueue / dequeue
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Some of the above values may arise in the op after an
-``rte_compressdev_enqueue_burst()``. If number ops enqueued < number ops requested then
-the app should check the op.status of nb_enqd+1. If status is RTE_COMP_OP_STATUS_NOT_PROCESSED,
-it likely indicates a full-queue case for a hardware device and a retry after dequeuing some ops is likely
-to be successful. If the op holds any other status, e.g. RTE_COMP_OP_STATUS_INVALID_ARGS, a retry with
+``rte_compressdev_enqueue_burst()``. If the number of ops enqueued < the number of ops requested
+then the app should check the op.status of nb_enqd+1.
+If the status is RTE_COMP_OP_STATUS_NOT_PROCESSED, it likely indicates a full-queue case for a
+hardware device, and a retry after dequeuing some ops is likely to be successful.
+If the op holds any other status, e.g. RTE_COMP_OP_STATUS_INVALID_ARGS, a retry with
 the same op is unlikely to be successful.
 
 
+.. _compressdev_prod_cons_op_status:
+
 Produced, Consumed And Operation Status
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- If status is RTE_COMP_OP_STATUS_SUCCESS,
+- If the status is RTE_COMP_OP_STATUS_SUCCESS,
     consumed = amount of data read from input buffer, and
     produced = amount of data written in destination buffer
 - If status is RTE_COMP_OP_STATUS_ERROR,
@@ -253,37 +257,37 @@ Produced, Consumed And Operation Status
 - If status is RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE,
     consumed = amount of data read, and
     produced = amount of data successfully produced until
-    out of space condition hit. PMD has ability to recover
-    from here, so application can submit next op from
-    consumed+1 and a destination buffer with available space.
+    out of space condition hit. The PMD has ability to recover
+    from here, so an application can submit the next op from
+    consumed+1, and a destination buffer with available space.
 
 Transforms
 ----------
 
 Compression transforms (``rte_comp_xform``) are the mechanism
 to specify the details of the compression operation such as algorithm,
-window size and checksum.
+window size, and checksum.
 
 Compression API Hash support
 ----------------------------
 
-Compression API allows application to enable digest calculation
+The compression API allows an application to enable digest calculation
 alongside compression and decompression of data. A PMD reflects its
 support for hash algorithms via capability algo feature flags.
-If supported, PMD calculates digest always on plaintext i.e.
+If supported, the PMD always calculates the digest on plaintext i.e.
 before compression and after decompression.
 
 Currently supported list of hash algos are SHA-1 and SHA2 family
 SHA256.
 
-See *DPDK API Reference* for details.
+See the `DPDK API Reference <https://doc.dpdk.org/api/rte__compressdev_8h.html>`_ for details.
 
-If required, application should set valid hash algo in compress
+If required, the application should set the valid hash algo in compress
 or decompress xforms during ``rte_compressdev_stream_create()``
-or ``rte_compressdev_private_xform_create()`` and pass a valid
+or ``rte_compressdev_private_xform_create()``, and pass a valid
 output buffer in ``rte_comp_op`` hash field struct to store the
-resulting digest. Buffer passed should be contiguous and large
-enough to store digest which is 20 bytes for SHA-1 and
+resulting digest. The buffer passed should be contiguous and large
+enough to store digest, which is 20 bytes for SHA-1 and
 32 bytes for SHA2-256.
 
 Compression API Stateless operation
@@ -295,20 +299,21 @@ An op is processed stateless if it has
 (required only on compression side),
 - All required input in source buffer
 
-When all of the above conditions are met, PMD initiates stateless processing
+When all of the above conditions are met, the PMD initiates stateless processing
 and releases acquired resources after processing of current operation is
-complete. Application can enqueue multiple stateless ops in a single burst
+complete. The application can enqueue multiple stateless ops in a single burst
 and must attach priv_xform handle to such ops.
 
 priv_xform in Stateless operation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-priv_xform is PMD internally managed private data that it maintains to do stateless processing.
-priv_xforms are initialized provided a generic xform structure by an application via making call
-to ``rte_compressdev_private_xform_create``, at an output PMD returns an opaque priv_xform reference.
-If PMD support SHAREABLE priv_xform indicated via algorithm feature flag, then application can
-attach same priv_xform with many stateless ops at-a-time. If not, then application needs to
-create as many priv_xforms as it expects to have stateless operations in-flight.
+A priv_xform is private data managed internally by the PMD to do stateless processing.
+A priv_xform is initialized by an application providing a generic xform structure
+to ``rte_compressdev_private_xform_create``, which returns an opaque priv_xform reference.
+If the PMD supports SHAREABLE priv_xform, indicated via algorithm feature flag,
+then the application can attach the same priv_xform with many stateless ops at a time.
+If not, then the application needs to create as many priv_xforms as it expects to have
+stateless operations in-flight.
 
 .. figure:: img/stateless-op.*
 
@@ -320,8 +325,9 @@ create as many priv_xforms as it expects to have stateless operations in-flight.
    Stateless Ops using Shareable priv_xform
 
 
-Application should call ``rte_compressdev_private_xform_create()`` and attach to stateless op before
-enqueuing them for processing and free via ``rte_compressdev_private_xform_free()`` during termination.
+The application should call ``rte_compressdev_private_xform_create()`` and attach it to a stateless
+op before enqueuing them for processing and free via ``rte_compressdev_private_xform_free()``
+during termination.
 
 An example pseudocode to setup and process NUM_OPS stateless ops with each of length OP_LEN
 using priv_xform would look like:
@@ -399,75 +405,80 @@ using priv_xform would look like:
 
 
 Stateless and OUT_OF_SPACE
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-OUT_OF_SPACE is a condition when output buffer runs out of space and where PMD
-still has more data to produce. If PMD runs into such condition, then PMD returns
-RTE_COMP_OP_OUT_OF_SPACE_TERMINATED error. In such case, PMD resets itself and can set
+OUT_OF_SPACE is a condition when the output buffer runs out of space and where the PMD
+still has more data to produce. If the PMD runs into such condition, then the PMD returns
+RTE_COMP_OP_OUT_OF_SPACE_TERMINATED error. In such case, the PMD resets itself and can set
 consumed=0 and produced=amount of output it could produce before hitting out_of_space.
-Application would need to resubmit the whole input with a larger output buffer, if it
+The application would need to resubmit the whole input with a larger output buffer, if it
 wants the operation to be completed.
 
 Hash in Stateless
 ~~~~~~~~~~~~~~~~~
-If hash is enabled, digest buffer will contain valid data after op is successfully
+If hash is enabled, the digest buffer will contain valid data after an op is successfully
 processed i.e. dequeued with status = RTE_COMP_OP_STATUS_SUCCESS.
 
 Checksum in Stateless
 ~~~~~~~~~~~~~~~~~~~~~
-If checksum is enabled, checksum will only be available after op is successfully
+If checksum is enabled, checksum will only be available after an op is successfully
 processed i.e. dequeued with status = RTE_COMP_OP_STATUS_SUCCESS.
 
+.. _compressdev_stateful_op:
+
 Compression API Stateful operation
 -----------------------------------
 
-Compression API provide RTE_COMP_FF_STATEFUL_COMPRESSION and
-RTE_COMP_FF_STATEFUL_DECOMPRESSION feature flag for PMD to reflect
+The compression API provides RTE_COMP_FF_STATEFUL_COMPRESSION and
+RTE_COMP_FF_STATEFUL_DECOMPRESSION feature flag for the PMD to reflect
 its support for Stateful operations.
 
-A Stateful operation in DPDK compression means application invokes enqueue
-burst() multiple times to process related chunk of data because
-application broke data into several ops.
+A Stateful operation in DPDK compression means the application invokes enqueue
+burst() multiple times to process a related chunk of data because the
+application broke the data into several ops.
 
-In such case
+In such cases
 - ops are setup with op_type RTE_COMP_OP_STATEFUL,
-- all ops except last set to flush value = RTE_COMP_FLUSH_NONE/SYNC
-and last set to flush value RTE_COMP_FLUSH_FULL/FINAL.
+- all ops except the last are set with flush value = RTE_COMP_FLUSH_NONE/SYNC
+and the last is set with flush value RTE_COMP_FLUSH_FULL/FINAL.
 
-In case of either one or all of the above conditions, PMD initiates
-stateful processing and releases acquired resources after processing
+In case of either one or all of the above conditions, the PMD initiates
+stateful processing and releases acquired resources after processing the
 operation with flush value = RTE_COMP_FLUSH_FULL/FINAL is complete.
-Unlike stateless, application can enqueue only one stateful op from
-a particular stream at a time and must attach stream handle
+Unlike stateless, the application can enqueue only one stateful op from
+a particular stream at a time and must attach a stream handle
 to each op.
 
 Stream in Stateful operation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-`stream` in DPDK compression is a logical entity which identifies related set of ops, say, a one large
-file broken into multiple chunks then file is represented by a stream and each chunk of that file is
-represented by compression op `rte_comp_op`. Whenever application wants a stateful processing of such
-data, then it must get a stream handle via making call to ``rte_compressdev_stream_create()``
-with xform, at an output the target PMD will return an opaque stream handle to application which
-it must attach to all of the ops carrying data of that stream. In stateful processing, every op
-requires previous op data for compression/decompression. A PMD allocates and set up resources such
-as history, states, etc. within a stream, which are maintained during the processing of the related ops.
+A stream in DPDK compression is a logical entity which identifies a related set of ops.
+For example, one large file broken into multiple chunks, then the file is represented by a stream,
+and each chunk of that file is represented by a compression op ``rte_comp_op``.
+Whenever an application wants stateful processing of such data, then it must get a stream handle
+via making call to ``rte_compressdev_stream_create()`` with an xform, which will return an opaque
+stream handle to attach to all of the ops carrying data of that stream.
+In stateful processing, every op requires previous op data for compression/decompression.
+A PMD allocates and sets up resources such as history, states, etc. within a stream,
+which are maintained during the processing of related ops.
 
-Unlike priv_xforms, stream is always a NON_SHAREABLE entity. One stream handle must be attached to only
-one set of related ops and cannot be reused until all of them are processed with status Success or failure.
+Unlike priv_xforms, a stream is always a NON_SHAREABLE entity. One stream handle must be attached
+to only one set of related ops and cannot be reused until all of them are processed with a
+success/failure status.
 
 .. figure:: img/stateful-op.*
 
    Stateful Ops
 
 
-Application should call ``rte_compressdev_stream_create()`` and attach to op before
+An application should call ``rte_compressdev_stream_create()`` and attach it to the op before
 enqueuing them for processing and free via ``rte_compressdev_stream_free()`` during
-termination. All ops that are to be processed statefully should carry *same* stream.
+termination. All ops that are to be processed statefully should carry the *same* stream.
 
-See *DPDK API Reference* document for details.
+See the `DPDK API Reference <https://doc.dpdk.org/api/rte__compressdev_8h.html>`_ for details.
 
-An example pseudocode to set up and process a stream having NUM_CHUNKS with each chunk size of CHUNK_LEN would look like:
+An example pseudocode to set up and process a stream having NUM_CHUNKS,
+with each chunk size of CHUNK_LEN, would look like:
 
 .. code-block:: c
 
@@ -549,64 +560,65 @@ An example pseudocode to set up and process a stream having NUM_CHUNKS with each
 
 
 Stateful and OUT_OF_SPACE
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If PMD supports stateful operation, then OUT_OF_SPACE status is not an actual
-error for the PMD. In such case, PMD returns with status
+If a PMD supports stateful operation, then an OUT_OF_SPACE status is not an actual
+error for the PMD. In such a case, the PMD returns with status
 RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE with consumed = number of input bytes
-read and produced = length of complete output buffer.
-Application should enqueue next op with source starting at consumed+1 and an
+read, and produced = length of complete output buffer.
+The application should enqueue the next op with source starting at consumed+1, and an
 output buffer with available space.
 
 Hash in Stateful
 ~~~~~~~~~~~~~~~~
-If enabled, digest buffer will contain valid digest after last op in stream
+If enabled, the digest buffer will contain valid digest after the last op in a stream
 (having flush = RTE_COMP_FLUSH_FINAL) is successfully processed i.e. dequeued
 with status = RTE_COMP_OP_STATUS_SUCCESS.
 
 Checksum in Stateful
 ~~~~~~~~~~~~~~~~~~~~
-If enabled, checksum will only be available after last op in stream
+If enabled, the checksum will only be available after the last op in a stream
 (having flush = RTE_COMP_FLUSH_FINAL) is successfully processed i.e. dequeued
 with status = RTE_COMP_OP_STATUS_SUCCESS.
 
 Burst in compression API
--------------------------
+------------------------
 
 Scheduling of compression operations on DPDK's application data path is
 performed using a burst oriented asynchronous API set. A queue pair on a compression
-device accepts a burst of compression operations using enqueue burst API. On physical
-devices the enqueue burst API will place the operations to be processed
+device accepts a burst of compression operations using the enqueue burst API.
+On physical devices the enqueue burst API will place the operations to be processed
 on the device's hardware input queue, for virtual devices the processing of the
 operations is usually completed during the enqueue call to the compression
 device. The dequeue burst API will retrieve any processed operations available
 from the queue pair on the compression device, from physical devices this is usually
-directly from the devices processed queue, and for virtual device's from a
+directly from the devices processed queue, and for virtual device's from an
 ``rte_ring`` where processed operations are placed after being processed on the
 enqueue call.
 
-A burst in DPDK compression can be a combination of stateless and stateful operations with a condition
-that for stateful ops only one op at-a-time should be enqueued from a particular stream i.e. no-two ops
-should belong to same stream in a single burst. However a burst may contain multiple stateful ops as long
-as each op is attached to a different stream i.e. a burst can look like:
+A burst in DPDK compression can be a combination of stateless and stateful operations with a
+condition that for stateful ops only one op at a time should be enqueued from a particular stream
+i.e. two ops should never belong to the same stream in a single burst.
+However, a burst may contain multiple stateful ops, as long as each op is attached to a different
+stream, i.e. a burst can look like:
 
 +---------------+--------------+--------------+-----------------+--------------+--------------+
 | enqueue_burst | op1.no_flush | op2.no_flush | op3.flush_final | op4.no_flush | op5.no_flush |
 +---------------+--------------+--------------+-----------------+--------------+--------------+
 
-Where, op1 .. op5 all belong to different independent data units. op1, op2, op4, op5 must be stateful
-as stateless ops can only use flush full or final and op3 can be of type stateless or stateful.
-Every op with type set to RTE_COMP_OP_STATELESS must be attached to priv_xform and
-Every op with type set to RTE_COMP_OP_STATEFUL *must* be attached to stream.
+Where, op1 .. op5 all belong to different independent data units. op1, op2, op4, op5 must be
+stateful as stateless ops can only use flush full or final and op3 can be of type stateless or
+stateful. Every op with type set to RTE_COMP_OP_STATELESS must be attached to priv_xform and
+every op with type set to RTE_COMP_OP_STATEFUL *must* be attached to stream.
 
 Since each operation in a burst is independent and thus can be completed
-out-of-order, applications which need ordering, should setup per-op user data
-area with reordering information so that it can determine enqueue order at
+out of order, applications which need ordering should setup a per-op user data
+area, with reordering information so that it can determine enqueue order at
 dequeue.
 
-Also if multiple threads calls enqueue_burst() on same queue pair then it’s
-application onus to use proper locking mechanism to ensure exclusive enqueuing
-of operations.
+Also, if multiple threads calls enqueue_burst() on the same queue pair then it's
+the application's responsibility to use a proper locking mechanism to ensure
+exclusive enqueuing of operations.
 
 Enqueue / Dequeue Burst APIs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -629,9 +641,10 @@ Sample code
 -----------
 
 There are unit test applications that show how to use the compressdev library inside
-app/test/test_compressdev.c
+``app/test/test_compressdev.c``
 
 Compression Device API
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The compressdev Library API is described in the *DPDK API Reference* document.
+The compressdev Library API is described in the
+`DPDK API Reference <https://doc.dpdk.org/api/rte__compressdev_8h.html>`_.
-- 
2.35.1

---
  Diff of the applied patch vs upstream commit (please double-check if non-empty:
---
--- -	2022-07-20 15:01:01.222998600 +0800
+++ 0052-doc-fix-grammar-and-formatting-in-compressdev-guide.patch	2022-07-20 15:00:58.791000367 +0800
@@ -1 +1 @@
-From 4c9484373fcd0aa4a240fdb2e797269eb2f26b9b Mon Sep 17 00:00:00 2001
+From 92962694e870727efa84358a3323c58ee1c2d8a0 Mon Sep 17 00:00:00 2001
@@ -4,0 +5,3 @@
+Cc: Xueming Li <xuemingl@nvidia.com>
+
+[ upstream commit 4c9484373fcd0aa4a240fdb2e797269eb2f26b9b ]
@@ -12 +14,0 @@
-Cc: stable@dpdk.org

  parent reply	other threads:[~2022-07-20  8:26 UTC|newest]

Thread overview: 180+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-06-21  8:01 patch " Xueming Li
2022-06-21  8:01 ` patch 'crypto/ipsec_mb: fix length and offset settings' " Xueming Li
2022-06-21  8:01 ` patch 'crypto/ipsec_mb: fix GMAC parameters setting' " Xueming Li
2022-06-21  8:01 ` patch 'eal/windows: fix data race when creating threads' " Xueming Li
2022-06-21  8:01 ` patch 'eal/windows: add missing C++ include guards' " Xueming Li
2022-06-21  8:01 ` patch 'examples/bond: fix invalid use of trylock' " Xueming Li
2022-06-21  8:01 ` patch 'net/iavf: fix HW ring scan method selection' " Xueming Li
2022-06-21  8:01 ` patch 'net/i40e: populate error in flow director parser' " Xueming Li
2022-06-21  8:01 ` patch 'net/netvsc: fix calculation of checksums based on mbuf flag' " Xueming Li
2022-06-21  8:01 ` patch 'net/mlx5: fix Tx when inlining is impossible' " Xueming Li
2022-06-21  8:01 ` patch 'net/mlx5: fix GTP handling in header modify action' " Xueming Li
2022-06-21  8:01 ` patch 'net/mlx5: fix Rx/Tx stats concurrency' " Xueming Li
2022-06-21  8:01 ` patch 'test/table: fix buffer overflow on lpm entry' " Xueming Li
2022-06-21  8:01 ` patch 'mem: skip attaching external memory in secondary process' " Xueming Li
2022-06-21  8:01 ` patch 'eal: fix C++ include for device event and DMA' " Xueming Li
2022-06-21  8:01 ` patch 'crypto/dpaa_sec: fix digest size' " Xueming Li
2022-06-21  8:01 ` patch 'crypto/dpaa2_sec: fix fle buffer leak' " Xueming Li
2022-06-21  8:01 ` patch 'crypto/dpaa2_sec: fix buffer pool ID check' " Xueming Li
2022-06-21  8:01 ` patch 'crypto/dpaa_sec: fix secondary process probing' " Xueming Li
2022-06-21  8:01 ` patch 'crypto/dpaa2_sec: fix operation status for simple FD' " Xueming Li
2022-06-21  8:01 ` patch 'common/dpaax: fix short MAC-I IV calculation for ZUC' " Xueming Li
2022-06-21  8:01 ` patch 'examples/l2fwd-crypto: fix stats refresh rate' " Xueming Li
2022-06-21  8:01 ` patch 'test/hash: report non HTM numbers for single thread' " Xueming Li
2022-06-21  8:01 ` patch 'net/nfp: remove unneeded header inclusion' " Xueming Li
2022-06-21  8:01 ` patch 'net/bonding: fix RSS key config with extended key length' " Xueming Li
2022-06-21  8:01 ` patch 'net/cxgbe: fix port ID in Rx mbuf' " Xueming Li
2022-06-21  8:01 ` patch 'net/cxgbe: fix Tx queue stuck with mbuf chain coalescing' " Xueming Li
2022-06-21  8:01 ` patch 'net/vhost: fix access to freed memory' " Xueming Li
2022-06-21  8:01 ` patch 'net/virtio: restore some optimisations with AVX512' " Xueming Li
2022-06-21  8:01 ` patch 'net/vhost: fix TSO feature default disablement' " Xueming Li
2022-06-21  8:01 ` patch 'vhost: fix missing virtqueue lock protection' " Xueming Li
2022-06-21  8:01 ` patch 'vdpa/mlx5: fix interrupt trash that leads to crash' " Xueming Li
2022-06-21  8:01 ` patch 'vdpa/mlx5: fix dead loop when process interrupted' " Xueming Li
2022-06-21  8:01 ` patch 'net/dpaa: fix event queue detach' " Xueming Li
2022-06-21  8:01 ` patch 'doc: update matching versions in ice guide' " Xueming Li
2022-06-21  8:01 ` patch 'net/bonding: fix stopping non-active slaves' " Xueming Li
2022-06-21  8:01 ` patch 'net/bonding: fix slave stop and remove on port close' " Xueming Li
2022-06-21  8:01 ` patch 'net/hns3: fix RSS disable' " Xueming Li
2022-06-21  8:01 ` patch 'net/hns3: fix rollback on RSS hash update' " Xueming Li
2022-06-21  8:01 ` patch 'net/hns3: remove redundant RSS tuple field' " Xueming Li
2022-06-21  8:01 ` patch 'net/hns3: remove unnecessary RSS switch' " Xueming Li
2022-06-21  8:01 ` patch 'app/testpmd: check statistics query before printing' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: fix reordering in NEON Rx' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: remove unused macro' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: fix device capability reporting' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: fix Rx configuration' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: fix ring group on Rx restart' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: avoid unnecessary endianness conversion' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: fix speed autonegotiation' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: force PHY update on certain configurations' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: fix link status when port is stopped' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: recheck FW readiness if in reset process' " Xueming Li
2022-06-21  8:01 ` patch 'net/bnxt: fix freeing VNIC filters' " Xueming Li
2022-06-21  8:01 ` patch 'eal/x86: fix unaligned access for small memcpy' " Xueming Li
2022-06-21  8:02 ` patch 'examples/l3fwd: fix scalar LPM' " Xueming Li
2022-06-21  8:02 ` patch 'test/ring: remove excessive inlining' " Xueming Li
2022-06-21  8:02 ` patch 'eal/freebsd: fix use of newer cpuset macros' " Xueming Li
2022-06-21  8:02 ` patch 'test: avoid hang if queues are full and Tx fails' " Xueming Li
2022-06-21  8:02 ` patch 'acl: fix rules with 8-byte field size' " Xueming Li
2022-06-21  8:02 ` patch 'rib: fix traversal with /32 route' " Xueming Li
2022-06-21  8:02 ` patch 'mbuf: dump outer VLAN' " Xueming Li
2022-06-21  8:02 ` patch 'doc: fix API index Markdown syntax' " Xueming Li
2022-06-21  8:02 ` patch 'devtools: fix null test for NUMA systems' " Xueming Li
2022-06-21  8:02 ` patch 'examples/ipsec-secgw: fix uninitialized memory access' " Xueming Li
2022-06-21  8:02 ` patch 'examples/ipsec-secgw: fix promiscuous mode option' " Xueming Li
2022-06-21  8:02 ` patch 'test/crypto: fix null check for ZUC authentication' " Xueming Li
2022-06-21  8:02 ` patch 'drivers/crypto: fix warnings for OpenSSL version' " Xueming Li
2022-06-21  8:02 ` patch 'doc: add missing auth algo for IPsec example' " Xueming Li
2022-06-21  8:02 ` patch 'app/testpmd: perform SW IP checksum for GRO/GSO packets' " Xueming Li
2022-06-21  8:02 ` patch 'app/testpmd: remove useless pointer checks' " Xueming Li
2022-06-21  8:02 ` patch 'ethdev: clarify null location case in xstats get' " Xueming Li
2022-06-21  8:02 ` patch 'net/hns3: fix xstats get return if xstats is null' " Xueming Li
2022-06-21  8:02 ` patch 'net/ipn3ke: " Xueming Li
2022-06-21  8:02 ` patch 'net/mvpp2: " Xueming Li
2022-06-21  8:02 ` patch 'net/axgbe: " Xueming Li
2022-06-21  8:02 ` patch 'ethdev: fix memory leak in xstats telemetry' " Xueming Li
2022-06-21  8:02 ` patch 'ethdev: fix possible null pointer access' " Xueming Li
2022-06-21  8:02 ` patch 'app/testpmd: replace hardcoded min mbuf number with macro' " Xueming Li
2022-06-21  8:02 ` patch 'app/testpmd: fix metering and policing command for RFC4115' " Xueming Li
2022-06-21  8:02 ` patch 'ethdev: prohibit polling stopped queue' " Xueming Li
2022-06-21  8:02 ` patch 'app/testpmd: do not poll stopped queues' " Xueming Li
2022-06-21  8:02 ` patch 'net/bonding: fix mbuf fast free usage' " Xueming Li
2022-06-21  8:02 ` patch 'net/memif: fix overwriting of head segment' " Xueming Li
2022-06-21  8:02 ` patch 'ethdev: fix port state when stop' " Xueming Li
2022-06-21  8:02 ` patch 'net/txgbe: fix max number of queues for SR-IOV' " Xueming Li
2022-06-21  8:02 ` patch 'net/nfp: fix disabling VLAN stripping' " Xueming Li
2022-06-21  8:02 ` patch 'ethdev: fix port close in secondary process' " Xueming Li
2022-06-21  8:02 ` patch 'net/bnxt: fix compatibility with some old firmwares' " Xueming Li
2022-06-21  8:02 ` patch 'doc: fix vhost multi-queue reconnection' " Xueming Li
2022-06-21  8:02 ` patch 'vhost: fix deadlock when message handling failed' " Xueming Li
2022-06-21  8:02 ` patch 'examples/vhost: fix crash when no VMDq' " Xueming Li
2022-06-21  8:02 ` patch 'net/mlx5: fix Tx recovery' " Xueming Li
2022-06-21  8:02 ` patch 'kni: fix build with Linux 5.18' " Xueming Li
2022-06-21  8:02 ` patch 'net/iavf: fix data path selection' " Xueming Li
2022-06-21  8:02 ` patch 'net/ixgbe: add option for link up check on pin SDP3' " Xueming Li
2022-06-21  8:02 ` patch 'net/ice/base: fix getting sched node from ID type' " Xueming Li
2022-06-21  8:02 ` patch 'net/ice: fix MTU info for DCF' " Xueming Li
2022-06-21  8:02 ` patch 'net/i40e: fix max frame size config at port level' " Xueming Li
2022-06-21  8:02 ` patch 'net/iavf: fix queue start exception handling' " Xueming Li
2022-06-21  8:02 ` patch 'net/iavf: fix mbuf release in multi-process' " Xueming Li
2022-06-21  8:02 ` patch 'net/iavf: fix Rx queue interrupt setting' " Xueming Li
2022-06-21  8:02 ` patch 'doc: update matching versions in i40e guide' " Xueming Li
2022-06-21  8:02 ` patch 'net/ice: fix outer L4 checksum in scalar Rx' " Xueming Li
2022-06-21  8:02 ` patch 'net/iavf: increase reset complete wait count' " Xueming Li
2022-06-21  8:02 ` patch 'examples/dma: fix Tx drop statistics' " Xueming Li
2022-06-21  8:02 ` patch 'raw/ifpga: unregister interrupt on close' " Xueming Li
2022-06-21  8:02 ` patch 'bus/fslmc: fix VFIO setup' " Xueming Li
2022-06-21  8:02 ` patch 'doc: fix formatting and link in BPF library guide' " Xueming Li
2022-06-21  8:02 ` patch 'app/testpmd: fix packet segment allocation' " Xueming Li
2022-06-21  8:02 ` patch 'app/testpmd: fix multicast address pool leak' " Xueming Li
2022-06-21  8:02 ` patch 'kni: use dedicated function to set random MAC address' " Xueming Li
2022-06-21  8:02 ` patch 'kni: use dedicated function to set " Xueming Li
2022-06-21  8:02 ` patch 'raw/ifpga: remove virtual devices on close' " Xueming Li
2022-06-21  8:02 ` patch 'vhost: fix async access' " Xueming Li
2022-06-21  8:03 ` patch 'net/bnxt: fix tunnel stateless offloads' " Xueming Li
2022-06-21  8:03 ` patch 'net/mlx5: fix RSS hash types adjustment' " Xueming Li
2022-07-20  8:20 ` patch 'vdpa/ifc: fix build with GCC 12' " Xueming Li
2022-07-20  8:20   ` patch 'app/flow-perf: " Xueming Li
2022-07-20  8:20   ` patch 'trace: fix init with long file prefix' " Xueming Li
2022-07-20  8:20   ` patch 'eal/x86: drop export of internal alignment macro' " Xueming Li
2022-07-20  8:20   ` patch 'baseband/acc100: update companion PF configure function' " Xueming Li
2022-07-20  8:20   ` patch 'baseband/acc100: add protection for some negative scenario' " Xueming Li
2022-07-20  8:20   ` patch 'baseband/acc100: remove RTE prefix for internal macros' " Xueming Li
2022-07-20  8:20   ` patch 'common/cpt: fix build with GCC 12' " Xueming Li
2022-07-20  8:20   ` patch 'test/ipsec: " Xueming Li
2022-07-20  8:20   ` patch 'crypto/scheduler: fix queue pair in scheduler failover' " Xueming Li
2022-07-20  8:20   ` patch 'test/crypto: fix cipher offset for ZUC' " Xueming Li
2022-07-20  8:20   ` patch 'test/ipsec: fix performance test' " Xueming Li
2022-07-20  8:20   ` patch 'eventdev/eth_tx: fix adapter creation' " Xueming Li
2022-07-20  8:20   ` patch 'net/bonding: fix RSS inconsistency between ports' " Xueming Li
2022-07-20  8:20   ` patch 'test/bonding: fix RSS test when disable RSS' " Xueming Li
2022-07-20  8:20   ` patch 'net/hns3: fix an unreasonable memset' " Xueming Li
2022-07-20  8:20   ` patch 'net/hns3: remove duplicate definition' " Xueming Li
2022-07-20  8:20   ` patch 'net/hns3: fix return value for unsupported tuple' " Xueming Li
2022-07-20  8:20   ` patch 'app/testpmd: fix bonding slave devices not released' " Xueming Li
2022-07-20  8:20   ` patch 'net/txgbe: fix register polling' " Xueming Li
2022-07-20  8:20   ` patch 'app/testpmd: revert MAC update in checksum forwarding' " Xueming Li
2022-07-20  8:20   ` patch 'vhost: fix missing enqueue pseudo-header calculation' " Xueming Li
2022-07-20  8:20   ` patch 'vhost/crypto: fix build with GCC 12' " Xueming Li
2022-07-20  8:20   ` patch 'vhost/crypto: fix descriptor processing' " Xueming Li
2022-07-20  8:20   ` patch 'malloc: fix allocation of almost hugepage size' " Xueming Li
2022-07-20  8:20   ` patch 'config: fix C++ cross compiler for Arm and PPC' " Xueming Li
2022-07-20  8:20   ` patch 'ci: enable C++ check " Xueming Li
2022-07-20  8:20   ` patch 'net/octeontx: fix port close' " Xueming Li
2022-07-20  8:20   ` patch 'net/qede: fix build with GCC 13' " Xueming Li
2022-07-20  8:20   ` patch 'net/ice/base: fix build with GCC 12' " Xueming Li
2022-07-20  8:21   ` patch 'net/qede: " Xueming Li
2022-07-20  8:21   ` patch 'net/mlx5: fix build with clang 14' " Xueming Li
2022-07-20  8:21   ` patch 'net/mlx5: fix RSS expansion for patterns with ICMP item' " Xueming Li
2022-07-20  8:21   ` patch 'net/mlx5: fix stack buffer overflow in drop action' " Xueming Li
2022-07-20  8:21   ` patch 'raw/ioat: fix build when ioat dmadev enabled' " Xueming Li
2022-07-20  8:21   ` patch 'rib: fix references for IPv6 implementation' " Xueming Li
2022-07-20  8:21   ` patch 'test/hash: fix out of bound access' " Xueming Li
2022-07-20  8:21   ` patch 'app/procinfo: show all non-owned ports' " Xueming Li
2022-07-20  8:21   ` patch 'test: check memory allocation for CRC' " Xueming Li
2022-07-20  8:21   ` patch 'net/hns3: fix descriptors check with SVE' " Xueming Li
2022-07-20  8:21   ` patch 'examples/distributor: fix distributor on Rx core' " Xueming Li
2022-07-20  8:21   ` patch 'doc: add more instructions for running as non-root' " Xueming Li
2022-08-01 12:21     ` Dmitry Kozlyuk
2022-07-20  8:21   ` patch 'net/bnxt: fix switch domain allocation' " Xueming Li
2022-07-20  8:21   ` patch 'net/bnxt: allow Tx only or Rx only' " Xueming Li
2022-07-20  8:21   ` patch 'net/bnxt: fix setting forced speed' " Xueming Li
2022-07-20  8:21   ` patch 'test/crypto: fix authentication IV for ZUC SGL' " Xueming Li
2022-07-20  8:21   ` patch 'test/crypto: fix ZUC vector IV format' " Xueming Li
2022-07-20  8:21   ` patch 'test/crypto: fix SNOW3G " Xueming Li
2022-07-20  8:21   ` patch 'baseband/acc100: remove prefix of internal file' " Xueming Li
2022-07-20  8:21   ` patch 'examples/fips_validation: handle empty payload' " Xueming Li
2022-07-20  8:21   ` patch 'crypto/qat: fix DOCSIS crash' " Xueming Li
2022-07-20  8:21   ` Xueming Li [this message]
2022-07-20  8:21   ` patch 'doc: fix grammar and parameters in l2fwd-crypto guide' " Xueming Li
2022-07-20  8:21   ` patch 'eventdev/eth_tx: fix queue delete' " Xueming Li
2022-07-20  8:21   ` patch 'app/testpmd: fix supported RSS offload display' " Xueming Li
2022-07-20  8:21   ` patch 'net/netvsc: fix vmbus device reference in multi-process' " Xueming Li
2022-07-20  8:21   ` patch 'doc: fix readability in vhost guide' " Xueming Li
2022-07-20  8:21   ` patch 'net/vhost: fix deadlock on vring state change' " Xueming Li
2022-07-20  8:21   ` patch 'vhost: add some trailing newline in log messages' " Xueming Li
2022-07-20  8:21   ` patch 'net/igc: support multi-process' " Xueming Li
2022-07-20  8:21   ` patch 'service: fix lingering active status' " Xueming Li
2022-07-20  8:21   ` patch 'gro: fix identifying fragmented packets' " Xueming Li
2022-07-20  8:21   ` patch 'examples/link_status_interrupt: fix stats refresh rate' " Xueming Li

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220720082132.3954126-52-xuemingl@nvidia.com \
    --to=xuemingl@nvidia.com \
    --cc=ciara.power@intel.com \
    --cc=roy.fan.zhang@intel.com \
    --cc=stable@dpdk.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).