docs: Provide CN translation for bitscrambler

docs/en/api-reference/peripherals/bitscrambler.rst

@@ -1,20 +1,23 @@
 BitScrambler Driver
 ========================
 
+:link_to_translation:`zh_CN:[中文]`
+
 Introduction
 ------------
 
-The BitScrambler is a peripheral that allows doing various transformation of data in a DMA stream based on an user-supplied program. ESP-IDF comes with an assembler for BitScrambler programs as well as build system and driver support for this peripheral. The BitScrambler peripheral in the {IDF_TARGET_NAME} has an independent TX and RX channel; both can be associated with the same or different peripherals.
+The BitScrambler is a peripheral that applies various data transformation to a DMA stream using an user-supplied program. ESP-IDF provides an assembler, build system, and driver support for BitScrambler programs. The BitScrambler peripheral in the {IDF_TARGET_NAME} has independent TX and RX channels; both can be linked to the same or different peripherals.
+
 
 Functional Overview
 -------------------
 
 .. list::
 
-    -  `BitScrambler assembly <#bitscrambler-assembly>`__ - covers how a BitScrambler assembly program is structured
+    -  `BitScrambler Assembly <#bitscrambler-assembly>`__ covers how a BitScrambler assembly program is structured.
-    -  `Build system integration <#bitscrambler-build>`__ - covers how BitScrambler programs are integrated in the ESP-IDF build system
+    -  `Build System Integration <#bitscrambler-build>`__ covers how BitScrambler programs are integrated in the ESP-IDF build system.
-    -  `Resource allocation and program loading <#bitscrambler-load>`__ Covers how to allocate BitScrambler instances and how to load a program into them
+    -  `Resource Allocation and Program Loading <#bitscrambler-load>`__ covers how to allocate BitScrambler instances and how to load a program into them.
-    -  `Loopback mode <#bitscrambler-loopback>`__ Covers how to use the BitScrambler in loopback mode
+    -  `Loopback Mode <#bitscrambler-loopback>`__ covers how to use the BitScrambler in loopback mode.
 
 .. _bitscrambler-assembly:
 
@@ -23,16 +26,14 @@ BitScrambler Assembly
 
 The operations a BitScrambler performs on the data in the DMA stream are defined in a BitScrambler program. As a BitScrambler program is a binary blob that is hard to write by hand, ESP-IDF includes an assembler. This assembler converts easier-to-write text files into BitScrambler binary programs.
 
-BitScrambler assembly files consist of comments, labels, instruction bundles, meta-instructions. The assembler ignores comments. Labels define a location in the program; instructions can e.g. jump to the location indicated by a label. Instruction bundles are a collection of sub-instructions that get assembled into one 257-bit binary BitScrambler instruction. Meta-instructions define global BitScrambler configuration, like the amount of trailing bytes, the prefetch mode, or the contents of the LUT ram.
+BitScrambler assembly files consist of comments, labels, instruction bundles, meta-instructions. The assembler ignores comments; Labels define a location in the program; Instructions can, e.g., jump to the location indicated by a label. Instruction bundles are a collection of sub-instructions that get assembled into one 257-bit binary BitScrambler instruction. Meta-instructions define global BitScrambler configuration, like the amount of trailing bytes, the prefetch mode, or the contents of the LUT RAM.
 
-BitScrambler assembly files are case-insensitive as well as not sensitive to indentation. This documentation will use upper and lower caps for readability, but the assembler itself doesn't care. Fields that can contain an integer normally are given in a base-10 number, but can also contain a hex value if prepended with ``0x`` or a binary value if prepended with ``0b``.
+BitScrambler assembly files are case-insensitive as well as not sensitive to indentation. This documentation uses upper and lower caps for readability, but the assembler itself doesn't care. Fields that can contain an integer normally are given in a base-10 number, but can also contain a hex value if prepended with ``0x`` or a binary value if prepended with ``0b``.
 
 Comments
 ~~~~~~~~
 
-A comment starts with a '#' and lasts until the end of the line. A comment can be placed anywhere where a space can be placed; this means that comments can be inside instruction bundles
+A comment starts with a ``#`` and extends to the end of the line. It can appear anywhere a space is allowed, including within instruction bundles between sub-instructions.
-in between sub-instructions.
-
 
 Labels
 ~~~~~~
@@ -50,71 +51,90 @@ Example:
         write 8,
         jmp loop_back
 
-The 'jmp' opcode in the instruction bundle will jump back to the start of itself, meaning that this instruction bundle will be executed over and over again in a tight loop.
+The ``jmp`` opcode in the instruction bundle will jump back to the start of itself, meaning that this instruction bundle will be executed over and over again in a tight loop.
 
-Instruction bundle
+Instruction Bundle
 ~~~~~~~~~~~~~~~~~~
 
-An instruction bundle consists of sub-instructions, separated by a comma. The entirety of the instruction bundle is assembled into one 257-bit instruction that the BitScrambler will execute in a single clock cycle; in other words, all sub-instructions in an instruction word will execute in parallel, at the same time. This also means the order of sub-instructions in an instruction in the assembly source does not matter. The instruction bundle ends after the last sub-instruction that is not followed by a comma.
+An instruction bundle consists of sub-instructions separated by commas. The entire bundle is assembled into one 257-bit instruction that the BitScrambler will execute in a single clock cycle. This means all sub-instructions within the bundle run in parallel, regardless of their order in the assembly source. The bundle ends with the last sub-instruction that is not followed by a comma.
 
