Skip to content

D
Docs

OpenHarmony / Docs
接近 2 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs
提交 93ed15fa 编写于 作者: A Annie_wang
浏览文件
操作

update docs 

Signed-off-by: NAnnie_wang <annie.wangli@huawei.com>
上级 c30d987d
展开全部 隐藏空白更改
内联 并排
Showing with 2771 addition and 2324 deletion
en/device-dev/driver/driver-platform-pin-des.md
浏览文件 @ 93ed15fa
# Pin
# Pin
## Overview
## Overview<a name="section1"></a>
### Function
### Pin<a name="section2"></a>
The pin module, also called pin controller, manages pin resources of the system on a chip (SoC) and implements the pin multiplexing function.
The pin module, also called pin controller, manages pin resources of system on a chip (SoC) vendors and provides the pin multiplexing function.
The module defines a set of common methods for managing pins, including:
- Obtaining or releasing the pin description handle: The kernel compares the pin name passed in with the pin names of each controller in the linked list. If a match is found, a pin description handle is obtained. After the operation on the pin is complete, the pin description handle will be released.
- Setting or obtaining the pull type of a pin: The pull type can be pull-up, pull-down, or floating.
- Setting or obtaining the pull strength of a pin: You can set the pull strength as required.
- Setting or obtaining the functions of a pin to implement pin multiplexing
The pin module provides a set of APIs for pin management, including:
### Basic Concepts<a name="section3"></a>
Pin, as a software concept, provides APIs for uniformly managing the pins from different SoC vendors, providing the pin multiplexing function, and configuring the electrical features of pins.
- Obtaining or releasing a pin description handle
- Setting or obtaining the pull type (pull-up, pull-down, or floating) of a pin
- Setting or obtaining the pull strength of a pin
- Setting or obtaining the function of a pin to implement pin multiplexing
### Basic Concepts
Pin is a software concept designed to uniformly manage SoC pins, implement pin multiplexing, and set electrical features of pins.
- SoC
An SOC is a chip that integrates microprocessors, analog IP cores, digital IP cores, and memory for specific purposes.
An SoC is a chip that integrates microprocessors, analog IP cores, digital IP cores, and memory for specific purposes.
- Pin multiplexing
When the number of pins of a chip cannot handle the increasing connection requests, you can set the software registers to make the pins to work in different states.
When the number of pins of a chip cannot handle the increasing connection requests, you can set software registers to make the pins to work in different states.
### Working Principles
### Working Principles<a name="section4"></a>
In the Hardware Driver Foundation (HDF), the pin module uses the unified service mode for API adaptation. In this mode, a device service is used as the pin 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.
In the HDF, the pin module does not support the user mode and therefore does not need to publish services. It uses the service-free mode in interface adaptation. The service-free mode applies to the devices that do not provide user-mode APIs or the OS that does not distinguish the user mode and the kernel mode. The **DevHandle**, a void pointer, directly points to the kernel mode address of the device object.
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 pin module is divided into the following layers:
- Interface layer: provides APIs for obtaining a pin, setting or obtaining the pull type, pull strength, and functions of a pin, and releasing a pin.
- Core layer: provides the capabilities of matching pin resources and adding, removing, and managing pin controllers. The core layer interacts with the adaptation layer by using hooks.
- Adaptation layer: instantiates hooks to implement specific functions.
**Figure 1** Service-free mode<a name="fig14423182615525"></a>
![](figures/service-free-mode.png "pin service-free mode")
- Interface layer: provides APIs for obtaining a pin, setting or obtaining the pull type, pull strength, and function of a pin, and releasing a pin.
- Core layer: provides the capabilities of matching pin resources, adding and removing a pin controller, and managing pins. The core layer interacts with the adaptation layer through hook functions.
- Adaptation layer: instantiates the hook functions to implement specific features.
### Constraints<a name="section5"></a>
**Figure 1** Unified service mode
![Unified service mode](figures/unified-service-mode.png)
Currently, the pin module supports only the kernels (LiteOS) of mini and small systems.
### Constraints
## Usage Guidelines<a name="section6"></a>
The pin module supports only the LiteOS-A kernel of the small system.
### When to Use<a name="7"></a>
## Usage Guidelines
The pin module is a software concept and is used to manage pin resources. You can set the functions, pull type, and pull strength of pins to implement pin multiplexing.
### When to Use
### Available APIs<a name="section8"></a>
The pin module is a software concept used to manage pin resources. You can set the function, pull type, and pull strength of pins to implement pin multiplexing.
The table below describes the APIs of the pin module. For more details, see API Reference.
### Available APIs
The following table describes the APIs of the pin module.
**Table 1** Pin driver APIs
<a name="table1"></a>
| **API** | **Description** |
| **API** | **Description** |
| ------------------------------------------------------------ | ---------------- |
| DevHandle PinGet(const char *pinName); | Obtains the pin description handle.|
| void PinPut(DevHandle handle); | Releases the pin description handle.|
| int32_t PinSetPull(DevHandle handle, enum PinPullType pullType); | Sets the pull type of a pin.|
| int32_t PinGetPull(DevHandle handle, enum PinPullType *pullType); | Obtains the pull type of a pin.|
| int32_t PinSetStrength(DevHandle handle, uint32_t strength); | Sets the pull strength of a pin.|
| int32_t PinGetStrength(DevHandle handle, uint32_t *strength); | Obtains the pull strength of a pin.|
| int32_t PinSetFunc(DevHandle handle, const char *funcName); | Sets the pin function. |
| int32_t PinGetFunc(DevHandle handle, const char **funcName); | Obtains the pin functions. |
| DevHandle PinGet(const char *pinName) | Obtains a pin description handle.|
| void PinPut(DevHandle handle) | Releases the pin description handle.|
| int32_t PinSetPull(DevHandle handle, enum PinPullType pullType) | Sets the pull type of a pin.|
| int32_t PinGetPull(DevHandle handle, enum PinPullType *pullType) | Obtains the pull type of a pin.|
| int32_t PinSetStrength(DevHandle handle, uint32_t strength) | Sets the pull strength of a pin.|
| int32_t PinGetStrength(DevHandle handle, uint32_t *strength) | Obtains the pull strength of a pin.|
| int32_t PinSetFunc(DevHandle handle, const char *funcName) | Sets the pin function.|
| int32_t PinGetFunc(DevHandle handle, const char **funcName) | Obtains the pin function. |
>![](../public_sys-resources/icon-note.gif) **NOTE**<br/>
>All APIs described in this document can be called only in the kernel space.
>![](../public_sys-resources/icon-note.gif) **NOTE**
>
>All the pin APIs described in this document can be used in kernel mode and user mode.
### How to Develop<a name="section9"></a>
### How to Develop
The figure below illustrates how to use the APIs.
The following figure illustrates how to use pin driver APIs.
**Figure 2** Using the pin driver APIs
**Figure 2** Using pin driver APIs<br>
![](figures/using-pin-process.png "Process of using the pin module")
#### Obtaining the Pin Description Handle
#### Obtaining a Pin Description Handle
Before performing an operation on a pin, call **PinGet** to obtain the pin description handle. This API returns the pin description handle that matches the input pin name.
Before performing an operation on a pin, use **PinGet()** to obtain the pin description handle based on the pin name.
```
```c
DevHandle PinGet(const char *pinName);
```
**Table 2** Description of PinGet
<a name="table2"></a>
| Parameter | Description |
| ---------- | ----------------------- |
| pinName | Pointer to the pin name. |
| **Return Value**| **Description** |
| NULL | Failed to obtain the pin description handle.|
| handle | Pin description handle obtained. |
| **Return Value**| **Description** |
| NULL | The operation fails.|
| handle | The operation is successful. The pin description handle obtained is returned. |
Example: Obtain the handle of P18.
Example: Obtain the pin description handle of P18.
```
DevHandle handle = NULL; /* Pin description handle */
char pinName = "P18"; /* Pin name. */
```c
DevHandle handle = NULL; // Pin description handle.
char pinName = "P18"; // Pin name.
handle = PinGet(pinName);
if (handle == NULL) {
HDF_LOGE("PinGet: get handle failed!\n");
......@@ -107,29 +110,28 @@ if (handle == NULL) {
#### Setting the Pull Type of a Pin
Call **PinSetPull** to set the pull type of a pin.
Use **PinSetPull()** to set the pull type of a pin.
```
```c
int32_t PinSetPull(DevHandle handle, enum PinPullType pullType);
```
**Table 3** Description of PinSetPull
<a name="table3"></a>
| Parameter | Description |
| Parameter | Description |
| ---------- | ----------------------- |
| handle | Pin description handle. |
| pullType | Pull type to set. |
| **Return Value**| **Description** |
| **Return Value**| **Description** |
| 0 | The operation is successful.|
| Negative value | The operation failed.|
| Negative value | The operation fails.|
Example: Set the pull type to pull-up.
```
```c
int32_t ret;
enum PinPullType pullTypeNum;
/* Set the pull type of a pin. */
pullTypeNum = 1;
ret = PinSetPull(handle, pullTypeNum);
......@@ -141,29 +143,28 @@ if (ret != HDF_SUCCESS) {
#### Obtaining the Pull Type of a Pin
Call **PinGetPull** to obtain the pull type of a pin.
Use **PinGetPull()** to obtain the pull type of a pin.
```
```c
int32_t PinGetPull(DevHandle handle, enum PinPullType *pullType);
```
**Table 4** Description of PinGetPull
<a name="table4"></a>
| Parameter | Description |
| ---------- | ------------------------- |
| handle | Pin description handle. |
| pullType | Pointer to the pull type obtained.|
| **Return Value**| **Description** |
| **Return Value**| **Description** |
| 0 | The operation is successful. |
| Negative value | The operation failed. |
| Negative value | The operation fails. |
Example: Obtain the pull type of a pin.
```
```c
int32_t ret;
enum PinPullType pullTypeNum;
/* Obtain the pull type of a pin. */
ret = PinGetPull(handle, &pullTypeNum);
if (ret != HDF_SUCCESS) {
......@@ -174,27 +175,25 @@ if (ret != HDF_SUCCESS) {
#### Setting the Pull Strength of a Pin
Call **PinSetStrength** to set the pull type of a pin.
Use **PinSetStrength()** to set the pull type of a pin.
```
```c
int32_t PinSetStrength(DevHandle handle, uint32_t strength);
```
**Table 5** Description of PinSetStrength
<a name="table5"></a>
| Parameter | Description |
| ---------- | ----------------------- |
| handle | Pin description handle. |
| strength | Pull strength to set. |
| **Return Value**| **Description** |
| **Return Value**| **Description** |
| 0 | The operation is successful.|
| Negative value | The operation failed.|
| Negative value | The operation fails.|
Example: Set the pull strength of the pin to 2.
```
```c
int32_t ret;
uint32_t strengthNum;
/* Set the pull strength of the pin. */
......@@ -208,29 +207,28 @@ if (ret != HDF_SUCCESS) {
#### Obtaining the Pull Strength of a Pin
Call **PinGetStrength** to obtain the pull strength set.
Use **PinGetStrength()** to obtain the pull strength of a pin.
```
```c
int32_t PinGetStrength(DevHandle handle, uint32_t *strength);
```
**Table 6** Description of PinGetStrength
<a name="table6"></a>
| Parameter | Description |
| ---------- | ------------------------- |
| handle | Pin description handle. |
| strength | Pointer to the pull strength obtained.|
| **Return Value**| **Description** |
| **Return Value**| **Description** |
| 0 | The operation is successful. |
| Negative value | The operation failed. |
| Negative value | The operation fails. |
Example: Obtain the pull strength of a pin.
```
```c
int32_t ret;
uint32_t strengthNum;
/* Obtain the pull strength of the pin. */
ret = PinGetStrength(handle, &strengthNum);
if (ret != HDF_SUCCESS) {
......@@ -241,31 +239,30 @@ if (ret != HDF_SUCCESS) {
#### Setting the Pin Function
The pin function refers to the pin multiplexing function. The function of each pin is different. For details about the pin functions, see [pin_config.hcs](https://gitee.com/openharmony/device_soc_hisilicon/blob/master/hi3516dv300/sdk_liteos/hdf_config/pin/pin_config.hcs).
The pin function refers to the multiplexed pin function. The function of each pin is different. For details about the pin function name, see **//device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/pin/pin_config.hcs**.
Call **PinSetFunc** to set the pin function.
Use **PinSetFunc()** to set the pin function.
```
```c
int32_t PinSetFunc(DevHandle handle, const char *funcName);
```
**Table 7** Description of PinSetFunc
<a name="table7"></a>
| Parameter | Description |
| ---------- | ------------------- |
| handle | Pin description handle. |
| funcName | Pointer to the pin function to set. |
| **Return Value**| **Description** |
| **Return Value**| **Description** |
| 0 | The operation is successful.|
| Negative value | The operation failed.|
| Negative value | The operation fails.|
Example: Set the pin function to LSADC_CH1 (ADC channel 1).
```
```c
int32_t ret;
char funcName = "LSADC_CH1";
/* Sets the pin function. */
ret = PinSetFunc(handle, funcName);
if (ret != HDF_SUCCESS) {
......@@ -276,31 +273,30 @@ if (ret != HDF_SUCCESS) {
#### Obtaining the Pin Function
Call **PinGetFunc** to obtain the pin function set.
Use **PinGetFunc()** to obtain the pin function.
```
```c
int32_t PinGetFunc(DevHandle handle, const char **funcName);
```
**Table 8** Description of PinGetFunc
<a name="table8"></a>
| Parameter | Description |
| ---------- | --------------------- |
| handle | Pin description handle. |
| funcName | Pointer to the function name obtained.|
| **Return Value**| **Description** |
| **Return Value**| **Description** |
| 0 | The operation is successful. |
| Negative value | The operation failed. |
| Negative value | The operation fails. |
Example: Obtain the pin function.
```
```c
int32_t ret;
char *funcName;
char *funcName = NULL;
/* Obtain the pin function. */
ret = PinGetFunc(handle,&funcName);
ret = PinGetFunc(handle, &funcName);
if (ret != HDF_SUCCESS) {
HDF_LOGE("PinGetFunc: failed, ret %d\n", ret);
return ret;
......@@ -309,16 +305,14 @@ if (ret != HDF_SUCCESS) {
#### Releasing a Pin Description Handle
After the operations on a pin are complete, call **PinPut** to release the pin description handle.
After the operations on a pin are complete, use **PinPut()** to release the pin description handle.
```
```c
void PinPut(DevHandle handle);
```
**Table 9** Description of PinPut
<a name="table9"></a>
| Parameter | Description |
| ---------- | -------------- |
| handle | Pin description handle. |
......@@ -327,13 +321,14 @@ void PinPut(DevHandle handle);
Example: Release a pin description handle.
```
```c
PinPut(handle);
```
## Development Example<a name="section10"></a>
## Example
The following uses the Hi3516D V300 development board as an example. The procedure is as follows:
The procedure is as follows:
1. Pass in the pin name to obtain the pin description handle.
2. Set the pull type of the pin. If the operation fails, release the pin description handle.
3. Obtain the pull type of the pin. If the operation fails, release the pin description handle.
......@@ -343,9 +338,9 @@ The procedure is as follows:
6. Obtain the pin function. If the operation fails, release the pin description handle.
7. Release the pin description handle if no operation needs to be performed on the pin.
```
#include "hdf_log.h" /* Header file for log APIs */
#include "pin_if.h" /* Header file for standard pin APIs */
```c
#include "hdf_log.h" /* Header file of the HDF log APIs. */
#include "pin_if.h" /* Header file of standard pin APIs. */
int32_t PinTestSample(void)
{
......@@ -361,7 +356,7 @@ int32_t PinTestSample(void)
/* Obtain the pin description handle. */
handle = PinGet(pinName);
if (handle == NULL) {
HDF_LOGE("PinGet: failed!\n");
HDF_LOGE("PinGet: pin get failed!\n");
return;
}
/* Set the pull type to pull-up for the pin. */
......@@ -407,4 +402,5 @@ ERR:
/* Release the pin description handle. */
PinPut(handle);
return ret;
}
\ No newline at end of file
}
```
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或