diff --git a/en/device-dev/driver/driver-platform-adc-des.md b/en/device-dev/driver/driver-platform-adc-des.md index f7075aa1d07a13320c429b23de01b41e5e18f25a..76c73fb3e947e45190831c6f060ae1c1ac1d97db 100644 --- a/en/device-dev/driver/driver-platform-adc-des.md +++ b/en/device-dev/driver/driver-platform-adc-des.md @@ -1,64 +1,79 @@ -# ADC +# ADC -## Overview +## Overview + +### Function An analog-to-digital converter (ADC) is a device that converts analog signals into digital signals. 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 + +### 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. +- Adaptation layer: implements driver-specific functions. + +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. -- Obtaining the analog-to-digital (AD) conversion result +**Figure 1** ADC physical connection - **Figure 1** ADC physical connection - - ![](figures/ADC_physical_connection.png "ADC_physical_connection") -## Available APIs +![](figures/ADC_physical_connection.png "ADC_physical_connection") + +### Constraints + +Currently, the ADC module supports only the kernels (LiteOS) of mini and small systems. + +## 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. + +### Available APIs + +The table below describes the APIs of the ADC module. For more details, see API Reference. **Table 1** APIs of the ADC driver - - - - - - - - - - - - - - - - - - -

Category

-

API

-

Description

-

Managing ADC devices

-

AdcOpen

-		Opens an ADC device.

-

AdcClose

-

Closes an ADC device.

-

Obtaining the conversion result

-

AdcRead

-

Reads the AD conversion result.

-
- -## Usage Guidelines - -### How to Use - -The figure below illustrates how to use the APIs. - - **Figure 2** Using ADC driver APIs - -![](figures/using-ADC-process.png "using-ADC-process.png") - -### Opening an ADC Device + +| API | Description | +| -------- | ---------------- | +| AdcOpen | Opens an ADC device. | +| AdcClose | Closes an ADC device. | +| AdcRead | Obtains the AD conversion result.| + +### How to Develop + +The figure below shows the general development process. + + **Figure 2** Process of using ADC APIs + +![](figures/using-ADC-process.png) + + +#### Opening an ADC Device. Call **AdcOpen** to open an ADC device. @@ -68,43 +83,20 @@ DevHandle AdcOpen(int16_t number); **Table 2** Description of AdcOpen - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

number

-

ADC device number.

-

Return Value

-

Description

-

NULL

-

Failed to open the ADC device.

-

Device handle

-

Handle of the ADC device opened.

-
- -For example, open device 1 of the two ADCs (numbered 0 and 1) in the system. + +| Parameter | Description | +| ---------- | ----------------- | +| number | ADC device number. | +| **Return Value**| **Description** | +| NULL | The operation failed. | +| Device handle | The operation is successful. The handle of the ADC device opened is returned.| + +Example: Open device 1 of the two ADCs (numbered 0 and 1) in the system. ```c DevHandle adcHandle = NULL; /* ADC device handle / -/* Open the ADC device. */ +/* Open ADC device 1. */ adcHandle = AdcOpen(1); if (adcHandle == NULL) { HDF_LOGE("AdcOpen: failed\n"); @@ -112,7 +104,7 @@ if (adcHandle == NULL) { } ``` -### Obtaining the AD Conversion Result +#### Obtaining the AD Conversion Result ```c int32_t AdcRead(DevHandle handle, uint32_t channel, uint32_t *val); @@ -120,48 +112,30 @@ int32_t AdcRead(DevHandle handle, uint32_t channel, uint32_t *val); **Table 3** Description of AdcRead - - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

ADC device handle.

-

channel

-

ADC device channel number.

-

val

-

AD conversion result.

-

Return Value

-

Description

-

0

-

The operation is successful.

-

Negative number

-

Failed to obtain the AC conversion result.

-
- -### Closing an ADC Device + +| Parameter | Description | +| ---------- | -------------- | +| handle | ADC device handle. | +| channel | ADC device channel number. | +| val | Pointer to the AD conversion result. | +| **Return Value**| **Description**| +| 0 | The operation is successful. | +| Negative value | The operation failed. | + +Example: Obtain the AD conversion result of channel 1. + +```c +uint32_t value; +int32_t ret; + +ret = AdcRead(adcHandle, 1, &value); +if (ret != 0) { + HDF_LOGE("ADC read fail!\n"); + return; +} +``` + +#### Closing an ADC Device Call **AdcClose** to close the ADC device after the ADC communication is complete. ```c @@ -169,31 +143,12 @@ void AdcClose(DevHandle handle); ``` **Table 4** Description of AdcClose - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