-The specific details of the BitScrambler can be found in the  *{IDF_TARGET_NAME} Technical Reference Manual* > *BitScrambler (BITSCRM)* [`PDF <{IDF_TARGET_TRM_EN_URL}#bitscrm>`__]. As a summary: the BitScrambler consists of a 32-bit output register. Each of its bits takes the value of any bit in any of the sources. The sources are:
+The specific details of the BitScrambler can be found in the  *{IDF_TARGET_NAME} Technical Reference Manual* > *BitScrambler (BITSCRM)* [`PDF <{IDF_TARGET_TRM_EN_URL}#bitscrm>`__].
 
- - a 64-bit input register that is being fed from the incoming DMA stream,
+In summary, BitScrambler contains a 32-bit output register, where each bit can take the value from any bit in any of the input sources. The sources are:
- - two 16-bit counters,
+
- - 30 registers that contain the output of various comparisons,
+ - a 64-bit input register fed by the incoming DMA stream
- - a fixed high and low bit,
+ - two 16-bit counters
- - the output of a look-up table (LUT) RAM,
+ - A 30 bits register that contains the output of various comparisons
- - the value of the output register in the previous cycle.
+ - a fixed high and low bit
+ - the output of a look-up table (LUT) RAM
+ - the value of the output register in the previous cycle
 
 Sub-instructions
 """"""""""""""""
 
-``set [output] [source_bits]`` - Routes one or more source bits to output bits. Note that it's possible to route multiple bits using the ``..`` operator: for instance ``set 0..3 O4..O6`` will have the same effect as ``set 0 O4, set 1 O5, set 2 O6, set 3 O7``. The first argument is the output bit or output bit range; output bits are numbered from 0 to 31. The second argument is one or a range of `source bits`_. Note that any output bits that do not have a corresponding ``set`` sub-instruction in an instruction bundle will be set to a low logic level.
+``set [output] [source_bits]``: Routes one or more source bits to output bits. Note that it's possible to route multiple bits using the ``..`` operator: for instance ``set 0..3 O4..O6`` will have the same effect as ``set 0 O4, set 1 O5, set 2 O6, set 3 O7``. The first argument is the output bit or output bit range; output bits are numbered from 0 to 31. The second argument is one or a range of `source bits`_. Note that any output bits that do not have a corresponding ``set`` sub-instruction in an instruction bundle will be set to a low logic level.
 
-``write [n]`` - After routing all output bits, take the least significant ``n`` output register bits and push them into the output DMA pipeline. ``n`` can be one of 0, 8, 16 or 32. If an instruction bundle does not have a ``write`` sub-instruction, it will be equivalent to a ``write 0``.
+``write [n]``: After routing all output bits, take the least significant ``n`` output register bits and push them into the output DMA pipeline. ``n`` can be one of 0, 8, 16 or 32. If an instruction bundle does not have a ``write`` sub-instruction, it will be equivalent to a ``write 0``.
 
-``read [n]`` - After routing all output bits and writing to the output register, take ``n`` bits from the input DMA pipeline and push them into the 64-bit input register. ``n`` can be one of 0, 8, 16 or 32. These bits will be shifted into the input FIFO starting from the MSB. As an example, a ``read 16`` will shift bits 63-16 of the input register down to bits 47-0 and the new 16 bits read from the input DMA pipeline will occupy bits 63-48 in the input register. If an instruction bundle does not have a ``read`` sub-instruction, it will be equivalent to a ``read 0``.
+``read [n]``: After routing all output bits and writing to the output register, take ``n`` bits from the input DMA pipeline and push them into the 64-bit input register. ``n`` can be one of 0, 8, 16 or 32. These bits will be shifted into the input FIFO starting from the MSB. As an example, a ``read 16`` shifts bits 63–16 of the input register down to bits 47–0 and the new 16 bits read from the input DMA pipeline will occupy bits 63–48 in the input register. If an instruction bundle does not have a ``read`` sub-instruction, it will be equivalent to a ``read 0``.
 
-An opcode - The opcodes are fully documented in the Technical Reference manual; here's a summary.
+opcode
+""""""
 
 .. only:: esp32p4
 
-    - ``LOOP(A|B) end_val ctr_add tgt`` - If the selected counter (A or B) ls smaller than end_val, add ``ctr_add`` to the selected counter (A or B) and jump to the label ``tgt``. If not, continue execution.
+    - ``LOOP(A|B) end_val ctr_add tgt``: If the selected counter (A or B) is smaller than end_val, add ``ctr_add`` to the selected counter (A or B) and jump to the label ``tgt``. If not, continue execution.
-    - ``ADD(A|B)[H|L] val`` - Add ``val`` to the selected counter. If 'H' or 'L' is appended, only the high or low 8-bit, respectively, of the counter is written back.
+    - ``ADD(A|B)[H|L] val``: Add ``val`` to the selected counter. If ``H`` or ``L`` is appended, only the high or low 8-bit, respectively, of the counter is written back.
-    - ``IF[N] source_bit tgt`` - If the source bit `source_bit` is one (for IF) or zero (for IFN), jump to the label ``tgt``.
+    - ``IF[N] source_bit tgt``: If the source bit `source_bit` is 1 (for IF) or zero (for IFN), jump to the label ``tgt``.
-    - ``LDCTD(A|B)[H|L] val`` - Load ``val`` into the indicated counter. If H or L is appended, only the high or low 8-bit, respectively, will be updated.
+    - ``LDCTD(A|B)[H|L] val``: Load ``val`` into the indicated counter. If H or L is appended, only the high or low 8-bit, respectively, will be updated.
-    - ``LDCTI(A|B)[H|L]`` - Load the indicated counter (A or B) with bits 16-31 sent to the output register. If H or L is appended, only the high or low 8-bit, respectively, will be updated.
+    - ``LDCTI(A|B)[H|L]``: Load the indicated counter (A or B) with bits 16-31 from the output register. If ``H`` or ``L`` is appended, only the high or low 8-bit, respectively, will be updated.
-    - ``JMP tgt`` - Unconditional jump to label ``tgt``. This is equal to ``IF h tgt``.
+    - ``JMP tgt``: Unconditional jump to label ``tgt``. This is equal to ``IF h tgt``.
-    - ``NOP`` - No operation. This is equal to ``ADDA 0``.
+    - ``NOP``: No operation. This is equal to ``ADDA 0``.
 
 .. only:: esp32c5
 
-    - ``LOOP(A|B) end_val ctr_add tgt`` - If the selected counter (A or B) ls smaller than end_val, add ``ctr_add`` to the selected counter (A or B) and jump to the label ``tgt``. If not, continue execution.
+    - ``LOOP(A|B) end_val ctr_add tgt``: If the selected counter (A or B) is smaller than end_val, add ``ctr_add`` to the selected counter (A or B) and jump to the label ``tgt``. If not, continue execution.
-    - ``ADD(A|B)[H|L] val`` - Add ``val`` to the selected counter. If 'H' or 'L' is appended, only the high or low 8-bit, respectively, of the counter is written back.
+    - ``ADD(A|B)[H|L] val``: Add ``val`` to the selected counter. If ``H`` or ``L`` is appended, only the high or low 8-bit, respectively, of the counter is written back.
-    - ``IF[N] source_bit tgt`` - If the source bit `source_bit` is one (for IF) or zero (for IFN), jump to the label ``tgt``.
+    - ``IF[N] source_bit tgt``: If the source bit `source_bit` is one (for IF) or zero (for IFN), jump to the label ``tgt``.
-    - ``LDCTD(A|B)[H|L] val`` - Load ``val`` into the indicated counter. If H or L is appended, only the high or low 8-bit, respectively, will be updated.
+    - ``LDCTD(A|B)[H|L] val``: Load ``val`` into the indicated counter. If H or L is appended, only the high or low 8-bit, respectively, will be updated.
-    - ``LDCTI(A|B)[H|L]`` - Load the indicated counter (A or B) with bits 16-31 sent to the output register. If H or L is appended, only the high or low 8-bit, respectively, will be updated.
+    - ``LDCTI(A|B)[H|L]``: Load the indicated counter (A or B) with bits 16-31 sent to the output register. If ``H`` or ``L`` is appended, only the high or low 8-bit, respectively, will be updated.
-    - ``ADDCTI(A|B)[H|L]`` - Add bits 16-31 sent to the output register to the indicated counter (A or B) . If H or L is appended, only the high or low 8-bit, respectively, will be evaluated and updated.
+    - ``ADDCTI(A|B)[H|L]``: Add bits 16–31 sent to the output register to the indicated counter (A or B). If ``H`` or ``L`` is appended, only the high or low 8-bit, respectively, will be evaluated and updated.
-    - ``JMP tgt`` - Unconditional jump to label ``tgt``. This is equal to ``IF h tgt``.
+    - ``JMP tgt``: Unconditional jump to label ``tgt``. This is equal to ``IF h tgt``.
-    - ``NOP`` - No operation. This is equal to ``ADDA 0``.
+    - ``NOP``: No operation. This is equal to ``ADDA 0``.
 
-Note that an instruction bundle can only contain one opcode, one ``read``, and one ``write``. It can contain multiple ``set`` instructions, although multiple ``set`` instruction cannot assign a value to the same output bits.
+.. note::
+
+    Note that an instruction bundle can only contain one opcode, one ``read``, and one ``write``. It can contain multiple ``set`` instructions, although multiple ``set`` instruction cannot assign a value to the same output bits.
 
 Source bits
 """""""""""
 
