An analog-to-digital converter (ADC) is a device that converts analog signals into digital signals.
An analog-to-digital converter (ADC) converts analog signals into digital signals for storage and computing. In addition to the power cable and ground cable, the ADC requires only one cable to connect to the target device. The following figure shows the physical connection of the ADC.
The ADC module provides a set of APIs to complete AD conversion, including:
The ADC APIs provide a set of common functions for ADC data transfer, including:
- Opening or closing an ADC device
- Opening or closing an ADC device
- Obtaining the analog-to-digital (AD) conversion result
- Obtaining the analog-to-digital (AD) conversion result
### Basic Concepts
### Basic Concepts
The ADC converts analog parameters into digital parameters for easy storage and computing. The technical specifications of the ADC include the following:
- Resolution
- Resolution
The number of binary bits that can be converted by an ADC. A greater number of bits indicates a higher resolution.
The number of binary bits that can be converted by an ADC. A greater number of bits indicates a higher resolution.
- Conversion error
- Conversion error
Difference between the actual and theoretical digital values output by an ADC. It is expressed by a multiple of the least significant bit. Generally, the maximum output error is used.
Difference between the actual and theoretical digital values output by an ADC. It is expressed by a multiple of the least significant bit. Generally, the maximum output error is used.
- Transition time
- Transition time
Time required by an ADC to perform a complete conversion.
Time required by an ADC to perform a complete conversion.
### Working Principles
### Working Principles
In the Hardware Driver Foundation (HDF), the ADC module uses the unified service mode for API adaptation. In this mode, a service is used as the ADC 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. If the independent service mode is used in this case, more device nodes need to be configured and more memory resources will be consumed.
In the Hardware Driver Foundation (HDF), the ADC module uses the unified service mode for API adaptation. In this mode, a service is used as the ADC 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. 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 ADC module is divided into the following layers:
- Interface layer: provides APIs for opening or closing a device and writing data.
- Core layer: provides the capabilities of binding, initializing, and releasing devices.
In addition to the power and ground cables, the ADC requires only one cable to connect to the target device. The figure below shows the physical connection.
Currently, the ADC module supports only the kernels (LiteOS) of mini and small systems.
The ADC module can read data only in polling mode.
## Usage Guidelines
## Usage Guidelines
### When to Use
### When to Use
An ADC is usually used to convert an analog voltage into a digital parameter, for example, it is used with a microphone to collect sound, used with an NTC resistor to measure temperature, or converts the output of analog sensors into digital parameters.
ADC devices are used to convert analog voltage or current into digital parameters. For example, an ADC can be used with an NTC resistor to measure temperature, or can be used to convert the output of an analog sensor into a digital parameter.
### Available APIs
### Available APIs
The table below describes the APIs of the ADC module. For more details, see API Reference.
The following table describes the APIs of the ADC module. For more information, see **//drivers/hdf_core/framework/include/platform/adc_if.h**.
**Table 1** APIs of the ADC driver
**Table 1** APIs of the ADC driver
| API | Description |
| API | Description |
| -------- | ---------------- |
| -------- | ---------------- |
| AdcOpen | Opens an ADC device. |
| DevHandle AdcOpen(uint32_t number) | Opens an ADC device. |
| AdcClose | Closes an ADC device. |
| void AdcClose(DevHandle handle) | Closes an ADC device. |
| AdcRead | Obtains the AD conversion result.|
| int32_t AdcRead(DevHandle handle, uint32_t channel, uint32_t \*val) | Obtains the AD conversion result.|
### How to Develop
### How to Develop
The figure below shows the general development process.
The following figure illustrates how to use ADC APIs.
An analog-to-digital converter (ADC) is a device that converts analog signals into digital signals. In the Hardware Driver Foundation (HDF), the ADC module uses the unified service mode for API adaptation. In this mode, a device service is used as the ADC 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 ADC 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
An analog-to-digital converter (ADC) is a device that converts analog signals into digital signals.
![](figures/unified-service-mode.png"ADC Unified Service Mode")
### Basic Concepts
- Resolution
## Available APIs
The number of binary bits that can be converted by an ADC. A greater number of bits indicates a higher resolution.
**AdcMethod**:
- Conversion error
Difference between the actual and theoretical digital values output by an ADC. It is expressed by a multiple of the least significant bit. Generally, the maximum output error is used.
```
- Transition time
Time required by an ADC to perform a complete conversion.
### Working Principles
In the Hardware Driver Foundation (HDF), the ADC module uses the unified service mode for API adaptation. In this mode, a device service is used as the ADC manager to handle access requests from the devices of the same type in a unified manner. The unified service mode applies to the scenario where there are many device objects of the same type. 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 following figure illustrates the unified service mode of the ADC module.
The ADC module is divided into the following layers:
- Interface layer: provides the capabilities of opening a device, writing data, and closing a device.
- Core layer: binds services, initializes and releases the PlatformManager, and provides the capabilities of adding, deleting, and obtaining controllers.
- Adaptation layer: implements hardware-related functions, such as controller initialization.
In the unified service mode, the core layer manages all controllers in a unified manner and publishes a service for the interface layer. That is, the driver does not need to publish a service for each controller.
**Figure 1** Unified service mode
![](figures/unified-service-mode.png"ADC Unified Service Mode")
## Usage Guidelines
### When to Use
ADC devices are used to convert analog voltage into digital parameters. For example, an ADC can be used with an NTC resistor to measure temperature, or can be used to convert the output of an analog sensor into a digital parameter. Before using ADC devices with OpenHarmony, you need to adapt the ADC driver to OpenHarmony. The following describes how to do it.
### Available APIs
To enable the upper layer to successfully operate the hardware by calling the ADC APIs, hook functions are defined in **//drivers/hdf_core/framework/support/platform/include/adc/adc_core.h** for the core layer. You need to implement these hook functions at the adaptation layer and hook them to implement the interaction between the interface layer and the core layer.
Definitions of **AdcMethod** and **AdcLockMethod**:
**Table 1** Description of the callback functions in AdcMethod
At the adaptation layer, **AdcMethod** must be implemented, and **AdcLockMethod** can be implemented based on service requirements. The core layer provides the default **AdcLockMethod**, in which a spinlock is used to protect the critical section.
If spinlock cannot be used, you can use another type of lock to implement **AdcLockMethod**. The custom **AdcLockMethod** will replace the default **AdcLockMethod**.
| read | **device**: structure pointer to the ADC controller at the core layer.<br>**channel**: channel ID, which is of the uint32_t type.| **val**: pointer to the signal data to be transmitted. It is of the uint32_t type.| HDF_STATUS| Reads the signal data sampled by the ADC.|
| read | **device**: structure pointer to the ADC controller at the core layer.<br>**channel**: channel number, which is of the uint32_t type.| **val**: pointer to the signal data to be transmitted. It is of the uint32_t type.| HDF_STATUS| Reads the signal data sampled by the ADC.|
| stop | **device**: structure pointer to the ADC controller at the core layer.| –| HDF_STATUS| Stops an ADC device.|
| stop | **device**: structure pointer to the ADC controller at the core layer.| –| HDF_STATUS| Stops an ADC device.|
| start | **device**: structure pointer to the ADC controller at the core layer.| –| HDF_STATUS| Starts an ADC device.|
| start | **device**: structure pointer to the ADC controller at the core layer.| –| HDF_STATUS| Starts an ADC device.|
> For details, see [Available APIs](#available-apis).
> For details about the functions in **AdcMethod**, see [Available APIs](#available-apis).
4. Debug the driver.
(Optional) For new drivers, verify basic functions, for example, check the information returned after the driver is attached and check whether signals are successfully collected.
### Example
## Development Example
The following uses the Hi3516D V300 driver **//device/soc/hisilicon/common/platform/adc/adc_hi35xx.c** as an example to describe how to perform the ADC driver adaptation.
The following uses **adc_hi35xx.c** as an example to present the information required for implementing device functions.
1. Instantiate the driver entry.
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 is collected to form a segment address space similar to an array for the upper layer to invoke.
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 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.
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.
ADC driver entry example:
ADC driver entry example:
Many devices may connect to the ADC. In the HDF, a manager object needs to be created for the ADC. When a device needs to be started, the manager object locates the target device based on the specified parameters.
Multiple devices may connect to the ADC controller. In the HDF, a manager object needs to be created for this type of devices. When a device needs to be started, the manager object locates the target device based on the specified parameters.
The driver of the ADC manager is implemented by the core layer. The **Init** function of the driver layer calls **AdcDeviceAdd** of the core layer to add devices to the ADC manager. Therefore, you do not need to implement this part.
You do not need to implement the driver of the ADC manager, which is implemented by the core layer. However, the **AdcDeviceAdd** function of the core layer must be invoked in the **Init** function to implement the related features.
.moduleName = "hi35xx_adc_driver", // (Mandatory) This parameter must be the same as that in the .hcs file.
.moduleName = "hi35xx_adc_driver", // (Mandatory) The value must be the same as the module name in the device_info.hcs file.
};
};
HDF_INIT(g_hi35xxAdcDriverEntry); // Call HDF_INIT to register the driver entry with the HDF.
HDF_INIT(g_hi35xxAdcDriverEntry); // Call HDF_INIT to register the driver entry with the HDF.
// Driver entry of the adc_core.c manager service at the core layer
/* Driver entry of the adc_core.c manager service at the core layer */
struct HdfDriverEntry g_adcManagerEntry = {
struct HdfDriverEntry g_adcManagerEntry = {
.moduleVersion = 1,
.moduleVersion = 1,
.Init = AdcManagerInit,
.Init = AdcManagerInit,
.Release = AdcManagerRelease,
.Release = AdcManagerRelease,
.moduleName = "HDF_PLATFORM_ADC_MANAGER", // The value is device0 in the device_info file.
.moduleName = "HDF_PLATFORM_ADC_MANAGER", // The value must be that of device0 in the device_info.hcs file.
};
};
HDF_INIT(g_adcManagerEntry);
HDF_INIT(g_adcManagerEntry);
```
```
2. Add **deviceNode** to the **device_info.hcs** file, and configure the device attributes in the **adc_config.hcs** file.
2. Add the **deviceNode** information to the **//vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs** file and configure the device attributes in **adc_config.hcs**.
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 **AdcDevice** members at the core layer.
The **deviceNode** information is related to the driver entry registration. The device attribute values are closely related to the driver implementation and the default values or value ranges of the **AdcDevice** members at the core layer.
In the unified service mode, the first device node in the **device_info** file must be the ADC manager. The parameters must be set as follows:
In the unified service mode, the first device node in the **device_info.hcs** file must be the ADC manager. The parameters must be set as follows:
| Parameter| Value|
| Parameter| Value|
| -------- | -------- |
| -------- | -------- |
| moduleName | **HDF_PLATFORM_ADC_MANAGER**|
| moduleName | **HDF_PLATFORM_ADC_MANAGER**|
| serviceName | –|
| serviceName | –|
| policy | **0**, which indicates that no service is published.|
| policy | **0**, which indicates that no service is published.|
| deviceMatchAttr | Reserved.|
| deviceMatchAttr | Reserved.|
Configure ADC controller information from the second node. This node specifies a type of ADC controllers rather than an ADC controller. In this example, there is only one ADC device. If there are multiple ADC devices, add the **deviceNode** information to the **device_info** file and add the corresponding device attributes to the **adc_config** file for each device.
Configure ADC controller information from the second node. This node specifies a type of ADC controllers rather than an ADC controller. In this example, there is only one ADC device. If there are multiple ADC devices, add the **deviceNode** information to the **device_info.hcs** file and add the corresponding device attributes to the **adc_config** file for each device.
-**device_info.hcs** configuration example
-**device_info.hcs** example
```c
```
root {
root {
device_info {
device_info {
platform :: host {
platform :: host {
device_adc :: device {
device_adc :: device {
device0 :: deviceNode {
device0 :: deviceNode {
policy = 0;
policy = 0;
priority = 50;
priority = 50;
permission = 0644;
permission = 0644;
moduleName = "HDF_PLATFORM_ADC_MANAGER";
moduleName = "HDF_PLATFORM_ADC_MANAGER";
serviceName = "HDF_PLATFORM_ADC_MANAGER";
serviceName = "HDF_PLATFORM_ADC_MANAGER";
}
}
device1 :: deviceNode {
device1 :: deviceNode {
policy = 0; // The value 0 indicates that no service is published.
policy = 0; // The value 0 indicates that no service is published.
priority = 55; // Driver startup priority.
priority = 55; // Driver startup priority.
permission = 0644; // Permission to create device nodes for the driver.
permission = 0644; // Permission for the device node created.
moduleName = "hi35xx_adc_driver"; // (Mandatory) Driver name, which must be the same as moduleName in the driver entry.
moduleName = "hi35xx_adc_driver"; // (Mandatory) Driver name, which must be the same as moduleName in the driver entry.
serviceName = "HI35XX_ADC_DRIVER"; // (Mandatory) Unique name of the service published by the driver.
serviceName = "HI35XX_ADC_DRIVER"; // (Mandatory) Unique name of the service published by the driver.
deviceMatchAttr = "hisilicon_hi35xx_adc";// (Mandatory) Private data of the controller. The value must be the same as that of the corresponding controller in adc_config.hcs.
deviceMatchAttr = "hisilicon_hi35xx_adc"; // (Mandatory) Private data of the controller. The value must be the same as that of the controller in adc_config.hcs.
// The specific controller information is configured in adc_config.hcs.
// The specific controller information is in adc_config.hcs.
}
}
}
}
}
}
}
}
}
}
```
```
-**adc_config.hcs** configuration example
-**adc_config.hcs** example
```
The following uses Hi3516D V300 as an example. Some fields are unique to Hi3516D V300. You can delete or add fields as required.
```c
root {
root {
platform {
platform {
adc_config_hi35xx {
adc_config_hi35xx {
match_attr = "hisilicon_hi35xx_adc";
match_attr = "hisilicon_hi35xx_adc";
template adc_device {
template adc_device {
regBasePhy = 0x120e0000;// Physical base address of the register.
regBasePhy = 0x120e0000; // Physical base address of the register.
regSize = 0x34; // Bit width of the register.
regSize = 0x34; // Bit width of the register.
deviceNum = 0; // Device number.
deviceNum = 0; // Device number.
validChannel = 0x1; // Valid channel.
validChannel = 0x1; // Valid channel.
dataWidth = 10; // Bit width of the received signal.
dataWidth = 10; // Data width after AD conversion, that is, the resolution.
scanMode = 1; // Scan mode.
scanMode = 1; // Scan mode.
delta = 0; // Delta parameter.
delta = 0; // Error range of the conversion result.
deglitch = 0;
deglitch = 0; // Setting of the deglitch.
glitchSample = 5000;
glitchSample = 5000; // Deglitch time window.
rate = 20000;
rate = 20000; // Conversion rate.
}
device_0 :: adc_device {
deviceNum = 0;
validChannel = 0x2;
}
}
}
}
device_0 :: adc_device {
deviceNum = 0;
validChannel = 0x2;
}
}
}
}
}
```
```
3. Initialize the **AdcDevice** 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 **AdcMethod** in **AdcDevice** (so that the underlying driver functions can be called).
After the **adc_config.hcs** file is configured, include the file in the **hdf.hcs** file. Otherwise, the configuration file cannot take effect.
- Defining a custom structure
To the driver, the custom structure holds parameters and data. The **DeviceResourceIface()** function provided by the HDF reads **adc_config.hcs** to initialize the custom structure and passes some important parameters, such as the device number and bus number, to the **AdcDevice** object at the core layer.
For example, if the **adc_config.hcs** file is in **//device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/adc/**, add the following statement to **hdf.hcs** of the product:
```c
#include "../../../../device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/adc/adc_config.hcs" // Relative path of the configuration file
```
```
This example is based on the Hi3516D V300 development board that runs the LiteOS. The corresponding **hdf.hcs** file is in **vendor/hisilicon/hispark_taurus/hdf_config/hdf.hcs** and **//device/hisilicon/hispark_taurus/sdk_liteos/hdf_config/hdf.hcs**. You can modify the file as required.
3. Initialize the **AdcDevice** 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 **AdcMethod** in **AdcDevice** (so that the underlying driver functions can be called).
- Define a custom structure.
To the driver, the custom structure holds parameters and data. The DeviceResourceIface() function provided by the HDF reads **adc_config.hcs** to initialize the custom structure and passes some important parameters, such as the device number and bus number, to the **AdcDevice** object at the core layer.
```c
struct Hi35xxAdcDevice {
struct Hi35xxAdcDevice {
struct AdcDevice device; // (Mandatory) Control object at the core layer. For details, see the description of AdcDevice.
struct AdcDevice device; // (Mandatory) Control object at the core layer. It must be the first member of the custom structure. For details, see the following description.
volatile unsigned char *regBase; // (Mandatory) Register base address.
volatile unsigned char *regBase; // (Mandatory) Register base address.
volatile unsigned char *pinCtrlBase;
volatile unsigned char *pinCtrlBase;
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) Register bit width.
uint32_t deviceNum; // (Mandatory) Device number.
uint32_t deviceNum; // (Mandatory) Device number.
uint32_t dataWidth; // (Mandatory) Data bit width of received signals.
uint32_t dataWidth; // (Mandatory) Data bit width of received signals.
@@ -185,7 +266,7 @@ The ADC module adaptation involves the following steps:
...
@@ -185,7 +266,7 @@ The ADC module adaptation involves the following steps:
uint32_t rate; // (Mandatory) Sampling rate.
uint32_t rate; // (Mandatory) Sampling rate.
};
};
// AdcDevice is the core layer controller structure. The **Init()** function assigns values to the members of AdcDevice.
/* AdcDevice is the core layer controller structure. The **Init()** function assigns values to the members of AdcDevice. */
struct AdcDevice {
struct AdcDevice {
const struct AdcMethod *ops;
const struct AdcMethod *ops;
OsalSpinlock spin;
OsalSpinlock spin;
...
@@ -196,25 +277,27 @@ The ADC module adaptation involves the following steps:
...
@@ -196,25 +277,27 @@ The ADC module adaptation involves the following steps:
};
};
```
```
- Instantiating **AdcMethod** in **AdcDevice**<br>This example does not provide the implementation of the **AdcLockMethod** callback. For details, see I2C driver development. Other members are initialized by the **Init** function.
- Instantiate the hook function structure **AdcMethod** of **AdcDevice**.
The **AdcLockMethod** is not implemented in this example. To instantiate the structure, refer to the I2C driver development. Other members are initialized in the **Init** function.
```
```c
static const struct AdcMethod g_method = {
static const struct AdcMethod g_method = {
.read = Hi35xxAdcRead,
.read = Hi35xxAdcRead,
.stop = Hi35xxAdcStop,
.stop = Hi35xxAdcStop,
.start = Hi35xxAdcStart,
.start = Hi35xxAdcStart,
};
};
```
```
-**Init** function
**Input parameter**:
- Implement the **Init** function.
Input parameter:
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information.
**HdfDeviceObject**, an interface parameter provided by the driver, contains the .hcs information.
**Return value**:
Return value:
**HDF_STATUS**<br/>The table below describes some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file.
**HDF_STATUS**<br/>The table below describes some status. For more information, see **HDF_STATUS** in the **//drivers/hdf_core/framework/include/utils/hdf_base.h** file.
| Status| Description|
| Status| Description|
| -------- | -------- |
| -------- | -------- |
...
@@ -225,19 +308,19 @@ The ADC module adaptation involves the following steps:
...
@@ -225,19 +308,19 @@ The ADC module adaptation involves the following steps:
| HDF_SUCCESS | Transmission successful.|
| HDF_SUCCESS | Transmission successful.|
| HDF_FAILURE | Transmission failed.|
| HDF_FAILURE | Transmission failed.|
**Function description**:
Function description:
Initializes the custom structure object and **AdcDevice**, and calls the **AdcDeviceAdd** function at the core layer.
Initializes the custom structure object and **AdcDevice**, and calls the **AdcDeviceAdd** function at the core layer.
ret = Hi35xxAdcReadDrs(hi35xx, node); // (Mandatory) Fill the default values in the adc_config file to the structure.
ret = Hi35xxAdcReadDrs(hi35xx, node); // （Mandatory) Use the default values in the adc_config file to fill in the structure. The function definition is as follows.
hi35xx->device.ops = &g_method; // (Mandatory) Attach the AdcMethod instance object.
hi35xx->device.ops = &g_method; // (Mandatory) Attach the AdcMethod instance object.
ret = AdcDeviceAdd(&hi35xx->device); // (Mandatory) Call this function to set the structure of the core layer. The driver accesses the platform core layer only after a success signal is returned.
ret = AdcDeviceAdd(&hi35xx->device)); // (Mandatory) Call this function to set the structure at the core layer. The driver can access the platform core layer only after a success signal is returned.
...
...
return HDF_SUCCESS;
return HDF_SUCCESS;
__ERR__:
__ERR__:
if (hi35xx != NULL) { // If the operation fails, execute the initialization function reversely.
if (hi35xx != NULL) { // If the operation fails, deinitialize related functions.
if (drsOps == NULL || drsOps->GetUint32 == NULL) {
HDF_LOGE("%s: invalid drs ops", __func__);
return HDF_ERR_NOT_SUPPORT;
}
/* Read the configuration parameters in sequence and fill them in the structure. */
ret = drsOps->GetUint32(node, "regBasePhy", &hi35xx->regBasePhy, 0);
if (ret != HDF_SUCCESS) {
HDF_LOGE("%s: read regBasePhy failed", __func__);
return ret;
}
ret = drsOps->GetUint32(node, "regSize", &hi35xx->regSize, 0);
if (ret != HDF_SUCCESS) {
HDF_LOGE("%s: read regSize failed", __func__);
return ret;
}
···
return HDF_SUCCESS;
}
}
```
```
-**Release** function
**Input parameter**:
- Implement the **Release** function.
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information.
Input parameter:
**Return value**:
**HdfDeviceObject**, an interface parameter provided by the driver, contains the .hcs information.
No value is returned.
Return value:
**Function description**:
No value is returned.
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.
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.
ret = drsOps->GetUint32(node, "deviceNum", (uint32_t *)&deviceNum, 0);
ret = drsOps->GetUint32(node, "deviceNum", (uint32_t *)&deviceNum, 0);
...
...
// You can call the AdcDeviceGet function to obtain the AdcDevice object based on deviceNum and call the AdcDeviceRemove function to release the AdcDevice object.
/* You can use AdcDeviceGet() to obtain the AdcDevice object based on deviceNum and use AdcDeviceRemove() to release the AdcDevice object. */
device = AdcDeviceGet(deviceNum);
device = AdcDeviceGet(deviceNum);
if (device != NULL && device->priv == node) {
if (device != NULL && device->priv == node) {
AdcDevicePut(device);
AdcDevicePut(device);
AdcDeviceRemove(device); // (Mandatory) Remove the AdcDevice object from the driver manager.
AdcDeviceRemove(device); // (Mandatory) Remove the AdcDevice object from the driver manager.
hi35xx = (struct Hi35xxAdcDevice *)device;// (Mandatory) Obtain the custom object through forced conversion and release the operation.
hi35xx = (struct Hi35xxAdcDevice *)device; // (Mandatory) Obtain the custom object through forcible conversion and perform the Release operation. To perform this operation, the device must be the first member of the custom structure.
A digit-to-analog converter (DAC) is a device that converts a digital signal into an analog signal in electronics.
A digit-to-analog converter (DAC) is a device that converts a digital signal into an analog signal in electronics. DAC devices are used to:
The DAC APIs provide a set of methods for DAC data transfer, including:
- Provide the output channel for the process control computer system and connect to the executor to implement automatic control of the production process.
- Serve as an important module in the analog-to-digital converter using feedback technologies.
The DAC module provides a set of methods for DAC data transfer, including:
- Opening or closing a DAC device
- Opening or closing a DAC device
- Setting the target digital-to-analog (DA) value
- Setting the target digital-to-analog (DA) value
### Basic Concepts
### Basic Concepts
The DAC module provides the output channel for the process control computer system. It connects to the executor to implement automatic control of the production process. It is also an important module in the analog-to-digital converter using feedback technologies.
- Resolution
- Resolution
The number of binary bits that can be converted by a DAC. A greater number of bits indicates a higher resolution.
The number of binary bits that can be converted by a DAC. A greater number of bits indicates a higher resolution.
...
@@ -32,7 +33,7 @@ The DAC module provides the output channel for the process control computer syst
...
@@ -32,7 +33,7 @@ The DAC module provides the output channel for the process control computer syst
### Working Principles
### Working Principles
In the Hardware Driver Foundation (HDF), the DAC module uses the unified service mode for API adaptation. In this mode, a service is used as the DAC 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. 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 shows the unified service mode.
In the Hardware Driver Foundation (HDF), the DAC module uses the unified service mode for API adaptation. In this mode, a service is used as the DAC 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. If the independent service mode is used, more device nodes need to be configured and memory resources will be consumed by services. The following figure illustrates the unified service mode of the DAC module.
The DAC module is divided into the following layers:
The DAC module is divided into the following layers:
...
@@ -40,9 +41,7 @@ The DAC module is divided into the following layers:
...
@@ -40,9 +41,7 @@ The DAC module is divided into the following layers:
- Core layer: provides the capabilities of binding, initializing, and releasing devices.
- Core layer: provides the capabilities of binding, initializing, and releasing devices.
**NOTE**<br/>The core layer can call the functions of the interface layer and uses the hook to call functions of the adaptation layer. In this way, the adaptation layer can indirectly call the functions of the interface layer, but the interface layer cannot call the functions of the adaptation layer.
>
> The core layer can call the functions of the interface layer and uses a hook to call functions of the adaptation layer. In this way, the adaptation layer can indirectly call the functions of the interface layer, but the interface layer cannot call the functions of the adaptation layer.
**Figure 1** Unified service mode
**Figure 1** Unified service mode
...
@@ -50,7 +49,7 @@ The DAC module is divided into the following layers:
...
@@ -50,7 +49,7 @@ The DAC module is divided into the following layers:
### Constraints
### Constraints
Currently, the DAC module supports only the kernels (LiteOS) of mini and small systems.
The DAC module supports only the kernel (LiteOS-A) for mini and small systems.
## Usage Guidelines
## Usage Guidelines
...
@@ -60,11 +59,11 @@ The DAC module converts digital signals into analog signals in the form of curre
...
@@ -60,11 +59,11 @@ The DAC module converts digital signals into analog signals in the form of curre
### Available APIs
### Available APIs
The table below describes the APIs of the DAC module. For more details, see API Reference.
The following table describes the APIs of the DAC module. For more information about the APIs, see **//drivers/hdf_core/framework/include/platform/dac_if.h**.
A digit-to-analog converter (DAC) is a device that converts a digital signal into an analog signal in electronics.
A digit-to-analog converter (DAC) is a device that converts a digital signal into an analog signal in electronics.
The DAC module supports development of digital-to-analog conversion. The DAC module provides the output channel for the process control computer system. It connects to the executor to implement automatic control of the production process. It is also an important module in the analog-to-digital converter using feedback technologies.
The DAC module supports development of digital-to-analog conversion. The DAC devices can be used to:
- Provide the output channel for the process control computer system and connect to the executor to implement automatic control of the production process.
- Serve as an important module in the analog-to-digital converter using feedback technologies.
### Basic Concepts
### Basic Concepts
...
@@ -28,54 +31,96 @@ The DAC module supports development of digital-to-analog conversion. The DAC mod
...
@@ -28,54 +31,96 @@ The DAC module supports development of digital-to-analog conversion. The DAC mod
### Working Principles
### Working Principles
In the Hardware Driver Foundation (HDF), the DAC module uses the unified service mode for API adaptation. In this mode, a device service is used as the DAC manager to handle access requests from the devices of the same type in a unified manner. The unified service mode applies to the scenario where there are many device objects of the same type. 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 shows the unified service mode.
In the Hardware Driver Foundation (HDF), the DAC module uses the unified service mode for API adaptation. In this mode, a device service is used as the DAC manager to handle access requests from the devices of the same type in a unified manner. The unified service mode applies to the scenario where there are many device objects of the same type. 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 DAC module uses the unified service mode, as shown in Figure 1.
The DAC module is divided into the following layers:
The DAC module is divided into the following layers:
- Interface layer: provides the capabilities of opening and closing a device and writing data.
- Interface layer: provides APIs for opening or closing a device and writing data.
- Core layer: provides the capabilities of binding, initializing, and releasing devices.
- Core layer: provides the capabilities of binding, initializing, and releasing devices.
- Adaptation layer: implements other functions.
- Adaptation layer: implements hardware-related functions, such as controller initialization.
**NOTE**<br/>The core layer can call the APIs of the interface layer and uses hooks to call APIs of the adaptation layer. In this way, the adaptation layer can indirectly call the APIs of the interface layer, but the interface layer cannot call the APIs of the adaptation layer.
In the unified service mode, the core layer manages all controllers in a unified manner and publishes a service for the interface layer. That is, the driver does not need to publish a service for each controller.
**Figure 1** Unified service mode
> **NOTE**<br/>The core layer can call the APIs of the interface layer and uses hooks to call APIs of the adaptation layer. In this way, the adaptation layer can indirectly call the APIs of the interface layer, but the interface layer cannot call the APIs of the adaptation layer.
**Figure 1** Unified service mode
![](figures/unified-service-mode.png"DAC unified service mode")
![](figures/unified-service-mode.png"DAC unified service mode")
### Constraints
### Constraints
Currently, the DAC module supports only the kernels (LiteOS) of mini and small systems.
The DAC module supports only the kernel (LiteOS-A) for mini and small systems.
## Development Guidelines
## Development Guidelines
### When to Use
### When to Use
The DAC module is used for digital-to-analog conversion, audio output, and motor control. The DAC driver is used when the digital signals input by the DAC module are converted into analog signals to output.
The DAC module is used for digital-to-analog conversion, audio output, and motor control. The DAC driver is used when the digital signals input by the DAC module are converted into analog signals to output. Before using DAC devices with OpenHarmony, you need to adapt the DAC driver to OpenHarmony. The following describes how to do it.
### Available APIs
### Available APIs
The **DacMethod** structure is used to call the DAC driver APIs.
To enable the upper layer to successfully operate the hardware by calling the DAC APIs, hook functions are defined in **//drivers/hdf_core/framework/support/platform/include/dac/dac_core.h** for the core layer. You need to implement these hook functions at the adaptation layer and hook them to implement the interaction between the interface layer and the core layer.
**DacMethod**:
Definitions of **DacMethod** and **DacLockMethod**:
At the adaptation layer, **DacMethod** must be implemented, and **DacLockMethod** can be implemented based on service requirements. The core layer provides the default **DacLockMethod**, in which a spinlock is used to protect the critical section.
**Table 1** Description of the DacMethod structure
If spinlock cannot be used, you can use another type of lock to implement **DacLockMethod**. The implemented **DacLockMethod** will replace the default **DacLockMethod**.
| write | **device**: structure pointer to the DAC controller at the core layer.<br>**channel**: channel ID, which is of the uint32_t type.<br>**val**: data to write, which is of the uint32_t type.| - | HDF_STATUS| Writes the target digit-to-analog (DA) value.|
| write | **device**: structure pointer to the DAC controller at the core layer.<br>**channel**: channel ID, which is of the uint32_t type.<br>**val**: data to write, which is of the uint32_t type.| - | HDF_STATUS| Writes the target digit-to-analog (DA) value.|
| start | **device**: structure pointer to the DAC controller at the core layer. | - | HDF_STATUS| Starts a DAC device. |
| start | **device**: structure pointer to the DAC controller at the core layer. | - | HDF_STATUS| Starts a DAC device. |
| stop | **device**: structure pointer to the DAC controller at the core layer. | - | HDF_STATUS| Stops a DAC device. |
| stop | **device**: structure pointer to the DAC controller at the core layer. | - | HDF_STATUS| Stops a DAC device. |
| lock | **device**: structure pointer to the DAC device object at the core layer.| -| HDF_STATUS| Acquires the critical section lock.|
| unlock | **device**: structure pointer to the DAC device object at the core layer.| -| HDF_STATUS| Releases the critical section lock.|
### How to Develop
### How to Develop
...
@@ -86,31 +131,31 @@ The DAC module adaptation procedure is as follows:
...
@@ -86,31 +131,31 @@ The DAC module adaptation procedure is as follows:
3. Instantiate the core layer APIs.
3. Instantiate the core layer APIs.
4. Debug the driver.
4. Debug the driver.
### Development Example
### Example
The following presents the information required for implementing device functions.
The following uses the Hi3516D V300 driver **//device/soc/hisilicon/common/platform/dac/dac_hi35xx.c** as an example to describe how to perform the DAC driver adaptation.
1. Instantiate the driver entry.
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 module name must be the same as that in **//vendor/hisilicon/hispark_taurus/hdf_config/device_info/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 **Init()** to load the driver. If **Init** fails to be called, the HDF calls **Release** to release driver resources and exit.
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 is collected to form a segment address space similar to an array for the upper layer to invoke.
Generally, the HDF calls the **Init()** function to load the driver. If **Init** fails to be called, the HDF calls **Release** to release driver resources and exit.
```c++
```c++
static struct HdfDriverEntry g_dacDriverEntry = {
static struct HdfDriverEntry g_dacDriverEntry = {
.moduleVersion = 1,
.moduleVersion = 1,
.Init = VirtualDacInit,
.Init = VirtualDacInit,
.Release = VirtualDacRelease,
.Release = VirtualDacRelease,
.moduleName = "virtual_dac_driver",// (Mandatory) The value must be the same as that in the .hcs file.
.moduleName = "virtual_dac_driver",// (Mandatory) The value must be the same as that in the .hcs file.
};
};
HDF_INIT(g_dacDriverEntry); // Call HDF_INIT to register the driver entry with the HDF.
HDF_INIT(g_dacDriverEntry); // Call HDF_INIT to register the driver entry with the HDF.
```
```
2. Configure attribute files.
2. Configure attribute files.
- Add the device node description to the **vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs** file.
- Add the **//vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs** file.
The device attribute values are closely related to the driver implementation and the default values or restriction ranges of the **DacDevice** members at the core layer, for example, the number of device channels and the maximum transmission speed.
The device attribute values are closely related to the driver implementation and the default values or value ranges of the **DacDevice** members at the core layer, for example, the number of device channels and the maximum transmission speed.
In the unified service mode, the first device node in the **device_info.hcs** file must be the DAC manager. The parameters must be set as follows:
In the unified service mode, the first device node in the **device_info.hcs** file must be the DAC manager. The parameters must be set as follows:
...
@@ -123,14 +168,14 @@ The following presents the information required for implementing device function
...
@@ -123,14 +168,14 @@ The following presents the information required for implementing device function
| serviceName | **HDF_PLATFORM_DAC_MANAGER** |
| serviceName | **HDF_PLATFORM_DAC_MANAGER** |
| deviceMatchAttr | Reserved. |
| deviceMatchAttr | Reserved. |
Configure DAC controller information from the second node. This node specifies a type of DAC controllers rather than a specific DAC controller. In this example, there is only one DAC device. If there are multiple DAC devices, you need to add the **deviceNode** information to the **device_info** file and add the corresponding device attributes to the **dac_config** file.
Configure DAC controller information from the second node. This node specifies a type of DAC controllers rather than a specific DAC controller. In this example, there is only one DAC device. If there are multiple DAC devices, add the **deviceNode** information to the **device_info.hcs** file and add the corresponding device attributes to the **dac_config.hcs** file for each device.
**device_info.hcs** configuration example:
**device_info.hcs** example:
```hcs
```hcs
root {
root {
device_dac :: device {
device_dac :: device {
// device0 is a DAC manager.
/* device0 is the DAC manager. */
device0 :: deviceNode {
device0 :: deviceNode {
policy = 0;
policy = 0;
priority = 52;
priority = 52;
...
@@ -139,21 +184,23 @@ The following presents the information required for implementing device function
...
@@ -139,21 +184,23 @@ The following presents the information required for implementing device function
moduleName = "HDF_PLATFORM_DAC_MANAGER";
moduleName = "HDF_PLATFORM_DAC_MANAGER";
}
}
}
}
// dac_virtual is a DAC controller.
/* dac_virtual is a DAC controller. */
dac_virtual :: deviceNode {
dac_virtual :: deviceNode {
policy = 0;
policy = 0;
priority = 56;
priority = 56;
permission = 0644;
permission = 0644;
moduleName = "virtual_dac_driver"; // (Mandatory) Driver name, which must be the same as moduleName in the driver entry.
moduleName = "virtual_dac_driver"; // (Mandatory) Driver name, which must be the same as moduleName in the driver entry.
serviceName = "VIRTUAL_DAC_DRIVER"; // (Mandatory) Unique name of the service published by the driver.
serviceName = "VIRTUAL_DAC_DRIVER"; // (Mandatory) Unique name of the service published by the driver.
deviceMatchAttr = "virtual_dac"; // (Mandatory) Controller private data, which must be same as that of the corresponding controller in dac_config.hcs.
deviceMatchAttr = "virtual_dac"; // (Mandatory) Controller private data, which must be same as that of the controller in dac_config.hcs.
}
}
}
}
```
```
- Configure the **dac_test_config.hcs** file.
- Configure the **dac_test_config.hcs** file.
Add a file, for example, **vendor/vendor_hisilicon/hispark_taurus/hdf_config/hdf_test/dac_test_config.hcs** and configure driver parameters.
Add a file to the directory of a product to configure driver parameters. For example, add the **vendor/hisilicon/hispark_taurus/hdf_config/hdf_test/dac_test_config.hcs** file for the hispark_taurus development board.
The configuration parameters are as follows:
```hcs
```hcs
root {
root {
...
@@ -162,304 +209,352 @@ The following presents the information required for implementing device function
...
@@ -162,304 +209,352 @@ The following presents the information required for implementing device function
match_attr = "virtual_dac"; // (Mandatory) The value must be the same as that of deviceMatchAttr in device_info.hcs.
match_attr = "virtual_dac"; // (Mandatory) The value must be the same as that of deviceMatchAttr in device_info.hcs.
template dac_device {
template dac_device {
deviceNum = 0; // Device number.
deviceNum = 0; // Device number.
validChannel = 0x1; // Valid channel 1.
validChannel = 0x1; // Valid channel 1.
rate = 20000; // Transmission speed.
rate = 20000; // Transmission speed.
}
}
device_0 :: dac_device {
device_0 :: dac_device {
deviceNum = 0; // Device number.
deviceNum = 0; // Device number.
validChannel = 0x2; // Valid channel 2.
validChannel = 0x2; // Valid channel 2.
}
}
}
}
}
}
}
}
```
```
3. Instantiate the core layer APIs.
After the **dac_config.hcs** file is configured, include the file in the **hdf.hcs** file. Otherwise, the configuration file cannot take effect.
- Initializing the **DacDevice** object
For example, if the path of **dac_config.hcs** is **device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/dac/dac_config.hcs**, add the following statement to **hdf.hcs** of the product:
Initialize the **DacDevice** member in the **VirtualDacParseAndInit** function.
```c
#include "../../../../device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/dac/dac_config.hcs" // Relative path of the file.
```
3. Instantiate the core layer APIs.
- Initialize the **DacDevice** object.
Initialize **DacDevice** in the **VirtualDacParseAndInit** function.
```c++
```c++
// Custom structure of the virtual driver
/* Custom structure of the virtual driver. */
struct VirtualDacDevice {
struct VirtualDacDevice {
// DAC device structure
/* DAC device structure. */
struct DacDevice device;
struct DacDevice device;
// DAC device number
/* DAC device number. */
uint32_t deviceNum;
uint32_t deviceNum;
// Valid channel
/* Valid channel. */
uint32_t validChannel;
uint32_t validChannel;
// DAC rate
/* DAC rate. */
uint32_t rate;
uint32_t rate;
};
};
// Parse and initialize the **DacDevice** object of the core layer.
/* Parse and initialize the **DacDevice** object of the core layer. */
/* Release the space for the virtual DAC device. */
OsalMemFree(virtual);
OsalMemFree(virtual);
// Set the pointer to 0.
/* Set the pointer to 0. */
virtual = NULL;
virtual = NULL;
return ret;
return ret;
}
}
// Initialize the pointer to the virtual DAC device.
/* Initialize the pointer to the virtual DAC device. */
VirtualDacDeviceInit(virtual);
VirtualDacDeviceInit(virtual);
// Initialize the priv object in DacDevice.
/* Initialize the priv object in DacDevice. */
virtual->device.priv = (void *)node;
virtual->device.priv = (void *)node;
// Initialize the devNum object in DacDevice.
/* Initialize the devNum object in DacDevice. */
virtual->device.devNum = virtual->deviceNum;
virtual->device.devNum = virtual->deviceNum;
// Initialize the ops object in DacDevice.
/* Initialize the ops object in DacDevice. */
virtual->device.ops = &g_method;
virtual->device.ops = &g_method;
// Add a DAC device.
/* Add a DAC device. */
ret = DacDeviceAdd(&virtual->device);
ret = DacDeviceAdd(&virtual->device);
if (ret != HDF_SUCCESS) {
if (ret != HDF_SUCCESS) {
// Failed to add the device.
/* Failed to add the device. */
HDF_LOGE("%s: add Dac controller failed! ret = %d", __func__, ret);
HDF_LOGE("%s: add Dac controller failed! ret = %d", __func__, ret);
// Release the space for the virtual DAC device.
/* Release the space for the virtual DAC device. */
OsalMemFree(virtual);
OsalMemFree(virtual);
// Set this pointer to null.
/* Set this pointer to null. */
virtual = NULL;
virtual = NULL;
return ret;
return ret;
}
}
return HDF_SUCCESS;
return HDF_SUCCESS;
}
}
```
```
- Defining a custom structure
The custom structure holds parameters and data for the driver. Define the custom structure based on the function parameters of the device. The **DacTestReadConfig()** provided by the HDF reads the values in the **dac_config.hcs** file, and **DeviceResourceIface()** initializes the custom structure and passes some important parameters, such as the device number and bus number, to the **DacDevice** object at the core layer.
- Define a custom structure.
```c++
The custom structure holds parameters and data for the driver. Define the custom structure based on the function parameters of the device. The **DacTestReadConfig()** provided by the HDF reads the values in the **dac_config.hcs** file, and **DeviceResourceIface()** initializes the custom structure and passes some important parameters, such as the device number and bus number, to the **DacDevice** object at the core layer.
struct VirtualDacDevice {
struct DacDevice device;// (Mandatory) Control object at the core layer. For details, see the description below.
> **NOTE**<br>For details about **DacMethod**, see [Available APIs](#available-apis).
For details about **DacMethod**, see [Available APIs](#available-apis).
- **Init** function
**Input parameter**:
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information.
**Return value**:
**HDF_STATUS**<br/>The table below describes some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file.
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information.
**HdfDeviceObject**, an interface parameter provided by the driver, contains the .hcs information.
**Return value**:
Return value:
No value is returned.
**HDF_STATUS**<br/>The table below describes some status. For more information, see **HDF_STATUS** in the **//drivers/hdf_core/framework/include/utils/hdf_base.h** file.
| HDF_ERR_MALLOC_FAIL | Failed to allocate memory. |
| HDF_ERR_IO | I/O error. |
| HDF_SUCCESS | Transmission successful. |
| HDF_FAILURE | Transmission failed. |
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 **Init()** has the corresponding value assignment operations.
Initializes the custom structure object and **DacDevice**, and calls the **DacDeviceAdd** function at the core layer.
if (drsOps->GetUint32(node, "rate", &virtual->rate, 0) != HDF_SUCCESS) {
HDF_LOGE("%s: Read rate fail!", __func__);
return HDF_ERR_IO;
}
return HDF_SUCCESS;
}
}
}
```
```
- Implement the **Release** function.
Input parameter:
**HdfDeviceObject**, an interface parameter provided 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 **Init()** has the corresponding value assignment operations.
The Inter-Integrated Circuit \(I2C\) is a simple, bidirectional, and synchronous serial bus that uses merely two wires.
## Overview
In an I2C communication, one controller communicates with one or more devices through the serial data line \(SDA\) and serial clock line \(SCL\), as shown in the figure below.
### Function
I2C data transfer must begin with a **START** condition and end with a **STOP** condition. Data is transmitted byte-by-byte from the most significant bit to the least significant bit.
The Inter-Integrated Circuit (I2C) is a simple, bidirectional, and synchronous serial bus that uses merely two wires. It is widely used in short-distance communication due to simple connection and low cost.
### Working Principles
In I2C communication, one controller communicates with one or more devices through the serial data line (SDA) and serial clock line (SCL), as shown in the figure below.
I2C data transfer must begin with a **START** condition and end with a **STOP** condition. Data is transmitted byte-by-byte from the most significant bit to the least significant bit.
Each I2C node is recognized by a unique address and can serve as either a controller or a device. When the controller needs to communicate with a device, it writes the device address to the bus through broadcast. A device matching this address sends a response to set up a data transfer channel.
Each I2C node is recognized by a unique address and can serve as either a controller or a device. When the controller needs to communicate with a device, it writes the device address to the bus through broadcast. A device matching this address sends a response to set up a data transfer channel.
The I2C APIs define a set of common functions for I2C data transfer, including:
The I2C module provides a set of APIs for I2C data transfer, including:
- Opening or closing an I2C controller
- Performing custom transfer via a message array
**Figure 1** I2C physical connection
- I2C controller management: opening or closing an I2C controller
- I2C message transfer: custom transfer by using a message array
**Figure 1** Physical connection diagram for I2C<br/>![](figures/physical-connection-diagram-for-i2c.png"physical-connection-diagram-for-i2c")
## Usage Guidelines
### When to Use
## Available APIs<a name="section545869122317"></a>
The I2C is used in communication with the sensors, executors, and input/output devices that support the I2C protocol.
**Table 1** APIs available for the I2C driver
### Available APIs
<aname="table1731550155318"></a>
The following table describes the APIs provided by the I2C module. For more information about the APIs, see **//drivers/hdf_core/framework/include/platform/i2c_if.h**.
<tdclass="cellrowborder"valign="top"width="53.339999999999996%"headers="mcps1.2.4.1.3 "><pid="p8738101941716"><aname="p8738101941716"></a><aname="p8738101941716"></a>Opens an I2C controller.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p573815197171"><aname="p573815197171"></a><aname="p573815197171"></a>Closes an I2C controller.</p>
<tdclass="cellrowborder"valign="top"width="53.339999999999996%"headers="mcps1.2.4.1.3 "><pid="p12738111912171"><aname="p12738111912171"></a><aname="p12738111912171"></a>Performs a custom transfer.</p>
<tdclass="cellrowborder"valign="top"width="79.34%"headers="mcps1.2.3.1.2 "><pid="p760471912388"><aname="p760471912388"></a><aname="p760471912388"></a>Failed to open the I2C controller.</p>
<tdclass="cellrowborder"valign="top"width="79.34%"headers="mcps1.2.3.1.2 "><pid="p3604181933818"><aname="p3604181933818"></a><aname="p3604181933818"></a>Handle of the I2C controller.</p>
</td>
</tr>
</tbody>
</table>
This example assumes that the system has eight I2C controllers \(numbered from 0 to 7\) and I2C controller 3 is to open.
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1051172572919"><aname="p1051172572919"></a><aname="p1051172572919"></a>Handle of an I2C controller.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p202951238218"><aname="p202951238218"></a><aname="p202951238218"></a>Message array of the data to transfer.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p259124622119"><aname="p259124622119"></a><aname="p259124622119"></a>Length of the message array.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p829512237217"><aname="p829512237217"></a><aname="p829512237217"></a>Number of message structures that are successfully transmitted.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1295192312112"><aname="p1295192312112"></a><aname="p1295192312112"></a>Failed to perform the message transfer.</p>
</td>
</tr>
</tbody>
</table>
The type of an I2C message transfer is defined by **I2cMsg**. Each message structure indicates a read or write operation. Multiple read or write operations can be performed by using a message array.
| msgs | Pointer to the message array to transfer.|
| count | Number of messages in the message array to transfer.|
| Return Value| **Description**|
| Positive integer| The operation is successful. The number of messages that are successfully transferred is returned.|
| Negative value| The operation fails.|
The I2C message type is defined by **I2cMsg**. Each message structure indicates a read or write operation. A message array specifies multiple read and write operations to perform.
Example of read and write operations:
```c
int32_tret;
int32_tret;
uint8_twbuff[2]={0x12,0x13};
uint8_twbuff[2]={0x12,0x13};
uint8_trbuff[2]={0};
uint8_trbuff[2]={0};
struct I2cMsg msgs[2]; /* Custom message array for transfer */
structI2cMsgmsgs[2];/* Custom message array to transfer. */
msgs[0].buf = wbuff; /* Data to write */
msgs[0].buf=wbuff;/* Data to write. */
msgs[0].len = 2; /* The length of the data to write is 2. */
msgs[0].len=2;/* The length of the data to write is 2. */
msgs[0].addr = 0x5A; /* The address of the device to write the data is 0x5A. */
msgs[0].addr=0x5A;/* The address of the device to write the data is 0x5A. */
msgs[0].flags = 0; /* The flag is 0, indicating the write operation. */
msgs[0].flags=0;/* The flag 0 indicates a write operation. */
msgs[1].buf = rbuff; /* Data to read */
msgs[1].buf=rbuff;/* Data to read. */
msgs[1].len = 2; /* The length of the data to read is 2. */
msgs[1].len=2;/* The length of the data to read is 2. */
msgs[1].addr = 0x5A; /* The address of the device to read is 0x5A. */
msgs[1].addr=0x5A;/* The address of the device to read is 0x5A. */
msgs[1].flags = I2C_FLAG_READ /* I2C_FLAG_READ is configured, indicating the read operation. */
msgs[1].flags=I2C_FLAG_READ/* I2C_FLAG_READ is set. */
/* Perform a custom transfer to transfer two messages. */
>- The device address in the **I2cMsg** structure does not contain the read/write flag bit. The read/write information is transferred by the read/write control bit in the member variable **flags**.
> - The device address in the **I2cMsg** structure does not contain the read/write flag bit. The read/write information is passed by the read/write control bit in **flags**.
>- The **I2cTransfer** function does not limit the number of message structures and the data length of each message structure, which are determined by the I2C controller.
>
>- The **I2cTransfer** function may cause the system to sleep and therefore cannot be called in the interrupt context.
> - The I2C controller determines the maximum number of messages to be transferred at a time and the maximum length of each message to transfer.
>
> - The **I2cTransfer** function may cause the system to sleep and therefore cannot be called in the interrupt context.
### Closing an I2C Controller<a name="section19481164133018"></a>
Call the **I2cClose()** function to close the I2C controller after the communication is complete.
#### Closing an I2C Controller
void I2cClose\(DevHandle \*handle\);
Call **I2cClose()** to close the I2C controller after the communication is complete.
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1213245577"><aname="p1213245577"></a><aname="p1213245577"></a>Handle of the I2C controller to close.</p>
</td>
</tr>
</tbody>
</table>
| Parameter| Description|
| -------- | -------- |
| handle | Handle of the I2C controller to close.|
```
Example:
I2cClose(i2cHandle); /* Close the I2C controller. */
```c
I2cClose(i2cHandle);/* Close an I2C controller. */
This example describes how to use I2C APIs with an I2C device on a development board.
### Example
This example shows a simple register read/write operation on TouchPad on a Hi3516D V300 development board. The basic hardware information is as follows:
The following example describes how to use I2C APIs to implement simple read/write operations on TouchPad from a Hi3516D V300 development board.
- SoC: hi3516dv300
The basic hardware information is as follows:
- Touch IC: The I2C address is 0x38, and the bit width of Touch IC's internal register is 1 byte.
-SoC: Hi3516D V300
- Schematic diagram: TouchPad is mounted to I2C controller 3. The reset pin of Touch IC is GPIO3.
-Touch IC: The I2C address is 0x38, and the bit width of touch IC internal register is 1 byte.
In this example, first we reset Touch IC. \(The development board supplies power to Touch IC by default after being powered on, and this use case does not consider the power supply\). Then, we perform a read/write operation on an internal register to test whether the I2C channel is normal.
- Hardware connection: The TouchPad is connected to I2C controller 3. The reset pin of the touch IC is GPIO 3.
In this example, reset the touch IC (the development board supplies power to the touch IC by default after being powered on) and perform read/write operations on the internal register to test whether the I2C channel is functioning.
>The example focuses on I2C device access and verifies the I2C channel. The read and write values of the device register are not concerned. The behavior caused by the read and write operations on the register is determined by the device itself.
> This example focuses on access to the I2C device and verifies the I2C channel, rather than the specific data read from or written to the device register and the result caused by the read and write operations on the register.
```
The sample code is as follows:
#include "i2c_if.h" /* Header file of I2C APIs */
#include "gpio_if.h" /* Header file of GPIO APIs */
```c
#include "hdf_log.h" /* Header file for log APIs */
#include "i2c_if.h" /* Header file of I2C APIs. */
#include "osal_io.h" /* Header file of I/O read and write APIs */
#include "gpio_if.h" /* Header file of GPIO APIs. */
#include "osal_time.h" /* Header file of delay and sleep APIs */
#include "hdf_log.h" /* Header file of log APIs. */
#include "osal_io.h" /* Header file of I/O read and write APIs. */
#include "osal_time.h" /* Header file of delay and sleep APIs. */
/* Define a TP device structure to store I2C and GPIO hardware information. */
/* Define a TP device structure to store I2C and GPIO hardware information. */
structTpI2cDevice{
structTpI2cDevice{
uint16_t rstGpio; /* Reset pin */
uint16_trstGpio;/* Reset pin. */
uint16_t busId; /* I2C bus ID */
uint16_tbusId;/* I2C bus number. */
uint16_t addr; /* I2C device address */
uint16_taddr;/* I2C device address. */
uint16_t regLen; /* Register bit width */
uint16_tregLen;/* Register bit width. */
DevHandle i2cHandle; /* I2C controller handle */
DevHandlei2cHandle;/* I2C controller handle. */
};
};
/* I2C pin I/O configuration. For details, see the SoC register manual. */
/* I2C pin I/O configuration. For details, see the SoC register manual. */
#define I2C3_DATA_REG_ADDR 0x112f008c /* Address of the SDA pin configuration register of I2C controller 3
#define I2C3_DATA_REG_ADDR 0x112f008c /* Address of the SDA pin configuration register of I2C controller 3. */
#define I2C3_CLK_REG_ADDR 0x112f0090 /* Address of the SCL pin configuration register of I2C controller 3
#define I2C3_CLK_REG_ADDR 0x112f0090 /* Address of the SCL pin configuration register of I2C controller 3. */
#define I2C_REG_CFG 0x5f1 /* Configuration values of SDA and SCL pins of I2C controller 3
#define I2C_REG_CFG 0x5f1 /* Configuration values of SDA and SCL pins of I2C controller 3. */
/* Initialize the reset pin of the TP. Pull up the pin for 20 ms, pull down the pin for 50 ms, and then pull up the pin for 20 ms to complete the resetting. */
/* Initialize the reset pin of the TP. Pull up the pin for 20 ms, pull down the pin for 50 ms, and then pull up the pin for 20 ms to complete the reset. */
The Inter-Integrated Circuit (I2C) bus is a simple and bidirectional two-wire synchronous serial bus developed by Philips. In the Hardware Driver Foundation (HDF), the I2C module uses the unified service mode for API adaptation. In this mode, a device service is used as the I2C 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 I2C module 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
The Inter-Integrated Circuit (I2C) is a simple, bidirectional, and synchronous serial bus that uses merely two wires. It is widely used in short-distance communication due to simple connection and low cost.
### Working Principles
In the Hardware Driver Foundation (HDF), the I2C module uses the unified service mode for API adaptation. In this mode, a device service is used as the I2C manager to handle access requests from the devices of the same type in a unified manner. The unified service mode applies to the scenario where there are many device objects of the same type. 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 following figure illustrates the unified service mode.
In the unified service mode, the core layer manages all controllers in a unified manner and publishes a service for the interface layer. That is, the driver does not need to publish a service for each controller.
The I2C module is divided into the following layers:
- Interface layer: provides the capabilities of opening and closing a device and transferring data.
- Core layer: binds services, initializes and releases the PlatformManager, and provides the capabilities of adding, deleting, and obtaining controllers.
- Adaptation layer: implements hardware-related functions, such as controller initialization.
**Figure 1** Unified service mode
**Figure 1** Unified service mode
![image](figures/unified-service-mode.png"I2C Unified Service Mode")
![image](figures/unified-service-mode.png"I2C Unified Service Mode")
## Available APIs
## Usage Guidelines
**I2cMethod** and **I2cLockMethod**
### When to Use
The I2C is used in communication with the sensors, executors, and input/output devices that support the I2C protocol. Before using I2C devices with OpenHarmony, you need to adapt the I2C driver to OpenHarmony. The following describes how to do it.
```
### Available APIs
To enable the upper layer to successfully operate the hardware by calling the I2C APIs, hook functions are defined in **//drivers/hdf_core/framework/support/platform/include/i2c/i2c_core.h** for the core layer. You need to implement these hook functions at the adaptation layer and hook them to implement the interaction between the interface layer and the core layer.
int32_t (*lock)(struct I2cCntlr *cntlr); // Add a lock.
void (*unlock)(struct I2cCntlr *cntlr); // Release the lock.
At the adaptation layer, **I2cMethod** must be implemented, and **I2cLockMethod** can be implemented based on service requirements. The core layer provides the default **I2cLockMethod**, in which a mutex is used to protect the critical section.
**Table 1** Description of the callback functions in I2cMethod
If a mutex cannot be used (for example, an I2C API is called in the interrupt context, which does not allow sleep, but a mutex may cause sleep), you can use another type of lock to implement **I2cLockMethod**. The implemented **I2cLockMethod** will replace the default **I2cLockMethod**.
| transfer | **cntlr**: structure pointer to the I2C controller at the core layer.<br><br>**msgs**: structure pointer to the messages to transfer.<br>**count**: number of messages. The value is of the uint16_t type.| –| HDF_STATUS| Transfers user messages.|
| transfer | **cntlr**: structure pointer to the I2C controller at the core layer.<br>**msgs**: structure pointer to the messages to transfer.<br>**count**: number of messages. The value is of the uint16_t type.| –| HDF_STATUS| Transfers user messages.|
> For details, see [Available APIs](#available-apis).
> For details, see [Available APIs](#available-apis).
4. Debug the driver.<br>
(Optional) For new drivers, verify basic functions, for example, check whether data is successfully transmitted and the information returned after the virtual file system (VFS) is mounted.
4. Debug the driver.
(Optional) For new drivers, verify basic functions, for example, check whether data is successfully transferred and the information returned after the virtual file system (VFS) is mounted.
## Development Example
### Example
The following uses **i2c_hi35xx.c** as an example to present the information required for implementing device functions.
The following uses the Hi3516D V300 driver **//device/soc/hisilicon/common/platform/i2c/i2c_hi35xx.c** as an example to describe how to perform the I2C driver adaptation.
1. Instantiate the driver entry.
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 is collected to form a segment address space similar to an array for the upper layer to invoke.
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 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.
Generally, the HDF calls **Bind()** and then **Init()** to load a driver. If **Init()** fails to be called, the HDF calls **Release()** to release driver resources and exit.
I2C driver entry example:
I2C driver entry example:
An I2C controller may be connected with multiple devices. You need to create a manager object in the HDF and publish a manager service to handle external access requests in a unified manner. Before a device is used, the manager service must be obtained first. Then, the manager service locates the target device based on the specified parameters.
Multiple devices may connect to the I2C controller. In the HDF, a manager object needs to be created for this type of devices, and a manager service is published to handle external access requests uniformly. When a device needs to be started, the manager service locates the target device based on the specified parameters.
The driver of the I2C manager is implemented by the core layer. Vendors do not need to care about the implementation of this part. However, the **Init** function must call the **I2cCntlrAdd** function of the core layer to implement corresponding features.
You do not need to implement the driver of the I2C manager, which is implemented by the core layer. However, the **I2cCntlrAdd** function of the core layer must be invoked in the **Init** function to implement the related features.
```
```c
struct HdfDriverEntry g_i2cDriverEntry = {
struct HdfDriverEntry g_i2cDriverEntry = {
.moduleVersion = 1,
.moduleVersion = 1,
.Init = Hi35xxI2cInit,
.Init = Hi35xxI2cInit,
.Release = Hi35xxI2cRelease,
.Release = Hi35xxI2cRelease,
.moduleName = "hi35xx_i2c_driver", // (Mandatory) The value must be the same as that in the config.hcs file.
.moduleName = "hi35xx_i2c_driver", // (Mandatory) The value must be the same as that in the config.hcs file.
};
};
HDF_INIT(g_i2cDriverEntry); // Call HDF_INIT to register the driver entry with the HDF.
HDF_INIT(g_i2cDriverEntry); // Call HDF_INIT to register the driver entry with the HDF.
// Driver entry of the i2c_core.c manager service at the core layer
/* Driver entry of the manager service i2c_core.c at the core layer. */
struct HdfDriverEntry g_i2cManagerEntry = {
struct HdfDriverEntry g_i2cManagerEntry = {
.moduleVersion = 1,
.moduleVersion = 1,
.Bind = I2cManagerBind,
.Bind = I2cManagerBind,
.Init = I2cManagerInit,
.Init = I2cManagerInit,
.Release = I2cManagerRelease,
.Release = I2cManagerRelease,
.moduleName = "HDF_PLATFORM_I2C_MANAGER", // This parameter corresponds to device0 in the device_info file.
.moduleName = "HDF_PLATFORM_I2C_MANAGER", // The value must be the same as that of device0 in the device_info.hcs file.
};
};
HDF_INIT(g_i2cManagerEntry);
HDF_INIT(g_i2cManagerEntry);
```
```
2. Add the **deviceNode** information to the **device_info.hcs** file and configure the device attributes in the **i2c_config.hcs** file.
2. Add the **deviceNode** information to the **//vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs** file and configure the device attributes in **i2c_config.hcs**.
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 value ranges of the **I2cCntlr** members at the core layer.
The **deviceNode** information is related to the driver entry registration. The device attribute values are closely related to the driver implementation and the default values or value ranges of the **I2cCntlr** members at the core layer.
In the unified service mode, the first device node in the **device_info** file must be the I2C manager. The table below lists the settings of its parameters.
In the unified service mode, the first device node in the **device_info.hcs** file must be the I2C manager. The table below lists the settings of its parameters.
**Table 2** Settings of the I2C manager
**Table 3** Settings of the I2C manager
| Parameter| Value|
| Parameter| Value|
| -------- | -------- |
| -------- | -------- |
| moduleName | **HDF_PLATFORM_I2C_MANAGER**|
| moduleName | **HDF_PLATFORM_I2C_MANAGER**|
| serviceName | **HDF_PLATFORM_I2C_MANAGER**|
| serviceName | **HDF_PLATFORM_I2C_MANAGER**|
| policy | **1** or **2**, depending on whether the service is published to the user mode.|
| policy | **1** or **2**, depending on whether the service is published to the user mode.|
| deviceMatchAttr | Reserved|
| deviceMatchAttr | This parameter is reserved.|
Configure I2C controller information from the second node. This node specifies a type of I2C controllers rather than a specific I2C controller. The controllers are distinguishes by **busID** and **reg_pbase**, which can be seen in the **i2c_config** file.
Configure I2C controller information from the second node. This node specifies a type of I2C controllers rather than a specific I2C controller. The controllers are distinguished by **busID** and **reg_pbase**, which can be seen in the **i2c_config.hcs** file.
-**device_info.hcs** configuration example
-**device_info.hcs** example
```c
```
root {
root {
device_info {
device_info {
match_attr = "hdf_manager";
match_attr = "hdf_manager";
device_i2c :: device {
device_i2c :: device {
device0 :: deviceNode {
device0 :: deviceNode {
policy = 2;
policy = 2;
priority = 50;
priority = 50;
permission = 0644;
permission = 0644;
moduleName = "HDF_PLATFORM_I2C_MANAGER";
moduleName = "HDF_PLATFORM_I2C_MANAGER";
serviceName = "HDF_PLATFORM_I2C_MANAGER";
serviceName = "HDF_PLATFORM_I2C_MANAGER";
deviceMatchAttr = "hdf_platform_i2c_manager";
deviceMatchAttr = "hdf_platform_i2c_manager";
}
}
device1 :: deviceNode {
device1 :: deviceNode {
policy = 0; // The value 0 indicates that no service is published.
policy = 0; // The value 0 indicates that no service needs to be published.
priority = 55; // Driver startup priority.
priority = 55; // Driver startup priority.
permission = 0644; // Permission for the device node created.
permission = 0644; // Permission for the driver to create a device node.
moduleName = "hi35xx_i2c_driver"; // (Mandatory) Driver name, which must be the same as moduleName in the driver entry.
moduleName = "hi35xx_i2c_driver"; // (Mandatory) Driver name, which must be the same as moduleName in the driver entry.
serviceName = "HI35XX_I2C_DRIVER"; // (Mandatory) Unique name of the service published by the driver.
serviceName = "HI35XX_I2C_DRIVER"; // (Mandatory) Unique name of the service published by the driver.
deviceMatchAttr = "hisilicon_hi35xx_i2c"; // (Mandatory) Private data of the controller. The value must be the same as the controller information in i2c_config.hcs.
deviceMatchAttr = "hisilicon_hi35xx_i2c"; // (Mandatory) Used to configure the private data of the controller. The value must be the same as the controller information in i2c_config.hcs.
//The specific controller information is in i2c_config.hcs.
//The specific controller information is stored in i2c_config.hcs.
}
}
}
}
}
}
}
}
```
```
-**i2c_config.hcs** example
-**i2c_config.hcs** configuration example
```c
root {
```
platform {
root {
i2c_config {
platform {
match_attr = "hisilicon_hi35xx_i2c"; // (Mandatory) The value must be the same as that of deviceMatchAttr in device_info.hcs.
i2c_config {
template i2c_controller { // Template configuration. In the template, you can configure the common parameters shared by service nodes.
match_attr = "hisilicon_hi35xx_i2c"; // (Mandatory) The value must be the same as that of deviceMatchAttr in device_info.hcs.
bus = 0; // (Mandatory) I2C identifier.
template i2c_controller { // Template configuration. In the template, you can configure the common parameters shared by service nodes.
reg_pbase = 0x120b0000; // (Mandatory) Physical base address.
bus = 0; // (Mandatory) I2C identifier.
reg_size = 0xd1; // (Mandatory) Register bit width.
reg_pbase = 0x120b0000; // (Mandatory) Physical base address.
irq = 0; // (Optional) Interrupt request (IRQ) number. The interrupt feature of the controller determines whether an IRQ number is required.
reg_size = 0xd1; // (Mandatory) Register bit width.
freq = 400000; // (Optional) Frequency used in hardware controller initialization.
irq = 0; // (Optional) Configured based on your requirements.
clk = 50000000; // (Optional) Controller clock. The controller clock initialization process determines whether a controller clock is required.
freq = 400000; // (Optional) Configured based on your requirements.
}
clk = 50000000; // (Optional) Configured based on your requirements.
controller_0x120b0000 :: i2c_controller {
}
bus = 0;
controller_0x120b0000 :: i2c_controller {
}
bus = 0;
controller_0x120b1000 :: i2c_controller {
}
bus = 1;
controller_0x120b1000 :: i2c_controller {
reg_pbase = 0x120b1000;
bus = 1;
}
reg_pbase = 0x120b1000;
...
}
}
...
}
}
}
}
```
}
```
After the **i2c_config.hcs** file is configured, include the file in the **hdf.hcs** file. Otherwise, the configuration file cannot take effect.
For example, if the path of **i2c_config.hcs** is **device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/i2c/i2c_config.hcs**, add the following statement to **hdf.hcs** of the product:
```c
#include "../../../../device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/i2c/i2c_config.hcs" // Relative path of the file.
```
3. Initialize the **I2cCntlr** 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 **I2cMethod** in **I2cCntlr** (so that the underlying driver functions can be called).
3. Initialize the **I2cCntlr** 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 **I2cMethod** in **I2cCntlr** (so that the underlying driver functions can be called).
- Defining a custom structure
- 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 **i2c_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 **I2cCntlr** 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 **i2c_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 **I2cCntlr** object at the core layer.
```c
```
/* Custom structure. */
// Custom structure
struct Hi35xxI2cCntlr {
struct Hi35xxI2cCntlr {
struct I2cCntlr cntlr; // (Mandatory) Control object at the core layer. For details, see the following description.
struct I2cCntlr cntlr; // (Mandatory) Control object at the core layer. For details, see the following description.
OsalSpinlock spin; // (Mandatory) You need to implement lock() and unlock() based on this variable.
OsalSpinlock spin; // (Mandatory) Lock or unlock an I2C operation function.
volatile unsigned char *regBase;// (Mandatory) Register base address.
volatile unsigned char *regBase;// (Mandatory) Register base address.
uint16_t regSize; // (Mandatory) Register bit width.
uint16_t regSize; // (Mandatory) Register bit width.
int16_t bus; // (Mandatory) The value can be read from the i2c_config.hcs file.
int16_t bus; // (Mandatory) The value can be read from the i2c_config.hcs file.
uint32_t clk; // (Optional) Customized.
uint32_t clk; // (Optional) Set it as required.
uint32_t freq; // (Optional) Customized.
uint32_t freq; // (Optional) Set it as required.
uint32_t irq; // (Optional) Customized.
uint32_t irq; // (Optional) Set it as required.
uint32_t regBasePhy; // (Mandatory) Physical base address of the register.
uint32_t regBasePhy // (Mandatory) Physical base address of the register.
};
};
// I2cCntlr is a controller structure at the core layer. The Init function assigns values to the members of I2cCntlr.
/* I2cCntlr is the core layer controller structure. The **Init()** function assigns values to the members of I2cCntlr. */
struct I2cCntlr {
struct I2cCntlr {
struct OsalMutex lock;
struct OsalMutex lock;
void *owner;
void *owner;
...
@@ -199,31 +259,32 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
...
@@ -199,31 +259,32 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
const struct I2cLockMethod *lockOps;
const struct I2cLockMethod *lockOps;
};
};
```
```
- Instantiating **I2cMethod** and **I2cLockMethod** (other members are initialized by **Init**)
- Instantiate **I2cMethod** and **I2cLockMethod**. Other members are initialized by **Init**.
```
// Example in i2c_hi35xx.c
```c
/* Example in i2c_hi35xx.c */
static const struct I2cMethod g_method = {
static const struct I2cMethod g_method = {
.transfer = Hi35xxI2cTransfer,
.transfer = Hi35xxI2cTransfer,
};
};
static const struct I2cLockMethod g_lockOps = {
static const struct I2cLockMethod g_lockOps = {
.lock = Hi35xxI2cLock, // Lock function
.lock = Hi35xxI2cLock, // Acquires the lock.
.unlock = Hi35xxI2cUnlock, // Unlock function
.unlock = Hi35xxI2cUnlock, // Release the lock.
};
};
```
```
-**Init** function
**Input parameter**:
- Implement the **Init** function.
Input parameter:
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information.
**HdfDeviceObject**, an interface parameter provided by the driver, contains the .hcs information.
**Return value**:
Return value:
**HDF_STATUS**<br/>The table below describes some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file.
**HDF_STATUS**<br/>The table below describes some status. For more information, see **HDF_STATUS** in the **//drivers/hdf_core/framework/include/utils/hdf_base.h** file.
**Table 3** HDF_STATUS
**Table 4** HDF_STATUS
| Status| Description|
| Status| Description|
| -------- | -------- |
| -------- | -------- |
...
@@ -234,16 +295,15 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
...
@@ -234,16 +295,15 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
| HDF_SUCCESS | Transmission successful.|
| HDF_SUCCESS | Transmission successful.|
| HDF_FAILURE | Transmission failed.|
| HDF_FAILURE | Transmission failed.|
**Function description**:
Function description:
Initializes the custom structure object and **I2cCntlr**, calls the **I2cCntlrAdd** function at the core layer, and mounts the VFS (optional).
Initialize the custom structure object and **I2cCntlr**, call **I2cCntlrAdd()** at the core layer, and connect to the VFS (optional).
hi35xx->cntlr.busId = hi35xx->bus; // (Mandatory) Initialize busId in I2cCntlr.
hi35xx->cntlr.busId = hi35xx->bus; // (Mandatory) Initialize busId in I2cCntlr.
hi35xx->cntlr.ops = &g_method; // (Mandatory) Hook the I2cMethod instance.
hi35xx->cntlr.ops = &g_method; // (Mandatory) Hook the I2cMethod instance.
hi35xx->cntlr.lockOps = &g_lockOps; // (Mandatory) Hook the I2cLockMethod instance.
hi35xx->cntlr.lockOps = &g_lockOps; // (Mandatory) Hook the I2cLockMethod instance.
(void)OsalSpinInit(&hi35xx->spin); // (Mandatory) Initialize the lock.
(void)OsalSpinInit(&hi35xx->spin); // (Mandatory) Initialize the lock.
ret = I2cCntlrAdd(&hi35xx->cntlr); // (Mandatory) Call this function to set the structure of the core layer. The driver accesses the platform core layer only after a success signal is returned.
ret = I2cCntlrAdd(&hi35xx->cntlr); // (Mandatory) Call this function to add the controller object to the core layer of the platform. The driver can access the core layer of the platform only after a success signal is returned.
...
...
#ifdef USER_VFS_SUPPORT
#ifdef USER_VFS_SUPPORT
(void)I2cAddVfsById(hi35xx->cntlr.busId);// (Optional) Mount the user-level VFS if required.
(void)I2cAddVfsById(hi35xx->cntlr.busId);// (Optional) Mount the user-level VFS if required.
#endif
#endif
return HDF_SUCCESS;
return HDF_SUCCESS;
__ERR__: // If the operation fails, execute the initialization functions reversely.
__ERR__: // If the operation fails, roll back the operations that have been performed in the function (such as unmapping I/O and releasing memory) and return an error code.
if (hi35xx != NULL) {
if (hi35xx != NULL) {
if (hi35xx->regBase != NULL) {
if (hi35xx->regBase != NULL) {
OsalIoUnmap((void *)hi35xx->regBase);
OsalIoUnmap((void *)hi35xx->regBase);
...
@@ -284,26 +344,26 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
...
@@ -284,26 +344,26 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
return ret;
return ret;
}
}
```
```
-**Release** function
**Input parameter**:
- Implement the **Release** function.
Input parameter:
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information.
**HdfDeviceObject**, an interface parameter provided by the driver, contains the .hcs information.
**Return value**:
Return value:
No value is returned.
No value is returned.
**Function description**:
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.
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.
// (Mandatory) Call the I2cCntlrGet function to obtain the I2cCntlr object based on bus ID of the device, and call the I2cCntlrRemove function to release the I2cCntlr object.
/* (Mandatory) Call I2cCntlrGet() to obtain the pointer to the I2cCntlr object based on the bus number of the device, and call I2cCntlrRemove() to remove the I2cCntlr object from the core layer of the platform. */
cntlr = I2cCntlrGet(bus);
cntlr = I2cCntlrGet(bus);
if (cntlr != NULL && cntlr->priv == node) {
if (cntlr != NULL && cntlr->priv == node) {
...
...
I2cCntlrRemove(cntlr);
I2cCntlrRemove(cntlr);
// (Mandatory) Unmap the addresses and release the lock and memory.
/* (Mandatory) Unmap the register address and release the lock and memory. */
@@ -8,7 +8,7 @@ Improved Inter-Integrated Circuit (I3C) is a simple and cost-efficient two-wire
...
@@ -8,7 +8,7 @@ Improved Inter-Integrated Circuit (I3C) is a simple and cost-efficient two-wire
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.
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 I3C driver APIs provide a set of common functions for I3C transfer, including:
The I3C module provides a set of common APIs for I3C transfer, including:
- Opening and closing an I3C controller
- Opening and closing an I3C controller
- Obtaining and setting I3C controller parameters
- Obtaining and setting I3C controller parameters
- Performing custom I3C message transfer by using a message array
- Performing custom I3C message transfer by using a message array
...
@@ -17,17 +17,14 @@ The I3C driver APIs provide a set of common functions for I3C transfer, includin
...
@@ -17,17 +17,14 @@ The I3C driver APIs provide a set of common functions for I3C transfer, includin
### Basic Concepts
### Basic Concepts
- 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.
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)
- 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 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:
1) The device has an I2C compliant static address that can be used by the host.
- The device has an I2C compliant static address that can be used by the host.
2) 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.
- 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)
- Common Command Code (CCC)
...
@@ -43,49 +40,54 @@ The I3C driver APIs provide a set of common functions for I3C transfer, includin
...
@@ -43,49 +40,54 @@ The I3C driver APIs provide a set of common functions for I3C transfer, includin
### Working Principles
### 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.
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.
Compared with I2C, I3C features higher speed and lower power consumption, supports IBIs, hot-joins of target devices, and controller switchover. I3C is also backward compatible with I2C target devices. 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.
Currently, the I3C module supports only the kernels (LiteOS) of mini and small systems.
The I3C module supports only the kernel (LiteOS-A) for mini and small systems and cannot be used in user mode.
## Usage Guidelines
## Usage Guidelines
### When to Use
### When to Use
I3C can connect to one or more I3C or I2C target devices. It is used to:
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 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.
- Communicate with devices with other ports (such as UART serial ports) through software or hardware protocols.
### Available APIs
### Available APIs
**Table 1** I3C driver APIs
The following table describes the APIs provided by the I3C module. For more information about the APIs, see **//drivers/hdf_core/framework/include/platform/i3c_if.h**.
**Table 1** I3C driver APIs
| API | Description |
| API | Description |
| ------------- | ----------------- |
| ------------- | ----------------- |
| I3cOpen | Opens an I3C controller. |
| DevHandle I3cOpen(int16_t number) | Opens an I3C controller. |
| I3cClose | Closes an I3C controller. |
| void I3cClose(DevHandle handle) | Closes an I3C controller. |
| 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_tret;
uint8_twbuff[2]={0x12,0x13};
uint8_trbuff[2]={0};
structI3cMsgmsgs[2];/* Custom message array for transfer. */
msgs[0].buf=wbuff;/* Data to write. */
msgs[0].len=2;/* Length of the data to write. */
msgs[0].addr=0x3F;/* Address of the device to which the data is written. */
msgs[0].flags=0;/* Transfer flag. A write operation is performed by default. */
msgs[1].buf=rbuff;/* Data to read. */
msgs[1].len=2;/* Length of the data to read. */
msgs[1].addr=0x3F;/* Address of the device from which the data is read. */
msgs[1].flags=I3C_FLAG_READ/* I3C_FLAG_READ is set. */
>- 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.
| 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 fails. |
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_tret;
uint8_twbuff[2]={0x12,0x13};
uint8_trbuff[2]={0};
structI3cMsgmsgs[2];/* Custom message array for transfer. */
msgs[0].buf=wbuff;/* Data to write. */
msgs[0].len=2;/* Length of the data to write. */
msgs[0].addr=0x3F;/* Address of the device to which the data is written. */
msgs[0].flags=0;/* Transfer flag. A write operation is performed by default. */
msgs[1].buf=rbuff;/* Data to read. */
msgs[1].len=2;/* Length of the data to read. */
msgs[1].addr=0x3F;/* Address of the device from which the data is read. */
msgs[1].flags=I3C_FLAG_READ/* I3C_FLAG_READ is set. */
>- 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 **flags**.
>- The I3C controller determines the maximum number of messages to transfer at a time and the maximum length of each message.
>- Using **I3cTransfer()** may cause the system to sleep. Do not call it in the interrupt context.
@@ -330,17 +318,15 @@ The following is an example:
...
@@ -330,17 +318,15 @@ The following is an example:
I3cClose(i3cHandle);/* Close the I3C controller. */
I3cClose(i3cHandle);/* Close the I3C controller. */
```
```
## Development Example
## Example
This following example shows how to use I3C APIs to manage an I3C device on a Hi3516D V300 development board.
Because the Hi3516D V300 SoC has no I3C controller, this example describes how to perform simple transfer operations on a virtual driver on a Hi3516D V300. The basic information is as follows:
The following example presents how to use I3C APIs to manage an I3C device on a Hi3516D V300 development board. <br>The basic hardware information is as follows:
- SoC: Hi3516D V300
- SoC: Hi3516D V300
- Virtual: The I3C address is 0x3f, and the register bit width is 1 byte.
- Virtual I3C device: The I3C address is 0x3f, and the register bit width is 1 byte.
- The virtual I3C devices are connected to virtual I3C controllers 18 and 19.
- The virtual I3C device is connected to I3C controllers 18 and 19.
Perform simple I3C transfer to test whether the I3C channels are normal.
Perform simple I3C transfer to test whether the I3C channels are normal.
...
@@ -349,7 +335,7 @@ The sample code is as follows:
...
@@ -349,7 +335,7 @@ 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 "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. */
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.
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.
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.
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.
### Basic Concepts
### Basic Concepts
...
@@ -16,16 +18,16 @@ I3C is a two-wire bidirectional serial bus, optimized for multiple sensor target
...
@@ -16,16 +18,16 @@ I3C is a two-wire bidirectional serial bus, optimized for multiple sensor target
- Dynamic Address Assignment (DAA)
- 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 I3C controller can dynamically allocate addresses to target devices to avoid address conflicts. Before addresses are allocated, each I3C device connected to an 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 an I2C compliant static address that can be used by the host.
- The device has a 48-bit temporary ID.
- 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.
The host must use a 48-bit temporary ID unless the device has a static IP address.
- Common Command Code (CCC)
- 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.
All I3C devices support CCC. The CCC can be sent to an I3C target device or all I3C target devices.
- Bus Characteristic Register (BCR)
- Bus Characteristic Register (BCR)
...
@@ -38,21 +40,23 @@ I3C is a two-wire bidirectional serial bus, optimized for multiple sensor target
...
@@ -38,21 +40,23 @@ I3C is a two-wire bidirectional serial bus, optimized for multiple sensor target
### Working Principles
### 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.
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. The following figure illustrtes the unified service mode.
The I3C module is divided into the following layers:
The I3C module is divided into the following layers:
- Interface layer: provides APIs for opening or closing a controller, transmitting messages, and obtaining and setting controller parameters.
- Interface layer: provides the capabilities of opening a device, writing data, and closing a device.
- Core layer: provides the capabilities of binding, initializing, and releasing devices.
- Core layer: binds services, initializes and releases the PlatformManager, and provides the capabilities of adding, deleting, and obtaining controllers. The core layer also provides capabilities of adding, deleting, and obtaining the devices connected to the I3C bus and interrupt callbacks.
- Adaptation layer: implements other functions.
- Adaptation layer: implements hardware-related functions, such as controller initialization.
In the unified service mode, the core layer manages all controllers in a unified manner and publishes a service for the interface layer. That is, the driver does not need to publish a service for each controller.
**Figure 1** Unified service mode
**Figure 1** Unified service mode
### Constraints
### Constraints
Currently, the I3C module supports only the kernels (LiteOS) of mini and small systems.
The I3C module supports only the kernel (LiteOS-A) for mini and small systems.
## Development Guidelines
## Development Guidelines
...
@@ -63,12 +67,13 @@ I3C can connect to one or more I3C or I2C target devices. It is used to:
...
@@ -63,12 +67,13 @@ 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 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.
- Communicate with devices with other ports (such as UART serial ports) through software or hardware protocols.
### Available APIs
Before using I3C devices with OpenHarmony, you need to adapt the I3C driver to OpenHarmony. The following describes how to do it.
**I3cMethod**:
### Available APIs
To enable the upper layer to successfully operate the hardware by calling the I3C APIs, hook functions are defined in **//drivers/hdf_core/framework/support/platform/include/i3c/i3c_core.h** for the core layer. You need to implement these hook functions at the adaptation layer and hook them to implement the interaction between the interface layer and the core layer.
|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.|
|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.|
|Transfer | **cntlr**: structure pointer to an I3C controller at the core layer.<br>**msgs**: structure pointer to the messages to transfer.<br>**count**: number of messages to transfer, 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.|
|i2cTransfer | **cntlr**: structure pointer to an I3C controller at the core layer.<br>**msgs**: structure pointer to the messages to transfer.<br>**count**: number of messages to transfer, 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.|
|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.|
|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.|
|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.|
|freeIbi| **device**: structure pointer to an I3C device at the core layer.| –| HDF_STATUS| Releases the IBI for an I3C device.|
### How to Develop
### How to Develop
The I3C module adaptation involves the following steps:
The I3C module adaptation involves the following steps:
...
@@ -108,65 +114,65 @@ The I3C module adaptation involves the following steps:
...
@@ -108,65 +114,65 @@ The I3C module adaptation involves the following steps:
3. Instantiate the I3C controller object.
3. Instantiate the I3C controller object.
- Initialize **I3cCntlr**.
- Initialize **I3cCntlr**.
- Instantiate **I3cMethod** in **I3cCntlr**. For details, see [Available APIs](#available-apis).
- Instantiate **I3cMethod** in **I3cCntlr**. For details, see the description of **I3cMethod** below.
4. Register an interrupt handler.
4. Register an interrupt handler.
Registers an interrupt handler for the controller to implement the device hot-join and IBI features.
Registers an interrupt handler for the controller to implement the device hot-join and IBI features.
### Example
## Development Example
1. Instantiate the driver entry.
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.
The driver entry must be a global variable of the **HdfDriverEntry** type (defined in **//drivers/hdf_core/framework/include/core/hdf_device_desc.h**), and the module name 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.
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.
> 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.
>
>
> Multiple devices may connect to the I3C controller. In the HDF, a manager object needs to be created for this type of devices, and a manager service is published to handle external access requests uniformly. When a device needs to be started, the manager service locates the target device based on the specified parameters.
> The core layer implements the driver of the I3C manager service. You 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.
>
> You do not need to implement the driver of the I3C manager, which is implemented by the core layer. However, the **I3cCntlrAdd** function of the core layer must be invoked in the **Init** function to implement the related features.
.moduleName = "virtual_i3c_driver",// (Mandatory) The value must be the same as that in the .hcs file.
.moduleName = "virtual_i3c_driver",// (Mandatory) The value must be the same as that in the .hcs file.
};
};
HDF_INIT(g_virtualI3cDriverEntry); // Call HDF_INIT to register the driver entry with the HDF.
HDF_INIT(g_virtualI3cDriverEntry); // Call HDF_INIT to register the driver entry with the HDF.
/* Driver entry of the i3c_core.c manager service at the core layer */
/* Driver entry of the i3c_core.c manager service at the core layer. */
struct HdfDriverEntry g_i3cManagerEntry = {
struct HdfDriverEntry g_i3cManagerEntry = {
.moduleVersion = 1,
.moduleVersion = 1,
.Init = I3cManagerInit,
.Init = I3cManagerInit,
.Release = I3cManagerRelease,
.Release = I3cManagerRelease,
.moduleName = "HDF_PLATFORM_I3C_MANAGER",// Correspond to device0 in the device_info file.
.moduleName = "HDF_PLATFORM_I3C_MANAGER", // The value must be the same as that of device0 in the device_info.hcs file.
};
};
HDF_INIT(g_i3cManagerEntry);
HDF_INIT(g_i3cManagerEntry);
```
```
2. Configure attribute files.
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.
Add the **deviceNode** information to the **//vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs** file and configure the device attributes in **i3c_config.hcs**.
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.
The **deviceNode** information is related to the driver entry registration. The device attribute values are closely related to the driver implementation and the default values or value ranges of the **I3cCntlr** members at the core layer.
In the unified service mode, the first device node in the **device_info.hcs** file must be the I3C manager. The I3C manager parameters must be set as follows:
|Parameter|Value|
|Parameter|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, add the **deviceNode** information to the **device_info** file and add the corresponding device attributes to the **i3c_config** file for each controller.
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.hcs** file and add the corresponding device attributes to the **i3c_config** file for each controller.
- **device_info.hcs** configuration example
- **device_info.hcs** example
```c
```c
root {
root {
...
@@ -180,17 +186,17 @@ The I3C module adaptation involves the following steps:
...
@@ -180,17 +186,17 @@ The I3C module adaptation involves the following steps:
}
}
}
}
i3c_virtual :: deviceNode {
i3c_virtual :: deviceNode {
policy = 0; // The value 0 indicates that no service is published.
policy = 0; // The value 0 indicates that no service is published.
priority = 56; // Driver startup priority.
priority = 56; // Driver startup priority.
permission = 0644; // Permission to create device nodes for the driver.
permission = 0644; // Permission for the device node created.
moduleName = "virtual_i3c_driver"; // (Mandatory) Driver name, which must be the same as moduleName in the driver entry.
moduleName = "virtual_i3c_driver"; // (Mandatory) Driver name, which must be the same as moduleName in the driver entry.
serviceName = "VIRTUAL_I3C_DRIVER"; // (Mandatory) Unique name of the service published by the driver.
serviceName = "VIRTUAL_I3C_DRIVER"; // (Mandatory) Unique name of the service published by the driver.
deviceMatchAttr = "virtual_i3c"; // (Mandatory) Controller private data, which must be same as that of the corresponding controller in i3c_config.hcs.
deviceMatchAttr = "virtual_i3c"; // (Mandatory) Controller private data, which must be same as that of the controller in i3c_config.hcs.
} // The specific controller information is in i3c_config.hcs.
} // The specific controller information is in i3c_config.hcs.
}
}
```
```
- i3c_config.hcs configuration example
- i3c_config.hcs example
```c
```c
root {
root {
...
@@ -216,208 +222,245 @@ The I3C module adaptation involves the following steps:
...
@@ -216,208 +222,245 @@ The I3C module adaptation involves the following steps:
}
}
}
}
```
```
After the **i3c_config.hcs** file is configured, include the file in the **hdf.hcs** file. Otherwise, the configuration file cannot take effect.
For example, if the path of **i3c_config.hcs** is **device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/i3c/i3c_config.hcs**, add the following statement to **hdf.hcs** of the product:
```c
#include "../../../../device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/i3c/i3c_config.hcs" // Relative path of the file.
```
3. Instantiate the I3C controller object.
3. Instantiate the I3C controller object.
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).
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).
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()**.
- Defining 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.
volatile unsigned char *regBase; //(Mandatory) Register base address.
uint32_t regBasePhy; // (Mandatory) Physical base address of the register.
uint32_t regSize; // (Mandatory) Bit width of the register.
uint16_t busId; // (Mandatory) Bus number.
uint16_t busMode;
uint16_t IrqNum;
uint32_t i3cMaxRate;
uint32_t i3cRate;
uint32_t i2cFmRate;
uint32_t i2cFmPlusRate;
};
/* I3cCntlr is the controller structure at the core layer. The Init function assigns values to the members of I3cCntlr.
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration file information.
**Return value**:
**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.
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__;
}
returnHDF_SUCCESS;
__ERR__:// If the controller fails to be added, deinitialize related functions.
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information.
**Return value**:
No value is returned.
Instantiate **I3cMethod** in **I3cCntlr**.<br>The **I3cLockMethod** hook function structure is not implemented in this example. To instantiate the structure, refer to the I2C driver development. Other members are initialized in **Init()**.
**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.
>
> 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.
if (drsOps == NULL || drsOps->GetUint32 == NULL) {
uint32_t i3cRate;
HDF_LOGE("%s: invalid drs ops fail!", __func__);
uint32_t i2cFmRate;
return;
uint32_t i2cFmPlusRate;
}
};
ret = drsOps->GetUint16(node, "busId", (uint16_t *)&busId, 0);
/* I3cCntlr is the controller structure at the core layer. The Init function assigns values to the members of I3cCntlr. */
if (ret != HDF_SUCCESS) {
struct I3cCntlr {
HDF_LOGE("%s: read busId fail!", __func__);
OsalSpinlock lock;
return;
void *owner;
}
int16_t busId;
...
struct I3cConfig config;
/* Call I3cCntlrGet() to obtain the I3cCntlr object based on the cntlrNum of the device, and then call I3cCntlrRemove() to release the I3cCntlr object. */
**HDF_STATUS**<br/>The table below describes some status. For more information, see **HDF_STATUS** in the **//drivers/hdf_core/framework/include/utils/hdf_base.h** file.
if (device == NULL || device->property == NULL) {
HDF_LOGE("%s: device or property is NULL", __func__);
ret = VirtualI3cReadDrs(virtual, node); // (Mandatory) Use the default values in the i3c_config file to fill in the structure. For details about the function definition, see the following.
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. The driver can access the platform core layer only when a success signal is returned.
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.
/* Read the configuration parameters in sequence and fill them in the structure. */
if (drsOps->GetUint16(node, "busId", &virtual->busId, 0) != HDF_SUCCESS) {
HDF_LOGE("%s: Read busId fail!", __func__);
return HDF_ERR_IO;
}
if (drsOps->GetUint16(node, "busMode", &virtual->busMode, 0) != HDF_SUCCESS) {
HDF_LOGE("%s: Read busMode fail!", __func__);
return HDF_ERR_IO;
}
if (drsOps->GetUint16(node, "IrqNum", &virtual->IrqNum, 0) != HDF_SUCCESS) {
HDF_LOGE("%s: Read IrqNum fail!", __func__);
return HDF_ERR_IO;
}
···
return HDF_SUCCESS;
}
```
- Implement the **Release** function.
**Input parameter**:
**HdfDeviceObject**, an interface parameter provided 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.
if (drsOps == NULL || drsOps->GetUint32 == NULL) {
HDF_LOGE("%s: invalid drs ops fail!", __func__);
return;
}
ret = drsOps->GetUint16(node, "busId", (uint16_t *)&busId, 0);
if (ret != HDF_SUCCESS) {
HDF_LOGE("%s: read busId fail!", __func__);
return;
}
...
/* 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);
I3cCntlrRemove(cntlr); // (Mandatory) Remove the I3cCntlr object from the manager driver.
virtual = (struct VirtualI3cCntlr *)cntlr; // (Mandatory) Obtain the custom object through a forced conversion and perform the release operation.
(void)OsalSpinDestroy(&virtual->spin);
OsalMemFree(virtual);
}
return;
return;
}
}
...
// Traverse and parse all nodes in i3c_config.hcs and perform the release operation on each node.
