From 3081ec08bcf593ec2e2349015593612910021ca0 Mon Sep 17 00:00:00 2001 From: Annie_wang Date: Tue, 5 Jul 2022 15:50:13 +0800 Subject: [PATCH] update docs Signed-off-by: Annie_wang --- .../driver/driver-platform-i3c-des.md | 530 ++++++------------ .../driver/driver-platform-i3c-develop.md | 395 +++++++------ .../figures/I3C_physical_connection.png | Bin 28436 -> 33726 bytes .../driver/figures/I3C_usage_flowchart.png | Bin 6383 -> 9847 bytes 4 files changed, 418 insertions(+), 507 deletions(-) diff --git a/en/device-dev/driver/driver-platform-i3c-des.md b/en/device-dev/driver/driver-platform-i3c-des.md index 487947c272..8931ca30f5 100644 --- a/en/device-dev/driver/driver-platform-i3c-des.md +++ b/en/device-dev/driver/driver-platform-i3c-des.md @@ -1,140 +1,109 @@ -# I3C +# I3C +## Introduction -## Overview +### Function -The Improved Inter-Integrated Circuit (I3C) is a simple and cost-efficient bidirectional 2-wire synchronous serial bus protocol developed by the Mobile Industry Processor Interface (MIPI) Alliance. +Improved Inter-Integrated Circuit (I3C) is a simple and cost-efficient two-wire bidirectional synchronous serial bus protocol developed by the Mobile Industry Processor Interface (MIPI) Alliance. -I3C is backward compatible with legacy Inter-Integrated Circuit (I2C). Moreover, it provides the in-band interrupt (IBI) function and supports hot-join of I3C devices. This eliminates the need for adding an extra interrupt line to implement interrupts in I2C. +I3C is a two-wire bidirectional serial bus, optimized for multiple sensor target devices and controlled by only one I3C controller at a time. It is backward compatible with Inter-Integrated circuit (I2C) target devices, but features higher speed and lower power consumption. Moreover, I3C supports in-band interrupts (IBIs), hot-joins of target devices, and controller switchover. The IBIs over the serial bus eliminates the need for an extra interrupt line to complete interrupts in I2C. I2C devices, I3C target devices, and the I3C secondary controller can co-exist on the same I3C bus. -The I2C device, I3C slave device, and I3C secondary master device can coexist on the I3C bus. +The I3C driver APIs provide a set of common functions for I3C transfer, including: +- Opening and closing an I3C controller +- Obtaining and setting I3C controller parameters +- Performing custom I3C message transfer by using a message array +- Requesting and releasing an IBI -The I3C APIs provide a set of common functions for I3C transfer, including: +### Basic Concepts -- Opening and closing an I3C controller -- Obtaining and setting I3C controller parameters -- Performing custom I3C message transfer by using a message array -- Requesting and releasing an IBI +- IBI + + When there is no start signal on the serial clock (SCL) line, the I3C target device can pull down the serial data (SDA) line to make the controller send an SCL start signal, which initiates an IBI request. If multiple target devices send interrupt requests at the same time, the I3C controller arbitrates the requests based on the target device addresses. The request with a lower address is responded first. + +- Dynamic Address Assignment (DAA) -[Figure 1](#fig1) shows the I3C physical connection. -**Figure 1** I3C physical connection
+ The I3C controller can dynamically allocate addresses to target devices to avoid address conflicts. Before addresses are allocated, each I3C device connected to a I3C bus must be uniquely identified in either of the following ways: + + - The device has an I2C compliant static address that can be used by the host. + - The device has a 48-bit temporary ID. + + The host must use a 48-bit temporary ID unless the device has a static IP address. + +- Common Command Code (CCC) + + All I3C devices support CCC. The CCC can be sent to a specific I3C target device or all I3C target devices. + +- Bus Characteristic Register (BCR) + + Each I3C device connected to an I3C bus has a read-only BCR, which describes the I3C compliant device's role and capabilities for use in DAA and CCC. + +- Device Characteristic Register (DCR) + + Each I3C device connected to an I3C bus has a read-only DCR, which describes the I3C compliant device type (such as accelerometers, gyroscope, and others) for use in DAA and DCC. + +### Working Principles + +In the Hardware Driver Foundation (HDF), the I3C module uses the unified service mode for API adaptation. In this mode, a service is used as the I3C manager to handle external access requests in a unified manner. The unified service mode applies when the system has multiple device objects of the same type, for example, when there are more than 10 I3C controllers. If the independent service mode is used in this case, more device nodes need to be configured and more memory resources will be consumed. + +Multiple devices, such as I2C target device, I3C target device, and I3C secondary controller, can be connected to an I3C bus. However, the I3C bus must have only one controller. + +**Figure 1** I3C physical connection ![](figures/I3C_physical_connection.png "I3C_physical_connection") -## Available APIs +### Constraints + +Currently, the I3C module supports only the kernels (LiteOS) of mini and small systems. + +## Usage Guidelines + +### When to Use + +I3C can connect to one or more I3C or I2C target devices. It is used to: +- Communicate with sensors, such as gyroscopes, barometers, and image sensors that support the I3C protocol. +- Communicate with devices with other ports (such as UART serial ports) through software or hardware protocols. + +### Available APIs **Table 1** I3C driver APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Category

-

API

-

Description

-

I3C controller management

-

I3cOpen

-		Opens an I3C controller.

-

I3cClose

-

Closes an I3C controller.

-

I3C transfer

-

I3cTransfer

-

Customizes an I3C transfer.

-

I3C controller configuration

-

I3cSetConfig

-		Sets an I3C controller.

-

I3cGetConfig

-

Obtains the I3C controller configuration.

-

I3C IBI

-

I3cRequestIbi

-		Requests an IBI.

-