-The ``set`` and ``if``/``ifn`` instructions have a ``source bit`` field. The following values can be put there:
+The ``set`` and ``if`` / ``ifn`` instructions have a ``source_bit`` field. The following values can be put there:
+
+- ``0`` – ``63``: The bit selected is sourced from the selected bit in the input register.
+- ``O0`` – ``O31``: The bit selected is sourced from the value the output register was assigned in the previous cycle.
+- ``A0`` – ``A15``: The bit selected is sourced from the selected bit in the A counter register.
+- ``B0`` – ``B15``: The bit selected is sourced from the selected bit in the B counter register.
+- ``L0`` – ``L31``: The bit selected is sourced from the output from the LUT RAM. As described in the Technical Reference Manual, the LUT RAM output is the LUT item at the position indicated by the most significant N bits of the bits routed to the output register in the previous cycle, with N being 9, 10 or 11 for a LUT width of 32, 16 or 8-bit respectively.
+- A condition compares (a portion of) counter B with bits that were routed to the output register in the previous cycle. These conditions consist of three parts:
+
+  1. The first part specifies whether compare all bits of counter B or only the high or low 8 bits:
+
+    - ``B``: Compare the entire B register
+    - ``BH``: Compare the high 8 bits of the B register
+    - ``BL``: Compare the low 8 bits of the B register
+
+  2. The second part is the comparison operator, which supports ``<=``, ``>``, or ``=``.
+  3. The third part specifies the offset in the output register for comparison with the selected part of the B register:
+
+    - For 16-bit comparisons, the offset can be ``O0`` or ``O16``
+    - For 8-bit comparisons, the offset can be ``O0``, ``O8``, ``O16`` or ``O24``
 
