[PATCH v2 0/1] doc: update to include bbdev snippet using literalinclude

[PATCH v2 0/1] doc: update to include bbdev snippet using literalinclude

[Nicolas Chautru]

v2: Rebased to latest to avoid git am failure when applying.
v1: Update to include bbdev snippet using literalinclude.

Nicolas Chautru (1):
  doc: update to include bbdev snippet using literalinclude

 doc/guides/prog_guide/bbdev.rst | 105 +++++++-------------------------
 lib/bbdev/rte_bbdev_op.h        |  15 +++++
 2 files changed, 38 insertions(+), 82 deletions(-)

-- 
2.37.1

[PATCH v2 1/1] doc: update to include bbdev snippet using literalinclude

[Nicolas Chautru]

Adding code snippet using literalinclude so that to keep
automatically these structures in doc in sync with the
bbdev source code.

Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>
---
 doc/guides/prog_guide/bbdev.rst | 105 +++++++-------------------------
 lib/bbdev/rte_bbdev_op.h        |  15 +++++
 2 files changed, 38 insertions(+), 82 deletions(-)

diff --git a/doc/guides/prog_guide/bbdev.rst b/doc/guides/prog_guide/bbdev.rst
index 72d14a8aeb..549f1d002a 100644
--- a/doc/guides/prog_guide/bbdev.rst
+++ b/doc/guides/prog_guide/bbdev.rst
@@ -510,20 +510,10 @@ This structure has three elements:
 BBDEV Turbo Encode Operation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: c
-
-    struct rte_bbdev_op_turbo_enc {
-        struct rte_bbdev_op_data input;
-        struct rte_bbdev_op_data output;
-
-        uint32_t op_flags;
-        uint8_t rv_index;
-        uint8_t code_block_mode;
-        union {
-            struct rte_bbdev_op_enc_cb_params cb_params;
-            struct rte_bbdev_op_enc_tb_params tb_params;
-        };
-    };
+.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h
+   :language: c
+   :start-after: Structure rte_bbdev_op_turbo_enc 8<
+   :end-before: >8 End of structure rte_bbdev_op_turbo_enc.
 
 The Turbo encode structure includes the ``input`` and ``output`` mbuf
 data pointers. The provided mbuf pointer of ``input`` needs to be big
@@ -606,26 +596,10 @@ TB-mode. CB-mode is a reduced version, where only one CB exists:
 BBDEV Turbo Decode Operation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: c
-
-    struct rte_bbdev_op_turbo_dec {
-        struct rte_bbdev_op_data input;
-        struct rte_bbdev_op_data hard_output;
-        struct rte_bbdev_op_data soft_output;
-
-        uint32_t op_flags;
-        uint8_t rv_index;
-        uint8_t iter_min:4;
-        uint8_t iter_max:4;
-        uint8_t iter_count;
-        uint8_t ext_scale;
-        uint8_t num_maps;
-        uint8_t code_block_mode;
-        union {
-            struct rte_bbdev_op_dec_cb_params cb_params;
-            struct rte_bbdev_op_dec_tb_params tb_params;
-        };
-    };
+.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h
+   :language: c
+   :start-after: Structure rte_bbdev_op_turbo_dec 8<
+   :end-before: >8 End of structure rte_bbdev_op_turbo_dec.
 
 The Turbo decode structure includes the ``input``, ``hard_output`` and
 optionally the ``soft_output`` mbuf data pointers.
@@ -751,26 +725,10 @@ given below.
 The structure passed for each LDPC encode operation is given below,
 with the operation flags forming a bitmask in the ``op_flags`` field.
 
-.. code-block:: c
-
-    struct rte_bbdev_op_ldpc_enc {
-
-        struct rte_bbdev_op_data input;
-        struct rte_bbdev_op_data output;
-
-        uint32_t op_flags;
-        uint8_t rv_index;
-        uint8_t basegraph;
-        uint16_t z_c;
-        uint16_t n_cb;
-        uint8_t q_m;
-        uint16_t n_filler;
-        uint8_t code_block_mode;
-        union {
-            struct rte_bbdev_op_enc_ldpc_cb_params cb_params;
-            struct rte_bbdev_op_enc_ldpc_tb_params tb_params;
-        };
-    };
+.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h
+   :language: c
+   :start-after: Structure rte_bbdev_op_ldpc_enc 8<
+   :end-before: >8 End of structure rte_bbdev_op_ldpc_enc.
 
 The LDPC encode parameters are set out in the table below.
 
@@ -949,33 +907,10 @@ given below.
 The structure passed for each LDPC decode operation is given below,
 with the operation flags forming a bitmask in the ``op_flags`` field.
 
-.. code-block:: c
-
-
-    struct rte_bbdev_op_ldpc_dec {
-
-        struct rte_bbdev_op_data input;
-        struct rte_bbdev_op_data hard_output;
-        struct rte_bbdev_op_data soft_output;
-        struct rte_bbdev_op_data harq_combined_input;
-        struct rte_bbdev_op_data harq_combined_output;
-
-        uint32_t op_flags;
-        uint8_t rv_index;
-        uint8_t basegraph;
-        uint16_t z_c;
-        uint16_t n_cb;
-        uint8_t q_m;
-        uint16_t n_filler;
-        uint8_t iter_max;
-        uint8_t iter_count;
-        uint8_t code_block_mode;
-        union {
-            struct rte_bbdev_op_dec_ldpc_cb_params cb_params;
-            struct rte_bbdev_op_dec_ldpc_tb_params tb_params;
-        };
-    };
-
+.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h
+   :language: c
+   :start-after: Structure rte_bbdev_op_ldpc_dec 8<
+   :end-before: >8 End of structure rte_bbdev_op_ldpc_dec.
 
 The LDPC decode parameters are set out in the table below.
 
