zcy
/
pluto_hdl_adi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: i3c_controller: Add documentation 

Signed-off-by: Jorge Marques <jorge.marques@analog.com>
main
Jorge Marques 2024-01-25 14:22:46 -03:00 committed by Jorge Marques
parent e646e61ce4
commit 15ff99a9bd
6 changed files with 1317 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
docs/library/i3c_controller/i3c_controller_core.rst Normal file
View File

@ -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
--------------------------------------------------------------------------------

150
docs/library/i3c_controller/i3c_controller_host_interface.rst Normal file
View File

@ -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.

48
docs/library/i3c_controller/index.rst Normal file
View File

@ -0,0 +1,48 @@
.. _i3c_controller:
I3C Controller
================================================================================
.. toctree::
:hidden:
Host Interface<i3c_controller_host_interface>
Core Module<i3c_controller_core>
Interface<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 <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.

433
docs/library/i3c_controller/interface.rst Normal file
View File

@ -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 <https://www.mipi.org/MIPI_I3C_mandatory_data_byte_values_public>`_
.. [#f1] `I3C Basic Specification v1.1.1 <https://www.mipi.org/specifications/i3c-sensor-specification>`_

1
docs/library/index.rst
View File

@ -15,6 +15,7 @@ Contents
:maxdepth: 1 :maxdepth: 1
axi_dmac/index axi_dmac/index
i3c_controller/index
spi_engine/index spi_engine/index
jesd204/index jesd204/index
axi_adxcvr/index axi_adxcvr/index

641
docs/regmap/adi_regmap_i3c_controller.txt Normal file
View File

@ -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
############################################################################################
############################################################################################