# I3C Transactions

## About the project

This HLA combines a stream of I3C events into multi-byte messages or transactions.

Transactions are delimited as defined in section 4.1 I3C Fundamental Principles of the MIPI I3C Basic specification (v1.1.1)

![I3C communication flow](./I3C_communication_flow.png)

This HLA can support the following types of transactions
* I2C Transactions / I3C Transaction not marked with the I3C Broadcast reserved byte (identified as 'Messages')
* I3C Transactions
* I3C Direct CCC Transactions
* I3C Broadcast CCC Transactions
* I3C HDR-DDR Transactions
* I3C HDR-DDR Direct CCC Transactions
* I3C HDR-DDR Broadcast CCC Transactions

This HLA is branched from Mark Garrison's I2C Transactions HLA

## Protocols over I3C

The I3C Transaction HLA gives the option to decode further communication protocols that exchange information over I3C.

The HLA can support the following second layer protocols:
* SPD
* MCTP

### SPD

This analyzer implements the SPD protocol described in the **SPD5118 Hub and Serial Presence Detect Device Standar** specified by JEDEC in the [JESD300-5B standar](https://www.jedec.org/document_search?search_api_views_fulltext=JESD300-5B).

The SPD HLA supports the next transactions:
* I2C HUB Device:
  * Write Command Data Packet
  * Read Command Data Packet
  * Read Command Data Packet with Default Address Pointer Mode
* I2C Local device:
  * Write Command Data Packet
    * TS0
    * TS1
    * PMIC
    * RCD
  * Read Command Data Packet
    * TS0
    * TS1
    * PMIC
    * RCD
* I3C HUB Device:
  * Write Command Data Packet (does not distinguish between PEC enable or disable)
  * Write Command Data Packet IBI Header (does not distinguish between PEC enable or disable)
  * Read Command Data Packet (does not distinguish between PEC enable or disable)
  * Read Command Data Packet IBI Header (does not distinguish between PEC enable or disable)
  * Read Command Data Packet with Read Address Pointer Mode (does not distinguish between PEC enable or disable)
* I3C Local device:
  * Write Command Data Packet (does not distinguish between PEC enable or disable)
    * TS0
    * TS1
    * PMIC
    * RCD
  * Read Command Data Packet (does not distinguish between PEC enable or disable)
    * TS0
    * TS1
    * PMIC
    * RCD

The following is a flow diagram of the logic behind the SPD decoding SDR mode:

![SPD-hla-FlowDiagram](./SecondLayerHLAs/SPDanalyzer/SPD_HLA_FlowDiagram.png)

### MCTP

This analyzer implements the **Management Component Transport Protocol (MCTP) over I3C** as specified in **DSP0233 v1.0.1** by DMTF.

MCTP messages may span multiple I3C transactions (packets). To visualize both levels of detail simultaneously, add the **I3C Transactions** HLA twice to your Saleae project with different options:

| Option | Description |
|---|---|
| **MCTP Packets** | Emits one bubble per I3C transaction, showing individual packet headers (SOM/EOM flags, sequence number, tag, EIDs) and payload bytes. |
| **MCTP Messages** | Emits one bubble per reassembled MCTP message, spanning from the first packet (SOM) to the last packet (EOM). Intermediate packets are suppressed so the bubble correctly spans the full message duration. |

**Frame types emitted:**

| Frame type | Emitted by | Description |
|---|---|---|
| `MCTP Packet` | MCTP Packets | One fully-decoded I3C/MCTP transaction |
| `MCTP Message` | MCTP Messages | Reassembled multi-packet message (SOM→EOM) |
| `MCTP Incomplete Message` | Both | Aborted or orphaned message (missing EOM) |
| `MCTP Seq Error` | Both | Packet received out of sequence |
| `MCTP Pending Read Notification` | Both | IBI with MDB=0xAE (target has MCTP data ready) |

**Key fields displayed per packet:** Source EID, Destination EID, Message Type, SOM/EOM flags, Sequence Number, Tag, PEC status, payload bytes.

**PEC verification:** The PEC byte is verified as CRC-8 SMBus over the I3C wire address byte followed by all MCTP packet bytes (per DSP0233 §8.2).

## Quick start:

### Getting started

To add the **I3C Transactions** HLA to Logic software, follow the instructions described in Saleae's [Software Extension -> Extension Installation page](https://support.saleae.com/extensions/installing-extensions).

### Software:

The HLA has 3 main components:

#### The main [HighLevelAnalyzer.py](./HighLevelAnalyzer.py)
This class follows the architecture described by Saleae in the [High-Level-Analyzer wiki](https://support.saleae.com/extensions/high-level-analyzer-extensions), and with the help of the decoders, it can give context to groups of incoming frames. The high-level analyzer works as a decoder handler, giving them frames to interpret, and using its output to show the contextualized frames and changing automatically between SDR and HDR-DDR.

#### Decoders
The decoders take the incoming frames, and using its state machine, can group them into a context-aware *transaction frame*, that describes the purpose of the frames and gives a holistic view of the transaction itself.
To enable SDR and HDR frame support, 2 decoders are created, these inherit from the [GenericDecoder.py](./GenericDecoder.py) that defines the methods to be overwritten by the child classes. The [SDRDecoder.py](./SDRDecoder.py) and [DDRDecoder.py](./DDRDecoder.py), overwrite the decoding function to support their respective mode and output the *transaction frame* and *decoding mode* for the High-Level Analyzer to use.

#### Second Layer Analyzers
The Decoder takes the I3C transaction with the **decode method** based on the frames committed by the LLA. Once an I3C transaction is decoded, a handler for the selected second layer HLA is called. If no second layer analyzer is selected, the **decode method** commits the I3C transaction frame.

In more detail, the code was written in a way it can easily be expanded to support more second-layer HLAs. The decoders have an instance of the [i3c_second_layer_handler](./SecondLayerHLAs/SecondLayerAnalyzerHandler.py) class that is in charge of returning the instance of the correct second layer hla that was selected by the user.

Then, the decoder interacts with the second layer HLA by predefined functions that are defined in the [second_layer_hla](./SecondLayerHLAs/SecondLayerAnalyzer.py) class. For example, to add the vendor-specific CCC commands, the I3C HLA will call the updateCCC from the second layer HLA that was inherited.

Therefore, to add a second layer, it is as simple as creating a class that inherits from [second_layer_hla](./SecondLayerHLAs/SecondLayerAnalyzer.py) and implements the inherited methods **updateCCC(), udpate_result_types** and **instruction_decoder()**. Second, the **get()** methods from the [i3c_second_layer_handler](./SecondLayerHLAs/SecondLayerAnalyzerHandler.py) class need to be updated to support the new second layer HLA option. Lastly, the new option must be added to the ChoiceSetting variable.

An UML diagram for this architecture can be seen next:

![UMLDiagramI3CHLA](./SecondLayerHLAs/HLADiagram.png)

Additionally, each HLA should have a specific logger using the logging Python class.
