From 15ff99a9bdca4745fc494bf02b1134e6f370ab97 Mon Sep 17 00:00:00 2001 From: Jorge Marques Date: Thu, 25 Jan 2024 14:22:46 -0300 Subject: [PATCH] docs: i3c_controller: Add documentation Signed-off-by: Jorge Marques --- .../i3c_controller/i3c_controller_core.rst | 44 ++ .../i3c_controller_host_interface.rst | 150 ++++ docs/library/i3c_controller/index.rst | 48 ++ docs/library/i3c_controller/interface.rst | 433 ++++++++++++ docs/library/index.rst | 1 + docs/regmap/adi_regmap_i3c_controller.txt | 641 ++++++++++++++++++ 6 files changed, 1317 insertions(+) create mode 100644 docs/library/i3c_controller/i3c_controller_core.rst create mode 100644 docs/library/i3c_controller/i3c_controller_host_interface.rst create mode 100644 docs/library/i3c_controller/index.rst create mode 100644 docs/library/i3c_controller/interface.rst create mode 100644 docs/regmap/adi_regmap_i3c_controller.txt diff --git a/docs/library/i3c_controller/i3c_controller_core.rst b/docs/library/i3c_controller/i3c_controller_core.rst new file mode 100644 index 000000000..c11dfee05 --- /dev/null +++ b/docs/library/i3c_controller/i3c_controller_core.rst @@ -0,0 +1,44 @@ +.. _i3c_controller core: + +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 commands and translates it into +low-level I3C bus transactions. + +Files +------------------------------------------------------------------------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Name + - Description + * - :git-hdl:`master:library/i3c_controller/i3c_controller_core/i3c_controller_core.v` + - Verilog source for the peripheral. + * - :git-hdl:`master:library/i3c_controller/i3c_controller_core/i3c_controller_core.tcl` + - TCL script to generate the Vivado IP-integrator project for the peripheral. + + +Configuration Parameters +-------------------------------------------------------------------------------- + +.. hdl-parameters:: + + * - CLK_MOD + - | Clock cycles per bus bit at maximun speed (12.5MHz), set to: + | * 8 clock cycles at 100MHz input clock. + | * 4 clock cycles at 50MHz input clock. + +Signal and Interface Pins +-------------------------------------------------------------------------------- + +.. hdl-interfaces:: + +Theory of Operation +-------------------------------------------------------------------------------- + diff --git a/docs/library/i3c_controller/i3c_controller_host_interface.rst b/docs/library/i3c_controller/i3c_controller_host_interface.rst new file mode 100644 index 000000000..e587bc1c8 --- /dev/null +++ b/docs/library/i3c_controller/i3c_controller_host_interface.rst @@ -0,0 +1,150 @@ +.. _i3c_controller host_interface: + +I3C Controller Host Interface +================================================================================ + +.. hdl-component-diagram:: + +The I3C Controller Host Interface peripheral allows asynchronous interrupt-driven memory-mapped +access to a I3C Controller Control Interface. +This is typically used in combination with a software program to dynamically +generate I3C transactions. + +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 +-------------------------------------------------------------------------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Name + - Description + * - :git-hdl:`master:library/i3c_controller/i3c_controller_host_interface/i3c_controller_host_interface.v` + - Verilog source for the peripheral. + * - :git-hdl:`master:library/i3c_controller/i3c_controller_host_interface/i3c_controller_host_interface.tcl` + - TCL script to generate the Vivado IP-integrator project for the peripheral. + +Configuration Parameters +-------------------------------------------------------------------------------- + +.. hdl-parameters:: + +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 + - 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 +-------------------------------------------------------------------------------- + +.. hdl-regmap:: + :name: i3c_controller_host_interface + +Theory of Operation +-------------------------------------------------------------------------------- + +FIFOs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +Synchronization Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +.. _i3c_controller interrupts: + +Interrupts +-------------------------------------------------------------------------------- + +The I3C Controller Host Interface peripheral has 8 internal interrupts, which are +asserted when: + +* ``CMD_ALMOST_EMPTY``: the level falls bellow the almost empty level. +* ``CMDR_ALMOST_FULL``: the level rises above the almost full level. +* ``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 :ref:`i3c_controller cmdr` event arrives. +* ``IBI_PENDING``: a new IBI event arrives. +* ``DAA_PENDING``: a peripheral requested an address during the DAA. + +The peripheral has 1 external interrupt which is supposed to be connected to the +upstream interrupt controller. +The external interrupt is a logical OR-operation over the internal interrupts, +meaning if at least one of the internal interrupts is asserted the external +interrupt is asserted and only if all internal interrupts are de-asserted the +external interrupt is de-asserted. + +In addition, each interrupt has a mask bit which can be used to stop the propagation +of the internal interrupt to the external interrupt. +If an interrupt is masked it will count towards the external interrupt state as if +it were not asserted. + +The mask bits can be modified by writing to the ``IRQ_MASK`` register. +The raw interrupt status can be read from the ``IRQ_SOURCE`` register and the +combined state of the ``IRQ_MASK`` and raw interrupt state can be read from the +``IRQ_PENDING`` register: + +.. code:: + + IRQ_PENDING = IRQ_SOURCE & IRQ_MASK; + IRQ = |IRQ_PENDING; + +FIFO Threshold Interrupts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The FIFO threshold interrupts can be used by software for flow control of the +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 +watermark. + +Pending Interrupts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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`. + +An application that generated a pending interrupt instruction can use this interrupt +to be notified when the instruction has been completed. +For example, for a ``cmd`` instruction, it has completed when the ``CMDR_PENDING`` +is received. + +To de-assert the interrupt, the application needs to acknowledge its reception +by writing 1 to the associated bit at the ``IRQ_PENDING`` register. diff --git a/docs/library/i3c_controller/index.rst b/docs/library/i3c_controller/index.rst new file mode 100644 index 000000000..2e3c80b70 --- /dev/null +++ b/docs/library/i3c_controller/index.rst @@ -0,0 +1,48 @@ +.. _i3c_controller: + +I3C Controller +================================================================================ + +.. toctree:: + :hidden: + + Host Interface + Core Module + Interface + +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 +-------------------------------------------------------------------------------- + +* :ref:`i3c_controller host_interface`: Memory mapped software accessible + interface to a I3C Controller command stream and/or offload cores. +* :ref:`i3c_controller core`: Main module which executes a I3C Controller command + stream and implements the I3C bus interface logic. + +Interfaces +-------------------------------------------------------------------------------- + +* :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 `: + Linux driver for the I3C Controller. +* :ref:`i3c_controller instruction-format`: Overview of the I3C Controller + instruction format. diff --git a/docs/library/i3c_controller/interface.rst b/docs/library/i3c_controller/interface.rst new file mode 100644 index 000000000..7980e0385 --- /dev/null +++ b/docs/library/i3c_controller/interface.rst @@ -0,0 +1,433 @@ +.. _i3c_controller control-interface: + +Control Interface +================================================================================ + +The control interface exchanges data between the cores within the I3C Controller. + +The interface consists of five streams: + +* cmd: carries instructions on what procedures the I3C Controller should execute. +* cmdr: carries synchronization events and metadata from sent instructions. +* sdo: carries data to be transmitted in the I3C bus. +* sdi: carries data received from the I3C bus during a CCC or private transfer. +* ibi: carries data received from the I3C bus during an IBI. + +.. _i3c_controller instruction-format: + +Instruction Set Specification +-------------------------------------------------------------------------------- + +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: + +Command Descriptors +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The generic structure of command 0 is: + ++--------------------------------------------------------------------+ +| Command 0 | ++---------+-------+--------------------------------------------------+ +| Name | Range | Description | ++=========+=======+==================================================+ +| | 31:23 | Reserved. | ++---------+-------+--------------------------------------------------+ +| Is CCC | 22 | Indicate if it is a CCC transfer (1) or not (0). | ++---------+-------+--------------------------------------------------+ +| Bcast. | 21 | Include broadcast header in private transfer (1) | +| header | | or not (0). | ++---------+-------+--------------------------------------------------+ +| Sr | 20 | Repeated start flag, yield a Sr (1) or P (0) | +| | | at the end of the transfer. | ++---------+-------+--------------------------------------------------+ +| Buffer | 19:8 | Unsigned 12-bits payload length, direction | +| lenght | | depends on RNW value. | ++---------+-------+--------------------------------------------------+ +| DA | 7:1 | 7-bit device address (don't care in broadcast | +| | | mode). | ++---------+-------+--------------------------------------------------+ +| RNW | 0:0 | If should retrieve data from device (1) or not | +| | | (0). | ++---------+-------+--------------------------------------------------+ + +The Sr flag will be ignored if the next Command Descriptor is available at the +correct clock cycle. +Also, the software must ensure the next Command Descriptor is from the same branch +of the state machine, for example, cannot jump from a Private Transfer to a +Broadcast CCC, must always return to Start (Sr=0). +For a flowchart of the those paths, see Fig. 168, p.387 from MIPI I3C +specification\ [#f1]_. + +The structure of command 1 depends on command 0 first bits and are defined in +the following subsections. + +.. note:: + + CCC always broadcast header after an idle bus, therefore "Bcast. header" + is ignored for CCC\s. + +.. _i3c_controller ccc: + +CCC Instruction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sent with :code:`adi_i3c_controller_send_ccc_cmd`, it does a CCC transfer. +The CCC ID is defined in the *linux/i3c/ccc.h* file. + +.. note:: + + The Controller enters the DAA procedure with the ENTDAA CCC + instruction and exits when its the hardware state machine sequence finishes. + For the ENTDAA CCC buffer length should be 0, even though DAs are sent during + the procedure. + +Bits not presented in the tables are assumed 0. +When Value is filled, it means it is the required constant value for this +transfer. + ++------------------------------------------------------------------------------+ +| Command 0, CCC instruction | ++----------+-------+--------+--------------------------------------------------+ +| Name | Range | Value | Description | ++==========+=======+========+==================================================+ +| Is CCC | 22 | 1 | CCC transfer type. | ++----------+-------+--------+--------------------------------------------------+ +| Sr | 20 | | Repeated start flag, yield a Sr (1) or P (0) | +| | | | at the end of the transfer. | ++----------+-------+--------+--------------------------------------------------+ +| Buffer | 19:8 | | Unsigned 12-bits payload length, direction | +| length | | | depends on RNW value. | ++----------+-------+--------+--------------------------------------------------+ +| DA | 7:1 | | 7-bit device address (don't care in broadcast | +| | | | mode). | ++----------+-------+--------+--------------------------------------------------+ +| RNW | 0:0 | | (1) sets the payload buffer as rx and (0) as tx. | ++----------+-------+--------+--------------------------------------------------+ + ++------------------------------------------------------------------------------+ +| Command 1, CCC instruction | ++---------+-------+---------+--------------------------------------------------+ +| Name | Range | Value | Description | ++=========+=======+=========+==================================================+ +| Type | 7 | | Direct (1) or broadcast (0), except SETXTIME | +| | | | and VENDOR. | ++---------+-------+---------+--------------------------------------------------+ +| ID | 6:0 | | CCC to transfer, is the same content as the | +| | | | payload to be sent in the bus. | ++---------+-------+---------+--------------------------------------------------+ + +Private Transfer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sent with :code:`adi_i3c_controller_priv_xfers`, it does a private transfer. + +Bits not presented in the tables are assumed 0. +When Value is filled, it means it is is the required constant value for this +transfer. + ++------------------------------------------------------------------------------+ +| Command 0, private instruction | ++----------+-------+--------+--------------------------------------------------+ +| Name | Range | Value | Description | ++==========+=======+========+==================================================+ +| Is CCC | 22 | 0 | Not a CCC transfer type. | ++----------+-------+--------+--------------------------------------------------+ +| Broad. | 21 | | Include broadcast header in private transfer (1) | +| header | | | or not (0). | ++----------+-------+--------+--------------------------------------------------+ +| Sr | 20 | | Repeated start flag, yield a Sr (1) or P (0) | +| | | | at the end of the transfer. | ++----------+-------+--------+--------------------------------------------------+ +| Buffer | 19:8 | | Unsigned 12-bits payload length, direction | +| lenght | | | depends on RNW value. | ++----------+-------+--------+--------------------------------------------------+ +| DA | 7:1 | | 7-bit device address (don't care in broadcast | +| | | | mode). | ++----------+-------+--------+--------------------------------------------------+ +| RNW | 0:0 | | (1) sets the payload buffer as rx and (0) as tx. | ++----------+-------+--------+--------------------------------------------------+ + ++------------------------------------------------------------------------------+ +| Command 1, private instruction (unused) | ++---------+-------+---------+--------------------------------------------------+ +| Name | Range | Value | Description | ++=========+=======+=========+==================================================+ ++---------+-------+---------+--------------------------------------------------+ + +.. _i3c_controller cmdr: + +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 interrupton is sent to +PS, see :ref:`i3c_controller interrupts`. + +In the cmdr, the buffer length is updated with the number of bytes actually +transferred. +For sending to the peripheral (RNW=0), it will be either 0, when the peripheral +does not ACK the address, or the original buffer length, since the peripheral +cannot stop the transfer in the middle, as it can during a rx transfer (RNW=1). + +The structure of the command receipt is: + ++--------------------------------------------------------------------+ +| Command receipt | ++---------+-------+--------------------------------------------------+ +| Name | Range | Description | ++=========+=======+==================================================+ +| | 31:24 | Reserved. | ++---------+-------+--------------------------------------------------+ +| Error | 23:20 | If an error occurred during the transfer. | ++---------+-------+--------------------------------------------------+ +| Buffer | 19:8 | Unsigned 12-bits transferred payload length. | +| length | | | ++---------+-------+--------------------------------------------------+ +| Sync | 7:0 | Command synchronization. | ++---------+-------+--------------------------------------------------+ + +The Sync is a synchronization identifier that increases (then returns to 0) +at each transfer. + +Error codes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The error codes are: + ++---------------------------------------------------------------------+ +| Command receipt error codes | ++------+-----------+--------------------------------------------------+ +| Code | ID | Description | ++======+===========+==================================================+ +| 0 | NO_ERROR | No error. | ++------+-----------+--------------------------------------------------+ +| 1 | CE0_ERROR | Illegally formatted CCC. | ++------+-----------+--------------------------------------------------+ +| 4 | CE2_ERROR | No response to broadcast address. | ++------+-----------+--------------------------------------------------+ +| 6 | NACK_RESP | The peripheral did not ACK the transfer. | ++------+-----------+--------------------------------------------------+ +| 8 | UDA_ERROR | DA in CMD instruction or IBI is unknown. | ++------+-----------+--------------------------------------------------+ + +The C0-3 errors are defined by the I3C specification. +The CE0 occurs when an unexpected number of bytes are received by the controller +during in a CCC. +The CE1 and CE3 never occurs in the implementation. +CE2 and NACK_RESP are very similar, but CE2 is restricted for the first ACK of +a transfer, when the controller sends the broadcast address 7'h7e. + +On software, check bit: + +* 3: for any NACK response. +* 4: for unknown address. + +.. _i3c_controller ibi: + +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 interrupt to the +PS. + +The structure of the received IBI is: + ++--------------------------------------------------------------------+ +| In-band interrupt | ++---------+-------+--------------------------------------------------+ +| Name | Range | Description | ++=========+=======+==================================================+ +| | 31:23 | Reserved. | ++---------+-------+--------------------------------------------------+ +| DA | 23:17 | Dynamic address. | ++---------+-------+--------------------------------------------------+ +| | 16 | Reserved. | ++---------+-------+--------------------------------------------------+ +| MDB | 15:8 | Mandatory data byte. | ++---------+-------+--------------------------------------------------+ +| Sync | 7:0 | IBI synchronization. | ++---------+-------+--------------------------------------------------+ + +.. note:: + + Additional bytes are not supported. + +The software interprets the mandatory data bytes, some by the I3C controller +driver and some by the peripheral driver. +The MIPI pre-defines and reserves some values for the MDB, +which are kept updated at the I3C MDB Values implementers table\ [#f0]_. + +There is two configurations for the IBI, to enable accepting IBI\s +and listen to peripheral IBI requests. + +If IBI is disabled, the controller will NACK IBI requests. +If enabled, the controller will ACK the IBI request and receive the +MDB. +In both cases, the controller will proceed with the cmd transfer after resolving +the IBI request (since the request occur during the header broadcast). + +SDI and SDO +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +During the serialization of the 32-bits FIFOs into 1-byte packages, +if the command descriptor describes a payload of length 5, the controller will +send the 4 bytes of the element at the top of SDO FIFO's stack, then the +left-most byte of the next SDO FIFO's element. + +For example, consider the following data: + +.. code:: c + + u32 data[2] = {0x78563412, 0xFE}; + +The table below exemplifies the sequence ("D" is discarded): + ++----------------------------------------------------+ +| Payload transfer, length = 5 | ++--------------------+-------+-------+-------+-------+ +| SDO FIFO Stack | Byte3 | Byte2 | Byte1 | Byte0 | ++====================+=======+=======+=======+=======+ +| #0 | 0x78 | 0x56 | 0x34 | 0x12 | ++--------------------+-------+-------+-------+-------+ +| #1 | D | D | D | 0xFE | ++--------------------+-------+-------+-------+-------+ + +For the SDI FIFO, considering the I3C bus sends the most significant byte first, +a transfer of 6 bytes would fill the SDI FIFO as follows: + ++----------------------------------------------------+ +| Payload transfer, length = 5 | ++--------------------+-------+-------+-------+-------+ +| SD1 FIFO Stack | Byte3 | Byte2 | Byte1 | Byte0 | ++====================+=======+=======+=======+=======+ +| #0 | 0 | 1 | 2 | 3 | ++--------------------+-------+-------+-------+-------+ +| #1 | 4 | D | D | D | ++--------------------+-------+-------+-------+-------+ + +.. _i3c_controller daa: + +Dynamic Address Assignment +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The Dynamic Address Assignment (DAA) is a procedure that is entered through the +ENTDAA CCC, see :ref:`i3c_controller ccc` for the instruction itself. + +.. attention:: + + The ``SDO`` FIFO **must** be empty before entering the DAA. + +During the DAA, after a peripheral acknowledges the procedure and sends its +PID, BCR, and DCR, the controller triggers the ``DAA_PENDING`` interrupt, +requesting a Dynamic Address (DA). +The software reads twice the SDI FIFO to acquire the PID, BCR and DCR (optional), +and writes a DA with T-bit to the MSB of SDO FIFO: + +.. code:: verilog + + reg [6:0] da; + reg [31:0] sdo; + sdo <= {da, ~^da, 24'b0} // DA + T-bit + don't care + +Then, it clears the ``PENDING_DAA`` interrupt (see :ref:`i3c_controller interrupts`). + +The controller repeats the procedure for every device that requests an address +during the DAA, and also the software resolves every subsequent interrupt. + +The read of the SDI FIFO is optional because the software can either: + +* Seek the desired DA using the received PID. +* Assign another DA using the ``GETPID`` and ``SETNEWDA`` CCCs at a latter opportunity. + +The second approach has the advantaged of stalling the bus for a shorter period of +time, while the first guarantees the target will be assigned the desired address. + +Word Command Interface +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The word command interface is an internal interface between the Framing/DAA and +the Word modules, it is based on the patterns of the I3C specifications, allowing +to yield events as commands, for example, broadcasting the I3C 7'h7e and waiting +the ACK. + +For cohesion, this interface uses the abbreviations from Fig. 168, p.397 from +MIPI I3C specification\ [#f1]_, e.g. the last example is BCAST_7E_W. + +The command has two fields: header and body, the header is an enumeration of +the possible commands, and body is a 1-byte that depends on the header. + +Configuration Registers +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. _i3c_controller offload-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 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 5-bit wide address, 32-bit data dual access block ram is used to store the +offload commands and 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 +-------------------------------------------------------------------------------- + +To ease debugging with the ILA core, the following signals are recommended to be +sampled: + +* ``bit_mod:rx_raw``: SDI input after one register sampling (data). +* ``bit_mod:scl``: SCL output (data). +* ``word:sm``: Current Word Command state (data). +* ``framing:cmdp_ccc_id``: CCC ID without broadcast field (trigger, data). + +.. warning:: + + To not sample the ``bit_mod:sdo`` signal, it will alter the SDA I/O logic and + the core won't work properly. + +The trigger at ``cmd_parser:cmdp_ccc_id`` allows to start the capture at the start +of the CCC of interest, then the other three debug signals provide a clear view of +the bus and the state of the state machine. + +For the depth of the ILA core, between 4096 and 8192 is sufficient to sample whole +transfers. +In particular, 8192 with "Trigger position on window" set to 0 is sufficient to sample +a whole ``ENTDAA`` with 1 peripheral requesting address. + +.. rubric:: Footnotes + +.. [#f0] `I3C MDB Values implementers table `_ +.. [#f1] `I3C Basic Specification v1.1.1 `_ diff --git a/docs/library/index.rst b/docs/library/index.rst index bb7060ef8..65fcf23e5 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -15,6 +15,7 @@ Contents :maxdepth: 1 axi_dmac/index + i3c_controller/index spi_engine/index jesd204/index axi_adxcvr/index diff --git a/docs/regmap/adi_regmap_i3c_controller.txt b/docs/regmap/adi_regmap_i3c_controller.txt new file mode 100644 index 000000000..4ad74dfa6 --- /dev/null +++ b/docs/regmap/adi_regmap_i3c_controller.txt @@ -0,0 +1,641 @@ +TITLE +I3C Controller (i3c_controller_host_interface) +i3c_controller_host_interface +ENDTITLE + +############################################################################################ +############################################################################################ + +REG +0x00 +VERSION +Version of the peripheral. Follows semantic versioning. Current version 0.01.00 +ENDREG + +FIELD +[31:16] 0x00 +VERSION_MAJOR +RO +ENDFIELD + +FIELD +[15:8] 0x01 +VERSION_MINOR +RO +ENDFIELD + +FIELD +[7:0] 0x00 +VERSION_PATCH +RO +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x01 +DEVICE_ID +ENDREG + +FIELD +[31:0] ''ID'' +DEVICE_ID +RO +Value of the ID configuration parameter. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x02 +SCRATCH +ENDREG + +FIELD +[31:0] 0x00000000 +SCRATCH +RW +Scratch register useful for debug. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x10 +ENABLE +ENDREG + +FIELD +[0] 0x1 +ENABLE +RW +Enable register. If the enable bit is set to 1 the internal state of the peripheral is reset. +For proper operation, the bit needs to be set to 0. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x20 +IRQ_MASK +ENDREG + +FIELD +[7] 0x0 +DAA_PENDING +RW +If set to 0 the DAA_PENDING interrupt is masked. +ENDFIELD + +FIELD +[6] 0x0 +IBI_PENDING +RW +If set to 0 the IBI_PENDING interrupt is masked. +ENDFIELD + +FIELD +[5] 0x0 +CMDR_PENDING +RW +If set to 0 the CMDR_PENDING interrupt is masked. +ENDFIELD + +FIELD +[4] 0x0 +IBI_ALMOST_FULL +RW +If set to 0 the IBI_ALMOST_FULL interrupt is masked. +ENDFIELD + +FIELD +[3] 0x0 +SDI_ALMOST_FULL +RW +If set to 0 the SDI_ALMOST_FULL interrupt is masked. +ENDFIELD + +FIELD +[2] 0x0 +SDO_ALMOST_EMPTY +RW +If set to 0 the SDO_ALMOST_EMPTY interrupt is masked. +ENDFIELD + +FIELD +[1] 0x0 +CMDR_ALMOST_FULL +RW +If set to 0 the CMDR_ALMOST_FULL interrupt is masked. +ENDFIELD + +FIELD +[0] 0x0 +CMD_ALMOST_EMPTY +RW +If set to 0 the CMD_ALMOST_EMPTY interrupt is masked. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x21 +IRQ_PENDING +ENDREG + +FIELD +[31:0] 0x00000000 +IRQ_PENDING +RW +Pending IRQs with mask. +Write 1 at the CMDR_PENDING bit to clear it. +For CMDR_PENDING and IBI_PENDING, will be cleared if the FIFOs are also empty. +For DAA_PENDING, will be cleared if the SDO FIFO is not empty, that means, got dynamic +address in the pipeline. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x22 +IRQ_SOURCE +ENDREG + +FIELD +[31:0] 0x00000000 +IRQ_SOURCE +RO +Pending IRQs without mask. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x30 +CMD_FIFO_ROOM +ENDREG + +FIELD +[31:0] 0xXXXXXXXX +CMD_FIFO_ROOM +RO +Number of free entries in the CMD FIFO. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x31 +CMDR_FIFO_LEVEL +ENDREG + +FIELD +[31:0] 0x00000000 +CMDR_FIFO_LEVEL +RO +Number of valid entries in the CMDR FIFO. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x32 +SDO_FIFO_ROOM +ENDREG + +FIELD +[31:0] 0xXXXXXXXX +SDO_FIFO_ROOM +RO +Number of free entries in the SDO FIFO. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x33 +SDI_FIFO_LEVEL +ENDREG + +FIELD +[31:0] 0x00000000 +SDI_FIFO_LEVEL +RO +Number of valid entries in the serial-data-in FIFO. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x34 +IBI_FIFO_LEVEL +ENDREG + +FIELD +[31:0] 0x00000000 +IBI_FIFO_LEVEL +RO +Number of valid entries in the in-bus-interrupt FIFO. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x35 +CMD_FIFO +Command FIFO register. Writing to this register inserts an entry into the CMD FIFO. +Writing to this register when the CMD FIFO is full has no effect and the written entry +is discarded. Reading from this register always returns 0x00000000. +The Software is responsive for a valid sequence of commands. +If the peripheral does not ACK when required during a command, the procedure exits and the +next command in the FIFO is interpreted. +See :ref:`i3c_controller instruction-format` for the structure of the command. +ENDREG + +FIELD +[22] 0xX +CMD_IS_CCC +WO +Indicate if it is a CCC transfer (1) or not (0). +ENDFIELD + +FIELD +[21] 0xX +CMD_BCAST_HEADER +WO +Include broadcast header in private transfer (1) or not (0). +ENDFIELD + +FIELD +[20] 0xX +CMD_SR +WO +Repeated start flag, yield a Sr (1) or P (0) at the end of the transfer. +ENDFIELD + +FIELD +[19:8] 0xXXX +CMD_BUFFER_LENGHT +WO +Unsigned 12-bits payload length, direction depends on RNW value. +ENDFIELD + +FIELD +[7:1] 0xXX +CMD_DA +WO +7-bit device address (don’t care in broadcast mode). +ENDFIELD + +FIELD +[0] 0xX +CMD_RNW +WO +If should retrieve data from device (1) or not (0). +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x36 +CMDR_FIFO +CMDR FIFO register. Reading from this register removes the first entry from the CMDR FIFO. +Reading this register when the CMDR FIFO is empty will return undefined data. +Writing to it has no effect. +ENDREG + +FIELD +[23:0] 0x?? +CMDR_FIFO_ERROR +RO +If an error occurred during the transfer. +ENDFIELD + +FIELD +[19:8] 0x?? +CMDR_FIFO_BUFFER_LENGTH +RO +Unsigned 12-bits transferred payload length. +ENDFIELD + +FIELD +[7:0] 0x?? +CMDR_FIFO_SYNC +RO +Command synchronization. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x37 +SDO_FIFO +SDO FIFO register. Writing to this register inserts an entry into the SDO FIFO. +Writing to this register when the SDO FIFO is full has no effect and the written entry +is discarded. Reading from this register always returns 0x00000000. +ENDREG + +FIELD +[31:24] 0xXX +SDO_FIFO_BYTE_3 +RO +ENDFIELD + +FIELD +[23:16] 0xXX +SDO_FIFO_BYTE_2 +RO +ENDFIELD + +FIELD +[15:8] 0xXX +SDO_FIFO_BYTE_1 +RO +ENDFIELD + +FIELD +[7:0] 0xXX +SDO_FIFO_BYTE_0 +RO +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x38 +SDI_FIFO +SDI FIFO register. Reading from this register removes the first entry from the SDI FIFO. +Reading this register when the SDI FIFO is empty will return undefined data. +Writing to it has no effect. +ENDREG + +FIELD +[31:0] 0xXXXXXXXX +SDI_FIFO +RO +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x39 +IBI_FIFO +IBI FIFO register. Reading from this register removes the first entry from the IBI FIFO. +Reading this register when the IBI FIFO is empty will return undefined data. +Writing to it has no effect. +ENDREG + +FIELD +[23:17] 0xXX +IBI_FIFO_DA +RO +IBI Dynamic address. +ENDFIELD + +FIELD +[15:8] 0xXX +IBI_FIFO_MDB +RO +IBI MDB, if the peripheral's BCR[2] is Low, the field is ignored. +ENDFIELD + +FIELD +[7:0] 0xXX +IBI_FIFO_SYNC +RO +Synchronization number. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x3a +FIFO_STATUS +ENDREG + +FIELD +[2] 0x1 +SDI_EMPTY +RO +If there is no element to be read in the SDI FIFO. +ENDFIELD + +FIELD +[1] 0x1 +IBI_EMPTY +RO +If there is no element to be read in the IBI FIFO. +ENDFIELD + +FIELD +[0] 0x1 +CMDR_EMPTY +RO +If there is no element to be read in the CMDR FIFO. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x40 +OPS +Configure the operation of the controller. +ENDREG + +FIELD +[7] 0x0 +OPS_STATUS_NOP +RO +This bit is set to 1 when the bus is not executing any procedure. +It is not idle bus condition since it set right after the Stop. +ENDIELD + +FIELD +[6:5] 0x0 +OPS_SPEED_GRADE +RW +Sets the speed grade in push-pull mode. +Speed with 100MHz driver clock are: +00: 1.56MHz (default) +01: 3.12MHz +10: 6.25MHz +11: 12.50MHz +ENDFIELD + +FIELD +[4:1] 0x0 +OPS_OFFLOAD_LENGTH +RW +Offload commands length. +ENDFIELD + +FIELD +[0] 0x0 +OPS_MODE +RW +Set 0 to direct transfers, 1 to offload operation. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x50 +IBI_CONFIG +Configure the In-Band Interrupt (IBI) feature. +ENDREG + +FIELD +[1] 0x0 +IBI_CONFIG_AUTO +WO +Set this bit to listen for IBI requests (when a peripheral pulls SDA Low during quiet times). +After the IBI request is resolved, the controller returns to idle, since it is was not doing +a cmd transfer. +IBI_CONFIG_ENABLE must be set 1. +ENDFIELD + +FIELD +[0] 0x0 +IBI_CONFIG_ENABLE +WO +Set this bit to accept (ACK) IBI requests. +If disabled, the controller will NACK IBI requests. +If enabled, the controller will ACK the IBI request and receive the MDB. +In both cases, the controller will proceed with the cmd transfer after resolving the IBI +request. +Accepted IBIs fill the IBI_FIFO and generate an interruption in the PS. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x60 +DEV_CHAR +Holds devices characteristics that are looked-up during execution. +The content is written only by software. +To read an address, write the address with DEV_CHAR_0_WEN 0 and then read. +ENDREG + +FIELD +[15:9] 0x00 +DEV_CHAR_ADDR +RW +Device address to apply DEV_CHAR[3:0]. +ENDFIELD + +FIELD +[8] 0xX +DEV_CHAR_WEN +W +Enable write of the fields. +ENDFIELD + +FIELD +[3] 0x0 +DEV_CHAR_HAS_IBI_MDB +RW +Indicates if the device sends an MDB during the IBI. +0 does not, 1 does. +ENDFIELD + +FIELD +[2] 0x0 +DEV_CHAR_IS_IBI_CAPABLE +RW +Indicates if the device can send IBI. +0 does not, 1 does. +ENDFIELD + +FIELD +[1] 0x0 +DEV_CHAR_IS_ATTACHED +RW +Indicate if the device is attached. +ENDFIELD + +[0] 0x0 +DEV_CHAR_IS_I2C +RW +Indicates if the device is I²C. +0 is I3C device, 1 is I²C device. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0xb0 + 0x01*n +OFFLOAD_CMD_n +Offload command memory. Write commands in sequence to these addresses and update the +OFFLOAD_CMD_LENGTH register. +ENDREG + +FIELD +[31:0] 0x00 +OFFLOAD_CMD +RW +The command to the I3C controller to execute. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0xc0 + 0x01*n +OFFLOAD_SDO_n +Offload SDO memory. +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] 0x00 +OFFLOAD_SDO_BYTE_3 +RO +ENDFIELD + +FIELD +[23:16] 0x00 +OFFLOAD_SDO_BYTE_2 +RO +ENDFIELD + +FIELD +[15:8] 0x00 +OFFLOAD_SDO_BYTE_1 +RO +ENDFIELD + +FIELD +[7:0] 0x00 +OFFLOAD_SDO_BYTE_0 +RO +ENDFIELD + +############################################################################################ +############################################################################################