API of HDF driver framework (1)

introduction

For the convenience of reference, this article collects the APIs provided by the HDF driver framework that I have encountered in the process of learning the Hongmeng driver subsystem. At the same time, some personal understanding and interpretation of these APIs are also added.

In addition, you can also read the source code or official documentation of these APIs:

https://device.harmonyos.com/cn/docs/documentation/apiref/core-0000001054718073  

​

1. Structure

1.1 HdfDriverEntry

The structure HdfDriverEntrycan be called HDF驱动入口结构体, representing the entry point of the device driver.

1. Official documents

https://device.harmonyos.com/cn/docs/documentation/apiref/hdfdriverentry-0000001055198130

2. Definition

drivers/framework/include/core/hdf_device_desc.h

struct HdfDriverEntry {
    //驱动程序的版本号
    int32_t moduleVersion;
    //驱动程序的名称，必须与驱动配置文件device_info.hcs中设备节点的moduleName属性保持一致。
    const char *moduleName;
    //三个函数指针，指向设备驱动的三个入口函数。
    int32_t (*Bind)(struct HdfDeviceObject *deviceObject);
    int32_t (*Init)(struct HdfDeviceObject *deviceObject);
    void (*Release)(struct HdfDeviceObject *deviceObject);
};

In the structure HdfDriverEntry, the function pointed to by the three function pointers is called the driver entry function , which is written by the driver developer and called by the HDF driver framework.

(1) Bind function

Driver service entry for notifying (registering) the driver to the HDF driver framework.

When the function executes successfully, the return value is equal to 0.

(2) Init function

It is mainly used to complete some initialization actions of the driver, such as obtaining device configuration information through the interface provided by HDF, initializing the device, subscribing to the services provided by the driver, and so on.

When the function executes successfully, the return value is equal to 0.

(3) Release function

Used to release the resources occupied by the driver.

---

In the process of loading the driver, the HDF driver framework first calls Bindthe function, and then calls Initthe function. When an exception occurs during the loading of the driver, or when the driver is unloaded, the HDF driver framework will call Releasea function to release the resources occupied by the driver.

The parameters of the driver entry function are all pointers to the structure HdfDeviceObject(see Section 1.2).

1.2 HdfDeviceObject

The structure HdfDeviceObjectcan be called HDF设备对象结构体, is generated by HDF, and represents a device node. The HDF driver framework obtains the configuration information of all device nodes by parsing the driver configuration file, and then it will create such a structure for each device node to store the configuration information of the device node and the driver service entry; when HDF When calling the driver entry function (see Section 1.1), the pointer to this structure will be passed to these functions as a parameter.

1. Official documents

https://device.harmonyos.com/cn/docs/documentation/apiref/hdfdeviceobject-0000001054479563

2. Definition

drivers/framework/include/core/hdf_device_desc.h

struct HdfDeviceObject {
    //指向驱动服务入口结构体的指针
    struct IDeviceIoService *service;
    //指向设备节点配置信息的指针，
    const struct DeviceResourceNode *property;
    //设备节点所属的设备类型
    DeviceClass deviceClass;
    //指向设备节点的私有数据
    void *priv;
};

HdfDeviceObjectThere are 4 members in the structure :

（1）service

Pointer to the driver service entry structure IDeviceIoService(see Section 1.3). The driver developer needs Bindto assign this pointer in the function (see Section 1.1) to inform HDF of the driver's external service entry.

（2）property

Pointer to a structure DeviceResourceNode(see Section 1.4). In this structure, the mandatory configuration information of the device node obtained by HDF is stored.

（3）deviceClass

The device type to which the device node belongs, value type: enumeration type DeviceClass(see section 3.1).

（4）priv

Pointer to private data for the device node.

1.3 IDeviceIoService

Most of the functions of the driver are presented in the form of external services. For any driver, the entrance of its external service must be IDeviceIoServicea structure. Even though you can customize the driver entry structure, the first member of the custom driver entry structure must be a IDeviceIoServicestructure.

1. Official documents

https://device.harmonyos.com/cn/docs/documentation/apiref/ideviceioservice-0000001055198134

2. Definition

drivers/framework/include/core/hdf_device_desc.h

struct IDeviceIoService {
    //驱动服务的ID
    struct HdfObject object;
    //当用户态的应用程序获取驱动服务的时候，该函数被HDF调用。
    int32_t (*Open)(struct HdfDeviceIoClient *client);
    //当用户态的应用程序调用应用态Dispatch函数的时候，HDF就会调用这个内核态的Dispatch函数，驱动开发者可以在这个函数中实现驱动提供的服务。 
    int32_t (*Dispatch)(struct HdfDeviceIoClient *client, int cmdId, struct HdfSBuf *data, struct HdfSBuf *reply);
    //当用户态的应用程序释放驱动服务的时候，该函数被HDF调用。
    void (*Release)(struct HdfDeviceIoClient *client);
};