ADC device handle.

-

Return Value

-

Description

-

None

-

No value is returned if the ADC device is closed.

-
+ +| Parameter | Description | +| ------ | ----------- | +| handle | ADC device handle.| +| **Return Value**| **Description** | +| N/A | N/A | Example: @@ -201,9 +156,9 @@ Example: AdcClose(adcHandle); /* Close the ADC device. */ ``` -## Example +### Example -This following example shows how to use ADC APIs to manage an ADC device on a Hi3516D V300 development board. +This following example shows how to use ADC APIs to manage an ADC device on a Hi3516D V300 board. The basic hardware information is as follows: @@ -242,7 +197,7 @@ static int32_t TestCaseAdc(void) for (i = 0; i < 30; i++) { ret = AdcRead(adcHandle, ADC_CHANNEL_NUM, &readBuf[i]); if (ret != HDF_SUCCESS) { - HDF_LOGE("%s: tp ADC write reg fail!:%d", __func__, ret); + HDF_LOGE("%s: Failed to read ADC!:%d", __func__, ret); AdcClose(adcHandle); return -1; } diff --git a/en/device-dev/driver/driver-platform-dac-des.md b/en/device-dev/driver/driver-platform-dac-des.md index 45cd858317a5affefb3bb285322f73c92b0b380c..4cffd91b8618ab4f466ce32f1ff0ca3e959f1e6b 100644 --- a/en/device-dev/driver/driver-platform-dac-des.md +++ b/en/device-dev/driver/driver-platform-dac-des.md @@ -1,6 +1,5 @@ # DAC - ## Overview ### DAC @@ -8,11 +7,9 @@ A digit-to-analog converter (DAC) is a device that converts a digital signal into an analog signal in electronics. The DAC APIs provide 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. @@ -35,29 +32,31 @@ 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 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, more device nodes need to be configured and memory resources will be consumed by services. 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 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. The DAC module is divided into the following layers: -- The interface layer provides APIs for opening or closing a device and writing data. -- The core layer provides the capabilities of binding, initializing, and releasing devices. -- The adaptation layer implements other functions. ->![](../public_sys-resources/icon-note.gif) **NOTE**
->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. +- Interface layer: provides APIs for opening or closing a device and writing data. +- Core layer: provides the capabilities of binding, initializing, and releasing devices. +- Adaptation layer: implements driver-specific functions. + +>![](../public_sys-resources/icon-note.gif) **NOTE** +> +> 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 -![](figures/unified-service-mode.png "DAC-unified-service-mode") +![](figures/unified-service-mode.png "DAC unified service mode") ### Constraints - Currently, the DAC module supports only the kernels (LiteOS) of mini and small systems. +Currently, the DAC module supports only the kernels (LiteOS) of mini and small systems. -## Development Guidelines +## Usage Guidelines ### When to Use - The DAC module converts digital signals into analog signals in the form of current, voltage, or charge. It is mainly used in audio devices. Audio players and headsets use the DAC module as the digital-to-analog conversion channels. +The DAC module converts digital signals into analog signals in the form of current, voltage, or charge. It is mainly used in audio devices. Audio players and headsets use the DAC module as the digital-to-analog conversion channels. ### Available APIs @@ -65,45 +64,44 @@ The table below describes the APIs of the DAC module. For more details, see API **Table 1** DAC driver APIs -| API | Description | -| :------------------------------------------------------------| :------------ | -| DevHandle DacOpen(uint32_t number) | Opens a DAC device. | -| void DacClose(DevHandle handle) | Closes a DAC device. | -| int32_t DacWrite(DevHandle handle, uint32_t channel, uint32_t val) | Sets a target DA value. | +| API | Description | +| ------------------------------------------------------------------ | ------------ | +| DevHandle DacOpen(uint32_t number) | Opens a DAC device. | +| void DacClose(DevHandle handle) | Closes a DAC device. | +| int32_t DacWrite(DevHandle handle, uint32_t channel, uint32_t val) | Sets a target DA value.| ### How to Develop -The figure below illustrates how to use the APIs. +The figure below shows the general development process. + +**Figure 2** Process of using DAC APIs -**Figure 2** Using DAC driver APIs -![](figures/using-DAC-process.png "using-DAC-process.png") +![](figures/using-DAC-process.png) #### Opening a DAC Device Call **DacOpen()** to open a DAC device before performing the DA conversion. -``` +```c++ DevHandle DacOpen(uint32_t number); ``` **Table 2** Description of DacOpen -| **Parameter** | Description | -| ---------- | ----------------- | -| number | DAC device number. | -| **Return Value**| **Description** | -| NULL | Failed to open the DAC device. | -| Device handle | Handle of the DAC device opened.| - - +| Parameter | Description | +| --------- | ---------------- | +| number | DAC device number. | +| **Return Value**| **Description** | +| NULL | The operation failed. | +| Device handle | The operation is successful. The handle of the DAC device opened is returned.| -Open device 1 of the two ADC devices (numbered 0 and 1) in the system. +Example: Open device 1 of the two DAC devices (numbered 0 and 1) in the system. -``` +```c++ DevHandle dacHandle = NULL; /* DAC device handle / -/* Open the DAC device. */ +/* Open DAC device 1. */ dacHandle = DacOpen(1); if (dacHandle == NULL) { HDF_LOGE("DacOpen: failed\n"); @@ -113,23 +111,22 @@ if (dacHandle == NULL) { #### Setting a Target DA Value -``` +```c++ int32_t DacWrite(DevHandle handle, uint32_t channel, uint32_t val); ``` **Table 3** Description of DacWrite - -| **Parameter** | Description | -| ---------- | -------------- | -| handle | DAC device handle. | -| channel | DAC channel number. | -| val | DA value to set. | +| Parameter | Description | +| --------- | ------------ | +| handle | DAC device handle. | +| channel | DAC channel number.| +| val | DA value to set. | | **Return Value**| **Description**| -| 0 | The operation is successful. | -| Negative value | The operation failed. | +| 0 | The operation is successful. | +| Negative value | The operation failed. | -``` +```c++ /* Write the target DA value through the DAC_CHANNEL_NUM channel. */ ret = DacWrite(dacHandle, DAC_CHANNEL_NUM, val); if (ret != HDF_SUCCESS) { @@ -142,28 +139,25 @@ int32_t DacWrite(DevHandle handle, uint32_t channel, uint32_t val); #### Closing a DAC Device After the DAC communication is complete, call **DacClose()** to close the DAC device. -``` +```c++ void DacClose(DevHandle handle); ``` **Table 4** Description of DacClose - -| **Parameter** | Description | -| ---------- | -------------- | -| handle | DAC device handle. | +| Parameter | Description | +| --------- | ------------ | +| handle | DAC device handle. | | **Return Value**| **Description**| -| void | - | - - +| void | - | Example: -``` +```c++ DacClose(dacHandle); /* Close the DAC device. */ ``` -## Development Example +## Example The procedure is as follows: @@ -173,8 +167,8 @@ The procedure is as follows: You can obtain the operation result by printing the log information based on the **val**. -``` -#include "hdmi_if.h" /* Header file for DAC APIs */ +```c++ +#include "dac_if.h" /* Header file for DAC APIs */ #include "hdf_log.h" /* Header file for log APIs */ /* Define device 0, channel 1. */ @@ -209,4 +203,4 @@ static int32_t TestCaseDac(void) return 0; } -``` \ No newline at end of file +``` diff --git a/en/device-dev/driver/figures/ADC_physical_connection.png b/en/device-dev/driver/figures/ADC_physical_connection.png index da94f3b486edb6b269ef341b12b1816f23036c32..d3cddfb92b63afc8ae1b3f8d02e4ac9c7aeb9edd 100644 Binary files a/en/device-dev/driver/figures/ADC_physical_connection.png and b/en/device-dev/driver/figures/ADC_physical_connection.png differ diff --git a/en/device-dev/driver/figures/using-ADC-process.png b/en/device-dev/driver/figures/using-ADC-process.png index 6aebca249fa9d7948eca5f0047cea6ac4074c731..691adc1e3454170d4c0f16f60739560ef2e3ea9f 100644 Binary files a/en/device-dev/driver/figures/using-ADC-process.png and b/en/device-dev/driver/figures/using-ADC-process.png differ