| .. _seed-0117: |
| |
| ============= |
| 0117: I3C |
| ============= |
| .. seed:: |
| :number: 117 |
| :name: I3C |
| :status: Accepted |
| :proposal_date: 2023-10-30 |
| :authors: Jack Chen |
| :cl: 178350 |
| :facilitator: Alexei Frolov |
| |
| ------- |
| Summary |
| ------- |
| A new peripheral protocol, I3C (pronounced eye-three-see) was introduced to |
| electronic world and it has been widely accepted by SoC and sensor |
| manufacturers. This seed is to propose a new front-end library pw_i3c, to help |
| communicate with devices on I3C bus. |
| |
| ---------- |
| Motivation |
| ---------- |
| Though widely used, I²C peripheral bus has several significant shortages, for |
| example the low bus speed, extra physical line to carry interrupt from each |
| device on the I²C bus, etc. To cope with higher requirements and to address |
| shortages of I²C, MIPI proposed a new fast, low-power and two-wire peripheral |
| protocol, I3C. |
| |
| I3C could be regarded as improved I²C. But in the meantime, it is a new protocol |
| which is different to I²C in both hardware and software. Some important |
| differences include: |
| |
| 1. I3C SDA uses open-drain mode when necessary for legacy I²C compatibility, |
| but switches to push-pull outputs whenever possible. |
| 2. I3C SCL runs in only in pull-pull mode and can only be driven by I3C |
| initiator. |
| 3. I3C devices supports dynamic address assignment (DAA) and has higher address |
| requirements. |
| 4. I3C needs bus initialization and DAA before it is ready to use. |
| 5. I3C has a standardized command set, called common command codes (CCC). |
| 6. I3C supports In-Band interrupt and hot-join. |
| 7. I3C device is identified by a 48-bit Provisioned ID (Manufacturer ID + Part |
| ID + Instance ID). |
| |
| In conclusion, it is worth providing an independent library pw_i3c to help |
| initialize I3C initiator and communicate with I3C devices on the bus. |
| |
| -------------------------- |
| Proposal (Detailed design) |
| -------------------------- |
| Since I3C is very similar to I²C, following proposal is to create a standalone |
| library pw_i3c, which shares a similar structure as pw_i2c. |
| |
| device type |
| ----------- |
| |
| The ``DeviceType`` is used to help differentiate legacy I²C devices and I3C |
| devices on one I3C bus. |
| |
| .. code-block:: c++ |
| |
| enum class DeviceType : bool { |
| kI2c, |
| kI3c, |
| }; |
| |
| Address |
| ------- |
| |
| The ``Address`` is a helper class to represent addresses which are used by |
| ``pw_i3c`` APIs. In I3C protocol, addresses are differentiated by I²C (static) |
| address and I3C (active or dynamic) address. The reason why device type is |
| embedded into address is that transactions for I²C and I3C devices are |
| different. So ``Initiator`` could tell the device type just by the provided |
| ``Address`` object. |
| |
| Apart from creating and checking ``Address`` at compile time, a helper |
| constructor to create and check ``Address`` at runtime is created, with |
| following reasons: |
| |
| 1. A new active/dynamic address could be assigned to I3C devices at run time. |
| 2. New devices could hot-join the bus at run time. |
| |
| .. code-block:: c++ |
| |
| class Address { |
| public: |
| static constexpr uint8_t kHotJoinAddress = 0x02; |
| static constexpr uint8_t kBroadcastAddress = 0x7E; |
| static constexpr uint8_t kStaticMaxAddress = 0x7F; |
| // For I3C, the active (dynamic) address restriction is dynamic (depending |
| // on devices on the bus, details can be found in "MIPI I3C Basic |
| // Specification Version 1.1.1" chapter 5.1.2.2.5). But to simplify the |
| // design, the strictest rule is applied. And there will be 108 addresses |
| // free for dynamic address chosen. |
| static constexpr uint8_t kDynamicMinAddress = 0x08; |
| static constexpr uint8_t kDynamicMaxAddress = 0x7D; |
| |
| // Helper constructor to ensure the address fits in the address space at |
| // compile time, skipping the construction time assert. |
| template <DeviceType kDeviceType, uint8_t kAddress> |
| static constexpr Address Create() { |
| static_assert(!IsOutOfRange(kDeviceType, kAddress)); |
| static_assert((DeviceType::kI2c == kDeviceType) || |
| !SingleBitErrorDetection(kAddress)); |
| return Address{kDeviceType, kAddress}; |
| } |
| |
| // Helper constructor to create the address at run time. |
| // Returns std::nullopt if provided type and address does not fit address |
| // rules. |
| static constexpr std::optional<Address> Create( |
| DeviceType device_type, uint8_t address) { |
| if (IsOutOfRange(device_type, address)) { |
| return std::nullopt; |
| } |
| if (DeviceType::kI3c == device_type && SingleBitErrorDetection(address)) { |
| return std::nullopt; |
| } |
| return Address{type, address}; |
| } |
| |
| // Return the type of address. |
| constexpr DeviceType GetType() const; |
| |
| // Return the address. |
| constexpr uint8_t GetAddress() const; |
| |
| private: |
| static constexpr uint8_t kAddressMask = 0x7F; |
| static constexpr int kTypeShift = 7; |
| static constexpr uint8_t kTypeMask = 0x01; |
| |
| constexpr Address(DeviceType type, uint8_t address) |
| : packed_address_{Pack(type, address)} {} |
| |
| uint8_t packed_address_; |
| }; |
| |
| Ccc |
| --- |
| |
| Common Command Codes are categorized into broadcast(Command Codes from 0x00 to |
| 0x7F) and direct(Command Codes from 0x80 to 0xFE). The rational behind it is |
| broadcast CCC can only be write and is executed in one transaction, but direct |
| CCC can be both write and read, and is executed in two transactions. We can |
| eliminate extra CCC type check in initiator CCC API. |
| |
| .. code-block:: c++ |
| |
| enum class CccBroadcast : uint8_t { |
| kEnc = 0x00, |
| kDisec = 0x01, |
| kEntdas0 = 0x02, |
| ... |
| kSetxtime = 0x28, |
| kSetaasa = 0x29, |
| } |
| |
| enum class CccDirect : uint8_t { |
| kEnc = 0x80, |
| kDisec = 0x81, |
| kEntas0 = 0x82, |
| ... |
| kSetxtime = 0x98, |
| kGetxtime = 0x99, |
| }; |
| |
| inline constexpr uint8_t kCccDirectBit = 7; |
| |
| enum class CccAction : bool { |
| kWrite, |
| kRead, |
| }; |
| |
| Initiator |
| --------- |
| |
| .. inclusive-language: disable |
| |
| Similar as ``pw::i2c``, ``Initiator`` is the common, base driver interface for |
| initiating thread-safe transactions with devices on an I3C bus. Other |
| documentation may call this style of interface an “master”, “central”, or |
| “controller”. |
| |
| .. inclusive-language: enable |
| |
| The main difference by comparison with I²C, is I3C initiator needs a bus |
| initialization and dynamic address assignment (DAA) step, before it is fully |
| functional. And after first bus initialization, I3C initiator should be able to |
| do bus re-initialization anytime when the bus is free. However, different |
| backend implementations may deal with this part differently. For example, Linux |
| does not expose I3C bus to userspace, which means users cannot control bus |
| initialization. NXP Mcuxpresso SDK exposes I3C as a pure library to users, so it |
| is users' responsibility to initialize the bus and perform DAA to get a usable |
| initiator. Zephyr provides more functions than Linux regarding I3C, which |
| makes I3C usage in Zephyr looks more likely to NXP Mcuxpresso SDK. |
| |
| Considering the complexity of different backend implementations of I3C bus, it |
| is better to have an "Initiator Maker" to take care of making an I3C |
| ``Initiator``. And this is not considered in the first version of ``pw_i3c`` |
| design. |
| |
| .. code-block:: c++ |
| |
| // PID is the unique identifier to an I3C device. |
| struct Pid { |
| uint16_t manuf_id = 0; |
| uint16_t part_id = 0; |
| uint16_t instance_id = 0; |
| |
| friend constexpr bool operator==(Pid const& lhs, Pid const& rhs) { |
| return (lhs.manuf_id == rhs.manuf_id) && (lhs.part_id == rhs.part_id) && |
| (lhs.instance_id == rhs.instance_id); |
| } |
| friend constexpr bool operator!=(Pid const& lhs, Pid const& rhs) { |
| return (lhs.manuf_id != rhs.manuf_id) || (lhs.part_id != rhs.part_id) || |
| (lhs.instance_id != rhs.instance_id); |
| } |
| |
| // Concat manuf_id, part_id and instance_id to a pid in 64-bit. |
| constexpr uint64_t AsUint64(Pid const pid) { |
| return (static_cast<uint64_t>(pid.manuf_id) << 33) | |
| (static_cast<uint64_t>(pid.part_id) << 16) | |
| (static_cast<uint64_t>(pid.instance_id) << 12); |
| } |
| |
| // Split a 64-bit pid into manuf_id, part_id and instance_id (struct Pid). |
| static constexpr Pid FromUint64(const uint64_t pid) { |
| return Pid{ |
| .manuf_id = ExtractBits<uint16_t, 47, 33>(pid), |
| .part_id = ExtractBits<uint16_t, 31, 16>(pid), |
| .instance_id = ExtractBits<uint16_t, 15, 12>(pid)}; |
| } |
| |
| }; |
| |
| // I3C supports in-band interrupt (IBI), but generalize the name to cover |
| // traditional interrupts. |
| // For IBI, the argument can be used to store data transferred. |
| // If the handler is queued in a workqueue, the data could be of any length. |
| // If the handler is executed inside CPU ISR directly, the data should only |
| // be mandatory data byte. |
| using InterruptHandler = ::pw::Function<void(ByteSpan)>; |
| |
| class Initiator { |
| public: |
| virtual ~Initiator() = default; |
| |
| // Pid is the unique identifier to an I3C device and it should be known to |
| // users through datasheets, like static addresses to I²C or I3C devices. |
| // But active (dynamic) address to an I3C device is changeable during |
| // run-time. Users could use this API to retrieve active address through |
| // PID. |
| // |
| // There are other information which users may be interested to know about |
| // an I3C device, like Bus Characteristics Register (BCR) and Device |
| // Characteristic Register(s) (DCR). But they can be read through direct |
| // read CCC API (ReadDirectCcc). |
| // |
| // Returns: |
| // Dynamic Address - Success. |
| // NOT_FOUND - Provided pid does not match with any active i3c device. |
| Result<Address> RetrieveDynamicAddressByPid(Pid pid); |
| |
| // Perform a broadcast CCC transaction. |
| // ccc_id: the broadcast CCC ID. |
| // buffer: payload to broadcast. |
| // |
| // Returns: |
| // OK - Success. |
| // INVALID_ARGUMENT - provided ccc_id is not supported. |
| // UNAVAILABLE - NACK condition occurred, meaning there are no active I3C |
| // devices on the bus. |
| // Other status codes as defined by backend. |
| Status WriteBroadcastCcc(CccBroadcast ccc_id, ConstByteSpan buffer); |
| Status WriteBroadcastCcc(CccBroadcast ccc_id, |
| const void* buffer, |
| size_t size_bytes); |
| |
| // Perform a direct write CCC transaction. |
| // ccc_id: the direct CCC ID. |
| // device_address: the address which the CCC targets for. |
| // buffer: payload to write. |
| // |
| // Returns: |
| // OK - Success. |
| // INVALID_ARGUMENT - provided ccc_id is not supported, or device_address is |
| // for I3C devices. |
| // UNAVAILABLE - NACK condition occurred, meaning there is no active I3C |
| // device with the provided device_address or it is busy now. |
| // Other status codes as defined by backend. |
| Status WriteDirectCcc(CccDirect ccc_id, |
| Address device_address, |
| ConstByteSpan buffer); |
| Status WriteDirectCcc(CccDirect ccc_id, |
| Address device_address, |
| const void* buffer, |
| size_t size_bytes); |
| |
| // Perform a direct read CCC transaction. |
| // ccc_id: the direct CCC ID. |
| // device_address: the address which the CCC targets for. |
| // buffer: payload to read. |
| // |
| // Returns: |
| // OK - Success. |
| // INVALID_ARGUMENT - provided ccc_id is not supported, or device_address is |
| // for I3C devices. |
| // UNAVAILABLE - NACK condition occurred, meaning there is no active I3C |
| // device with the provided device_address or it is busy now. |
| // Other status codes as defined by backend. |
| Status ReadDirectCcc(CccDirect ccc_id, |
| Address device_address, |
| ByteSpan buffer); |
| Status ReadDirectCcc(CccDirect ccc_id, |
| Address device_address, |
| void* buffer, |
| size_t size_bytes); |
| |
| // Write bytes and read bytes (this is normally executed in two independent |
| // transactions). |
| // |
| // Timeout is no longer needed in I3C transactions because only I3C |
| // initiator drives the clock in push-pull mode, and devices on the bus |
| // cannot stretch the clock. |
| // |
| // Returns: |
| // Ok - Success. |
| // UNAVAILABLE - NACK condition occurred, meaning the addressed device did |
| // not respond or was unable to process the request. |
| // Other status codes as defined by backend. |
| Status WriteReadFor(Address device_address, |
| ConstByteSpan tx_buffer, |
| ByteSpan rx_buffer); |
| Status WriteReadFor(I3cResponder device, |
| const void* tx_buffer, |
| size_t tx_size_bytes, |
| void* rx_buffer, |
| size_t rx_size_bytes); |
| |
| // Write bytes. |
| // |
| // Returns: |
| // OK - Success. |
| // UNAVAILABLE - NACK condition occurred, meaning the addressed device did |
| // not respond or was unable to process the request. |
| // Other status codes as defined by backend. |
| Status WriteFor(Address device_address, ConstByteSpan tx_buffer); |
| Status WriteFor(Address device_address, |
| const void* tx_buffer, |
| size_t tx_size_bytes); |
| |
| // Read bytes. |
| // |
| // Returns: |
| // OK - Success. |
| // UNAVAILABLE - NACK condition occurred, meaning the addressed device did |
| // not respond or was unable to process the request. |
| // Other status codes as defined by backend. |
| Status ReadFor(Address device_address, ByteSpan rx_buffer); |
| Status ReadFor(Address device_address, |
| void* rx_buffer, |
| size_t rx_size_bytes); |
| |
| // Probes the device for an ACK after only writing the address. |
| // This is done by attempting to read a single byte from the specified |
| // device. |
| // |
| // Returns: |
| // OK - Success. |
| // UNAVAILABLE - NACK condition occurred, meaning the addressed device did |
| // not respond or was unable to process the request. |
| Status ProbeDeviceFor(Address device_address); |
| |
| // Sets a (IBI) handler to execute when an interrupt is triggered from a |
| // device with the provided address. Handler for one address should be |
| // registered only once, unless it is cleared. Registration twice with |
| // same address should fail. |
| // |
| // Note that hot-join handler could be registered with this function since |
| // hot-join is sent through IBI. |
| // |
| // This handler is finally executed by I3C initiator, which means it may |
| // include any valid I3C actions (write and read). When I3C write/read |
| // happens, the interrupt handler is more like an I3C transaction than a |
| // traditional interrupt. Different I3C initiators may execute the handler |
| // in different ways. Some may queue the work on a workqueue and some may |
| // execute the handler directly inside IBI IRQ. Users should be aware of the |
| // backend algorithm and when execution happens in IBI IRQ, they should just |
| // read the mandatory data byte out through the handler and perform other |
| // actions in a different thread. |
| // |
| // Warning: |
| // This method is not thread-safe and cannot be used in interrupt handlers. |
| // |
| // Returns: |
| // OK - The interrupt handler was configured. |
| // INVALID_ARGUMENT - The handler is empty, or the handler is for IBI but |
| // the address is not for an I3C device. |
| // Other status codes as defined by the backend. |
| Status SetInterruptHandler(Address device_address, |
| InterruptHandler&& handler); |
| |
| // Clears the interrupt handler. |
| // |
| // Warning: |
| // This method is not thread-safe and cannot be used in interrupt handlers. |
| // |
| // Returns: |
| // OK - The interrupt handler was cleared |
| // INVALID_ARGUMENT - the handler is for IBI but the address is not for an |
| // I3C device. |
| // Other status codes as defined by the backend. |
| Status ClearInterruptHandler(Address device_address); |
| |
| // Enables interrupts which will trigger the interrupt handler. |
| // |
| // Warning: |
| // This method is not thread-safe and cannot be used in interrupt handlers. |
| // |
| // Preconditions: |
| // A handler has been set using `SetInterruptHandler()`. |
| // |
| // Returns: |
| // OK - The interrupt handler was enabled. |
| // INVALID_ARGUMENT - the handler is for IBI but the address is not for an |
| // I3C device. |
| // Other status codes as defined by the backend. |
| Status EnableInterruptHandler(Address device_address); |
| |
| // Disables interrupts which will trigger the interrupt handler. |
| // |
| // Warning: |
| // This method is not thread-safe and cannot be used in interrupt handlers. |
| // |
| // Preconditions: |
| // A handler has been set using `SetInterruptHandler()`. |
| // |
| // Returns: |
| // OK - The interrupt handler was disabled. |
| // INVALID_ARGUMENT - the handler is for IBI but the address is not for an |
| // I3C device. |
| // Other status codes as defined by the backend. |
| Status DisableInterruptHandler(Address device_address); |
| |
| private: |
| virtual Result<Address> DoRetrieveDynamicAddressByPid(Pid pid) = 0; |
| virtual Status DoTransferCcc(CccAction read_or_write, |
| uint8_t ccc_id, |
| std::optional<Address> device_address, |
| ByteSpan buffer) = 0; |
| virtual Status DoWriteReadFor(Address device_address, |
| ConstByteSpan tx_buffer, |
| ByteSpan rx_buffer) = 0; |
| virtual Status DoSetInterruptHandler(Address address, |
| InterruptHandler&& handler) = 0; |
| virtual Status DoEnableInterruptHandler(Address address, bool enable) = 0; |
| }; |
| |
| Device |
| ------ |
| |
| Same as ``pw::i2c::Device``, a ``Device`` class is used in ``pw::i3c`` to |
| write/read arbitrary chunks of data over a bus to a specific device, or perform |
| other I3C operations, e.g. direct CCC. |
| Though PID is the unique identifier for I3C devices, considering backward |
| compatibility with I²C devices, this object also wraps the Initiator API with |
| an active ``Address``. Application should initiate or be notified the |
| ``Address`` change and update the ``Address`` in ``Device`` object. |
| |
| .. code-block:: c++ |
| |
| class Device { |
| public: |
| // It is users' responsibility to get and pass the active (dynamic) address |
| // when creating a ``Device``. If the dynamic address of an I3C device is |
| // unknown, users could get it through initiator: |
| // pw::i3c::Initiator::RetrieveDynamicAddressByPid(); |
| constexpr Device(Initiator& initiator, Address device_address, Pid pid) |
| : initiator_(initiator), |
| device_address_(device_address), |
| pid_(pid) {} |
| |
| // For I2C devices connected to I3C bus, pid_ is default-initialized to be |
| // std::nullopt. |
| constexpr Device(Initiator& initiator, Address device_address) |
| : initiator_(initiator), |
| device_address_(device_address) {} |
| |
| Device(const Device&) = delete; |
| Device(Device&&) = default; |
| ~Device() = default; |
| |
| // Perform a direct write CCC transaction. |
| // ccc_id: the direct CCC ID. |
| // buffer: payload to write. |
| // |
| // Returns: |
| // OK - Success. |
| // INVALID_ARGUMENT - provided ccc_id is not supported, or device_address_ |
| // is not for I3C devices. |
| // UNAVAILABLE - NACK condition occurred, meaning there is no active I3C |
| // device with the provided device_address or it is busy now. |
| // Other status codes as defined by backend. |
| Status WriteDirectCcc(CccDirect ccc_id, ConstByteSpan buffer); |
| Status WriteDirectCcc(CccDirect ccc_id, |
| const void* buffer, |
| size_t size_bytes); |
| |
| // Perform a direct read CCC transaction. |
| // ccc_id: the direct CCC ID. |
| // buffer: payload to read. |
| // |
| // Returns: |
| // OK - Success. |
| // INVALID_ARGUMENT - provided ccc_id is not supported, or device_address_ |
| // is not for I3C devices. |
| // UNAVAILABLE - NACK condition occurred, meaning there is no active I3C |
| // device with the provided device_address or it is busy now. |
| // Other status codes as defined by backend. |
| Status ReadDirectCcc(CccDirect ccc_id, ByteSpan buffer); |
| Status ReadDirectCcc(CccDirect ccc_id, |
| const void* buffer, |
| size_t size_bytes); |
| |
| // Write bytes and read bytes (this is normally executed in two independent |
| // transactions). |
| // |
| // Timeout is no longer needed in I3C transactions because only I3C |
| // initiator drives the clock in push-pull mode, and devices on the bus |
| // cannot stretch the clock. |
| // |
| // Returns: |
| // OK - Success. |
| // UNAVAILABLE - NACK condition occurred, meaning the addressed device did |
| // not respond or was unable to process the request. |
| // Other status codes as defined by backend. |
| Status WriteReadFor(ConstByteSpan tx_buffer, ByteSpan rx_buffer); |
| Status WriteReadFor(const void* tx_buffer, |
| size_t tx_size_bytes, |
| void* rx_buffer, |
| size_t rx_size_bytes); |
| |
| // Write bytes. |
| // |
| // Returns: |
| // OK - Success. |
| // UNAVAILABLE - NACK condition occurred, meaning the addressed device did |
| // not respond or was unable to process the request. |
| // Other status codes as defined by backend. |
| Status WriteFor(ConstByteSpan tx_buffer); |
| Status WriteFor(const void* tx_buffer, size_t tx_size_bytes); |
| |
| // Read bytes. |
| // |
| // Returns: |
| // Ok - Success. |
| // UNAVAILABLE - NACK condition occurred, meaning the addressed device did |
| // not respond or was unable to process the request. |
| // Other status codes as defined by backend. |
| Status ReadFor(ByteSpan rx_buffer); |
| Status ReadFor(void* rx_buffer, size_t rx_size_bytes); |
| |
| // Probes the device for an ACK after only writing the address. |
| // This is done by attempting to read a single byte from this device. |
| // |
| // Returns: |
| // Ok - Success. |
| // UNAVAILABLE - NACK condition occurred, meaning the addressed device did |
| // not respond or was unable to process the request. |
| Status ProbeFor(); |
| |
| // Sets a (IBI) handler to execute when an interrupt is triggered from a |
| // device with the provided address. Handler for one address should be |
| // registered only once, unless it is cleared. Registration twice with |
| // same address should fail. |
| // |
| // This handler is finally executed by I3C initiator, which means it may |
| // include any valid I3C actions (write and read). When I3C write/read |
| // happens, the interrupt handler is more like an I3C transaction than a |
| // traditional interrupt. Different I3C initiators may execute the handler |
| // in different ways. Some may queue the work on a workqueue and some may |
| // execute the handler directly inside IBI IRQ. Users should be aware of the |
| // backend algorithm and when execution happens in IBI IRQ, they should just |
| // read the mandatory data byte out through the handler and perform other |
| // actions in a different thread. |
| // |
| // Warning: |
| // This method is not thread-safe and cannot be used in interrupt handlers. |
| // Do not register hot-join handler for I3C devices as hot-join handler is |
| // initiator specific, not for a single device. |
| // |
| // Returns: |
| // OK - The interrupt handler was configured. |
| // INVALID_ARGUMENT - The handler is empty, or the handler is for IBI but |
| // the device is an I3C device. |
| // Other status codes as defined by the backend. |
| Status SetInterruptHandler(InterruptHandler&& handler); |
| |
| // Clears the interrupt handler. |
| // |
| // Warning: |
| // This method is not thread-safe and cannot be used in interrupt handlers. |
| // |
| // Returns: |
| // OK - The interrupt handler was cleared |
| // INVALID_ARGUMENT - the handler is for IBI but the device is an I3C device. |
| // Other status codes as defined by the backend. |
| Status ClearInterruptHandler(); |
| |
| // Enables interrupts which will trigger the interrupt handler. |
| // |
| // Warning: |
| // This method is not thread-safe and cannot be used in interrupt handlers. |
| // |
| // Preconditions: |
| // A handler has been set using `SetInterruptHandler()`. |
| // |
| // Returns: |
| // OK - The interrupt handler was enabled. |
| // INVALID_ARGUMENT - the handler is for IBI but the device is an I3C device. |
| // Other status codes as defined by the backend. |
| Status EnableInterruptHandler(); |
| |
| // Disables interrupts which will trigger the interrupt handler. |
| // |
| // Warning: |
| // This method is not thread-safe and cannot be used in interrupt handlers. |
| // |
| // Preconditions: |
| // A handler has been set using `SetInterruptHandler()`. |
| // |
| // Returns: |
| // OK - The interrupt handler was disabled. |
| // INVALID_ARGUMENT - the handler is for IBI but the device is an I3C device. |
| // Other status codes as defined by the backend. |
| Status DisableInterruptHandler(); |
| |
| // Update device address during run-time actively. |
| // |
| // Warning: |
| // This function is dedicatedly to I3C devices. |
| void UpdateAddressActively(Address new_address); |
| |
| // Update device address during run-time Passively. |
| // initiator_ will be responsible for retrieving the dynamic address and |
| // substitute the device_address_. |
| // |
| // Warning: |
| // This function is dedicatedly to I3C devices. |
| // |
| // Returns: |
| // OK - Success. |
| // UNIMPLEMENTED - pid is empty (I²C device). |
| // NOT_FOUND - initiator_ fails to retrieve dynamic address based on pid_. |
| Status UpdateAddressPassively(); |
| |
| private: |
| Initiator& initiator_; |
| Address device_address_; |
| std::optional<Pid> pid_; |
| }; |
| |
| ------------ |
| Alternatives |
| ------------ |
| Since I3C is similar to I²C and pw_i3c is similar to pw_i2c, instead of creating |
| a standalone library, an alternative solution is to combine pw_i3c and pw_i2c, |
| and providing a single library pw_ixc, or other suitable names. And in this |
| comprehensive library, I3C-related features could be designed to be optional. |
| |
| On one hand, this solution could reuse a lot of code and simplify some work in |
| user level, if users want to abstract usage of I²C and I3C in application. |
| On the other hand, it also brings churn to existing projects using pw_i2c, and |
| ambiguity and confusion in the long run (I²C is mature, but I3C is new and |
| actively improving). |
| |
| -------------- |
| Open Questions |
| -------------- |
| 1. As mentioned in the description of I3C ``Initiator`` class, the creation of a |
| fully functional ``Initiator`` would be handled by a different class. |
| |
| 2. Because there are two types of ``Address`` in I3C, the static and dynamic, |
| the ``pw::i3c::Address`` is not compatible with ``pw::i2c::Address``. So when |
| users try to create an ``Address`` for an I²C device, they need to carefully |
| choose the correct class depending on which bus the device is connected to. |
| This class may cause bigger concern if ``Address`` is needed to be shared |
| through interface in application code. |
| But the problem is resolvable by templating ``Address`` in caller code. |
| Also, we can have a helper function in ``pw::i3c::Address``, which consumes a |
| ``pw::i2c::Addres``s and create a ``pw::i3c::Address``. This helper will be |
| added and discussed further in a following patch. |
| |
| 3. ``DeviceType`` is embedded into ``Address``. So ``pw::i3c::Initiator`` could |
| tell the device type (I²C or I3C) based on provided ``Address``. But this is |
| not necessary because Initiator has performed DAA during initialization so it |
| should know which addresses have been assigned to I3C devices. |
| In this case, the only advantage of this design is to help applying address |
| restriction during creating ``Address`` object. Should address restriction be |
| taken care of by HAL? Though fewer, I²C has reserved addresses, too, but they |
| are not checked in ``pw::i2c::Address``. |
| |
| 4. ``RegisterDevice`` for I3C is the same as I²C, in protocol. To read/write |
| from a register, the ``Initiator`` sends an active address on the bus. Once |
| acknowledged, it will send the register address followed by data. |
| So the ideal design is to abstract ``RegisterDevice`` across I²C and I3C, or |
| maybe even other peripheral buses (e.g. SPI and DSI). However, the underlying |
| register operation functions are different. It is better to be handled in a |
| separate SEED. |