IDeviceIoServiceThere are 4 members in the structure :

The first member objectis used to store the ID of the driver service and HdfObjectthe structure type (see Section 1.6). There is only one field (objectId) in this structure, which is a 32-bit integer assigned by HDF.

The functions pointed to by the next three function pointers are all called by HDF, and the parameters of the functions are also passed in by HDF. The first parameter is a pointer to a structure HdfDeviceIoClient(see Section 1.7). Driver developers can choose whether to write these three functions according to actual needs.

(1) Open function

HdfIoServiceBindThis function is called by HDF when calling a function (see Section 2.9) to obtain driver services in a user-mode application .

(2) Dispatch function

Functions must be used for the interaction between user-mode applications and kernel-mode drivers Dispatch. This function is written by the driver developer, and is called by HDF when the application program calls the Dispatch interface function (see Section 1.11) provided by HDF to use the driver service. When HDF calls this function, four parameters are passed in:

parameter	type	describe
client	HdfDeviceIoClient structure (see section 1.7) pointer	This structure is used to store the information of the HDF device IO service client.
cmdId	integer	command word from the application.
data	Pointer to HdfSBuf structure (see Section 1.8)	Points to a buffer that holds data received from the application.
reply	Pointer to HdfSBuf structure (see Section 1.8)	Points to a buffer where data is sent back to the application.

(3) Release function

HdfIoServiceRecycleThis function is called by HDF when calling a function (see Section 2.11) to release driver services in a user-mode application .

1.4 DeviceResourceNode

It is used to store the configuration information of a device node in the device tree, including the name and attributes of the device node, and pointers to the parent node, child node, and sibling nodes of the device node. Through this structure, multiple device nodes form a device tree in the form of a doubly linked list.

1. Official documents

https://device.harmonyos.com/cn/docs/documentation/apiref/deviceresourcenode-0000001054598157

2. Definition

drivers/framework/include/config/device_resource_if.h

struct DeviceResourceNode {
    const char *name;   //节点的名称                    
    uint32_t hashValue; //节点的ID                 
    struct DeviceResourceAttr *attrData; //指向节点的属性结构体（见1.5节）   
    struct DeviceResourceNode *parent;   //指向父节点的指针    
    struct DeviceResourceNode *child;    //指向子节点的指针       
    struct DeviceResourceNode *sibling;  //指向兄弟姐妹节点的指针   
};

1.5 DeviceResourceAttr

An attribute used to store device nodes. The attributes of the device node are stored in the form of a one-way linked list, and each node in the linked list is a DeviceResourceAttrstructure that stores an attribute of the device node.

1. Official documents

https://device.harmonyos.com/cn/docs/documentation/apiref/deviceresourceattr-0000001055078135

2. Definition

drivers/framework/include/config/device_resource_if.h

struct DeviceResourceAttr {
    const char *name;   //属性的名称
    const char *value;  //属性的值
    struct DeviceResourceAttr *next; //指向下一个属性的指针
};

1.6 HD Object

There is only one member objectId, which is a 32bit integer.

1. Official documents

https://device.harmonyos.com/cn/docs/develop/apiref/hdfobject-0000001054918155

2. Definition

drivers/framework/include/core/hdf_object.h

struct HdfObject {
    int32_t objectId; 
};

1.7 HdfDeviceIoClient

This structure is used to store the information of the HDF device IO service client. The device driver publishes services through HDF, which is equivalent to a "server"; the application program requests services through HDF, which is equivalent to a "client".

1. Official documents

https://device.harmonyos.com/cn/docs/develop/apiref/hdfdeviceioclient-0000001054879532

2. Definition

drivers/framework/include/core/hdf_device_desc.h

struct HdfDeviceIoClient {
    //指向HDF设备对象结构体的指针
    struct HdfDeviceObject *device;
    //指向客户端的私有数据
    void *priv;
};

1.8 HdfSBuf

The data buffer defined by the HDF driver framework.

1. Official documents

https://device.harmonyos.com/cn/docs/develop/apiref/hdfsbuf-0000001055039516

2. Definition

drivers/framework/ability/sbuf/src/hdf_sbuf.c

1.9 DeviceResourceIface

This structure does not need to be created by the driver developer. It is created by HDF according to the type of device configuration file (see Section 3.2), and it is full of function pointers. The functions pointed to are used to obtain various configuration information of the device. It is the driver The program obtains the entry of device configuration information. Driver developers only need to call the interface function DeviceResourceGetIfaceInstance(see Section 2.8) to obtain the address of this structure, and then obtain the configuration information of the device by calling the function pointed to by the function pointer inside.

