* [PATCH v2 1/1] doc: update to include bbdev snippet using literalinclude
2022-10-12 18:16 [PATCH v2 0/1] doc: update to include bbdev snippet using literalinclude Nicolas Chautru
@ 2022-10-12 18:16 ` Nicolas Chautru
2022-10-27 14:23 ` [EXT] " Akhil Goyal
0 siblings, 1 reply; 3+ messages in thread
From: Nicolas Chautru @ 2022-10-12 18:16 UTC (permalink / raw)
To: dev, gakhil; +Cc: 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
^ permalink raw reply [flat|nested] 3+ messages in thread