i3c_controller: Review fixes

Signed-off-by: Jorge Marques <jorge.marques@analog.com>

Author: gastmaier

docs/library/i3c_controller/i3c_controller_core.rst

@@ -6,7 +6,8 @@ I3C Controller Core
 .. hdl-component-diagram::
 
 The I3C Controller Core peripheral forms the heart of the I3C Controller.
-It is responsible for handling a I3C Controller commandsand translates it into low-level I3C bus transactions.
+It is responsible for handling a I3C Controller commands and translates it into
+low-level I3C bus transactions.
 
 Files
 -------------------------------------------------------------------------------

docs/library/i3c_controller/i3c_controller_host_interface.rst

@@ -10,9 +10,9 @@ access to a I3C Controller Control Interface.
 This is typically used in combination with a software program to dynamically
 generate I3C transactions.
 
-The peripheral has also support for providing memory-mapped access to one or more
-:ref:`i3c_controller offload-control-interface` cores and change its content
-dynamically at runtime.
+The peripheral also has support for providing memory-mapped access to one or more
+:ref:`i3c_controller offload-interface` cores and change its content dynamically at
+runtime.
 
 Files
 --------------------------------------------------------------------------------
@@ -38,6 +38,33 @@ Signal and Interface Pins
 
 .. hdl-interfaces::
 
+   * - s_axi_aclk
+     - All ``s_axi`` signals and ``irq`` are synchronous to this clock.
+   * - s_axi_aresetn
+     - Synchronous active-low reset.
+       Resets the internal state of the peripheral.
+   * - s_axi
+     - AXI-Lite bus slave.
+       Memory-mapped AXI-lite bus that provides access to modules register map.
+   * - irq
+     - Level-High Interrupt.
+       Interrupt output of the module. Is asserted when at least one of the
+       modules interrupt is pending and unmasked.
+   * - offload_trigger
+     - On offload operation, assert to start a burst.
+   * - sdio
+     - Group of byte stream interfaces (``SDI``, ``SDO``, and ``IBI``),
+       internally connected to thei respective FIFOs.
+   * - offload
+     - SDI output of the :ref:`i3c_controller offload-interface`,
+       generally consumed to a DMA.
+   * - cmdp
+     - Parsed :ref:`i3c_controller command_descriptors` to instruct the
+       :ref:`i3c_controller core`.
+   * - rmap
+     - Interface give the :ref:`i3c_controller core` access to some register map
+       addresses.
+
 Register Map
 --------------------------------------------------------------------------------
 
@@ -68,7 +95,7 @@ asserted when:
 * ``SDO_ALMOST_EMPTY``: the level falls bellow the almost empty level.
 * ``SDI_ALMOST_FULL``: the level rises above the almost full level.
 * ``IBI_ALMOST_FULL``: the level rises above the almost full level.
-* ``CMDR_PENDING``: a new synchronization event arrives.
+* ``CMDR_PENDING``: a new :ref:`i3c_controller cmdr` event arrives.
 * ``IBI_PENDING``: a new IBI event arrives.
 * ``DAA_PENDING``: a peripheral requested an address during the DAA.
 
@@ -98,14 +125,9 @@ FIFO Threshold Interrupts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The FIFO threshold interrupts can be used by software for flow control of the
-streams.
-
-If an application wants to send more data than what fits into the FIFO can write
-samples into the FIFO until it is full then suspend operation wait for the almost
-empty interrupt and continue writing data to the FIFO.
-Similarly, when the application wants to read more data than what fits into FIFO
-it should listen for the almost full interrupt and read data from the FIFO when
-it occurs.
+streams, for example,
+listen to the FIFO level interrupts during data transfer to and from the FIFOs
+to avoid data loss.
 
 The FIFO threshold interrupt is asserted when then FIFO level rises above the
 watermark and is automatically de-asserted when the level drops below the
@@ -114,7 +136,7 @@ watermark.
 Pending Interrupts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The pending interrupts ``*_PENDING`` is asserted when a new sync event is received
+The pending interrupt ``*_PENDING`` is asserted when a new sync event is received
 from a stream.
 For information about the ``CMDR`` see :ref:`i3c_controller cmdr`, and about the
 ``IBI`` see :ref:`i3c_controller ibi`.

docs/library/i3c_controller/index.rst

@@ -10,8 +10,19 @@ I3C Controller
    Core Module<i3c_controller_core>
    Interface<interface>
 
-I3C Controller is subset of the I3C specification to interface peripheral such
-as ADCs through I3C.
+I3C Controller is subset of the I3C-basic specification to interface peripherals
+such as ADCs through I3C.
+
+It consist out of two sub-modules which communicate over well defined interfaces.
+The :ref:`i3c_controller core` is a lean but powerful execution module, which
+implements the I3C bus control logic.
+It is controlled by a command stream generated by the :ref:`i3c_controller host_interface`,
+which parses the :ref:`i3c_controller command_descriptors`.
+
+The :ref:`i3c_controller offload-interface` operation mode allows to execute
+a pre-programmed command stream when triggered by an external event, allowing for
+minimal latency.
+
 
 Sub-modules
 --------------------------------------------------------------------------------