-- ``0``-``63`` -  The bit selected is sourced from the selected bit in the input register.
-- ``O0``-``O31`` - The bit selected is sourced from the value the output register was assigned in the previous cycle.
-- ``A0``-``A15`` - The bit selected is sourced from the selected bit in the A counter register.
-- ``B0``-``B15`` - The bit selected is sourced from the selected bit in the B counter register.
-- ``L0``-``L31`` - The bit selected is sourced from the output from the LUT ram. As described in the Technical Reference Manual, the LUT RAM output is the LUT item at the position indicated by the most significant N bits of the bits routed to the output register in the previous cycle, with N being 9, 10 or 11 for a LUT width of 32, 16 or 8-bits respectively.
-- A condition comparing (a portion of) counter B with bits that were routed to the output register in the previous cycle. These conditions consist of three parts: depending on if you want to compare the entirety of the B register or only the upper or lower 8 bits, the first part is 'B', 'BH' or BL' respectively. The second part is the comparison operator: '<=', '>' and '=' are supported here. The third is the offset into the output register that will be compared to the selected part of the B register: this can be O0 or O16 for 16-bit comparisons and O0, O8, O16 or O24 for 8-bit comparison.
 - ``H`` or ``L``. These sources are fixed-high or fixed-low.
 
-Note that not all sources can be used together in the same instruction. For instance, it is not possible to use a bit from one of the two counters as well as a bit from the upper 32 bits of the input FIFO in the same instruction bundle. The assembler will generate an error if an instruction bundle tries to do this anyway.
+.. note::
 
+    Note that not all sources can be used together in the same instruction. For instance, it is not possible to use a bit from one of the two counters as well as a bit from the upper 32 bits of the input FIFO in the same instruction bundle. The assembler will generate an error if an instruction bundle tries to do this anyway.
 
 Example
 """""""
@@ -131,42 +151,32 @@ An example BitScrambler program might look like this:
         jmp loop_back
 
 
-This program only has one instruction (as only the line with the ``jmp`` does not end in a comma). It
+This program only has one instruction (as only the line with the ``jmp`` does not end in a comma). It takes the lower 4 bits of the data read from memory and sends it to the upper 4 bits of the first byte of the output register. It also takes the next 4 bits of the input register and sends it to the lower 4 bits of the output register. It then writes 8 bits (one byte) to the output, while reading 8 bits from the input. Finally, the program continues by jumping back to the start of the instruction. Note that this all is executed in one BitScrambler cycle, and as the sub-instructions all are part of the same instruction, they could be specified in any order within the instruction. The end result of this small BitScrambler program is that it takes in data, e.g., ``01 23 45 67`` and swaps the high and low nibble of every bytes, resulting in an output of ``10 32 54 76``.
-takes the lower 4 bits of the data read from memory and sends it to the upper 4 bits of the first byte
-of the output register. It also takes the next 4 bits of the input register and sends it to the lower
-4 bits of the output register. It then writes 8 bits (one byte) to the output, while reading 8 bits
-from the input. Finally, the program continues by jumping back to the start of the instruction. Note
-that this all is executed in one BitScrambler cycle, and as the sub-instructions all are part of
-the same instruction, they could be specified in any order within the instruction. The end result
-of this small BitScrambler program is that it takes in data, e.g. ``01 23 45 67`` and swaps the high
-and low nibble of every bytes, resulting in an output of ``10 32 54 76``.
 
 
 Meta-instructions
 ~~~~~~~~~~~~~~~~~
 
-Meta-instructions set global BitScrambler configuration. Meta-instructions are allowed anywhere within the assembly file (except within an instruction bundle) and due to their nature will also have effect on the preceding assembly code. At the moment, two meta-instructions are defined. ``cfg`` sets a global BitScrambler setting, while ``lut`` defines lookuptable RAM content.
+Meta-instructions set global BitScrambler configuration. Meta-instructions are allowed anywhere in the assembly file (except within an instruction bundle) and may also affect the preceding assembly code due to their nature. Currently, two meta-instructions are defined: ``cfg`` sets a global BitScrambler setting, and ``lut`` defines lookup table RAM content.
 
 
 Global configuration meta-instructions
 """"""""""""""""""""""""""""""""""""""
 
