diff mbox series

[v1] doc: update to include bbdev snippet using literalinclude

Message ID 20221001011547.49459-1-nicolas.chautru@intel.com (mailing list archive)
State Superseded, archived
Delegated to: akhil goyal
Headers show
Series [v1] doc: update to include bbdev snippet using literalinclude | expand

Checks

Context Check Description
ci/iol-testing warning apply patch failure
ci/checkpatch success coding style OK

Commit Message

Nicolas Chautru Oct. 1, 2022, 1:15 a.m. UTC
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 mbox series

Patch

diff --git a/doc/guides/prog_guide/bbdev.rst b/doc/guides/prog_guide/bbdev.rst
index 0149a99198..7b95d72524 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.
 
@@ -1135,12 +1070,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 c0940ce085..05fe814ffc 100644
--- a/lib/bbdev/rte_bbdev_op.h
+++ b/lib/bbdev/rte_bbdev_op.h
@@ -402,6 +402,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;
@@ -445,6 +447,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.
  *
@@ -475,6 +478,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.
@@ -535,6 +540,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 {
@@ -643,6 +649,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;
@@ -662,6 +670,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".
@@ -676,6 +685,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;
@@ -716,6 +727,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.
  *
@@ -725,6 +737,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;
@@ -765,6 +779,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 {