@@ -24,12 +35,14 @@ Sub-modules
 Interfaces
 --------------------------------------------------------------------------------
 
-* :ref:`i3c_controller control-interface`: SPI Engine command stream.
-* :ref:`i3c_controller offload-control-interface`: Program the command stream
-  stored in a offload module.
+* :ref:`i3c_controller control-interface`: Command descriptors.
+* :ref:`i3c_controller offload-interface`: Command descriptors for cyclic operation,
+  with SDI data generally consumed by a DMA.
 
 Software
 --------------------------------------------------------------------------------
 
+* :git-linux:`Linux Driver <i3c:drivers/i3c/master/adi-i3c-master.c>`:
+  Linux driver for the I3C Controller.
 * :ref:`i3c_controller instruction-format`: Overview of the I3C Controller
   instruction format.

docs/library/i3c_controller/interface.rst

@@ -18,8 +18,8 @@ The interface consists of five streams:
 Instruction Set Specification
 --------------------------------------------------------------------------------
 
-The I3C Controller instruction set is a pair of 32-bit instruction set (command
-0 and command 1).
+The I3C Controller instruction set is a pair of 32-bit command descriptors
+(command 0 and command 1), with the latter present only for some command 0 values.
 
 .. _i3c_controller command_descriptors:
 
@@ -85,7 +85,7 @@ The CCC ID is defined in the *linux/i3c/ccc.h* file.
    the procedure.
 
 Bits not presented in the tables are assumed 0.
-When Value is filled, it means it is is the required constant value for this
+When Value is filled, it means it is the required constant value for this
 transfer.
 
 +------------------------------------------------------------------------------+
@@ -164,7 +164,7 @@ Command Receipts
 
 Command receipts (cmdr) are returned descriptors for each command descriptor
 executed (cmd).
-When a new cmdr is written to the CMDR FIFO, an interruption is sent to
+When a new cmdr is written to the CMDR FIFO, an interrupton is sent to
 PS, see :ref:`i3c_controller interrupts`.
 
 In the cmdr, the buffer length is updated with the number of bytes actually
@@ -232,7 +232,7 @@ In-Band Interrupts
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 IBI\s are accepted autonomously during bus idle if the feature is enabled.
-The accepted IBI\s fill the IBI FIFO and generate an interruption in the
+The accepted IBI\s fill the IBI FIFO and generate an interrupt to the
 PS.
 
 The structure of the received IBI is:
@@ -364,42 +364,43 @@ the possible commands, and body is a 1-byte that depends on the header.
 Configuration Registers
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-.. _i3c_controller offload-control-interface:
+.. _i3c_controller offload-interface:
 
-Offload Control Interface
+Offload Interface
 --------------------------------------------------------------------------------
 
 The offload interface allows to cyclic operation with SDI output to a DMA.
 The offload commands are the same as in :ref:`i3c_controller command_descriptors`,