1. Official documents

https://device.harmonyos.com/cn/docs/documentation/apiref/deviceresourceiface-0000001054918151

2. Definition

drivers/framework/include/config/device_resource_if.h

3. Function pointers in the structure

（1）GetUint32

int32_t (*GetUint32)(const struct DeviceResourceNode *node, const char *attrName, uint32_t *value, uint32_t def)

nodeRead the value of the attribute (parameter) from a device node (parameter attrName), and save the read value to valuethe variable pointed to by the pointer (parameter); if the value of the specified attribute is not read, save defthe value of the parameter to the pointer (parameter value) in the variable pointed to.

1.10 HdfIoService

This structure is used to represent a driver service object, which can be understood as the interface that the driver exposes to the application through the HDF framework.

1. Official documents

https://device.harmonyos.com/cn/docs/documentation/apiref/hdfioservice-0000001054598161

2. Definition

drivers/framework/include/core/hdf_io_service_if.h:127 

This structure should be generated by HDF and provided to the application program. The most important member is the HdfIoDispatcherpointer to the structure (see Section 1.11). In the application program, call the function HdfIoServiceBind(see Section 2.9), and get HdfIoServicethe pointer to the structure according to the name of the driver service.

1.11 HdfIoDispatcher

There is only one member in this structure: the function pointer Dispatch.

1. Official documents

https://device.harmonyos.com/cn/docs/develop/apiref/hdfiodispatcher-0000001055078139

2. Definition

drivers/framework/include/core/hdf_io_service_if.h:115 

struct HdfIoDispatcher {
    int (*Dispatch)(struct HdfObject *service, int cmdId, struct HdfSBuf *data, struct HdfSBuf *reply);
};

The function pointed to by the pointer here Dispatchdoes not need to be written by the driver developer, but is provided by the HDF framework and can be called by the application program. When calling the function pointed to by the pointer in the application Dispatch, it needs to pass in the following four parameters:

parameter	type	describe
service	Pointer to HdfObjecta structure (see Section 1.6)	The value of this parameter is the address of the first member of HdfIoServiceBindthe structure (see 1.10) obtained by calling the function (see 2.9).HdfIoService
cmdId	integer	The command word sent by the application to the driver.
data	Pointer to HdfSBuf structure (see Section 1.8)	Points to a buffer that is used to store data sent to the driver.
reply	Pointer to HdfSBuf structure (see Section 1.8)	Points to a buffer that holds data received from the driver.

When the function pointed to by the pointer is called in the application program Dispatch, it will eventually cause the function in the driver program Dispatchto be executed.

1.12 HdfDevEventListener

Listeners for driving events.

1. Official documents

https://device.harmonyos.com/cn/docs/develop/apiref/hdfdeveventlistener-0000001055358108

2. Definition

drivers/framework/include/core/hdf_io_service_if.h:99

If you want to listen to the events actively reported by the driver in the application program and process them, you must first define such a structure, and then call the function ( HdfDeviceRegisterEventListenersee Section 2.10) to register it. When the application program monitors the event actively reported by the driver, the onReceivecallback function pointed to by the function pointer will be automatically executed to process the event actively reported by the driver.

onReceiveThe type definition of a function pointer OnDevEventReceiveis as follows:

Developers need to write the callback function pointed to by the function pointer in the application program onReceive. This callback function has 4 incoming parameters:

(1) listener: Pointer to the listener ( HdfDevEventlistenerstructure, see Section 1.12).

(2) service: HdfIoServiceA pointer to a structure (see Section 1.10).

(3) id: The number of the event reported by the driver.

(4) data: point to the buffer of the data received from the driver.

1.13 SubscriberCallback

Callback structure related to driver service subscription.

1. Official documents

https://device.harmonyos.com/cn/docs/documentation/apiref/subscribercallback-0000001055358146

2. Definition

drivers/framework/include/core/hdf_device_desc.h:164

The structure SubscriberCallbackhas two members:

(1) deviceObject: Pointer to the device object structure HdfDeviceObject(see Section 1.2).

(2) OnServiceConnected: Callback function pointer.

int32_t (*OnServiceConnected)(struct HdfDeviceObject *deviceObject, const struct HdfObject *service)

After subscribing to the driver service with a function HdfDeviceSubscribeService(see Section 2.14), when the driver is loaded, the function pointed to by this pointer will be automatically called by HDF. HDF passes in two parameters when calling this function: the first parameter is a pointer to the device object structure HdfDeviceObject(see Section 1.2); the second parameter is a pointer to the driver service entry structure (see Section 1.3).

Next: "API of HDF Driver Framework" (2
)

​