Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
“2f7bb84fded2fccc19ff21c271fcaea833c1540b”上不存在“blog/front-end-learn/demo/css-5.html”
未验证 提交 ec2adeb5 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!6344 [翻译完成】#I5C6Q4 

Merge pull request !6344 from Annie_wang/PR5343
上级 042cff48 3081ec08
隐藏空白更改
内联 并排
Showing with 418 addition and 507 deletion
en/device-dev/driver/driver-platform-i3c-des.md
浏览文件 @ ec2adeb5
# I3C<a name="1"></a> # I3C
## Introduction
## Overview<a name="section1"></a> ### 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 - IBI
- Obtaining and setting I3C controller parameters
- Performing custom I3C message transfer by using a message array 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.
- Requesting and releasing an IBI
- Dynamic Address Assignment (DAA)
[Figure 1](#fig1) shows the 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:
**Figure 1** I3C physical connection<a name="fig1"></a><br/>
- 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") ![](figures/I3C_physical_connection.png "I3C_physical_connection")
## Available APIs<a name="section2"></a> ### 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 **Table 1** I3C driver APIs
<a name="table1"></a>
| API | Description |
<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="18.63%"><p>Category</p> | ------------- | ----------------- |
</th> | I3cOpen | Opens an I3C controller. |
<th class="cellrowborder" valign="top" width="28.03%"><p>API</p> | I3cClose | Closes an I3C controller. |
</th> | I3cTransfer | Performs custom transfer. |
<th class="cellrowborder" valign="top" width="53.339999999999996%"><p>Description</p> | I3cSetConfig | Sets the I3C controller. |
</th> | I3cGetConfig | Obtains the I3C controller configuration. |
</tr> | I3cRequestIbi | Requests an IBI. |
</thead> | I3cFreeIbi | Releases an IBI. |
<tbody><tr><td class="cellrowborder" bgcolor="#ffffff" rowspan="2" valign="top" width="18.63%"><p>I3C controller management</p>
</td> >![](../public_sys-resources/icon-note.gif) **NOTE**<br>
<td class="cellrowborder" valign="top" width="28.03%"><p>I3cOpen</p> >All APIs described in this document can be called only in kernel mode.
</td>
<td class="cellrowborder" valign="top" width="53.339999999999996%">Opens an I3C controller.</p> ### How to Develop
</td>
</tr> The figure below illustrates the use of I3C driver APIs.
<tr><td class="cellrowborder" valign="top"><p>I3cClose</p>
</td> **Figure 2** Process of using I3C driver APIs
<td class="cellrowborder" valign="top"><p>Closes an I3C controller.</p>
</td>
</tr>
<tr><td class="cellrowborder" bgcolor="#ffffff" valign="top" width="18.63%"><p>I3C transfer</p>
</td>
<td class="cellrowborder" valign="top" width="28.03%"><p>I3cTransfer</p>
</td>
<td class="cellrowborder" valign="top" width="53.339999999999996%"><p>Customizes an I3C transfer.</p>
</td>
</tr>
<tr><td class="cellrowborder" bgcolor=ffffff rowspan="2" valign="top" width="18.63%"><p>I3C controller configuration</p>
</td>
<td class="cellrowborder" valign="top" width="28.03%"><p>I3cSetConfig</p>
</td>
<td class="cellrowborder"valign="top" width="53.339999999999996%">Sets an I3C controller.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top"><p>I3cGetConfig</p>
</td>
<td class="cellrowborder" valign="top"><p>Obtains the I3C controller configuration.</p>
</td>
</tr>
<tr><td class="cellrowborder" bgcolor=ffffff rowspan="2" valign="top" width="18.63%"><p>I3C IBI</p>
</td>
<td class="cellrowborder" valign="top" width="28.03%"><p>I3cRequestIbi</p>
</td>
<td class="cellrowborder" valign="top" width="53.339999999999996%">Requests an IBI.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top"><p>I3cFreeIbi</p>
</td>
<td class="cellrowborder" valign="top"><p>Releases an IBI.</p>
</td>
</tr>
</table>
>![](../public_sys-resources/icon-note.gif) **NOTE**<br/>
>
>All functions described in this document can be called only in the kernel space.
## Usage Guidelines<a name="section3"></a>
### How to Use<a name="section4"></a>
[Figure 2](#fig2) shows how I3C works.
**Figure 2** How I3C works<a name="fig2"></a><br/>
![](figures/I3C_usage_flowchart.png "I3C_usage_flowchart") ![](figures/I3C_usage_flowchart.png "I3C_usage_flowchart")
### Opening an I3C Controller<a name="section5"></a> #### 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 ```c
DevHandle I3cOpen(int16_t number); DevHandle I3cOpen(int16_t number);
``` ```
**Table 2** Description of I3cOpen **Table 2** Description of I3cOpen
<a name="table2"></a> | Name | Description |
| ---------- | ------------------- |
<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="20.66%"><p>Parameter</strong></p> | number | I3C controller number. |
</th> | **Return Value**| **Description** |
<th class="cellrowborder" valign="top" width="79.34%"><p><strong>Description</strong></p> | NULL | The operation failed. |
</th> | Controller handle| The operation is successful. The handle of the I3C controller opened is returned. |
</tr>
</thead> Example: Open I3C controller 1 of the eight I3C controllers numbered from 0 to 7 in the system.
<tbody><tr><td class="cellrowborder" valign="top" width="20.66%"><p>number</p>
</td>
<td class="cellrowborder" valign="top" width="79.34%"><p>I3C controller ID.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="20.66%"><p><strong>Return Value</strong></p>
</td>
<td class="cellrowborder" valign="top" width="79.34%"><p><strong>Description</strong></p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="20.66%"><p>NULL</p>
</td>
<td class="cellrowborder" valign="top" width="79.34%"><p>Failed to open the I3C controller.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="20.66%"><p>Controller handle</p>
</td>
<td class="cellrowborder" valign="top" width="79.34%"><p>Handle of the I3C controller opened.</p>
</td>
</tr>
</tbody>
</table>
The following example opens I3C controller 1 of the eight I3C controllers (numbered from 0 to 7) in the system.
```c ```c
DevHandle i3cHandle = NULL; /* I3C controller handle. / DevHandle i3cHandle = NULL; /* I3C controller handle. /
...@@ -147,7 +116,7 @@ if (i3cHandle == NULL) { ...@@ -147,7 +116,7 @@ if (i3cHandle == NULL) {
} }
``` ```
### Performing I3C Communication<a name="section6"></a> #### Performing I3C Communication
Call **I3cTransfer()** to transfer messages. Call **I3cTransfer()** to transfer messages.
```c ```c
...@@ -156,53 +125,18 @@ int32_t I3cTransfer(DevHandle handle, struct I3cMsg *msgs, int16_t count, enum T ...@@ -156,53 +125,18 @@ int32_t I3cTransfer(DevHandle handle, struct I3cMsg *msgs, int16_t count, enum T
**Table 3** Description of I3cTransfer **Table 3** Description of I3cTransfer
<a name="table3"></a>
| Name | Description |
<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="50%"><p><strong> Parameter</strong></p> | ---------- | -------------------------------------------- |
</th> | handle | I3C controller handle. |
<th class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p> | msgs | Pointer to the message array of the data to transfer. |
</th> | count | Length of the message array. |
</tr> | mode | Transmission mode. The value **0** indicates I2C mode, **1** indicates I3C mode, and **2** indicates CCC transmission. |
</thead> | **Return Value**| **Description** |
<tbody><tr><td class="cellrowborder" valign="top" width="50%"><p>handle</p> | Positive integer | The operation is successful. The number of message structures that are successfully transmitted is returned. |
</td> | Negative value | The operation failed. |
<td class="cellrowborder" valign="top" width="50%"><p>I3C controller handle.</p>
</td> 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.
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>msgs</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>Pointer to the message structure array of the data to be transmitted.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>count</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>Length of the message array.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>mode</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>Transmission mode, where the value <b>0</b> indicates the I2C mode, <b>1</b> indicates the I3C mode, and <b>2</b> indicates transmission of the Common Command Code (CCC).
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p><strong>Return Value</strong></p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>Positive integer</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>Number of message structures successfully transferred.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>Negative number</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>The operation failed.</p>
</td>
</tr>
</tbody>
</table>
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.
```c ```c
int32_t ret; int32_t ret;
...@@ -225,13 +159,14 @@ if (ret != 2) { ...@@ -225,13 +159,14 @@ if (ret != 2) {
} }
``` ```
>![](../public_sys-resources/icon-caution.gif) **Caution** >![](./public_sys-resources/icon-caution.gif) **Caution**<br>
>
>- 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 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. >- 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. >- Using **I3cTransfer()** may cause the system to sleep. Do not call it in the interrupt context.
### Obtaining the I3C Controller Configuration<a name="section7"></a> #### Obtaining the I3C Controller Configuration
Call **I3cGetConfig()** to obtain the configuration of an I3C controller.
```c ```c
int32_t I3cGetConfig(DevHandle handle, struct I3cConfig *config); int32_t I3cGetConfig(DevHandle handle, struct I3cConfig *config);
...@@ -239,43 +174,30 @@ 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 **Table 4** Description of I3cGetConfig
<a name="table4"></a>
| Name | Description |
<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="50%"><p><strong>Parameter</strong></p> | ---------- | -------------- |
</th> | handle | I3C controller handle. |
<th class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p> | config | Pointer to the I3C controller configuration. |
</th> | **Return Value**| **Description**|
</tr> | 0 | The operation is successful. |
</thead> | Negative value | The operation failed. |
<tbody><tr><td class="cellrowborder" valign="top" width="50%"><p>handle</p>
</td> The following is an example of obtaining the I3C controller configuration:
<td class="cellrowborder" valign="top" width="50%"><p>I3C controller handle.</p>
</td> ```c
</tr> struct I3cConfig config;
<tr><td class="cellrowborder" valign="top" width="50%"><p>config</p>
</td> ret = I3cGetConfig(i3cHandle, &config);
<td class="cellrowborder" valign="top" width="50%"><p>Pointer to the I3C controller configuration.</p> if (ret != HDF_SUCCESS) {
</td> HDF_LOGE("%s: Get config fail!", __func__);
</tr> return HDF_FAILURE;
<tr><td class="cellrowborder" valign="top" width="50%"><p><strong>Return Value</strong></p> }
</td> ```
<td class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p>
</td> #### Setting an I3C Controller
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>0</p> Call **I3cSetConfig()** to set an I3C controller.
</td>
<td class="cellrowborder" valign="top" width="50%"><p>The operation is successful.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>Negative number</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>Failed to obtain the I3C controller configuration.</p>
</td>
</tr>
</tbody>
</table>
### Configuring an I3C Controller<a name="section8"></a>
```c ```c
int32_t I3cSetConfig(DevHandle handle, struct I3cConfig *config); int32_t I3cSetConfig(DevHandle handle, struct I3cConfig *config);
...@@ -283,43 +205,32 @@ 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 **Table 5** Description of I3cSetConfig
<a name="table5"></a>
| Name | Description |
<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="50%"><p><strong>Parameter</strong></p> | ---------- | -------------- |
</th> | handle | I3C controller handle. |
<th class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p> | config | Pointer to the I3C controller configuration. |
</th> | **Return Value**| **Description**|
</tr> | 0 | The operation is successful. |
</thead> | Negative value | The operation failed. |
<tbody><tr><td class="cellrowborder" valign="top" width="50%"><p>handle</p>
</td> The following is an example of setting an I3C controller:
<td class="cellrowborder" valign="top" width="50%"><p>I3C controller handle.</p>
</td> ```c
</tr> struct I3cConfig config;
<tr><td class="cellrowborder" valign="top" width="50%"><p>config</p>
</td> config->busMode = I3C_BUS_HDR_MODE;
<td class="cellrowborder" valign="top" width="50%"><p>Pointer to the I3C controller configuration.</p> config->curMaster = NULL;
</td> ret = I3cSetConfig(i3cHandle, &config);
</tr> if (ret != HDF_SUCCESS) {
<tr><td class="cellrowborder" valign="top" width="50%"><p><strong>Return Value</strong></p> HDF_LOGE("%s: Set config fail!", __func__);
</td> return HDF_FAILURE;
<td class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p> }
</td> ```
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>0</p> #### Requesting an IBI
</td>
<td class="cellrowborder" valign="top" width="50%"><p>The operation is successful.</p> Call **I3cRequestIbi()** to request an IBI.
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>Negative number</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>Failed to configure the I3C controller.</p>
</td>
</tr>
</tbody>
</table>
### Requesting an IBI<a name="section9"></a>
```c ```c
int32_t I3cRequestIbi(DevHandle handle, uint16_t addr, I3cIbiFunc func, uint32_t payload); 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 ...@@ -327,51 +238,18 @@ int32_t I3cRequestIbi(DevHandle handle, uint16_t addr, I3cIbiFunc func, uint32_t
**Table 6** Description of I3cRequestIbi **Table 6** Description of I3cRequestIbi
<a name="table6"></a>
| Name | Description |
<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="50%"><p><strong>Parameter</strong></p> | ---------- | -------------- |
</th> | handle | I3C controller handle. |
<th class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p> | addr | I3C device address. |
</th> | func | Callback used to return the IBI. |
</tr> | payload | IBI payload. |
</thead> | **Return Value**| **Description**|
<tbody><tr><td class="cellrowborder" valign="top" width="50%"><p>handle</p> | 0 | The operation is successful. |
</td> | Negative value | The operation failed. |
<td class="cellrowborder" valign="top" width="50%"><p>I3C controller handle.</p>
</td> The following is an example:
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>addr</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>I3C device address.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>func</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>Callback used to return the IBI.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>payload</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>IBI payload.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p><strong>Return Value</strong></p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p>
</td>
</tr>
<tr><td class="cellrowborder"valign="top" width="50%"><p>0</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>The operation is successful.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>Negative number</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p> Failed to request the IBI.</p>
</td>
</tr>
</tbody>
</table>
```c ```c
static int32_t TestI3cIbiFunc(DevHandle handle, uint16_t addr, struct I3cIbiData data) static int32_t TestI3cIbiFunc(DevHandle handle, uint16_t addr, struct I3cIbiData data)
...@@ -388,7 +266,7 @@ int32_t I3cTestRequestIbi(void) ...@@ -388,7 +266,7 @@ int32_t I3cTestRequestIbi(void)
DevHandle i3cHandle = NULL; DevHandle i3cHandle = NULL;
int32_t ret; int32_t ret;
/* Open an I3C controller. */ /* Open the I3C controller. */
i3cHandle = I3cOpen(1); i3cHandle = I3cOpen(1);
if (i3cHandle == NULL) { if (i3cHandle == NULL) {
HDF_LOGE("I3cOpen: failed\n"); HDF_LOGE("I3cOpen: failed\n");
...@@ -407,7 +285,9 @@ int32_t I3cTestRequestIbi(void) ...@@ -407,7 +285,9 @@ int32_t I3cTestRequestIbi(void)
} }
``` ```
### Releasing an IBI<a name="section10"></a> #### Releasing an IBI
Call **I3cFreeIbi()** to release an IBI.
```c ```c
int32_t I3cFreeIbi(DevHandle handle, uint16_t addr); int32_t I3cFreeIbi(DevHandle handle, uint16_t addr);
...@@ -415,47 +295,22 @@ 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 **Table 7** Description of I3cFreeIbi
<a name="table7"></a>
| Name | Description |
<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="50%"><p><strong>Parameter</strong></p> | ---------- | -------------- |
</th> | handle | I3C controller handle. |
<th class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p> | addr | I3C device address. |
</th> | **Return Value**| **Description**|
</tr> | 0 | The operation is successful. |
</thead> | Negative value | The operation failed. |
<tbody><tr><td class="cellrowborder" valign="top" width="50%"><p>handle</p>
</td> The following is an example:
<td class="cellrowborder" valign="top" width="50%"><p>I3C controller handle.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>addr</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>I3C device address.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p><strong>Return Value</strong></p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p><strong>Description</strong></p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>0</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>The operation is successful.</p>
</td>
</tr>
<tr><td class="cellrowborder" valign="top" width="50%"><p>Negative number</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>Failed to release the IBI.</p>
</td>
</tr>
</tbody>
</table>
```c ```c
I3cFreeIbi(i3cHandle, 0x3F); /* Release an IBI. */ I3cFreeIbi(i3cHandle, 0x3F); /* Release an IBI. */
``` ```
### Closing an I3C controller<a name="section11"></a> #### Closing an I3C Controller
Call **I3cClose()** to close the I3C controller after the communication is complete. Call **I3cClose()** to close the I3C controller after the communication is complete.
```c ```c
...@@ -464,28 +319,18 @@ void I3cClose(DevHandle handle); ...@@ -464,28 +319,18 @@ void I3cClose(DevHandle handle);
**Table 8** Description of I3cClose **Table 8** Description of I3cClose
<a name="table4"></a>
<table><thead align="left"><tr><th class="cellrowborder" valign="top" width="50%"><p> Parameter</p> | Name | Description |
</th> | ---------- | -------------- |
<th class="cellrowborder" valign="top" width="50%"><p>Description</p> | handle | I3C controller handle. |
</th>
</tr>
</thead>
<tbody><tr><td class="cellrowborder" valign="top" width="50%"><p>handle</p>
</td>
<td class="cellrowborder" valign="top" width="50%"><p>I3C controller handle.</p>
</td>
</tr>
</tbody>
</table>
The following is an example:
```c ```c
I3cClose(i3cHandle); /* Close an I3C controller. */ I3cClose(i3cHandle); /* Close the I3C controller. */
``` ```
## Example<a name="section12""></a> ## Development Example
This following example shows how to use I3C APIs to manage an I3C device on a Hi3516D V300 development board. 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: ...@@ -503,10 +348,9 @@ The sample code is as follows:
```c ```c
#include "i3c_if.h" /* Header file for I3C standard APIs */ #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 "hdf_log.h" /* Header file for log APIs */
##include "osal_io.h" /* Header file for I/O read and write 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. */ /* Define a device structure to hold information. */
struct TestI3cDevice { struct TestI3cDevice {
...@@ -516,7 +360,7 @@ struct TestI3cDevice { ...@@ -516,7 +360,7 @@ struct TestI3cDevice {
DevHandle i3cHandle; /* I3C controller handle */ 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, static int TestI3cReadWrite(struct TestI3cDevice *testDevice, unsigned int regAddr,
unsigned char *regData, unsigned int dataLen, uint8_t flag) unsigned char *regData, unsigned int dataLen, uint8_t flag)
{ {
...@@ -539,7 +383,7 @@ static int TestI3cReadWrite(struct TestI3cDevice *testDevice, unsigned int regAd ...@@ -539,7 +383,7 @@ static int TestI3cReadWrite(struct TestI3cDevice *testDevice, unsigned int regAd
msgs[0].buf = regBuf; msgs[0].buf = regBuf;
msgs[1].addr = testDevice->addr; 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].len = dataLen;
msgs[1].buf = regData; msgs[1].buf = regData;
......
en/device-dev/driver/driver-platform-i3c-develop.md
浏览文件 @ ec2adeb5
# I3C # I3C
## Overview<a name="1"></a> ## 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<a name="fig1"></a> 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) ![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<a name="2"></a> ### Available APIs
**I3cMethod**: **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| ```c
|-|-|-|-|-| struct I3cMethod {
|sendCccCmd|**cntlr**: structure pointer to an I3C controller at the core layer. <br/>**ccc**: pointer to the input common command code (CCC) structure.|**ccc**: pointer to the output CCC structure.|HDF_STATUS|Sends a CCC.| int32_t (*sendCccCmd)(struct I3cCntlr *cntlr, struct I3cCccCmd *ccc);
|Transfer |**cntlr**: structure pointer to an I3C controller at the core layer. <br/>**msgs**: structure pointer to user messages. <br/>**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.| int32_t (*transfer)(struct I3cCntlr *cntlr, struct I3cMsg *msgs, int16_t count);
|i2cTransfer |**cntlr**: structure pointer to an I3C controller at the core layer. <br/>**msgs**: structure pointer to user messages. <br>**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.| int32_t (*i2cTransfer)(struct I3cCntlr *cntlr, struct I3cMsg *msgs, int16_t count);
|setConfig|**cntlr**: structure pointer to an I3C controller at the core layer. <br/>**config**: pointer to controller configuration parameters.|–|HDF_STATUS|Sets an I3C controller.| int32_t (*setConfig)(struct I3cCntlr *cntlr, struct I3cConfig *config);
|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.| int32_t (*getConfig)(struct I3cCntlr *cntlr, struct I3cConfig *config);
|requestIbi|**device**: structure pointer to an I3C device at the core layer.|–|HDF_STATUS|Requests an IBI for an I3C device.| int32_t (*requestIbi)(struct I3cDevice *dev);
|freeIbi|**device**: structure pointer to an I3C device at the core layer.|–|HDF_STATUS|Releases the IBI for an I3C device.| void (*freeIbi)(struct I3cDevice *dev);
};
## How to Develop<a name="3"></a> ```
**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.<br>**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.<br>**msgs**: structure pointer to the messages to transfer.<br>**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.<br>**msgs**: structure pointer to the messages to transfer.<br>**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.<br>**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: The I3C module adaptation involves the following steps:
1. Instantiate the driver entry. 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. 2. Configure attribute files.
- Add the **deviceNode** information to the **device_info.hcs** file. - Add the **deviceNode** information to the **device_info.hcs** file.
- (Optional) Add the **i3c_config.hcs** file. - (Optional) Add the **i3c_config.hcs** file.
3. Instantiate the I3C controller object. 3. Instantiate the I3C controller object.
- Initialize **I3cCntlr**.
- Instantiate **I3cMethod** in **I3cCntlr**.
For details, see [Available APIs](#available-apis). - 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.
4. Register an interrupt handler.
## Development Example<a name="4"></a> 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. 1. Instantiate the driver entry.
>
> 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.
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 ```c
static struct HdfDriverEntry g_virtualI3cDriverEntry = { static struct HdfDriverEntry g_virtualI3cDriverEntry = {
.moduleVersion = 1, .moduleVersion = 1,
...@@ -92,20 +149,22 @@ The I3C module adaptation involves the following steps: ...@@ -92,20 +149,22 @@ The I3C module adaptation involves the following steps:
HDF_INIT(g_i3cManagerEntry); 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: 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| |Name|Value|
|-|-| |-|-|
|moduleName |HDF_PLATFORM_I3C_MANAGER| |moduleName |HDF_PLATFORM_I3C_MANAGER|
|serviceName|Reserved| |serviceName|Reserved|
|policy|0| |policy|0|
|cntlrMatchAttr| Reserved | |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 ```c
root { root {
...@@ -129,7 +188,7 @@ The I3C module adaptation involves the following steps: ...@@ -129,7 +188,7 @@ The I3C module adaptation involves the following steps:
} }
``` ```
- **i3c_config.hcs** configuration reference - i3c_config.hcs configuration example
```c ```c
root { root {
...@@ -138,9 +197,9 @@ The I3C module adaptation involves the following steps: ...@@ -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. 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. template i3c_controller { // Template configuration. In the template, you can configure the common parameters shared by device nodes.
busId = 0; // (Mandatory) I3C bus number. 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. 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. IrqNum = 20; // (Mandatory) Interrupt request (IRQ) number.
i3cMaxRate = 12900000; // (Optional) Maximum clock rate in I3C mode. i3cMaxRate = 12900000; // (Optional) Maximum clock rate in I3C mode.
i3cRate = 12500000; // (Optional) 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: ...@@ -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 - Define a custom structure.
> 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. > 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 ```c
struct VirtualI3cCntlr { 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. 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. 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 busMode;
uint16_t IrqNum; uint16_t IrqNum;
uint32_t i3cMaxRate; uint32_t i3cMaxRate;
...@@ -179,7 +238,7 @@ The I3C module adaptation involves the following steps: ...@@ -179,7 +238,7 @@ The I3C module adaptation involves the following steps:
uint32_t i2cFmPlusRate; 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 { struct I3cCntlr {
OsalSpinlock lock; OsalSpinlock lock;
void *owner; void *owner;
...@@ -192,109 +251,115 @@ The I3C module adaptation involves the following steps: ...@@ -192,109 +251,115 @@ The I3C module adaptation involves the following steps:
void *priv; 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: **Return value**:
> **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.|
> Function description: HDF_STATUS<br>The table below lists some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file.
> Initializes the custom structure object and **I3cCntlr**, and calls the **I3cCntlrAdd** function to add the I3C controller to the core layer.
| Status| Description|
```c | -------- | -------- |
static int32_t VirtualI3cParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node) | HDF_ERR_INVALID_OBJECT | Invalid controller object.|
{ | HDF_ERR_MALLOC_FAIL | Failed to allocate memory.|
int32_t ret; | HDF_ERR_INVALID_PARAM | Invalid parameter.|
struct VirtualI3cCntlr *virtual = NULL; // (Mandatory) Custom structure object. | HDF_ERR_IO | I/O error.|
(void)device; | 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. **Function description**:
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;
}
static int32_t VirtualI3cInit(struct HdfDeviceObject *device) Initializes the custom structure object and **I3cCntlr**, and calls the **I3cCntlrAdd** function to add the I3C controller to the core layer.
{
int32_t ret; ```c
const struct DeviceResourceNode *childNode = NULL; static int32_t VirtualI3cParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node)
{
if (device == NULL || device->property == NULL) { int32_t ret;
HDF_LOGE("%s: device or property is NULL", __func__); struct VirtualI3cCntlr *virtual = NULL; // (Mandatory) Custom structure object.
return HDF_ERR_INVALID_OBJECT; (void)device;
}
virtual = (struct VirtualI3cCntlr *)OsalMemCalloc(sizeof(*virtual)); // (Mandatory) Allocate memory.
DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { if (virtual == NULL) {
ret = VirtualI3cParseAndInit(device, childNode); HDF_LOGE("%s: Malloc virtual fail!", __func__);
if (ret != HDF_SUCCESS) { return HDF_ERR_MALLOC_FAIL;
break; }
}
} ret = VirtualI3cReadDrs(virtual, node); // (Mandatory) Fill the default values defined in the i3c_config file to the structure.
if (ret != HDF_SUCCESS) {
return ret; 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 - **Release** function
> Input parameter: **Input parameter**:
> **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration.
> **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information.
> Return value:
> None. **Return value**:
>
> Function description: No value is returned.
> 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.
**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 ```c
static void VirtualI3cRemoveByNode(const struct DeviceResourceNode *node) static void VirtualI3cRemoveByNode(const struct DeviceResourceNode *node)
...@@ -317,7 +382,7 @@ The I3C module adaptation involves the following steps: ...@@ -317,7 +382,7 @@ The I3C module adaptation involves the following steps:
return; 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); cntlr = I3cCntlrGet(busId);
if (cntlr != NULL && cntlr->priv == node) { if (cntlr != NULL && cntlr->priv == node) {
I3cCntlrPut(cntlr); I3cCntlrPut(cntlr);
...@@ -346,8 +411,10 @@ The I3C module adaptation involves the following steps: ...@@ -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 ```c
static int32_t VirtualI3cReservedAddrWorker(struct VirtualI3cCntlr *virtual, uint16_t addr) static int32_t VirtualI3cReservedAddrWorker(struct VirtualI3cCntlr *virtual, uint16_t addr)
...@@ -390,7 +457,7 @@ The I3C module adaptation involves the following steps: ...@@ -390,7 +457,7 @@ The I3C module adaptation involves the following steps:
return HDF_ERR_INVALID_PARAM; return HDF_ERR_INVALID_PARAM;
} }
virtual = (struct VirtualI3cCntlr *)data; 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(); ibiAddr = VirtualI3cGetIbiAddr();
if (CHECK_RESERVED_ADDR(ibiAddr) == I3C_ADDR_RESERVED) { if (CHECK_RESERVED_ADDR(ibiAddr) == I3C_ADDR_RESERVED) {
HDF_LOGD("%s: Calling VirtualI3cResAddrWorker...", __func__); HDF_LOGD("%s: Calling VirtualI3cResAddrWorker...", __func__);
...@@ -412,4 +479,4 @@ The I3C module adaptation involves the following steps: ...@@ -412,4 +479,4 @@ The I3C module adaptation involves the following steps:
return HDF_SUCCESS; return HDF_SUCCESS;
} }
``` ```
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或