@@ -1137,12 +1072,18 @@ A flexible number of Rx antennas are being processed in parallel with the same c
 The API allows more generally for flexibility in what the PMD may support (capability flags) and
 flexibility to adjust some of the parameters of the processing.
 
-The operation/capability flags that can be set for each FFT operation are given below.
+The structure passed for each FFT operation is given below,
+with the operation flags forming a bitmask in the ``op_flags`` field.
 
   **NOTE:** The actual operation flags that may be used with a specific
   bbdev PMD are dependent on the driver capabilities as reported via
   ``rte_bbdev_info_get()``, and may be a subset of those below.
 
+.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h
+   :language: c
+   :start-after: Structure rte_bbdev_op_fft 8<
+   :end-before: >8 End of structure rte_bbdev_op_fft.
+
 +--------------------------------------------------------------------+
 |Description of FFT capability flags                                 |
 +====================================================================+
diff --git a/lib/bbdev/rte_bbdev_op.h b/lib/bbdev/rte_bbdev_op.h
index 6dfef9b49f..2b6ffb80fe 100644
--- a/lib/bbdev/rte_bbdev_op.h
+++ b/lib/bbdev/rte_bbdev_op.h
@@ -403,6 +403,8 @@ struct rte_bbdev_op_dec_ldpc_tb_params {
  * The output mbuf data structure is expected to be allocated by the
  * application with enough room for the output data.
  */
+
+/* Structure rte_bbdev_op_turbo_dec 8< */
 struct rte_bbdev_op_turbo_dec {
 	/** The Virtual Circular Buffer, wk, size 3*Kpi for each CB */
 	struct rte_bbdev_op_data input;
@@ -446,6 +448,7 @@ struct rte_bbdev_op_turbo_dec {
 		struct rte_bbdev_op_dec_turbo_tb_params tb_params;
 	};
 };
+/* >8 End of structure rte_bbdev_op_turbo_dec. */
 
 /** Operation structure for LDPC decode.
  *
@@ -476,6 +479,8 @@ struct rte_bbdev_op_turbo_dec {
  * The output mbuf data structure is expected to be allocated by the
  * application with enough room for the output data.
  */
+
+/* Structure rte_bbdev_op_ldpc_dec 8< */
 struct rte_bbdev_op_ldpc_dec {
 	/** The Virtual Circular Buffer for this code block, one LLR
 	 * per bit of the original CB.
@@ -536,6 +541,7 @@ struct rte_bbdev_op_ldpc_dec {
 		struct rte_bbdev_op_dec_ldpc_tb_params tb_params;
 	};
 };
+/* >8 End of structure rte_bbdev_op_ldpc_dec. */
 
 /** Turbo encode code block parameters */
 struct rte_bbdev_op_enc_turbo_cb_params {
@@ -644,6 +650,8 @@ struct rte_bbdev_op_enc_ldpc_tb_params {
  * The output mbuf data structure is expected to be allocated by the
  * application with enough room for the output data.
  */
+
+/* Structure rte_bbdev_op_turbo_enc 8< */
 struct rte_bbdev_op_turbo_enc {
 	/** The input CB or TB data */
 	struct rte_bbdev_op_data input;
@@ -663,6 +671,7 @@ struct rte_bbdev_op_turbo_enc {
 		struct rte_bbdev_op_enc_turbo_tb_params tb_params;
 	};
 };
+/* >8 End of structure rte_bbdev_op_turbo_enc. */
 
 /** Operation structure for LDPC encode.
  * An operation can be performed on one CB at a time "CB-mode".
@@ -677,6 +686,8 @@ struct rte_bbdev_op_turbo_enc {
  * The output mbuf data structure is expected to be allocated by the
  * application with enough room for the output data.
  */
+
+/* Structure rte_bbdev_op_ldpc_enc 8< */
 struct rte_bbdev_op_ldpc_enc {
 	/** The input TB or CB data */
 	struct rte_bbdev_op_data input;
@@ -717,6 +728,7 @@ struct rte_bbdev_op_ldpc_enc {
 		struct rte_bbdev_op_enc_ldpc_tb_params tb_params;
 	};
 };
+/* >8 End of structure rte_bbdev_op_ldpc_enc. */
 
 /** Operation structure for FFT processing.
  *
@@ -726,6 +738,8 @@ struct rte_bbdev_op_ldpc_enc {
  * The output mbuf data structure is expected to be allocated by the
  * application with enough room for the output data.
  */
+
+/* Structure rte_bbdev_op_fft 8< */
 struct rte_bbdev_op_fft {
 	/** Input data starting from first antenna. */
 	struct rte_bbdev_op_data base_input;
@@ -766,6 +780,7 @@ struct rte_bbdev_op_fft {
 	/** Adjust the FP6 exponent for INT<->FP16 conversion. */
 	uint16_t fp16_exp_adjust;
 };
+/* >8 End of structure rte_bbdev_op_fft. */
 
 /** List of the capabilities for the Turbo Decoder */
 struct rte_bbdev_op_cap_turbo_dec {
-- 
2.37.1

RE: [EXT] [PATCH v2 1/1] doc: update to include bbdev snippet using literalinclude

[Akhil Goyal]

> Adding code snippet using literalinclude so that to keep
> automatically these structures in doc in sync with the
> bbdev source code.
> 
> Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>
Applied to dpdk-next-crypto

Thanks.