I3cFreeIbi

-

Releases an IBI.

-
- - - ->![](../public_sys-resources/icon-note.gif) **NOTE**
-> ->All functions described in this document can be called only in the kernel space. - -## Usage Guidelines - -### How to Use - -[Figure 2](#fig2) shows how I3C works. - -**Figure 2** How I3C works
+ +| API | Description | +| ------------- | ----------------- | +| I3cOpen | Opens an I3C controller. | +| I3cClose | Closes an I3C controller. | +| I3cTransfer | Performs custom transfer. | +| I3cSetConfig | Sets the I3C controller. | +| I3cGetConfig | Obtains the I3C controller configuration. | +| I3cRequestIbi | Requests an IBI. | +| I3cFreeIbi | Releases an IBI. | + +>![](../public_sys-resources/icon-note.gif) **NOTE**
+>All APIs described in this document can be called only in kernel mode. + +### How to Develop + +The figure below illustrates the use of I3C driver APIs. + +**Figure 2** Process of using I3C driver APIs ![](figures/I3C_usage_flowchart.png "I3C_usage_flowchart") -### Opening an I3C Controller +#### Opening an I3C Controller -Before I3C communication, call **I3cOpen** to open an I3C controller. +Before I3C communication, call **I3cOpen()** to open an I3C controller. ```c DevHandle I3cOpen(int16_t number); ``` **Table 2** Description of I3cOpen - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

number

-

I3C controller ID.

-

Return Value

-

Description

-

NULL

-

Failed to open the I3C controller.

-

Controller handle

-

Handle of the I3C controller opened.

-
- -The following example opens I3C controller 1 of the eight I3C controllers (numbered from 0 to 7) in the system. +| Name | Description | +| ---------- | ------------------- | +| number | I3C controller number. | +| **Return Value**| **Description** | +| NULL | The operation failed. | +| Controller handle| The operation is successful. The handle of the I3C controller opened is returned. | + +Example: Open I3C controller 1 of the eight I3C controllers numbered from 0 to 7 in the system. ```c DevHandle i3cHandle = NULL; /* I3C controller handle. / @@ -147,7 +116,7 @@ if (i3cHandle == NULL) { } ``` -### Performing I3C Communication +#### Performing I3C Communication Call **I3cTransfer()** to transfer messages. ```c @@ -156,53 +125,18 @@ int32_t I3cTransfer(DevHandle handle, struct I3cMsg *msgs, int16_t count, enum T **Table 3** Description of I3cTransfer - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

I3C controller handle.

-

msgs

-

Pointer to the message structure array of the data to be transmitted.

-

count

-

Length of the message array.

-

mode

-

Transmission mode, where the value 0 indicates the I2C mode, 1 indicates the I3C mode, and 2 indicates transmission of the Common Command Code (CCC). -

Return Value

-

Description

-

Positive integer

-

Number of message structures successfully transferred.

-

Negative number

-

The operation failed.

-
- -The I3C messages are of the I3cMsg type. Each message structure indicates a read or write operation. A message array is used to perform multiple read or write operations. + +| Name | Description | +| ---------- | -------------------------------------------- | +| handle | I3C controller handle. | +| msgs | Pointer to the message array of the data to transfer. | +| count | Length of the message array. | +| mode | Transmission mode. The value **0** indicates I2C mode, **1** indicates I3C mode, and **2** indicates CCC transmission. | +| **Return Value**| **Description** | +| Positive integer | The operation is successful. The number of message structures that are successfully transmitted is returned. | +| Negative value | The operation failed. | + +The I3C messages are of the I3cMsg type. Each message structure indicates a read or write operation. A message array can be used to perform multiple read or write operations. ```c int32_t ret; @@ -225,13 +159,14 @@ if (ret != 2) { } ``` ->![](../public_sys-resources/icon-caution.gif) **Caution** -> +>![](./public_sys-resources/icon-caution.gif) **Caution**
>- The device address in the **I3cMsg** structure does not contain the read/write flag bit. The read/write information is passed by the read/write control bit in the member variable **flags**. >- The **I3cTransfer()** function does not limit the number of message structures or the length of data in each message structure. The I3C controller determines these two limits. >- Using **I3cTransfer()** may cause the system to sleep. Do not call it in the interrupt context. -### Obtaining the I3C Controller Configuration +#### Obtaining the I3C Controller Configuration + +Call **I3cGetConfig()** to obtain the configuration of an I3C controller. ```c int32_t I3cGetConfig(DevHandle handle, struct I3cConfig *config); @@ -239,43 +174,30 @@ int32_t I3cGetConfig(DevHandle handle, struct I3cConfig *config); **Table 4** Description of I3cGetConfig - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

I3C controller handle.

-

config

-

Pointer to the I3C controller configuration.

-

Return Value

-

Description

-

0

-

The operation is successful.

-

Negative number

-

Failed to obtain the I3C controller configuration.

-
- -### Configuring an I3C Controller + +| Name | Description | +| ---------- | -------------- | +| handle | I3C controller handle. | +| config | Pointer to the I3C controller configuration. | +| **Return Value**| **Description**| +| 0 | The operation is successful. | +| Negative value | The operation failed. | + +The following is an example of obtaining the I3C controller configuration: + +```c +struct I3cConfig config; + +ret = I3cGetConfig(i3cHandle, &config); +if (ret != HDF_SUCCESS) { + HDF_LOGE("%s: Get config fail!", __func__); + return HDF_FAILURE; +} +``` + +#### Setting an I3C Controller + +Call **I3cSetConfig()** to set an I3C controller. ```c int32_t I3cSetConfig(DevHandle handle, struct I3cConfig *config); @@ -283,43 +205,32 @@ int32_t I3cSetConfig(DevHandle handle, struct I3cConfig *config); **Table 5** Description of I3cSetConfig - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