-however no command receipt is emitted and less complex should be preferred with
-this interface, specially that the I3C specification allows the peripheral to
-reject a transfer.
-
-Instead of writing the command to a FIFO, the user shall write the commands in
-sequence to the OFFLOAD_CMD_* registers and update the OFFLOAD_CMD_LENGTH
-register subfield (one shall set the OPS_MODE to offload at the same write).
-The offload logic will then execute in cycles at each offload_trigger when
-in OPS_MODE offload ('b11).
-
-In summary, are suitable of the offload interface register read transfers.
+however no command receipt is emitted and less complex transactions are preferred
+with this interface, specially that the I3C specification allows the peripheral to
+reject a transfer;
+in summary, are suitable of the offload interface register read transfers, e.g.
+ADC readings.
+
+To use this mode,
+instead of writing the command to the CMD FIFO and the payloads to SDO FIFO:
+
+* Write the command descriptors in sequence of execution to the OFFLOAD_CMD_*
+  registers.
+* Populate the OFFLOAD_SDO_* registers with the SDO payload, preserving unused
+  bytes slots (don't mix different commands payload in the same address).
+* Update the OPS_OFFLOAD_LENGTH register subfield with the number of commands
+  descriptors.
+
+The offload logic will then execute a burst for each offload_trigger
+(OPS_MODE must be 'b1).
+Also, one shall set the OPS_MODE to offload at the same write of the
+OPS_OFFLOAD_LENGTH.
 
 The Block RAM Offload
 --------------------------------------------------------------------------------
 
-A 16-bit wide address, 32-bit data dual access block ram is used to store the
+A 5-bit wide address, 32-bit data dual access block ram is used to store the
 offload commands and SDO.
 
-The registers are mapped at [4:4] LSB:
-
-.. list-table::
-   :header-rows: 1
-
-   * - Value [5:5]
-     - Description
-   * - ``0``
-     - Commands
-   * - ``1``
-     - SDO
+The bit 5 indicates if it's a command descriptor ('b0) or a SDO payload ('b1).
+The actual width of the address and data depends on the implementation, but in
+general the 5-bit address is placed as a 16-bit address with the 11 MSB grounded.
 
 Debugging Tips
 --------------------------------------------------------------------------------

docs/regmap/adi_regmap_i3c_controller.txt

@@ -183,7 +183,7 @@ CMD_FIFO_ROOM
 ENDREG
 
 FIELD
-[31:0] 0x????????
+[31:0]
 CMD_FIFO_ROOM
 RO
 Number of free entries in the CMD FIFO.
@@ -213,7 +213,7 @@ SDO_FIFO_ROOM
 ENDREG
 
 FIELD
-[31:0] 0x????????
+[31:0]
 SDO_FIFO_ROOM
 RO
 Number of free entries in the SDO FIFO.
@@ -265,7 +265,7 @@ See :ref:`i3c_controller instruction-format` for the structure of the command.
 ENDREG
 
 FIELD
-[31:0] 0x??
+[31:0]
 CMD_FIFO
 WO
 The command to the I3C controller to execute.
@@ -357,7 +357,7 @@ Writing to it has no effect.
 ENDREG
 
 FIELD
-[31:0] 0x??
+[31:0] 0x????????
 SDI_FIFO
 RO
 ENDFIELD
@@ -426,24 +426,25 @@ ENDFIELD
 REG
 0x40
 OPS
+Configure the operation of the controller.
 ENDREG
 
 FIELD
-[0] 0x??
+[0] 0x0
 OPS_MODE
 RW
-Set 0 to private transfers, 1 to offload.
+Set 0 to direct transfers, 1 to offload operation.
 ENDFIELD
 
 FIELD
-[4:1] 0x??
+[4:1] 0x0
 OPS_OFFLOAD_LENGTH
 RW
 Offload commands length.
 ENDFIELD
 
 FIELD
-[6:5] 0x??
+[6:5] 0x00
 OPS_SPEED_GRADE
 RW
 Sets the speed grade in push-pull mode.
@@ -467,10 +468,11 @@ ENDIELD
 REG
 0x50
 IBI_CONFIG
+Configure the In-Band Interrupt (IBI) feature.
 ENDREG
 
 FIELD
-[0] 0x??
+[0] 0x0
 IBI_CONFIG_ENABLE
 WO
 Set this bit to accept (ACK) IBI requests.
@@ -482,7 +484,7 @@ Accepted IBIs fill the IBI_FIFO and generate an interruption in the PS.
 ENDFIELD
 
 FIELD
-[1] 0x??
+[1] 0x0
 IBI_CONFIG_AUTO
 WO
 Set this bit to listen for IBI requests (when a peripheral pulls SDA Low during quiet times).
@@ -534,14 +536,14 @@ Indicates if the device sends an MDB during the IBI.
 ENDFIELD
 
 FIELD
-[8:8] 0x???
+[8:8] 0xX
 DEV_CHAR_WEN
 W
 Enable write of the fields.
 ENDFIELD
 
 FIELD
-[15:9] 0x???
+[15:9] 0x??
 DEV_CHAR_ADDR
 RW
 Device address to apply DEV_CHAR[3:0].
@@ -557,15 +559,52 @@ Offload command memory. Write commands in sequence to these addresses and update
 OFFLOAD_CMD_LENGTH register.
 ENDREG
 
+FIELD
+[31:0] 0x??????
+OFFLOAD_CMD
+RW
+The command to the I3C controller to execute.
+ENDFIELD
+
 ############################################################################################
 ############################################################################################
 
 REG
 0xc0 + 0x01*n
 OFFLOAD_SDO_n
 Offload SDO memory.
-The length is infered by the commands and reset after each burst.
+Dual access memory sector used to store the SDO payload for the offload execution.
+The SDO is read by the parsing the OFFLOAD_CMD commands.
+For example, if the first command on OFFLOAD_CMD is a write with length 3 and the next with
+length 2, 3 bytes from OFFLOAD_SDO_0 are sent, then 2 bytes from OFFLOAD_SDO_1 are sent.
+If OPS_OFFLOAD_LENGTH is 2, then the burst concludes and the "pointer" resets to
+OFFLOAD_SDO_0, otherwise, the execution continues until all commands are resolved, always
+bounded by OPS_OFFLOAD_LENGTH.
 ENDREG
 
+FIELD
+[31:24] 0x??
+OFFLOAD_SDO_BYTE_3
+RO
+ENDFIELD
+
+FIELD
+[23:16] 0x??
+OFFLOAD_SDO_BYTE_2
+RO
+ENDFIELD
+
+FIELD
+[15:8] 0x??
+OFFLOAD_SDO_BYTE_1
+RO
+ENDFIELD
+
+FIELD
+[7:0] 0x??
+OFFLOAD_SDO_BYTE_0
+RO
+ENDFIELD
+
 ############################################################################################
 ############################################################################################