@@ -201,13 +201,13 @@ The following uses **gpio_hi35xx.c** as an example to present the information re
-**Init** function
Input parameter:
**Input parameter**:
**HdfDeviceObject**, an interface parameter exposed 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/framework/include/utils/hdf_base.h** file.
**Table 2** HDF_STATUS
...
...
@@ -220,7 +220,7 @@ The following uses **gpio_hi35xx.c** as an example to present the information re
| HDF_SUCCESS | Initialization successful.|
| HDF_FAILURE | Initialization failed.|
Function description:
**Function description**:
Initializes the custom structure object and **GpioCntlr**, calls the **GpioCntlrAdd** function at the core layer, and (optional) connects to the virtual file system (VFS).
...
...
@@ -241,7 +241,7 @@ The following uses **gpio_hi35xx.c** as an example to present the information re
...
ret = Pl061GpioInitCntlrMem(pl061); // Allocate memory.
...
pl061->cntlr.count = pl061->groupNum x pl061->bitNum;// (Mandatory) Calculate the number of pins.
pl061->cntlr.count = pl061->groupNum * pl061->bitNum;// (Mandatory) Calculate the number of pins.
pl061->cntlr.priv = (void *)device->property; // (Mandatory) Store device attributes.
pl061->cntlr.ops = &g_method; // (Mandatory) Attach the GpioMethod instance.
pl061->cntlr.device = device; // (Mandatory) Prerequisites for conversion between HdfDeviceObject and GpioCntlr.
...
...
@@ -258,17 +258,20 @@ The following uses **gpio_hi35xx.c** as an example to present the information re
```
-**Release** function
Input parameter:
**Input parameter**:
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration file information.
Return value:
**Return value**:
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. All forced conversion operations for obtaining the corresponding object can be successful only when the **Init** function has the value assignment operations.
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.
@@ -241,7 +241,7 @@ The HDMI module adaptation involves the following steps:
struct HdmiAdapterHost {
struct HdmiCntlr *cntlr; // (Mandatory) Control object at the core layer. The details are as follows:
volatile unsigned char *regBase;// (Mandatory) Register base address.
uint32_t regBasePhy // (Mandatory) Physical base address of the register.
uint32_t regBasePhy; // (Mandatory) Physical base address of the register.
uint32_t regSize; // (Mandatory) Register bit width.
uint32_t irqNum; // (Mandatory) IRQ number.
};
...
...
@@ -321,7 +321,7 @@ The HDMI module adaptation involves the following steps:
**Return value**:
HDF_STATUS
**HDF_STATUS**
The table below describes some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file.
...
...
@@ -385,7 +385,7 @@ The HDMI module adaptation involves the following steps:
**Return value**:
HDF_STATUS
**HDF_STATUS**
**Function description**:
...
...
@@ -412,16 +412,16 @@ The HDMI module adaptation involves the following steps:
Releases the memory and deletes the controller. This function assigns values to the **Release** callback in the driver entry structure. If the HDF fails to call the **Init** function to initialize the driver, the **Release** function can be called to release driver resources.
> All forced conversion operations for obtaining the corresponding object can be successful only when the **Init** function has the corresponding value assignment operations.
cntlr = (struct MmcCntlr *)obj->service;// Forcibly convert HdfDeviceObject to HdmiCntlr by using service. For details about the value assignment, see the Bind function.
cntlr = (struct HdmiCntlr *)obj->service;// Forcibly convert HdfDeviceObject to HdmiCntlr by using service. For details about the value assignment, see the Bind function.
...
HimciDeleteHost((struct HimciAdapterHost *)cntlr->priv);// Customized memory release function. A forced conversion from HdmiCntlr to HimciAdapterHost is involved in the process.
> All forced conversion operations for obtaining the corresponding object can be successful only when the **Init** function has the corresponding value assignment operations.
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.
**Figure 1** Unified service mode
**Figure 1** Unified service mode
![image](figures/unified-service-mode.png"I2C Unified Service Mode")
...
...
@@ -59,7 +59,10 @@ The I2C module adaptation involves the following steps:
The following uses **i2c_hi35xx.c** as an example to present the information required for implementing device functions.
1. Instantiate the driver entry.<br/>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.
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.
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.
I2C driver entry example:
...
...
@@ -68,13 +71,12 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
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.
```
struct HdfDriverEntry g_i2cDriverEntry = {
.moduleVersion = 1,
.Init = Hi35xxI2cInit,
.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.
...
...
@@ -84,11 +86,13 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
.Bind = I2cManagerBind,
.Init = I2cManagerInit,
.Release = I2cManagerRelease,
.moduleName = "HDF_PLATFORM_I2C_MANAGER",// This parameter corresponds to device0 in the device_info file.
.moduleName = "HDF_PLATFORM_I2C_MANAGER", // This parameter corresponds to device0 in the device_info file.
};
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.
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.
...
...
@@ -102,7 +106,7 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
| moduleName | **HDF_PLATFORM_I2C_MANAGER**|
| serviceName | **HDF_PLATFORM_I2C_MANAGER**|
| policy | **1** or **2**, depending on whether the service is published to the user mode.|
| deviceMatchAttr | This parameter is reserved.|
| deviceMatchAttr | 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.
...
...
@@ -182,7 +186,7 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
uint32_t clk; // (Optional) Customized.
uint32_t freq; // (Optional) Customized.
uint32_t irq; // (Optional) Customized.
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.
...
...
@@ -206,18 +210,18 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
static const struct I2cLockMethod g_lockOps = {
.lock = Hi35xxI2cLock, // Lock function
.unlock = Hi35xxI2cUnlock,// Unlock function
.unlock = Hi35xxI2cUnlock,// Unlock function
};
```
-**Init** function
Input parameter:
**Input parameter**:
**HdfDeviceObject**, an interface parameter exposed 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/framework/include/utils/hdf_base.h** file.
**Table 3** HDF_STATUS
...
...
@@ -230,7 +234,7 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
| HDF_SUCCESS | Transmission successful.|
| 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).
...
...
@@ -282,15 +286,15 @@ The following uses **i2c_hi35xx.c** as an example to present the information req
```
-**Release** function
Input parameter:
**Input parameter**:
**HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information.
Return value:
**Return value**:
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.
> The system may have multiple I3C controllers. Therefore, you need to create a manager object in the HDF and publish a manager service to uniformly handle external access requests. Then, the manager service locates the controller to open based on the specified parameters.
>
> The core layer implements the driver of the I3C manager service. Vendors do not need to care about the implementation. However, the **I3cCntlrAdd()** function at the core layer must be called in the implementation of **Init()** to implement related features.
> 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.
@@ -155,7 +157,7 @@ The I3C module adaptation involves the following steps:
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.
|Name|Value|
|Parameter|Value|
|-|-|
|moduleName |HDF_PLATFORM_I3C_MANAGER|
|serviceName|Reserved|
...
...
@@ -219,14 +221,16 @@ The I3C module adaptation involves the following steps:
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).
- Define a custom structure.
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.
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.
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.
...
...
@@ -252,9 +256,8 @@ The I3C module adaptation involves the following steps:
};
```
> 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()**.
- **Init** function
-**Init** function
**Input parameter**:
...
...
@@ -262,7 +265,7 @@ The I3C module adaptation involves the following steps:
**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.
**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.
| Status| Description|
| -------- | -------- |
...
...
@@ -273,7 +276,6 @@ The I3C module adaptation involves the following steps:
| HDF_SUCCESS | Transmission successful.|
| HDF_FAILURE | Transmission failed.|
**Function description**:
Initializes the custom structure object and **I3cCntlr**, and calls the **I3cCntlrAdd** function to add the I3C controller to the core layer.
...
...
@@ -347,7 +349,9 @@ The I3C module adaptation involves the following steps:
}
```
- **Release** function
-**Release** function
**Input parameter**:
...
...
@@ -359,7 +363,10 @@ The I3C module adaptation involves the following steps:
**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.
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.
>For details about the functions in **MipiCsiCntlrMethod**, see [Available APIs](#available-apis).
4. Debug the driver.
- (Optional) For new drivers, verify the basic functions, for example, the data transmission and the information returned after the **MipiCsiCntlrMethod** instance is attached.
(Optional) For new drivers, verify the basic functions, for example, the data transmission and the information returned after the **MipiCsiCntlrMethod** instance is attached.
## Development Example
...
...
@@ -76,9 +79,10 @@ The following uses **mipi_rx_hi35xx.c** as an example to present the information
The device attribute values are closely related to the default values or value range of the **MipiCsiCntlr** members at the core layer. The **deviceNode** information is related to the driver entry registration.
In this example, the MIPI controller attributes are defined in the source file. If required, add the **deviceMatchAttr** information to **deviceNode** in the **device_info** file and add the **mipicsi_config.hcs** file.
>In this example, the MIPI controller attributes are defined in the source file. If required, add the **deviceMatchAttr** information to **deviceNode** in the **device_info** file and add the **mipicsi_config.hcs** file.
-**device_info.hcs** configuration example
-**device_info.hcs** configuration example
```c
root{
...
...
@@ -101,25 +105,30 @@ The following uses **mipi_rx_hi35xx.c** as an example to present the information
}
```
2. Instantiate the driver entry.<br/>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**. The function pointer members in the **HdfDriverEntry** structure are filled by the vendors' operation functions. 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.
2. 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**. The function pointer members in the **HdfDriverEntry** structure are filled by the vendors' operation functions. 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.
- MIPI CSI driver entry example
- MIPI CSI driver entry example
```c
structHdfDriverEntryg_mipiCsiDriverEntry={
.moduleVersion=1,
.Init=Hi35xxMipiCsiInit,// See the Init function.
.Release=Hi35xxMipiCsiRelease,//See the Release function.
.Release=Hi35xxMipiCsiRelease,// See the Release function.
.moduleName="HDF_MIPI_RX",// (Mandatory) The value must be the same as that in the device_info.hcs file.
};
HDF_INIT(g_mipiCsiDriverEntry);// Call HDF_INIT to register the driver entry with the HDF.
```
3. Initialize the **MipiCsiCntlr** 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 **MipiCsiCntlrMethod** in **MipiCsiCntlr** (so that the underlying driver functions can be called).
- Defining a custom structure
- Defining a custom structure
To the driver, the custom structure hols parameters and data. The values in the **config** file are used to initialize the structure members. In this example, the MIPI CSI attributes are defined in the source file. Therefore, the basic member structure is similar to that of **MipiCsiCntlr**.
...
...
@@ -176,7 +185,12 @@ The following uses **mipi_rx_hi35xx.c** as an example to present the information
};
```
- Instantiating **MipiCsiCntlrMethod** in **MipiCsiCntlr** (other members are initialized by **Init**)
- Instantiating **MipiCsiCntlrMethod** in **MipiCsiCntlr**
>
>
>Other members are initialized by **Init**.
```c
static struct MipiCsiCntlrMethod g_method = {
...
...
@@ -195,7 +209,7 @@ The following uses **mipi_rx_hi35xx.c** as an example to present the information
};
```
- Init function
-**Init** function
**Input parameter**:
...
...
@@ -203,13 +217,12 @@ The following uses **mipi_rx_hi35xx.c** as an example to present the 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.
**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.
@@ -283,7 +295,10 @@ The following uses **mipi_rx_hi35xx.c** as an example to present the information
}
```
- Release function
-**Release** function
**Input parameter**:
...
...
@@ -297,7 +312,9 @@ The following uses **mipi_rx_hi35xx.c** as an example to present the information
Releases the memory and deletes the controller. This function assigns values to the **Release** API in the driver entry structure. When 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.
>All forced conversion operations for obtaining the corresponding object can be successful only when the **Init** function has the value assignment operations.