I3C controller handle.

-

config

-

Pointer to the I3C controller configuration.

-

Return Value

-

Description

-

0

-

The operation is successful.

-

Negative number

-

Failed to configure the I3C controller.

-
- -### Requesting an IBI + +| Name | Description | +| ---------- | -------------- | +| handle | I3C controller handle. | +| config | Pointer to the I3C controller configuration. | +| **Return Value**| **Description**| +| 0 | The operation is successful. | +| Negative value | The operation failed. | + +The following is an example of setting an I3C controller: + +```c +struct I3cConfig config; + +config->busMode = I3C_BUS_HDR_MODE; +config->curMaster = NULL; +ret = I3cSetConfig(i3cHandle, &config); +if (ret != HDF_SUCCESS) { + HDF_LOGE("%s: Set config fail!", __func__); + return HDF_FAILURE; +} +``` + +#### Requesting an IBI + +Call **I3cRequestIbi()** to request an IBI. ```c int32_t I3cRequestIbi(DevHandle handle, uint16_t addr, I3cIbiFunc func, uint32_t payload); @@ -327,51 +238,18 @@ int32_t I3cRequestIbi(DevHandle handle, uint16_t addr, I3cIbiFunc func, uint32_t **Table 6** Description of I3cRequestIbi - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

I3C controller handle.

-

addr

-

I3C device address.

-

func

-

Callback used to return the IBI.

-

payload

-

IBI payload.

-

Return Value

-

Description

-

0

-

The operation is successful.

-

Negative number

-

Failed to request the IBI.

-
+ +| Name | Description | +| ---------- | -------------- | +| handle | I3C controller handle. | +| addr | I3C device address. | +| func | Callback used to return the IBI. | +| payload | IBI payload. | +| **Return Value**| **Description**| +| 0 | The operation is successful. | +| Negative value | The operation failed. | + +The following is an example: ```c static int32_t TestI3cIbiFunc(DevHandle handle, uint16_t addr, struct I3cIbiData data) @@ -388,7 +266,7 @@ int32_t I3cTestRequestIbi(void) DevHandle i3cHandle = NULL; int32_t ret; - /* Open an I3C controller. */ + /* Open the I3C controller. */ i3cHandle = I3cOpen(1); if (i3cHandle == NULL) { HDF_LOGE("I3cOpen: failed\n"); @@ -407,7 +285,9 @@ int32_t I3cTestRequestIbi(void) } ``` -### Releasing an IBI +#### Releasing an IBI + +Call **I3cFreeIbi()** to release an IBI. ```c int32_t I3cFreeIbi(DevHandle handle, uint16_t addr); @@ -415,47 +295,22 @@ int32_t I3cFreeIbi(DevHandle handle, uint16_t addr); **Table 7** Description of I3cFreeIbi - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

I3C controller handle.

-

addr

-

I3C device address.

-

Return Value

-

Description

-

0

-

The operation is successful.

-

Negative number

-

Failed to release the IBI.

-
+ +| Name | Description | +| ---------- | -------------- | +| handle | I3C controller handle. | +| addr | I3C device address. | +| **Return Value**| **Description**| +| 0 | The operation is successful. | +| Negative value | The operation failed. | + +The following is an example: ```c I3cFreeIbi(i3cHandle, 0x3F); /* Release an IBI. */ ``` -### Closing an I3C controller +#### Closing an I3C Controller Call **I3cClose()** to close the I3C controller after the communication is complete. ```c @@ -464,28 +319,18 @@ void I3cClose(DevHandle handle); **Table 8** Description of I3cClose - - - - - - - - - -

Parameter

-

Description

-

handle

-

I3C controller handle.