-- ``cfg prefetch true|false`` - If prefetch is set to ``true``, on BitScrambler start it will read 64 bits from the input DMA stream into the input register. If set to ``false``, the input register will be initialized to zero. This setting defaults to ``true`` if not specified.
+- ``cfg prefetch true|false``: If prefetch is set to ``true``, the BitScrambler will read 64 bits from the input DMA stream into the input register at startup. If set to ``false``, the input register is initialized to zero. This setting defaults to ``true`` if not specified.
-- ``cfg eof_on upstream|downstream`` - After the input stream ends, the BitScrambler will still process a certain amount of 'trailing' dummy bytes so it can flush any data contained in its registers. This setting indicates from where the data will be counted: ``upstream`` makes the bitscrambler count the bytes being read, ``downstream`` makes it count the bytes being written. This defaults to ``upstream`` if not specified.
+- ``cfg eof_on upstream|downstream``: After the input stream ends, the BitScrambler will still process a certain amount of 'trailing' dummy bytes so it can flush any data contained in its registers. This setting indicates from where the data will be counted: ``upstream`` makes the bitscrambler count the bytes being read, ``downstream`` makes it count the bytes being written. This defaults to ``upstream`` if not specified.
-- ``cfg trailing_bytes N`` - This indicates how many dummy bytes will be read or written (depending on the ``eof_on`` setting) before the BitScrambler indicates an end-of-stream on its output. This defaults to ``0`` if not specified.
+- ``cfg trailing_bytes N``: This indicates how many dummy bytes will be read or written (depending on the ``eof_on`` setting) before the BitScrambler indicates an end-of-stream on its output. This defaults to ``0`` if not specified.
-- ``cfg lut_width_bits 8|16|32`` - This selects the bus width of the LUT output RAM, in bits. The LUT can be 2048x8bit, 1024*16bit or 512*32bits in size. This defaults to ``32`` if not specified.
+- ``cfg lut_width_bits 8|16|32``: This selects the bus width of the LUT output RAM, in bits. The LUT can be 2048x8 bits, 1024x16 bits or 512x32 bits in size. This defaults to ``32`` if not specified.
 
 
 LUT content meta-instructions
 """""""""""""""""""""""""""""
 
-``lut`` instructions are used to specify the contents of the LUT RAM. This meta-instruction is followed by one or more numerical values, separated by spaces or commas. LUT RAM locations
+``lut`` instructions are used to specify the contents of the LUT RAM. This meta-instruction is followed by one or more numerical values, separated by spaces or commas. LUT RAM locations are defined in the order they're encountered in the assembly program; the first value is always stored at location 0, the second value encountered is always stored at location 1, etc. The amount of arguments to a LUT meta-instruction is arbitrary as LUT meta-instructions can always be broken up or merged. For instance, ``lut 1,2,3,4`` is the same as ``lut 1,2`` on one line and ``lut 3,4`` on the next line. Note that LUT values must be within range with respect to the value given to the ``cfg lut_width_bits`` configuration meta-statement.
-are defined in the order they're encountered in the assembly program; the first value is always stored at location 0, the second value encountered is always stored at location 1, etc. The amount of arguments to a LUT meta-instruction is arbitrary as LUT meta-instructions can always be broken up or merged. For instance, ``lut 1,2,3,4`` is the same as ``lut 1,2`` on one line and ``lut 3,4`` on the next line.
-Note that LUT values must be within range with respect to the value given to the ``cfg lut_width_bits`` configuration meta-statement.
 
 .. _bitscrambler-build:
 
-Build system integration
+Build System Integration
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 The BitScrambler has full ESP-IDF build system support. A component (including the main component) can have BitScrambler assembly source files in its source directories. These files generally have the suffix ``.bsasm``. To assemble and link such a file into the main application, the CMakeLists.txt file for the component can call ``target_bitscrambler_add_src("assembly_file.bsasm")``. For instance, for an assembly file called ``my_program.bsasm``, a CMakeLists.txt file may look like this:
@@ -194,14 +204,14 @@ To use the assembled BitScrambler program, you would refer to it as such:
     bitscrambler_load_program(bs, my_bitscrambler_program);
 
 
-.. _bitscrambler-load:
+.. _bitscrambler-loopback:
 
-
+Loopback Mode
-Loopback mode
 ^^^^^^^^^^^^^
+
 The BitScrambler supports a loopback mode which is useful for data transformations that do not involve a peripheral. The loopback mode occupies both the TX and RX channels of the BitScrambler, although only the TX BitScrambler actually executes code. Note that even if loopback mode does not involve a peripheral, one still needs to be selected; the peripheral does not need to be initialized or used, but if it is, its DMA features will be unavailable.
 
-Resource allocation and program loading
+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`.
@@ -209,7 +219,7 @@ In loopback mode, a BitScrambler object is created using :cpp:func:`bitscrambler
 Application Example
 -------------------
 
-* :example:`peripherals/bitscrambler` demonstrates how to use the BitScrambler loopback mode to transform a buffer of data into a different format.
+* :example:`peripherals/bitscrambler` demonstrates how to use BitScrambler loopback mode to transform a buffer of data into a different format.
 
 API Reference
 -------------

docs/zh_CN/api-reference/peripherals/bitscrambler.rst

@@ -1 +1,229 @@
-.. include:: ../../../en/api-reference/peripherals/bitscrambler.rst
+比特调节器 (BitScrambler) 驱动
+====================================
+
+:link_to_translation:`en:[English]`
+
+介绍
+----
+
+比特调节器 (BitScrambler) 是一个外设，能够基于用户提供的程序对 DMA 数据流执行多种类型的转换。ESP-IDF 提供了比特调节器程序的汇编器、构建系统和驱动支持。在 {IDF_TARGET_NAME} 中，比特调节器外设具有独立的 TX（发送）和 RX（接收）通道，可分别关联到相同或不同的外设。
+
+
+功能概述
+--------
+
+.. list::
+
+    -  `比特调节器汇编程序 <#bitscrambler-assembly>`__：介绍比特调节器汇编程序的结构
+    -  `构建系统集成 <#bitscrambler-build>`__：介绍比特调节器程序如何与 ESP-IDF 构建系统集成
+    -  `资源分配与程序加载 <#bitscrambler-load>`__：介绍如何分配比特调节器实例以及如何加载程序
+    -  `回环模式 <#bitscrambler-loopback>`__：介绍如何在回环模式下使用比特调节器
+
+.. _bitscrambler-assembly:
+
+比特调节器汇编程序
+^^^^^^^^^^^^^^^^^^^^^^^
+
+比特调节器对 DMA 数据流执行的操作由比特调节器程序定义。由于比特调节器程序是一个难以手动编写的二进制 blob，因此 ESP-IDF 提供了汇编器，将易于编写的文本文件转换为比特调节器二进制程序。
+
+比特调节器汇编文件由注释、标签、指令包和元指令组成。对于注释，汇编器会直接忽略。标签用于定义程序中的位置。指令可以跳转到标签指定的位置。指令包是一组子指令，这些指令会被组装成一个 257 位的比特调节器指令。元指令用于定义比特调节器的全局配置，例如尾随字节数、预取模式或查找表 (LUT) 内容。
+
+比特调节器汇编文件不区分大小写，也不依赖缩进。本文档中使用的大小写混合仅便于阅读。整数字段默认使用十进制，但也可使用十六进制（前缀 ``0x``）或二进制（前缀 ``0b``）。
+
+注释
+~~~~
+
+注释以 ``#`` 开头，并持续到行末。注释可以出现在允许空格的任何位置，包括指令包内的子指令之间。
+
+标签
+~~~~~~
+
+任何由非空白字符组成并以英文冒号结尾的字符串都是一个标签。标签是对汇编文件中下一个指令包的符号引用。标签不能放在指令包内部，而应位于指令包之前。
+
+示例：
+
+.. code:: asm
+
+    loop_back:
+        set 0..3 4..7,
+        set 4..7 0..3,
+        read 8,
+        write 8,
+        jmp loop_back
+
+该指令包中的 ``jmp`` 指令会跳回自身的起始位置，反复执行整个指令包，形成一个紧密循环。
+
+指令包
+~~~~~~~~~~~~~~~~~~
+
+指令包由以逗号分隔的子指令组成。整个指令包会被汇编成一条 257 位的指令，由比特调节器在单个时钟周期内执行完成。指令包中的所有子指令会并行执行，而不受它们在汇编源代码中的顺序影响。指令包在最后一个没有逗号的子指令后结束。
+
+如需了解比特调节器的详细信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **比特调节器** [`PDF <{IDF_TARGET_TRM_CN_URL}#bitscrm>`__]。
+
+总结来说，比特调节器包含一个 32 位的输出寄存器，其每一位可以取自任意一个源的任意一位。支持的源包括：
+
+- 一个 64 位的输入寄存器，从传入的 DMA 数据流中获取数据
+- 两个 16 位的计数器
+- 一个 30 位寄存器，包含各种比较的输出结果
+- 一个固定的高位和低位
+- 一个查找表 (LUT) RAM 的输出
+- 上一周期中输出寄存器的值
+
+子指令
+""""""""""""""
+
+``set [output] [source_bits]``：将一个或多个源位路由到输出位。注意，可以使用 ``..`` 操作符路由多个位，例如 ``set 0..3 O4..O6`` 等效于 ``set 0 O4, set 1 O5, set 2 O6, set 3 O7``。第一个参数是输出位或输出位范围，输出位的编号范围为 0 到 31。第二个参数是一个或一组 `源位 (source_bit)`_。注意，在指令包中，如果某些输出位没有对应的 ``set`` 子指令，会默认将其设置为低逻辑电平。
+
+``write [n]``：在路由所有输出位后，取寄存器的最低有效 ``n`` 位并推送到 DMA 的输出流中。``n`` 可以是 0、8、16 或 32。如果指令包中没有 ``write`` 子指令，则其效果等同于 ``write 0``。
+
+``read [n]``：在路由所有输出位并将数据写入输出寄存器后，从输入 DMA 流中读取 ``n`` 位数据，并将其推入 64 位输入寄存器。``n`` 的取值可以是 0、8、16 或 32。这些新读取的位将从最高有效位开始依次进入 FIFO。例如，执行 ``read 16`` 将输入寄存器中原本的位 63～16 整体下移至位 47～0，而从 DMA 流读取的新 16 位数据会填充输入寄存器的位 63～48。如果一个指令包中没有 ``read`` 指令，其效果等同于 ``read 0``。
+
+操作码 (opcode)
+""""""""""""""""""
+
+.. only:: esp32p4
+
+    - ``LOOP(A|B) end_val ctr_add tgt``：如果选定的计数器（A 或 B）小于 end_val，将 ``ctr_add`` 添加到选定的计数器（A 或 B），并跳转到标签 ``tgt``。否则继续执行。
+    - ``ADD(A|B)[H|L] val``：将 ``val`` 添加到选定的计数器。如果附加了 ``H`` 或 ``L``，则分别仅更新计数器的高 8 位或低 8 位。
+    - ``IF[N] source_bit tgt``：如果源位 `source_bit` 为 1（对于 IF）或 0（对于 IFN），则跳转到标签 ``tgt``。
+    - ``LDCTD(A|B)[H|L] val``：将 ``val`` 加载到指定的计数器中。如果附加了 ``H`` 或 ``L``，则分别仅更新计数器的高 8 位或低 8 位。
+    - ``LDCTI(A|B)[H|L]``：将输出寄存器的 16-31 位加载到指定的计数器（A 或 B）中。如果附加了 H 或 L，则分别仅更新计数器的高 8 位或低 8 位。
+    - ``JMP tgt``：无条件跳转到标签 ``tgt``，等同于 ``IF h tgt``。
+    - ``NOP``：无操作，等同于 ``ADDA 0``。
+
+.. only:: esp32c5
+
+    - ``LOOP(A|B) end_val ctr_add tgt``：如果选定的计数器（A 或 B）小于 end_val，将 ``ctr_add`` 添加到选定的计数器（A 或 B），并跳转到标签 ``tgt``。否则继续执行。
+    - ``ADD(A|B)[H|L] val``：将 ``val`` 添加到选定的计数器。如果附加了 ``H`` 或 ``L``，则分别仅更新计数器的高 8 位或低 8 位。
+    - ``IF[N] source_bit tgt``：如果源位 `source_bit` 为 1（对于 IF）或 0（对于 IFN），则跳转到标签 ``tgt``。
+    - ``LDCTD(A|B)[H|L] val``：将 ``val`` 加载到指定的计数器中。如果附加了 ``H`` 或 ``L``，则分别仅更新计数器的高 8 位或低 8 位。
+    - ``LDCTI(A|B)[H|L]``：将发送到输出寄存器的 16～31 位加载到指定的计数器（A 或 B）。如果附加了 ``H`` 或 ``L``，则分别仅更新计数器的高 8 位或低 8 位。
+    - ``ADDCTI(A|B)[H|L]``：将发送到输出寄存器的 16～31 位加到指定的计数器（A 或 B）上。如果附加了 ``H`` 或 ``L``，则分别仅评估并更新计数器的高 8 位或低 8 位。
+    - ``JMP tgt``：无条件跳转到标签 ``tgt``，等同于 ``IF h tgt``。
+    - ``NOP`` - 无操作，等同于 ``ADDA 0``。
+
+.. note::
+
+    注意，一个指令包中只能包含一个操作码、一个 ``read`` 指令和一个 ``write`` 指令，但可以包含多个 ``set`` 指令。多个 ``set`` 指令不能对同一输出位进行赋值。
+
+源位 (source_bit)
+""""""""""""""""""""
+
+``set`` 和 ``if``/ ``ifn`` 指令包含一个 ``source_bit`` 字段，其取值范围如下：
+
+- ``0`` ～ ``63``：选定的位来源于输入寄存器中对应的位。
+- ``O0`` ～ ``O31``：选定的位来源于上一周期中输出寄存器的值。
+- ``A0`` ～ ``A15``：选定的位来源于 A 计数器寄存器中对应的位。
+- ``B0`` ～ ``B15``：选定的位来源于 B 计数器寄存器中对应的位。
+- ``L0`` ～ ``L31``：选定的位来源于 LUT RAM 的输出。根据**{IDF_TARGET_NAME} 技术参考手册** [`PDF <{IDF_TARGET_TRM_CN_URL}>`__]，LUT RAM 的输出是 LUT 中某个项，该项的位置由上一周期路由到输出寄存器的最高有效 N 位决定。其中，N 的取值对应 32、16 和 8 位的 LUT，分别为 9、10、11。
+- 将 B 计数器的部分值与上一周期传输至输出寄存器的位进行比较时，整个条件由三部分组成：
+
+  1. 第一部分：指定比较的是 B 计数器的全部位，还是仅高 8 位或低 8 位：
+
+    - ``B``：比较整个 B 计数器
+    - ``BH``：比较 B 计数器的高 8 位
+    - ``BL``：比较 B 计数器的低 8 位
+
+  2. 第二部分：比较运算符，支持操作 ``<=``、 ``>`` 和 ``=``。
+  3. 第三部分：指定输出寄存器中用于比较的位偏移：
+
+    - 16 位比较时，可选 ``O0`` 或 ``O16``
+    - 8 位比较时，可选 ``O0``、``O8``、``O16`` 或 ``O24``
+
+- ``H`` 或 ``L``：这些源是固定的高逻辑电平或低逻辑电平。
+
+.. note::
+
+    注意，并非所有源都可以在同一指令中一起使用。例如，无法在同一指令包中同时使用来自两个计数器的某一位和来自输入 FIFO 高 32 位中的某个位。如果指令包尝试这样做，汇编器会生成错误。
+
+示例
+""""
+
+如下是比特调节器的一个程序示例：
+
+.. code:: asm
+
+    loop_back:
+        set 0..3 4..7,
+        set 4..7 0..3,
+        read 8,
+        write 8,
+        jmp loop_back
+
+
+这个程序只有一条指令（因为只有最后的 ``jmp`` 行没有以逗号结尾）。此程序将从内存读取的低 4 位数据传送到输出寄存器的第一个字节的高 4 位，同时，将输入寄存器接下来的 4 位数据传送到输出寄存器的低 4 位。然后，它将 8 位数据（一个字节）写入输出，并从输入中读取 8 位数据。最后，程序跳转回指令开始处继续执行。注意，这些操作都在一个比特调节器周期内执行，并且由于子指令都属于同一条指令，因此在指令内部可以按任何顺序指定。这个小型比特调节器程序的最终结果是：接收数据，例如 ``01 23 45 67``，并交换每个字节的高低半字节，输出结果为 ``10 32 54 76``。
+
+
+元指令
+~~~~~~~~
+
+元指令用于设置全局的比特调节器配置。元指令可以出现在汇编文件的任何位置（指令包内部除外），并且由于其全局性质，可能会影响之前的汇编代码。目前定义了两条元指令：``cfg`` 用于全局比特调节器设置，``lut`` 定义查找表 (lookup table) RAM 的内容。
+
+
+全局配置元指令
+"""""""""""""""
+
+- ``cfg prefetch true|false``：如果 ``prefetch`` 设置为 ``true``，则比特调节器启动时，从输入 DMA 流中读取 64 位数据到输入寄存器中。如果设置为 ``false``，输入寄存器将被初始化为零。默认为 ``true``。
+- ``cfg eof_on upstream|downstream``：输入流结束后，比特调节器仍会计算一定量的“尾随”填充字节，以便清空其寄存器中可能存储的数据。此设置表示的是尾随字节的来源：如果设置为 ``upstream``，比特调节器从输入流中读取一定数量的填充字节，如果设置为 ``downstream``，比特调节器会等待写入足够的字节。默认为 ``upstream``。
+- ``cfg trailing_bytes N``：该设置指示比特调节器在指示输出流结束之前，需要读取或写入（取决于 ``eof_on`` 设置）多少个填充字节。默认值为 ``0``。
+- ``cfg lut_width_bits 8|16|32``：该设置选择 LUT 输出 RAM 的总线宽度（单位：位）。LUT 的大小可以是 2048×8 位、1024×16 位或 512×32 位。默认值为 ``32``。
+
+
+LUT 内容元指令
+"""""""""""""""""""""""""""""
+
+``lut`` 指令用于指定 LUT RAM 的内容。该元指令后跟一个或多个数值，用空格或逗号分隔。LUT RAM 的位置是按它们在汇编程序中出现的顺序定义的；第一个值总是存储在位置 0，第二个值总是存储在位置 1，以此类推。LUT 元指令的参数数量是任意的，因为 LUT 元指令可以随时拆分或合并。例如，``lut 1,2,3,4`` 等同于 ``lut 1,2`` 在一行， ``lut 3,4`` 在下一行。注意，LUT 的值必须在与 ``cfg lut_width_bits`` 配置元语句所给定的值的范围内。
+
+.. _bitscrambler-build:
+
+构建系统集成
+^^^^^^^^^^^^^^
+
+比特调节器完全支持 ESP-IDF 构建系统。一个组件（包括主组件）可以在其源目录中直接包含比特调节器汇编源文件，这些文件通常具有后缀 ``.bsasm``。具体而言，需在组件的 CMakeLists.txt 文件中调用 ``target_bitscrambler_add_src("assembly_file.bsasm")``，从而将此类文件汇编并链接到主应用程序中。例如，对于名为 ``my_program.bsasm`` 的汇编文件，CMakeLists.txt 文件可能如下所示：
+
+.. code:: cmake
+
+    idf_component_register(SRCS "main.c" "some-file.c"
+                    INCLUDE_DIRS "./include")
+
+    target_bitscrambler_add_src("my_program.bsasm")
+
+要使用汇编后的比特调节器程序，可以这样引用：
+
+.. code:: c
+
+    // 创建一个变量 'my_bitscrambler_program'，它解析为
+    // 二进制的比特调节器程序。
+    // 第二个参数与汇编文件的名称相同，但不包括 ".bsasm"
+    BITSCRAMBLER_PROGRAM(my_bitscrambler_program, "my_program");
+
+    [...]
+
+    bitscrambler_handle_t bs;
+    [...创建比特调节器实例]
+    bitscrambler_load_program(bs, my_bitscrambler_program);
+
+
+.. _bitscrambler-loopback:
+
+回环模式
+^^^^^^^^^
+
+比特调节器支持回环模式，适用于不涉及外设的数据转换任务。回环模式下，TX 和 RX 通道都会被占用，但实际上只有 TX 比特调节器执行代码。注意，即使回环模式不涉及外设，仍然需要选择一个外设。此外设无需初始化或使用，但如果使用，将无法使用其 DMA 功能。
+
+资源分配和程序加载
+^^^^^^^^^^^^^^^^^^^^^
+
+在回环模式下，使用 :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` 释放硬件资源并清理内存。
+
+应用示例
+--------
+
+* :example:`peripherals/bitscrambler` 演示了如何使用比特调节器回环模式将数据包转换为不同的格式。
+
+API 参考
+--------
+
+.. include-build-file:: inc/bitscrambler.inc
+.. include-build-file:: inc/bitscrambler_loopback.inc
+.. include-build-file:: inc/bitscrambler_peri_select.inc