From 27e1a30acc18f77240fa691e76e11fb960f2a1cf Mon Sep 17 00:00:00 2001 From: morris Date: Mon, 12 May 2025 17:08:10 +0800 Subject: [PATCH] docs(bitscrambler): update documentation with integration details --- docs/en/api-reference/peripherals/bitscrambler.rst | 10 ++++++++++ docs/en/api-reference/peripherals/parlio/parlio_tx.rst | 2 ++ docs/en/api-reference/peripherals/rmt.rst | 2 ++ docs/zh_CN/api-reference/peripherals/bitscrambler.rst | 10 ++++++++++ .../api-reference/peripherals/parlio/parlio_tx.rst | 2 ++ docs/zh_CN/api-reference/peripherals/rmt.rst | 2 ++ 6 files changed, 28 insertions(+) diff --git a/docs/en/api-reference/peripherals/bitscrambler.rst b/docs/en/api-reference/peripherals/bitscrambler.rst index 1c9563ee2b..53a620353a 100644 --- a/docs/en/api-reference/peripherals/bitscrambler.rst +++ b/docs/en/api-reference/peripherals/bitscrambler.rst @@ -220,6 +220,16 @@ Resource Allocation and Program Loading In loopback mode, a BitScrambler object is created using :cpp:func:`bitscrambler_loopback_create`. If there is a BitScrambler peripheral matching the requested characteristics, this function will return a handle to it. You can then use :cpp:func:`bitscrambler_load_program` to load a program into it, then call :cpp:func:`bitscrambler_loopback_run` to transform a memory buffer using the loaded program. You can call :cpp:func:`bitscrambler_loopback_run` any number of times; it's also permissible to use :cpp:func:`bitscrambler_load_program` to change programs between calls. Finally, to free the hardware resources and clean up memory, call :cpp:func:`bitscrambler_free`. +Integrating BitScrambler with Peripheral Drivers +------------------------------------------------ + +The BitScrambler can be used alongside other peripheral modules (with GDMA interface support) to perform data transformation and transmission tasks. Currently, the following peripheral modules are integrated with the BitScrambler: + +.. list:: + + :SOC_PARLIO_SUPPORTED: - **Parlio TX Driver**: The BitScrambler acts as a transmission layer decorator function, which can be dynamically enabled during runtime. For details, refer to :ref:`parlio-tx-bitscrambler-decorator`. + :SOC_RMT_SUPPORT_DMA: - **RMT TX Driver**: The BitScrambler functions similarly to an RMT encoder. A dedicated encoder has been designed using the BitScrambler. For details, refer to :ref:`rmt-bitscrambler-encoder`. + Application Example ------------------- diff --git a/docs/en/api-reference/peripherals/parlio/parlio_tx.rst b/docs/en/api-reference/peripherals/parlio/parlio_tx.rst index 6cb4ec9ba6..5d469be742 100644 --- a/docs/en/api-reference/peripherals/parlio/parlio_tx.rst +++ b/docs/en/api-reference/peripherals/parlio/parlio_tx.rst @@ -311,6 +311,8 @@ The waveform of the external clock input is shown below: .. only:: SOC_BITSCRAMBLER_SUPPORTED + .. _parlio-tx-bitscrambler-decorator: + Custom Bitstream Generation with BitScrambler ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/api-reference/peripherals/rmt.rst b/docs/en/api-reference/peripherals/rmt.rst index 41fa81aa11..e8224e256c 100644 --- a/docs/en/api-reference/peripherals/rmt.rst +++ b/docs/en/api-reference/peripherals/rmt.rst @@ -445,6 +445,8 @@ While the functionality of an encoding process using the simple callback encoder .. only:: SOC_BITSCRAMBLER_SUPPORTED and SOC_RMT_SUPPORT_DMA + .. _rmt-bitscrambler-encoder: + BitScrambler Encoder ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/zh_CN/api-reference/peripherals/bitscrambler.rst b/docs/zh_CN/api-reference/peripherals/bitscrambler.rst index fd456e1c72..bdc3571191 100644 --- a/docs/zh_CN/api-reference/peripherals/bitscrambler.rst +++ b/docs/zh_CN/api-reference/peripherals/bitscrambler.rst @@ -220,6 +220,16 @@ LUT 内容元指令 在回环模式下，使用 :cpp:func:`bitscrambler_loopback_create` 创建一个比特调节器对象。如果有一个与请求的特性匹配的比特调节器外设，该函数将返回此外设的句柄。然后，使用 :cpp:func:`bitscrambler_load_program` 将比特调节器程序加载到创建的对象中，再调用 :cpp:func:`bitscrambler_loopback_run` 使用此加载的程序进行内存缓冲区的比特转换。可以多次调用 :cpp:func:`bitscrambler_loopback_run`，也可以在调用之间使用 :cpp:func:`bitscrambler_load_program` 更改程序。最后，调用 :cpp:func:`bitscrambler_free` 释放硬件资源并清理内存。 +在外设驱动中集成比特调节器 +-------------------------- + +比特调节器可以与其他外设模块（须支持 GDMA 接口）配合使用，以实现数据转换和传输任务。当前，以下外设模块已经完成了与 BitScrambler 的对接： + +.. list:: + + :SOC_PARLIO_SUPPORTED: - **Parlio TX 驱动**：比特调节器被设计成了传输层的装饰器函数，可以在运行期间动态启用，详情请参考 :ref:`parlio-tx-bitscrambler-decorator` + :SOC_RMT_SUPPORT_DMA: - **RMT TX 驱动**：比特调节器的作用和 RMT 编码器的功能类似，因此我们利用比特调节器设计了一个专门的编码器，详情请参考 :ref:`rmt-bitscrambler-encoder` + 应用示例 -------- diff --git a/docs/zh_CN/api-reference/peripherals/parlio/parlio_tx.rst b/docs/zh_CN/api-reference/peripherals/parlio/parlio_tx.rst index 8acda22ccf..ad0fd0ee58 100644 --- a/docs/zh_CN/api-reference/peripherals/parlio/parlio_tx.rst +++ b/docs/zh_CN/api-reference/peripherals/parlio/parlio_tx.rst @@ -311,6 +311,8 @@ TX 单元可以选择各种不同的时钟源，其中外部时钟源较为特 .. only:: SOC_BITSCRAMBLER_SUPPORTED + .. _parlio-tx-bitscrambler-decorator: + 配合比特调节器 (BitScrambler) 产生自定义的比特流 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-reference/peripherals/rmt.rst b/docs/zh_CN/api-reference/peripherals/rmt.rst index 9d633f8fd6..49efe8342a 100644 --- a/docs/zh_CN/api-reference/peripherals/rmt.rst +++ b/docs/zh_CN/api-reference/peripherals/rmt.rst @@ -445,6 +445,8 @@ RMT 编码器是 RMT TX 事务的一部分，用于在特定时间生成正确 .. only:: SOC_BITSCRAMBLER_SUPPORTED and SOC_RMT_SUPPORT_DMA + .. _rmt-bitscrambler-encoder: + 比特调节 (BitScrambler) 编码器 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~