-
+| Name | Description | +| ---------- | -------------- | +| handle | I3C controller handle. | +The following is an example: ```c -I3cClose(i3cHandle); /* Close an I3C controller. */ +I3cClose(i3cHandle); /* Close the I3C controller. */ ``` -## Example +## Development Example This following example shows how to use I3C APIs to manage an I3C device on a Hi3516D V300 development board. @@ -503,10 +348,9 @@ The sample code is as follows: ```c #include "i3c_if.h" /* Header file for I3C standard APIs */ -#include "i3c_ccc.h" /* Header file for I3C CCC */ #include "hdf_log.h" /* Header file for log APIs */ ##include "osal_io.h" /* Header file for I/O read and write APIs */ -##include "osal_time.h" /* Header file for delay and sleep APIs */ +#include "osal_time.h" /* Header file for delay and sleep APIs */ /* Define a device structure to hold information. */ struct TestI3cDevice { @@ -516,7 +360,7 @@ struct TestI3cDevice { DevHandle i3cHandle; /* I3C controller handle */ }; -/* Use I3cTransfer to encapsulate a register read/write helper function. Use flag to indicate a read or write operation. */ +/* Use I3cTransfer() to encapsulate a register read/write helper function. Use flag to indicate a read or write operation. */ static int TestI3cReadWrite(struct TestI3cDevice *testDevice, unsigned int regAddr, unsigned char *regData, unsigned int dataLen, uint8_t flag) { @@ -539,7 +383,7 @@ static int TestI3cReadWrite(struct TestI3cDevice *testDevice, unsigned int regAd msgs[0].buf = regBuf; msgs[1].addr = testDevice->addr; - msgs[1].flags = (flag == 1) ? I3C_FLAG_READ: 0; /* Add a read flag bit to read data. */ + msgs[1].flags = (flag == 1) ? I3C_FLAG_READ : 0; /* Add the read flag. */ msgs[1].len = dataLen; msgs[1].buf = regData; diff --git a/en/device-dev/driver/driver-platform-i3c-develop.md b/en/device-dev/driver/driver-platform-i3c-develop.md index d67a87a160..8c3a571fc6 100644 --- a/en/device-dev/driver/driver-platform-i3c-develop.md +++ b/en/device-dev/driver/driver-platform-i3c-develop.md @@ -1,78 +1,135 @@ # I3C -## Overview +## Introduction -The Improved Inter-Integrated Circuit (I3C) is a simple and cost-efficient bidirectional 2-wire synchronous serial bus protocol developed by the Mobile Industry Processor Interface (MIPI) Alliance. In the Hardware Driver Foundation (HDF), the I3C module uses the unified service mode for API adaptation. In this mode, a device service is used as the I3C manager to handle external access requests in a unified manner, which is reflected in the configuration file. The unified service mode applies to the scenario where there are many device objects of the same type, for example, when the I3C has more than 10 controllers. If the independent service mode is used, more device nodes need to be configured and memory resources will be consumed by services. +### Function -**Figure 1** Unified service mode +Improved Inter-Integrated Circuit (I3C) is a simple and cost-efficient two-wire bidirectional synchronous serial bus protocol developed by the Mobile Industry Processor Interface (MIPI) Alliance. + +I3C is a two-wire bidirectional serial bus, optimized for multiple sensor target devices and controlled by only one I3C controller at a time. It is backward compatible with Inter-Integrated circuit (I2C) target devices, but features higher speed and lower power consumption and supports in-band interrupts (IBIs), hot-joins of target devices, and controller switchover. + +### Basic Concepts + +- IBI + + When there is no start signal on the serial clock (SCL) line, the I3C target device can pull down the serial data (SDA) line to make the controller send an SCL start signal, which initiates an IBI request. If multiple target devices send interrupt requests at the same time, the I3C controller arbitrates the requests based on the target device addresses. The request with a lower address is responded first. + +- Dynamic Address Assignment (DAA) + + The I3C controller can dynamically allocate addresses to target devices to avoid address conflicts. Before addresses are allocated, each I3C device connected to a I3C bus must be uniquely identified in either of the following ways: + + - The device has an I2C compliant static address that can be used by the host. + - The device has a 48-bit temporary ID. + + The host must use a 48-bit temporary ID unless the device has a static IP address. + +- Common Command Code (CCC) + + All I3C devices support CCC. The CCC can be sent to a specific I3C target device or all I3C target devices. + +- Bus Characteristic Register (BCR) + + Each I3C device connected to an I3C bus has a read-only BCR, which describes the I3C compliant device's role and capabilities for use in DAA and CCC. + +- Device Characteristic Register (DCR) + + Each I3C device connected to an I3C bus has a read-only DCR, which describes the I3C compliant device type (such as accelerometers, gyroscope, and others) for use in DAA and DCC. + + +### Working Principles + +In the Hardware Driver Foundation (HDF), the I3C module uses the unified service mode for API adaptation. In this mode, a service is used as the I3C manager to handle external access requests in a unified manner. The unified service mode applies when the system has multiple device objects of the same type, for example, when there are more than ten I3C controllers. If the independent service mode is used in this case, more device nodes need to be configured and more memory resources will be consumed. The figure below illustrates the unified service mode. + +The I3C module is divided into the following layers: + +- The interface layer provides APIs for opening or closing a controller, transmitting messages, and obtaining and setting controller parameters. +- The core layer provides the capabilities of binding, initializing, and releasing devices. +- The adaptation layer implements other functions. + + **Figure 1** Unified service mode ![image1](figures/unified-service-mode.png) +### Constraints + +Currently, the I3C module supports only the kernels (LiteOS) of mini and small systems. + +## Development Guidelines + +### When to Use + +I3C can connect to one or more I3C or I2C target devices. It is used to: + +- Communicate with sensors, such as gyroscopes, barometers, and image sensors that support the I3C protocol. +- Communicate with devices with other ports (such as UART serial ports) through software or hardware protocols. -## Available APIs +### Available APIs **I3cMethod**: - ```c - struct I3cMethod { - int32_t (*sendCccCmd)(struct I3cCntlr *cntlr, struct I3cCccCmd *ccc); - int32_t (*transfer)(struct I3cCntlr *cntlr, struct I3cMsg *msgs, int16_t count); - int32_t (*i2cTransfer)(struct I3cCntlr *cntlr, struct I3cMsg *msgs, int16_t count); - int32_t (*setConfig)(struct I3cCntlr *cntlr, struct I3cConfig *config); - int32_t (*getConfig)(struct I3cCntlr *cntlr, struct I3cConfig *config); - int32_t (*requestIbi)(struct I3cDevice *dev); - void (*freeIbi)(struct I3cDevice *dev); - }; - ``` - **Table 1** APIs for the members in the I3cMethod structure - - |Method|Input Parameter|Output Parameter|Return Value|Description| - |-|-|-|-|-| - |sendCccCmd|**cntlr**: structure pointer to an I3C controller at the core layer.
**ccc**: pointer to the input common command code (CCC) structure.|**ccc**: pointer to the output CCC structure.|HDF_STATUS|Sends a CCC.| - |Transfer |**cntlr**: structure pointer to an I3C controller at the core layer.
**msgs**: structure pointer to user messages.
**count**: number of messages, which is of the int16_t type.|**msgs**: structure pointer to user messages.|HDF_STATUS|Transfers user messages in I3C mode.| - |i2cTransfer |**cntlr**: structure pointer to an I3C controller at the core layer.
**msgs**: structure pointer to user messages.
**count**: number of messages, which is of the int16_t type.|**msgs**: structure pointer to user messages.|HDF_STATUS|Transfers user messages in I2C mode.| - |setConfig|**cntlr**: structure pointer to an I3C controller at the core layer.
**config**: pointer to controller configuration parameters.|–|HDF_STATUS|Sets an I3C controller.| - |getConfig|**cntlr**: structure pointer to an I3C controller at the core layer.|**config**: pointer to controller configuration parameters.|HDF_STATUS|Obtains the configuration of an I3C controller.| - |requestIbi|**device**: structure pointer to an I3C device at the core layer.|–|HDF_STATUS|Requests an IBI for an I3C device.| - |freeIbi|**device**: structure pointer to an I3C device at the core layer.|–|HDF_STATUS|Releases the IBI for an I3C device.| - -## How to Develop + + +```c +struct I3cMethod { + int32_t (*sendCccCmd)(struct I3cCntlr *cntlr, struct I3cCccCmd *ccc); + int32_t (*transfer)(struct I3cCntlr *cntlr, struct I3cMsg *msgs, int16_t count); + int32_t (*i2cTransfer)(struct I3cCntlr *cntlr, struct I3cMsg *msgs, int16_t count); + int32_t (*setConfig)(struct I3cCntlr *cntlr, struct I3cConfig *config); + int32_t (*getConfig)(struct I3cCntlr *cntlr, struct I3cConfig *config); + int32_t (*requestIbi)(struct I3cDevice *dev); + void (*freeIbi)(struct I3cDevice *dev); +}; +``` + +**Table 1** Description of the callback functions in I3cMethod +|Function|Input Parameter|Output Parameter|Return Value|Description| +|-|-|-|-|-| +|sendCccCmd| **cntlr**: structure pointer to an I3C controller at the core layer.
**ccc**: pointer to the CCC to send.| **ccc**: pointer to the CCC sent.| HDF_STATUS|Sends a CCC.| +|Transfer| **cntlr**: structure pointer to an I3C controller at the core layer.
**msgs**: structure pointer to the messages to transfer.
**count**: length of the message array, which is of the int16_t type.| **msgs**: structure pointer to the messages transferred.| HDF_STATUS|Transfers user messages in I3C mode.| +|i2cTransfer| **cntlr**: structure pointer to an I3C controller at the core layer.
**msgs**: structure pointer to the messages to transfer.
**count**: length of the message array, which is of the int16_t type.| **msgs**: structure pointer to the messages transferred.| HDF_STATUS|Transfers user messages in I2C mode.| +|setConfig| **cntlr**: structure pointer to an I3C controller at the core layer.
**config**: pointer to the controller configuration.| –| HDF_STATUS|Sets an I3C controller.| +|getConfig| **cntlr**: structure pointer to an I3C controller at the core layer.| **config**: pointer to the controller configuration.| HDF_STATUS|Obtains the I3C controller configuration.| +|requestIbi| **device**: structure pointer to an I3C device at the core layer.| –| HDF_STATUS|Requests an IBI for an I3C device.| +|freeIbi| **device**: structure pointer to an I3C device at the core layer.| –| HDF_STATUS|Releases the IBI for an I3C device.| +### How to Develop The I3C module adaptation involves the following steps: 1. Instantiate the driver entry. - - Instantiate the **HdfDriverEntry** structure. - - Call **HDF_INIT** to register the **HdfDriverEntry** instance with the HDF. + + - Instantiate the **HdfDriverEntry** structure. + - Call **HDF_INIT** to register the **HdfDriverEntry** instance with the HDF. 2. Configure attribute files. - - - Add the **deviceNode** information to the **device_info.hcs** file. - - (Optional) Add the **i3c_config.hcs** file. - + + - Add the **deviceNode** information to the **device_info.hcs** file. + - (Optional) Add the **i3c_config.hcs** file. + 3. Instantiate the I3C controller object. - - - Initialize **I3cCntlr**. - - Instantiate **I3cMethod** in **I3cCntlr**. - For details, see [Available APIs](#available-apis). - -4. Register an interrupt handler. - Register an interrupt handler for the controller to implement the device hot-join and in-band interrupt (IBI) features. + - Initialize **I3cCntlr**. + - Instantiate **I3cMethod** in **I3cCntlr**. For details, see [Available APIs](#available-apis). - +4. Register an interrupt handler. -## Development Example + Registers an interrupt handler for the controller to implement the device hot-join and IBI features. -1. Instantiate the driver entry. The driver entry must be a global variable of the **HdfDriverEntry** type (defined in **hdf\_device\_desc.h**), and the value of **moduleName** must be the same as that in **device\_info.hcs**. In the HDF, the start address of each **HdfDriverEntry** object of all loaded drivers are collected to form a segment address space similar to an array for the upper layer to invoke. - Generally, the HDF calls the **Bind** function and then the **Init** function to load a driver. If **Init** fails to be called, the HDF calls **Release** to release driver resources and exit. - I3C driver entry reference: +## Development Example - > The I3C module may be connected with multiple controllers. Therefore, in the HDF, a manager object is created for the I3C, and a manager service is published to handle external access requests in a unified manner. Before a controller is opened, the manager service needs to be obtained first. Then, the manager service locates the target controller based on the specified parameters. - > - > The core layer implements the driver of the I3C manager service. Vendors do not need to care about the implementation. However, during the implementation of **Init()**, the **I3cCntlrAdd()** function at the core layer needs to be called to implement related features. +1. Instantiate the driver entry. + The driver entry must be a global variable of the **HdfDriverEntry** type (which is defined in **hdf_device_desc.h**), and the value of **moduleName** must be the same as that in **device_info.hcs**. In the HDF, the start address of each **HdfDriverEntry** object of all loaded drivers is collected to form a segment address space similar to an array for the upper layer to invoke. + + Generally, the HDF calls the **Bind** function and then the **Init** function to load a driver. If **Init** fails to be called, the HDF calls **Release** to release driver resources and exit. + + I3C driver entry example: + + > The system may have multiple I3C controllers. Therefore, you need to create a manager object in the HDF and publish a manager service to uniformly handle external access requests. Then, the manager service locates the controller to open based on the specified parameters. + > + > The core layer implements the driver of the I3C manager service. Vendors do not need to care about the implementation. However, the **I3cCntlrAdd()** function at the core layer must be called in the implementation of **Init()** to implement related features. + ```c static struct HdfDriverEntry g_virtualI3cDriverEntry = { .moduleVersion = 1, @@ -92,20 +149,22 @@ The I3C module adaptation involves the following steps: HDF_INIT(g_i3cManagerEntry); ``` -2. Add **deviceNode** to the **device\_info.hcs** file, and configure the device attributes in the **i3c\_config.hcs** file. The **deviceNode** information is related to registration of the driver entry. The device attribute values are closely related to the driver implementation and the default values or restriction ranges of the **I3cCntlr** members at the core layer. +2. Configure attribute files. + + Add **deviceNode** to the **device_info.hcs** file, and configure the device attributes in the **i3c_config.hcs** file. The **deviceNode** information is related to registration of the driver entry. The device attribute values are closely related to the driver implementation and the default values or restriction ranges of the **I3cCntlr** members at the core layer. - In the unified service mode, the first device node in the **device\_info** file must be the I3C manager. The I3C manager parameters must be set as follows: - - |Member|Value| + In the unified service mode, the first device node in the **device_info** file must be the I3C manager. The I3C manager parameters must be set as follows. + + |Name|Value| |-|-| |moduleName |HDF_PLATFORM_I3C_MANAGER| |serviceName|Reserved| |policy|0| |cntlrMatchAttr| Reserved | - - Configure I3C controller information from the second node. This node specifies a type of I3C controllers rather than a specific I3C controller. In this example, there is only one I3C controller. If there are multiple I3C controllers, you need to add the **deviceNode** information to the **device\_info** file and add the corresponding device attributes to the **i3c\_config** file. - - **device_info.hcs** configuration reference + Configure I3C controller information from the second node. This node specifies a type of I3C controllers rather than a specific I3C controller. In this example, there is only one I3C controller. If there are multiple I3C controllers, add the **deviceNode** information to the **device_info** file and add the corresponding device attributes to the **i3c_config** file for each controller. + + - **device_info.hcs** configuration example ```c root { @@ -129,7 +188,7 @@ The I3C module adaptation involves the following steps: } ``` - - **i3c_config.hcs** configuration reference + - i3c_config.hcs configuration example ```c root { @@ -138,9 +197,9 @@ The I3C module adaptation involves the following steps: match_attr = "virtual_i3c"; // (Mandatory) The value must be the same as that of deviceMatchAttr in device_info.hcs. template i3c_controller { // Template configuration. In the template, you can configure the common parameters shared by device nodes. busId = 0; // (Mandatory) I3C bus number. - busMode = 0x0; // Bus mode. Which can be 0x0 (pure), 0x1 (mixed-fast), 0x2 (mixed-limited), or 0x3 (mixed-slow). + busMode = 0x0; // Bus mode, which can be 0x0 (pure), 0x1 (mixed-fast), 0x2 (mixed-limited), or 0x3 (mixed-slow). regBasePhy = 0x120b0000; // (Mandatory) Physical base address. - regSize = 0xd1; // (Mandatory) Register bit width. + regSize = 0xd1; // (Mandatory) Register bit width. IrqNum = 20; // (Mandatory) Interrupt request (IRQ) number. i3cMaxRate = 12900000; // (Optional) Maximum clock rate in I3C mode. i3cRate = 12500000; // (Optional) Clock rate in I3C mode. @@ -156,21 +215,21 @@ The I3C module adaptation involves the following steps: } ``` -3. Initialize the **I3cCntlr** object at the core layer, including initializing the custom structure (passing parameters and data) and instantiating **I3cMethod** (used to call the underlying functions of the driver) in **I3cCntlr**. +3. Instantiate the I3C controller object. - The **HdfDriverEntry** member functions (**Bind**, **Init**, and **Release**) must be implemented in this step. + Initialize the **I3cCntlr** object at the core layer, including defining a custom structure (to pass parameters and data) and implementing the **HdfDriverEntry** member functions (**Bind**, **Init** and **Release**) to instantiate **I3cMethod** in **I3cCntlr** (so that the underlying driver functions can be called). - - Custom structure reference - - > The custom structure holds parameters and data for the driver. The HDF reads the values in the **i3c_config.hcs** file and initializes the structure members through **DeviceResourceIface**. Some important values, such as the device number and bus number, are also passed to the **I3cCntlr** object at the core layer. + - Define a custom structure. + + > To the driver, the custom structure holds parameters and data. The **DeviceResourceIface** method provided by the HDF reads the values in the **i3c_config.hcs** file to initialize the members in the custom structure and passes important parameters, such as the device number and bus number, to the **I3cCntlr** object at the core layer. ```c struct VirtualI3cCntlr { - struct I3cCntlr cntlr; // (Mandatory) Control object at the core layer. For details, see the following description of I3cCntlr. + struct I3cCntlr cntlr; // (Mandatory) Control object at the core layer. For details, see the following description. volatile unsigned char *regBase;// (Mandatory) Register base address. - uint32_t regBasePhy; // (Mandatory) Physical base address of the register. + uint32_t regBasePhy; // (Mandatory) Physical base address of the register. uint32_t regSize; // (Mandatory) Bit width of the register. - uint16_t busId; // (Mandatory) Device number. + uint16_t busId; // (Mandatory) Bus number. uint16_t busMode; uint16_t IrqNum; uint32_t i3cMaxRate; @@ -179,7 +238,7 @@ The I3C module adaptation involves the following steps: uint32_t i2cFmPlusRate; }; - /* I3cCntlr is the controller structure at the core layer. Its members are assigned with values by using the Init function. + /* I3cCntlr is the controller structure at the core layer. The Init function assigns values to the members of I3cCntlr. struct I3cCntlr { OsalSpinlock lock; void *owner; @@ -192,109 +251,115 @@ The I3C module adaptation involves the following steps: void *priv; }; ``` + + > Instantiate **I3cMethod** in **I3cCntlr**. The **I3cLockMethod** callback structure is not implemented in this example. To instantiate the structure, refer to the I2C driver development. Other members are initialized in **Init()**. - > **(Important)** This example does not provide the instantiation of the **I3cLockMethod** callback structure in **I3cCntlr**. For details, see the I2C driver development. Other members are initialized in the **Init** function. + - **Init** function + **Input parameter**: - - **Init** function + **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration file information. - > Input parameter: - > **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration. - > - > Return value: - > **HDF_STATUS** (The following table lists some states. For more details, see **HDF\_STATUS** definition in the **/drivers/framework/include/utils/hdf\_base.h file**.) - - |State|Description| - |:-|:--| - |HDF_ERR_INVALID_OBJECT|Invalid controller object.| - |HDF_ERR_INVALID_PARAM |Invalid parameter.| - |HDF_ERR_MALLOC_FAIL |Failed to allocate memory.| - |HDF_ERR_IO |I/O error.| - |HDF_SUCCESS |Transmission successful.| - |HDF_FAILURE |Transmission failed.| + **Return value**: - > Function description: - > Initializes the custom structure object and **I3cCntlr**, and calls the **I3cCntlrAdd** function to add the I3C controller to the core layer. - - ```c - static int32_t VirtualI3cParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node) - { - int32_t ret; - struct VirtualI3cCntlr *virtual = NULL; // (Mandatory) Custom structure object. - (void)device; + HDF_STATUS
The table below lists some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file. + + | Status| Description| + | -------- | -------- | + | HDF_ERR_INVALID_OBJECT | Invalid controller object.| + | HDF_ERR_MALLOC_FAIL | Failed to allocate memory.| + | HDF_ERR_INVALID_PARAM | Invalid parameter.| + | HDF_ERR_IO | I/O error.| + | HDF_SUCCESS | Transmission successful.| + | HDF_FAILURE | Transmission failed.| - virtual = (struct VirtualI3cCntlr *)OsalMemCalloc(sizeof(*virtual)); // (Mandatory) Allocate memory. - if (virtual == NULL) { - HDF_LOGE("%s: Malloc virtual fail!", __func__); - return HDF_ERR_MALLOC_FAIL; - } - ret = VirtualI3cReadDrs(virtual, node); // (Mandatory) Fill the default values defined in the i3c_config file to the structure. - if (ret != HDF_SUCCESS) { - HDF_LOGE("%s: Read drs fail! ret:%d", __func__, ret); - goto __ERR__; - } - ... - virtual->regBase = OsalIoRemap(virtual->regBasePhy, virtual->regSize);// (Mandatory) Address mapping. - ret = OsalRegisterIrq(hi35xx->softIrqNum, OSAL_IRQF_TRIGGER_NONE, I3cIbiHandle, "I3C", virtual); // (Mandatory) Register the interrupt handler. - if (ret != HDF_SUCCESS) { - HDF_LOGE("%s: register irq failed!", __func__); - return ret; - } - ... - VirtualI3cCntlrInit(virtual); // (Mandatory) Initialize the I3C device. - virtual->cntlr.priv = (void *)node; // (Mandatory) Set the storage device attributes. - virtual->cntlr.busId = virtual->busId; // (Mandatory) Initialize I3cCntlr. - virtual->cntlr.ops = &g_method; // (Mandatory) Connect to the I3cMethod instance. - (void)OsalSpinInit(&virtual->spin); - ret = I3cCntlrAdd(&virtual->cntlr); // (Mandatory) Call this function to add the controller to the core layer. If a success signal is returned, the driver is completely connected to the core layer. - if (ret != HDF_SUCCESS) { - HDF_LOGE("%s: add i3c controller failed! ret = %d", __func__, ret); - (void)OsalSpinDestroy(&virtual->spin); - goto __ERR__; - } - - return HDF_SUCCESS; - __ERR__: // If the controller fails to be added, deinitialize related functions. - if (virtual != NULL) { - OsalMemFree(virtual); - virtual = NULL; - } - - return ret; - } + **Function description**: - static int32_t VirtualI3cInit(struct HdfDeviceObject *device) - { - int32_t ret; - const struct DeviceResourceNode *childNode = NULL; - - if (device == NULL || device->property == NULL) { - HDF_LOGE("%s: device or property is NULL", __func__); - return HDF_ERR_INVALID_OBJECT; - } - - DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { - ret = VirtualI3cParseAndInit(device, childNode); - if (ret != HDF_SUCCESS) { - break; - } - } - - return ret; - } + Initializes the custom structure object and **I3cCntlr**, and calls the **I3cCntlrAdd** function to add the I3C controller to the core layer. + + ```c + static int32_t VirtualI3cParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node) + { + int32_t ret; + struct VirtualI3cCntlr *virtual = NULL; // (Mandatory) Custom structure object. + (void)device; + + virtual = (struct VirtualI3cCntlr *)OsalMemCalloc(sizeof(*virtual)); // (Mandatory) Allocate memory. + if (virtual == NULL) { + HDF_LOGE("%s: Malloc virtual fail!", __func__); + return HDF_ERR_MALLOC_FAIL; + } + + ret = VirtualI3cReadDrs(virtual, node); // (Mandatory) Fill the default values defined in the i3c_config file to the structure. + if (ret != HDF_SUCCESS) { + HDF_LOGE("%s: Read drs fail! ret:%d", __func__, ret); + goto __ERR__; + } + ... + virtual->regBase = OsalIoRemap(virtual->regBasePhy, virtual->regSize);// (Mandatory) Address mapping. + ret = OsalRegisterIrq(hi35xx->softIrqNum, OSAL_IRQF_TRIGGER_NONE, I3cIbiHandle, "I3C", virtual); // (Mandatory) Register an interrupt handler. + if (ret != HDF_SUCCESS) { + HDF_LOGE("%s: register irq failed!", __func__); + return ret; + } + ... + VirtualI3cCntlrInit(virtual); // (Mandatory) Initialize the I3C device. + virtual->cntlr.priv = (void *)node; // (Mandatory) Set the storage device attributes. + virtual->cntlr.busId = virtual->busId; // (Mandatory) Initialize I3cCntlr. + virtual->cntlr.ops = &g_method; // (Mandatory) Attach the I3cMethod instance. + (void)OsalSpinInit(&virtual->spin); + ret = I3cCntlrAdd(&virtual->cntlr); // (Mandatory) Call this function to add the controller to the core layer. If a success signal is returned, the driver is completely connected to the core layer. + if (ret != HDF_SUCCESS) { + HDF_LOGE("%s: add i3c controller failed! ret = %d", __func__, ret); + (void)OsalSpinDestroy(&virtual->spin); + goto __ERR__; + } + + return HDF_SUCCESS; + __ERR__: // If the controller fails to be added, deinitialize related functions. + if (virtual != NULL) { + OsalMemFree(virtual); + virtual = NULL; + } + + return ret; + } + + static int32_t VirtualI3cInit(struct HdfDeviceObject *device) + { + int32_t ret; + const struct DeviceResourceNode *childNode = NULL; + + if (device == NULL || device->property == NULL) { + HDF_LOGE("%s: device or property is NULL", __func__); + return HDF_ERR_INVALID_OBJECT; + } + + DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { + ret = VirtualI3cParseAndInit(device, childNode); + if (ret != HDF_SUCCESS) { + break; + } + } + + return ret; + } ``` - **Release** function - - > Input parameter: - > **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration. - > - > Return value: - > None. - > - > Function description: - > Releases the memory and deletes the controller. This function assigns a value to the **Release** function in the driver entry structure. If the HDF fails to call the **Init** function to initialize the driver, the **Release** function can be called to release driver resources. All forced conversion operations for obtaining the corresponding object can be successful only when the **Init** function has the corresponding value assignment operations. + + **Input parameter**: + + **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information. + + **Return value**: + + No value is returned. + + **Function description**: + + Releases the memory and deletes the controller. This function assigns values to the **Release** function in the driver entry structure. If the HDF fails to call the **Init** function to initialize the driver, the **Release** function can be called to release driver resources. All forced conversion operations for obtaining the corresponding object can be successful only when the **Init** function has the value assignment operations. ```c static void VirtualI3cRemoveByNode(const struct DeviceResourceNode *node) @@ -317,7 +382,7 @@ The I3C module adaptation involves the following steps: return; } ... - /* Call the I3cCntlrGet function to obtain the I3cCntlr object through the cntlrNum of the device, and call the I3cCntlrRemove function to release the I3cCntlr object. */ + /* Call I3cCntlrGet() to obtain the I3cCntlr object based on the cntlrNum of the device, and then call I3cCntlrRemove() to release the I3cCntlr object. */ cntlr = I3cCntlrGet(busId); if (cntlr != NULL && cntlr->priv == node) { I3cCntlrPut(cntlr); @@ -346,8 +411,10 @@ The I3C module adaptation involves the following steps: } } ``` + +4. Register an interrupt handler. -4. Implement the interrupt handler. The interrupt handler helps implement operations such as hot-join and IBI based on the address of the interrupt generated. + The interrupt handler performs an IBI or hot-join based on the address where the interrupt is generated. ```c static int32_t VirtualI3cReservedAddrWorker(struct VirtualI3cCntlr *virtual, uint16_t addr) @@ -390,7 +457,7 @@ The I3C module adaptation involves the following steps: return HDF_ERR_INVALID_PARAM; } virtual = (struct VirtualI3cCntlr *)data; - /* (Mandatory) Obtain the address where the interrupt is generated. Use the CHECK_RESERVED_ADDR macro to determine whether the address is a reserved address of the I3C. */ + /* (Mandatory) Obtain the address where the interrupt is generated. Use the CHECK_RESERVED_ADDR macro to determine whether the address is an I3C address. */ ibiAddr = VirtualI3cGetIbiAddr(); if (CHECK_RESERVED_ADDR(ibiAddr) == I3C_ADDR_RESERVED) { HDF_LOGD("%s: Calling VirtualI3cResAddrWorker...", __func__); @@ -412,4 +479,4 @@ The I3C module adaptation involves the following steps: return HDF_SUCCESS; } - ``` \ No newline at end of file + ``` diff --git a/en/device-dev/driver/figures/I3C_physical_connection.png b/en/device-dev/driver/figures/I3C_physical_connection.png index e83d1b2f65c29c86596d7113e7653fc6377123e5..b8062713ce1d0faad70e40fc6766fdd8f2a446e6 100644 GIT binary patch literal 33726 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 lk#J~Q$tGwg8uaf{{;zv<2?WX diff --git a/en/device-dev/driver/figures/I3C_usage_flowchart.png b/en/device-dev/driver/figures/I3C_usage_flowchart.png index 394b5c321bf5ce09cc2ffbfd3fc69fc8875f1b1e..ac226f9af3bb18bb1d642de8818c5414cf60af3b 100644 GIT binary patch literal 9847 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