[PATCH v1 0/1] doc: bbdev device discovery clarification

[PATCH v1 0/1] doc: bbdev device discovery clarification

[Nicolas Chautru]

Adding more information in bbdev documentation related to the
bbdev device discovery from info_get which was not very verbose so far.
Notably for FEC and FFT operations which have extra parameters to
manage different implementation variants.

Also use code snippet to refer to info structure and keep the doc
in sync moving forward.

This is on top of this serie
https://patches.dpdk.org/project/dpdk/list/?series=29744

Nicolas Chautru (1):
  doc: bbdev device discovery clarification

 doc/guides/prog_guide/bbdev.rst | 60 ++++++++++++++++++++++++++++-----
 lib/bbdev/rte_bbdev.h           |  6 ++++
 2 files changed, 57 insertions(+), 9 deletions(-)

-- 
2.34.1

[PATCH v1 1/1] doc: bbdev device discovery clarification

[Nicolas Chautru]

Adding more context and information related the data exposed
through device discovery notably for FEC and FFT operations.

Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>
---
 doc/guides/prog_guide/bbdev.rst | 60 ++++++++++++++++++++++++++++-----
 lib/bbdev/rte_bbdev.h           |  6 ++++
 2 files changed, 57 insertions(+), 9 deletions(-)

diff --git a/doc/guides/prog_guide/bbdev.rst b/doc/guides/prog_guide/bbdev.rst
index c43e478eda..01a8a6d79b 100644
--- a/doc/guides/prog_guide/bbdev.rst
+++ b/doc/guides/prog_guide/bbdev.rst
@@ -261,16 +261,58 @@ information:
   structure, this is where capabilities reside along with other specifics like:
   maximum queue sizes and priority level.
 
-.. code-block:: c
+.. literalinclude:: ../../../lib/bbdev/rte_bbdev.h
+   :language: c
+   :start-after: Structure rte_bbdev_driver_info 8<
+   :end-before: >8 End of structure rte_bbdev_driver_info.
 
-    struct rte_bbdev_info {
-        int socket_id;
-        const char *dev_name;
-        const struct rte_device *device;
-        uint16_t num_queues;
-        bool started;
-        struct rte_bbdev_driver_info drv;
-    };
+.. literalinclude:: ../../../lib/bbdev/rte_bbdev.h
+   :language: c
+   :start-after: Structure rte_bbdev_info 8<
+   :end-before: >8 End of structure rte_bbdev_info.
+
+Capabilities details for LDPC Decoder
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On top of the ``RTE_BBDEV_LDPC_<*>`` capabilities the device also exposes the LLR numerical
+representation expected by the decoder as a fractional fixed-point representation.
+For instance, when the representation (``llr_size``, ``llr_decimals``) = (8, 2) respectively,
+this means that each input LLR in the data provided by the application must be computed as 8 total
+bits (including sign bit) where 2 of these are fractions bits (also referred to as S8.2 format).
+It is up to the user application during LLR generation to scale the LLR according to this
+optimal numerical representation. Any mis-scaled LLR would cause wireless performance degradation.
+
+The ``harq_buffer_size`` exposes the amount of dedicated DDR made available for the device operation.
+This is specific for accelerator non-integrated on the CPU (separate PCIe device) which may
+include separate on-card memory.
+
+Capabilities details for FFT function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The total number of distinct time windows supported for the post-FFT point-wise multiplication is
+exposed as ``fft_windows_num``. The ``window_index`` provided for each cyclic shift in each
+``rte_bbdev_op_fft`` operation is expected to be limited to that size.
+
+The information related to the width of each of these pre-configured window is also exposed
+using the ``fft_window_width`` array. This provides the number of non-null samples used for each
+window index when scaling back the size to a reference of 1024 FFT. The actual shape size is
+effectively scaled up or down based on the dynamic size of the FFT operation being used.
+
+This allows to distinguish different version of the flexible pointwise windowing applied to the
+FFT and exposes this platform configuration to the application.
+
+Other optional capabilities exposed during device discovery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The device status can be used to expose additional information related to the state of the
+platform notably based on its configuration state or related to error management
+(correctable or non).
+
+The queue topology exposed to the device is provided on top of the capabilities. This provides
+the number of queues available for the exposed bbdev device (the physical device may have more)
+for each operation as well as the different level of priority available for arbitration.
+These are based on the arrays and parameters ``num_queues``, ``queue_priority``,
+``max_num_queues``, ``queue_size_lim``.
 
 
 Operation Processing
diff --git a/lib/bbdev/rte_bbdev.h b/lib/bbdev/rte_bbdev.h
index d12e2e7fbc..925c78cae1 100644
--- a/lib/bbdev/rte_bbdev.h
+++ b/lib/bbdev/rte_bbdev.h
@@ -313,6 +313,8 @@ int
 rte_bbdev_stats_reset(uint16_t dev_id);
 
 /** Device information supplied by the device's driver */
+
+/* Structure rte_bbdev_driver_info 8< */
 struct rte_bbdev_driver_info {
 	/** Driver name */
 	const char *driver_name;
@@ -352,6 +354,7 @@ struct rte_bbdev_driver_info {
 	/** FFT windowing width for 2048 FFT - size defined in capability. */
 	uint16_t *fft_window_width;
 };
+/* >8 End of structure rte_bbdev_driver_info. */
 
 /** Macro used at end of bbdev PMD list */
 #define RTE_BBDEV_END_OF_CAPABILITIES_LIST() \
@@ -361,6 +364,8 @@ struct rte_bbdev_driver_info {
  * Device information structure used by an application to discover a devices
  * capabilities and current configuration
  */
+
+/* Structure rte_bbdev_info 8< */
 struct rte_bbdev_info {
 	int socket_id;  /**< NUMA socket that device is on */
 	const char *dev_name;  /**< Unique device name */
@@ -369,6 +374,7 @@ struct rte_bbdev_info {
 	bool started;  /**< Set if device is currently started */
 	struct rte_bbdev_driver_info drv;  /**< Info from device driver */
 };
+/* >8 End of structure rte_bbdev_info. */
 
 /**
  * Retrieve information about a device.
-- 
2.34.1

Re: [PATCH v1 0/1] doc: bbdev device discovery clarification

[Maxime Coquelin]

On 10/10/23 22:34, Nicolas Chautru wrote:
> Adding more information in bbdev documentation related to the
> bbdev device discovery from info_get which was not very verbose so far.
> Notably for FEC and FFT operations which have extra parameters to
> manage different implementation variants.
> 
> Also use code snippet to refer to info structure and keep the doc
> in sync moving forward.
> 
> This is on top of this serie
> https://patches.dpdk.org/project/dpdk/list/?series=29744
> 
> Nicolas Chautru (1):
>    doc: bbdev device discovery clarification
> 
>   doc/guides/prog_guide/bbdev.rst | 60 ++++++++++++++++++++++++++++-----
>   lib/bbdev/rte_bbdev.h           |  6 ++++
>   2 files changed, 57 insertions(+), 9 deletions(-)
> 

Applied to next-baseband/for-main.

Thanks,
Maxime