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
- Obtaining the analog-to-digital (AD) conversion result
### 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
The number of binary bits that can be converted by an ADC. A greater number of bits indicates a higher resolution.
- 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 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
### 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
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
| API | Description |
| API | Description |
| -------- | ---------------- |
| AdcOpen | Opens an ADC device. |
| AdcClose | Closes an ADC device. |
| AdcRead | Obtains the AD conversion result.|
| DevHandle AdcOpen(uint32_t number) | Opens an ADC device. |
| void AdcClose(DevHandle handle) | Closes an ADC device. |
| int32_t AdcRead(DevHandle handle, uint32_t channel, uint32_t \*val) | Obtains the AD conversion result.|
### How to Develop
The figure below shows the general development process.
The following figure illustrates how to use ADC APIs.
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
- Setting the target digital-to-analog (DA) value
### 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
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
### 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:
...
...
@@ -40,9 +41,7 @@ The DAC module is divided into the following layers:
- Core layer: provides the capabilities of binding, initializing, and releasing devices.
> 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.
**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.
**Figure 1** Unified service mode
...
...
@@ -50,7 +49,7 @@ The DAC module is divided into the following layers:
### 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
...
...
@@ -60,11 +59,11 @@ The DAC module converts digital signals into analog signals in the form of curre
### 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**.
@@ -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.
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
- Obtaining and setting I3C controller parameters
- 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
### Basic Concepts
- IBI
When there is no start signal on the serial clock (SCL) line, the I3C target device can pull down the serial data (SDA) line to make the controller send an SCL start signal, which initiates an IBI request. If multiple target devices send interrupt requests at the same time, the I3C controller arbitrates the requests based on the target device addresses. The request with a lower address is responded first.
- Dynamic Address Assignment (DAA)
The I3C controller can dynamically allocate addresses to target devices to avoid address conflicts. Before addresses are allocated, each I3C device connected to a I3C bus must be uniquely identified in either of the following ways:
- The device has an I2C compliant static address that can be used by the host.
- The device has a 48-bit temporary ID.
The host must use a 48-bit temporary ID unless the device has a static IP address.
1) 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.
- Common Command Code (CCC)
...
...
@@ -43,49 +40,54 @@ The I3C driver APIs provide a set of common functions for I3C transfer, includin
### 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
### When to Use
I3C can connect to one or more I3C or I2C target devices. It is used to:
- Communicate with sensors, such as gyroscopes, barometers, and image sensors that support the I3C protocol.
- Communicate with devices with other ports (such as UART serial ports) through software or hardware protocols.
### Available APIs
**Table 1** I3C driver APIs
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. |
| I3cClose | Closes an I3C controller. |
| I3cTransfer | Performs custom transfer. |
| I3cSetConfig | Sets the I3C controller. |
| I3cGetConfig | Obtains the I3C controller configuration. |
| 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
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:
I3cClose(i3cHandle);/* Close the I3C controller. */
```
## Development Example
This following example shows how to use I3C APIs to manage an I3C device on a Hi3516D V300 development board.
## Example
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
- 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.
...
...
@@ -349,7 +335,7 @@ The sample code is as follows:
```c
#include "i3c_if.h" /* Header file for I3C standard 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 */
/* Define a device structure to hold information. */
