diff --git a/docs/index.rst b/docs/index.rst index 31126fb53a9..85e9dc20fdb 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,8 +13,9 @@ HDL Reference Designs :caption: Libraries :hidden: - library/spi_engine/index library/axi_dmac/index + library/spi_engine/index + library/i3c_controller/index .. attention:: 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 00000000000..5412ace7e66 --- /dev/null +++ b/docs/library/i3c_controller/i3c_controller_core.rst @@ -0,0 +1,39 @@ +.. _i3c_controller core: + +I3C Controller Core +================================================================================ + +.. symbolator:: ../../../library/i3c_controller/i3c_controller_core/i3c_controller_core.v + :caption: i3c_controller_core + +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. + +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:: + +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 00000000000..af6f90fba8f --- /dev/null +++ b/docs/library/i3c_controller/i3c_controller_host_interface.rst @@ -0,0 +1,67 @@ +.. _i3c_controller host_interface: + +I3C Controller Host Interface +================================================================================ + +.. symbolator:: ../../../library/i3c_controller/i3c_controller_host_interface/i3c_controller_host_interface.v + :caption: i3c_controller_host_interface + +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 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. + +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:: + +Register Map +-------------------------------------------------------------------------------- + +.. hdl-regmap:: + :name: i3c_controller_host_interface + +Theory of Operation +-------------------------------------------------------------------------------- + +FIFOs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +Synchronization Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +Interrupts +-------------------------------------------------------------------------------- + + +FIFO Threshold Interrupts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SYNC_EVENT Interrupt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/library/i3c_controller/index.rst b/docs/library/i3c_controller/index.rst new file mode 100644 index 00000000000..26c678365b3 --- /dev/null +++ b/docs/library/i3c_controller/index.rst @@ -0,0 +1,35 @@ +.. _i3c_controller: + +I3C Controller +================================================================================ + +.. toctree:: + :hidden: + + Host Interface + Core Module + Interface + +I3C Controller is subset of the I3C specification to interface peripheral such +as ADCs through I3C. + +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`: SPI Engine command stream. +* :ref:`i3c_controller offload-control-interface`: Program the command stream + stored in a offload module. + +Software +-------------------------------------------------------------------------------- + +* :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 00000000000..da2025a2cd9 --- /dev/null +++ b/docs/library/i3c_controller/interface.rst @@ -0,0 +1,398 @@ +.. _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 instruction set (command +0 and command 1). + +Transfer modes +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Transfer modes, abbreviated as XMIT, are different methods to generate transfers. + +There are four modes: + +* 0: Burst with static sub-address prefixing the first byte. +* 1: Prefix each byte with incremented-by-1 sub-address. +* 2: Prefix each byte with sub-address. +* 3: Burst without sub-address + +Only mode 3 is implemented. +For the others modes, one shall implement a register to store the sub-address. + +.. _i3c_controller command_descriptors: + +Command descriptors +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The generic structure of command 0 is: + ++--------------------------------------------------------------------+ +| Command 0 | ++---------+-------+--------------------------------------------------+ +| Name | Range | Description | ++=========+=======+==================================================+ +| | 31:31 | Not implemented, DDR related. | ++---------+-------+--------------------------------------------------+ +| Is CCC | 30:30 | Indicate if it is a CCC transfer (1) or not (0). | ++---------+-------+--------------------------------------------------+ +| Bcast. | 29:29 | Include broadcast header in private transfer (1) | +| header | | or not (0). | ++---------+-------+--------------------------------------------------+ +| XMIT | 28:27 | Private transfer transmit mode. | ++---------+-------+--------------------------------------------------+ +| | 26:26 | Reserved. | ++---------+-------+--------------------------------------------------+ +| Sr | 25:25 | Repeated start flag, yield a Sr (1) or P (0) | +| | | at the end of the transfer. | ++---------+-------+--------------------------------------------------+ +| | 24:24 | 10-bit I2C address (1) (Not implemented) or | +| | | 7-bit address (0). | ++---------+-------+--------------------------------------------------+ +| Buffer | 23:12 | Unsigned 12-bits payload length, direction | +| lenght | | depends on RNW value. | ++---------+-------+--------------------------------------------------+ +| | 11:08 | Unused. | ++---------+-------+--------------------------------------------------+ +| DA | 07:01 | 7-bit device address (don't care in broadcast | +| | | mode). | ++---------+-------+--------------------------------------------------+ +| RNW | 00:00 | 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 Descripto is from the same branch +of the state machine, for example, cannot jump from a Private Transfer to a +Broadcast CCC, must allways 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. + +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. + +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, CCC instruction | ++----------+-------+--------+--------------------------------------------------+ +| Name | Range | Value | Description | ++==========+=======+========+==================================================+ +| Is CCC | 30:30 | 1 | CCC transfer type. | ++----------+-------+--------+--------------------------------------------------+ +| Sr | 25:25 | | Repeated start flag, yield a Sr (1) or P (0) | +| | | | at the end of the transfer. | ++----------+-------+--------+--------------------------------------------------+ +| Buffer | 23:12 | | Unsigned 12-bits payload length, direction | +| length | | | depends on RNW value. | ++----------+-------+--------+--------------------------------------------------+ +| DA | 07:01 | | 7-bit device address (don't care in broadcast | +| | | | mode). | ++----------+-------+--------+--------------------------------------------------+ +| RNW | 00:00 | | (1) sets the payload buffer as rx and (0) as tx. | ++----------+-------+--------+--------------------------------------------------+ + ++------------------------------------------------------------------------------+ +| Command 1, CCC instruction | ++---------+-------+---------+--------------------------------------------------+ +| Name | Range | Value | Description | ++=========+=======+=========+==================================================+ +| Type | 07:07 | | Direct (1) or broadcast (0), except SETXTIME | +| | | | and VENDOR. | ++---------+-------+---------+--------------------------------------------------+ +| ID | 06:00 | | 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 | 30:30 | 0 | Not a CCC transfer type. | ++----------+-------+--------+--------------------------------------------------+ +| Broad. | 29:29 | | Include broadcast header in private transfer (1) | +| header | | | or not (0). | ++----------+-------+--------+--------------------------------------------------+ +| XMIT | 28:27 | 3 | Private transfer transmit mode, burst without | +| | | | sub-address. | ++----------+-------+--------+--------------------------------------------------+ +| Sr | 25:25 | | Repeated start flag, yield a Sr (1) or P (0) | +| | | | at the end of the transfer. | ++----------+-------+--------+--------------------------------------------------+ +| Buffer | 23:12 | | Unsigned 12-bits payload length, direction | +| lenght | | | depends on RNW value. | ++----------+-------+--------+--------------------------------------------------+ +| DA | 07:01 | | 7-bit device address (don't care in broadcast | +| | | | mode). | ++----------+-------+--------+--------------------------------------------------+ +| RNW | 00:00 | | (1) sets the payload buffer as rx and (0) as tx. | ++----------+-------+--------+--------------------------------------------------+ + ++------------------------------------------------------------------------------+ +| Command 1, private instruction (unused) | ++---------+-------+---------+--------------------------------------------------+ +| Name | Range | Value | Description | ++=========+=======+=========+==================================================+ ++---------+-------+---------+--------------------------------------------------+ + +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 +PS. + +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:28 | Reserved. | ++---------+-------+--------------------------------------------------+ +| Error | 27:24 | If an error occurred during the transfer. | ++---------+-------+--------------------------------------------------+ +| | 23:20 | Reserved. | ++---------+-------+--------------------------------------------------+ +| Buffer | 19:08 | Unsigned 12-bits transferred payload length. | +| length | | | ++---------+-------+--------------------------------------------------+ +| Sync | 07:00 | Command synchronization. | ++---------+-------+--------------------------------------------------+ + +The Sync is a synchronization identifier that increases (then returns to 0) +at each transfer. + +The error codes are: + ++---------------------------------------------------------------------+ +| Command receipt error codes | ++------+-----------+--------------------------------------------------+ +| Code | ID | Description | ++======+===========+==================================================+ +| 0 | NO_ERROR | No error. | ++------+-----------+--------------------------------------------------+ +| 1 | CE0_ERROR | Illegally formatted CCC. | ++------+-----------+--------------------------------------------------+ +| 2 | CE1_ERROR | Monitoring error. | ++------+-----------+--------------------------------------------------+ +| 3 | CE2_ERROR | No response to broadcast address. | ++------+-----------+--------------------------------------------------+ +| 9 | NACK_RESP | The peripheral did not ACK the transfer. | ++------+-----------+--------------------------------------------------+ + +The C01-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 never occurs in the implementation, is listed here because it is listed +in the linux absctraction header for I3C. +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. + +.. todo:: + + Implement NACK_RESP or drop it. + +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 +PS. + +The structure of the received IBI is: + ++--------------------------------------------------------------------+ +| In-band interrupt | ++---------+-------+--------------------------------------------------+ +| Name | Range | Description | ++=========+=======+==================================================+ +| | 31:23 | Reserved. | ++---------+-------+--------------------------------------------------+ +| DA | 23:17 | Dynamic address. | ++---------+-------+--------------------------------------------------+ +| | 16:16 | Reserved. | ++---------+-------+--------------------------------------------------+ +| MDB | 15:08 | Mandatory data byte. | ++---------+-------+--------------------------------------------------+ +| Sync | 07:00 | 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The SDI FIFO (Rx) and SDO FIFO (Tx) are MSB left-aligned. +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 most +significant byte of the next SDO FIFO's element. + +The table below exemplifies the sequence, with each byte numbered by it transfer +sequence (lowest first), "D" is discarted. + ++----------------------------------------------------+ +| Payload transfer, length = 5 | ++--------------------+-------+-------+-------+-------+ +| SDO FIFO Stack | Byte3 | Byte2 | Byte1 | Byte0 | ++====================+=======+=======+=======+=======+ +| #0 | 0 | 1 | 2 | 3 | ++--------------------+-------+-------+-------+-------+ +| #1 | 4 | D | D | D | ++--------------------+-------+-------+-------+-------+ + +The same sequence applies to the SDI FIFO, it is important to remember that +software is responsible to interpret the SDI FIFO stack and properly handle the +unfilled/discarded bytes. + + +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 cohersion, this interface uses the abbreviations from Fig. 168, p.397 from +MIPI I3C specificatiom\ [#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-control-interface: + +Offload control 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 emmited 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 tranfers. + +The block ram device characteristics +-------------------------------------------------------------------------------- + +A 16-bit wide address, 32-bit data dual access block ram is used to store the +device characteristics. + +The registers are mapped at [5:4] LSB: + +.. list-table:: + :header-rows: 1 + + * - Value [6:5] + - Description + * - ``00`` + - Device characteristics 0 + * - ``01`` + - Device characteristics 1 + * - ``10`` + - Device characteristics 2 + * - ``11`` + - Reserved + +The block ram offload +-------------------------------------------------------------------------------- + +A 16-bit wide address, 32-bit data dual access block ram is used to store the +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 + +.. rubric:: Footnotes + +.. [#f0] `I3C MDB Values implementers table `_ +.. [#f1] `I3C Basic Specification v1.1.1 `_ diff --git a/docs/regmap/adi_regmap_i3c_controller.txt b/docs/regmap/adi_regmap_i3c_controller.txt index e3d26b6a78a..d782192ff95 100644 --- a/docs/regmap/adi_regmap_i3c_controller.txt +++ b/docs/regmap/adi_regmap_i3c_controller.txt @@ -1,5 +1,6 @@ TITLE -I3C Controller (axi_i3c_controller) +I3C Controller (i3c_controller_host_interface) +i3c_controller_host_interface ENDTITLE ############################################################################################ @@ -248,12 +249,13 @@ 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 Instruction Set Specification in the wiki documentation for the structure of the command. -ENDFIELD +ENDREG + FIELD [31:0] 0x?? CMD_FIFO -The command to the I3C controller to execute. WO +The command to the I3C controller to execute. ENDFIELD ############################################################################################ @@ -283,6 +285,7 @@ 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] 0x?? @@ -476,23 +479,23 @@ ENDREG FIELD [0:0] 0x??? DEV_CHAR_0_n_DA_PARIETY -Pariety of the dynamic address. RW +Pariety of the dynamic address. ENDFIELD FIELD [7:1] 0x??? DEV_CHAR_0_n_DA -Dynamic address. RW +Dynamic address. ENDFIELD FIELD [8:8] 0x1 DEV_CHAR_0_n_IS_I3C +RW Indicates if the device is an I3C device. Since only I3C is supported, will always be 1. -RW ENDFIELD ############################################################################################ @@ -510,8 +513,8 @@ ENDREG FIELD [31:0] 0x??? DEV_CHAR_1_n_PID_1 -32-MSB from the PID. RW +32-MSB from the PID. ENDFIELD ############################################################################################ @@ -529,25 +532,25 @@ ENDREG FIELD [7:0] 0x??? DEV_CHAR_2_n_DCR/LVR +RW Stores the DCR of I3C devices or LVR of I2C devices. LVR should only be written, and DCR only be read. Currently, LVR has no effect. -RW ENDFIELD FIELD [15:8] 0x??? DEV_CHAR_2_n_BCR -Should only be read. RW +Should only be read. ENDFIELD FIELD [31:16] 0x??? DEV_CHAR_2_n_PID_0 +RW 16-LSB from the PID. Should only be read. -RW ENDFIELD ############################################################################################ @@ -560,22 +563,22 @@ ENDREG FIELD [15:0] 0x?? -DEV_CTRL +DEVS_CTRL +RW Slots for peripherals, each HIGH bit represents a peripherals attached. The index match the DEV_CHAR_*_ indexes. The Controller, index 0, is set to HIGH when a DA is written to DEV_CHAR_0_0, while the others peripherals are set HIGH when the peripherals actually receives the DA during the DAA. The state can also be overwritten to explicit attach device (e.g. has static addr). -RW ENDFIELD FIELD [31:16] 0x?? -DEV_CLR +DEVS_CLR +WO Write the index of a peripheral (offset by 16) bit to clear its slot. The stored value in DEV_CHAR_*_* is not affected by this register. -WO ENDFIELD ############################################################################################