# DriverUtils ## **Overview** Defines common macros and interfaces of the driver module. This module provides interfaces such as log printing, doubly linked list operations, and work queues. **Since:** 1.0 **Version:** 1.0 ## **Summary** ## Files

File Name

Description

hdf_base.h

Declares driver common types, including the enumerated values returned by the function and the macro for obtaining the array size.

hdf_dlist.h

Declares doubly linked list structures and interfaces.

hdf_log.h

Declares log printing functions of the driver module. This module provides functions for printing logs at the verbose, debug, information, warning, and error levels.

hdf_workqueue.h

Declares work queue structures and interfaces.

## Data Structures

Data Structure Name

Description

DListHead

Describes a doubly linked list.

HdfWork

Describes a work item and a delayed work item. This structure defines the work and delayed work items, and then calls the initialization function HdfWorkInit or HdfDelayedWorkInit to perform initialization. The HdfAddWork() function is to add a work item to a work queue immediately, and the HdfAddDelayedWork() function is to add a work item to a work queue after the configured delayed time.

HdfWorkQueue

Describes a work queue.

## Macros

Macro Name and Value

Description

HDF_WAIT_FOREVER 0xFFFFFFFF

Indicates that the function keeps waiting to obtain a semaphore or mutex.

HDF_ARRAY_SIZE (a) (sizeof(a) / sizeof((a)[0]))

Defines the array size.

HDF_KILO_UNIT 1000

Defines a time conversion unit, for example, the unit for converting from second to millisecond.

CONTAINER_OF(ptr, type, member) (type *)((char *)(ptr) - (char *)&((type *)0)->member)

Obtains the address of a structure variable from its member address.

DLIST_FIRST_ENTRY(ptr, type, member) CONTAINER_OF((ptr)->next, type, member)

Obtains the first node of a doubly linked list.

DLIST_LAST_ENTRY(ptr, type, member) CONTAINER_OF((ptr)->prev, type, member)

Obtains the last node of a doubly linked list.

DLIST_FOR_EACH_ENTRY(pos, head, type, member)

Traverses all nodes in a doubly linked list.

DLIST_FOR_EACH_ENTRY_SAFE(pos, tmp, head, type, member)

Traverses all nodes in a doubly linked list. This function is used to delete the nodes pointed to by pos during traversal.

LOG_TAG_MARK_EXTEND(HDF_TAG) #HDF_TAG

  

HDF_LOGV(fmt, arg...) printf("[HDF:V/" LOG_TAG "]" fmt "\r\n", ##arg)

Prints logs at the verbose level.

HDF_LOGD(fmt, arg...) printf("[HDF:D/" LOG_TAG "]" fmt "\r\n", ##arg)

Prints logs at the debug level.

HDF_LOGI(fmt, arg...) printf("[HDF:I/" LOG_TAG "]" fmt "\r\n", ##arg)

Prints logs at the information level.

HDF_LOGW(fmt, arg...) printf("[HDF:W/" LOG_TAG "]" fmt "\r\n", ##arg)

Prints logs at the warning level.

HDF_LOGE(fmt, arg...) printf("[HDF:E/" LOG_TAG "]" fmt "\r\n", ##arg)

Prints logs at the error level.

## Typedefs

Typedef Name

Description

HdfWorkFunc) (void *)

typedef void(*

Describes a work execution function type.

## Enumerations

Enumeration Name

Description

HDF_STATUS { HDF_SUCCESS = 0, HDF_FAILURE = -1, HDF_ERR_NOT_SUPPORT = -2, HDF_ERR_INVALID_PARAM = -3, HDF_ERR_INVALID_OBJECT = -4, HDF_ERR_MALLOC_FAIL = -6, HDF_ERR_TIMEOUT = -7, HDF_ERR_THREAD_CREATE_FAIL = -10, HDF_ERR_QUEUE_FULL = -15, HDF_ERR_DEVICE_BUSY = -16, HDF_ERR_IO = -17, HDF_ERR_BAD_FD = -18, HDF_BSP_ERR_OP = HDF_BSP_ERR_NUM(-1), HDF_ERR_BSP_PLT_API_ERR = HDF_BSP_ERR_NUM(-2), HDF_PAL_ERR_DEV_CREATE = HDF_BSP_ERR_NUM(-3), HDF_PAL_ERR_INNER = HDF_BSP_ERR_NUM(-4), HDF_DEV_ERR_NO_MEMORY = HDF_DEV_ERR_NUM(-1), HDF_DEV_ERR_NO_DEVICE = HDF_DEV_ERR_NUM(-2), HDF_DEV_ERR_NO_DEVICE_SERVICE = HDF_DEV_ERR_NUM(-3), HDF_DEV_ERR_DEV_INIT_FAIL = HDF_DEV_ERR_NUM(-4), HDF_DEV_ERR_PUBLISH_FAIL = HDF_DEV_ERR_NUM(-5), HDF_DEV_ERR_ATTACHDEV_FAIL = HDF_DEV_ERR_NUM(-6), HDF_DEV_ERR_NODATA = HDF_DEV_ERR_NUM(-7), HDF_DEV_ERR_NORANGE = HDF_DEV_ERR_NUM(-8), HDF_DEV_ERR_OP = HDF_DEV_ERR_NUM(-10) }

Enumerates HDF return value types.

{ HDF_WORK_BUSY_PENDING = 1 << 0, HDF_WORK_BUSY_RUNNING = 1 << 1 }

Enumerates statuses of a work item or a delayed work item.

## Functions

Function Name

Description

DListHeadInit (struct DListHead *head)

static void

Initializes a doubly linked list.

DListIsEmpty (const struct DListHead *head)

static bool

Checks whether a doubly linked list is empty.

DListRemove (struct DListHead *entry)

static void

Removes a node from a doubly linked list.

DListInsertHead (struct DListHead *entry, struct DListHead *head)

static void

Inserts a node from the head of a doubly linked list.

DListInsertTail (struct DListHead *entry, struct DListHead *head)

static void

Inserts a node from the tail of a doubly linked list.

DListMerge (struct DListHead *list, struct DListHead *head)

static void

Merges two linked lists by adding the list specified by list to the head of the list specified by head and initializes the merged list.

HdfWorkQueueInit (HdfWorkQueue *queue, char *name)

int32_t

Initializes a work queue.

HdfWorkInit (HdfWork *work, HdfWorkFunc func, void *arg)

int32_t

Initializes a work item.

HdfDelayedWorkInit (HdfWork *work, HdfWorkFunc func, void *arg)

int32_t

Initializes a delayed work item.

HdfWorkDestroy (HdfWork *work)

void

Destroys a work item.

HdfWorkQueueDestroy (HdfWorkQueue *queue)

void

Destroys a work queue.

HdfDelayedWorkDestroy (HdfWork *work)

void

Destroys a delayed work item.

HdfAddWork (HdfWorkQueue *queue, HdfWork *work)

bool

Adds a work item to a work queue.

HdfAddDelayedWork (HdfWorkQueue *queue, HdfWork *work, unsigned long ms)

bool

Adds a delayed work item to a work queue.

HdfWorkBusy (HdfWork *work)

unsigned int

Obtains the status of a work item or delayed work item.

HdfCancelWorkSync (HdfWork *work)

bool

Cancels a work item. This function waits until the work item is complete.

HdfCancelDelayedWorkSync (HdfWork *work)

bool

Cancels a delayed work item.

## **Details** ## **Macro Definition Documentation** ## CONTAINER\_OF ``` #define CONTAINER_OF( ptr, type, member ) (type *)((char *)(ptr) - (char *)&((type *)0)->member) ``` **Description:** Obtains the address of a structure variable from its member address. **Parameters:**

Name

Description
ptr Indicates the structure member address.
type Indicates the structure type.
member Indicates the structure member.
## DLIST\_FIRST\_ENTRY ``` #define DLIST_FIRST_ENTRY( ptr, type, member ) [CONTAINER_OF](driverutils.md#ga818b9cca761fe7bc18e4e417da772976)((ptr)->next, type, member) ``` **Description:** Obtains the first node of a doubly linked list. **Parameters:**

Name

Description
ptr Indicates the structure member address.
type Indicates the structure type.
member Indicates the structure member.
## DLIST\_FOR\_EACH\_ENTRY ``` #define DLIST_FOR_EACH_ENTRY( pos, head, type, member ) ``` ``` Values: for ((pos) = [CONTAINER_OF](driverutils.md#ga818b9cca761fe7bc18e4e417da772976)((head)->next, type, member); \ &(pos)->member != (head); \ (pos) = [CONTAINER_OF](driverutils.md#ga818b9cca761fe7bc18e4e417da772976)((pos)->member.next, type, member)) ``` **Description:** Traverses all nodes in a doubly linked list. **Parameters:**

Name

Description
pos Indicates the pointer to the structure variable.
head Indicates the pointer to the linked list head.
type Indicates the structure type.
member Indicates the member type of the structure.
## DLIST\_FOR\_EACH\_ENTRY\_SAFE ``` #define DLIST_FOR_EACH_ENTRY_SAFE( pos, tmp, head, type, member ) ``` ``` Values: for ((pos) = [CONTAINER_OF](driverutils.md#ga818b9cca761fe7bc18e4e417da772976)((head)->next, type, member), \ (tmp) = [CONTAINER_OF](driverutils.md#ga818b9cca761fe7bc18e4e417da772976)((pos)->member.next, type, member); \ &(pos)->member != (head); \ (pos) = (tmp), (tmp) = [CONTAINER_OF](driverutils.md#ga818b9cca761fe7bc18e4e417da772976)((pos)->member.next, type, member)) ``` **Description:** Traverses all nodes in a doubly linked list. This function is used to delete the nodes pointed to by **pos** during traversal. **Parameters:**

Name

Description
pos Indicates the pointer to the structure variable.
tmp Indicates the pointer to the structure variable, pointing to the next node of pos.
head Indicates the pointer to the linked list head.
type Indicates the structure type.
member Indicates the member type of the structure.
## DLIST\_LAST\_ENTRY ``` #define DLIST_LAST_ENTRY( ptr, type, member ) [CONTAINER_OF](driverutils.md#ga818b9cca761fe7bc18e4e417da772976)((ptr)->prev, type, member) ``` **Description:** Obtains the last node of a doubly linked list. **Parameters:**

Name

Description
ptr Indicates the structure member address.
type Indicates the structure type.
member Indicates the structure member.
## HDF\_LOGD ``` #define HDF_LOGD( fmt, arg... ) [printf](io.md#ga98631211a4a8aee62f572375d5b637be)("[HDF:D/" LOG_TAG "]" fmt "\r\n", ##arg) ``` **Description:** Prints logs at the debug level. To use this function, you must define **HDF\_LOG\_TAG**, for example, \#define HDF\_LOG\_TAG evt. ## HDF\_LOGE ``` #define HDF_LOGE( fmt, arg... ) [printf](io.md#ga98631211a4a8aee62f572375d5b637be)("[HDF:E/" LOG_TAG "]" fmt "\r\n", ##arg) ``` **Description:** Prints logs at the error level. To use this function, you must define **HDF\_LOG\_TAG**, for example, \#define HDF\_LOG\_TAG evt. ## HDF\_LOGI ``` #define HDF_LOGI( fmt, arg... ) [printf](io.md#ga98631211a4a8aee62f572375d5b637be)("[HDF:I/" LOG_TAG "]" fmt "\r\n", ##arg) ``` **Description:** Prints logs at the information level. To use this function, you must define **HDF\_LOG\_TAG**, for example, \#define HDF\_LOG\_TAG evt. ## HDF\_LOGV ``` #define HDF_LOGV( fmt, arg... ) [printf](io.md#ga98631211a4a8aee62f572375d5b637be)("[HDF:V/" LOG_TAG "]" fmt "\r\n", ##arg) ``` **Description:** Prints logs at the verbose level. To use this function, you must define **HDF\_LOG\_TAG**, for example, \#define HDF\_LOG\_TAG evt. ## HDF\_LOGW ``` #define HDF_LOGW( fmt, arg... ) [printf](io.md#ga98631211a4a8aee62f572375d5b637be)("[HDF:W/" LOG_TAG "]" fmt "\r\n", ##arg) ``` **Description:** Prints logs at the warning level. To use this function, you must define **HDF\_LOG\_TAG**, for example, \#define HDF\_LOG\_TAG evt. ## LOG\_TAG\_MARK\_EXTEND ``` #define LOG_TAG_MARK_EXTEND( HDF_TAG) #HDF_TAG ``` **Description:** Add quotation mark ## **Typedef Documentation** ## HdfWorkFunc ``` typedef void(* HdfWorkFunc) (void *) ``` **Description:** Describes a work execution function type. The thread of the work queue executes this function after the work item is added to the work queue. ## **Enumeration Type Documentation** ## anonymous enum ``` anonymous enum ``` **Description:** Enumerates statuses of a work item or a delayed work item.

Enumerator

Description
HDF_WORK_BUSY_PENDING

The work item or delayed work item is pending.

HDF_WORK_BUSY_RUNNING

The work item or delayed work item is running.

## HDF\_STATUS ``` enum [HDF_STATUS](driverutils.md#ga7e01536ecbe9b17563dd3fe256202a67) ``` **Description:** Enumerates HDF return value types.

Enumerator

Description
HDF_SUCCESS

The operation is successful.

HDF_FAILURE

Failed to invoke the OS underlying function.

HDF_ERR_NOT_SUPPORT

Not supported.

HDF_ERR_INVALID_PARAM

Invalid parameter.

HDF_ERR_INVALID_OBJECT

Invalid object.

HDF_ERR_MALLOC_FAIL

Memory allocation fails.

HDF_ERR_TIMEOUT

Timeout occurs.

HDF_ERR_THREAD_CREATE_FAIL

Failed to create a thread.

HDF_ERR_QUEUE_FULL

The queue is full.

HDF_ERR_DEVICE_BUSY

The device is busy.

HDF_ERR_IO

I/O error.

HDF_ERR_BAD_FD

Incorrect file descriptor.

HDF_BSP_ERR_OP

Failed to operate a BSP module.

HDF_ERR_BSP_PLT_API_ERR

The platform API of the BSP module is incorrect.

HDF_PAL_ERR_DEV_CREATE

Failed to create a BSP module device.

HDF_PAL_ERR_INNER

Internal error codes of the BSP module.

HDF_DEV_ERR_NO_MEMORY

Failed to allocate memory to the device module.

HDF_DEV_ERR_NO_DEVICE

The device module has no device.

HDF_DEV_ERR_NO_DEVICE_SERVICE

The device module has no device service.

HDF_DEV_ERR_DEV_INIT_FAIL

Failed to initialize a device module.

HDF_DEV_ERR_PUBLISH_FAIL

The device module failed to release a service.

HDF_DEV_ERR_ATTACHDEV_FAIL

Failed to attach a device to a device module.

HDF_DEV_ERR_NODATA

Failed to read data from a device module.

HDF_DEV_ERR_NORANGE

The device module data is out of range.

HDF_DEV_ERR_OP

Failed to operate a device module.

## **Function Documentation** ## DListHeadInit\(\) ``` static void DListHeadInit (struct [DListHead](dlisthead.md) * head) ``` **Description:** Initializes a doubly linked list. **Parameters:**

Name

Description
head Indicates the pointer to the linked list DListHead. The parameter cannot be empty.
## DListInsertHead\(\) ``` static void DListInsertHead (struct [DListHead](dlisthead.md) * entry, struct [DListHead](dlisthead.md) * head ) ``` **Description:** Inserts a node from the head of a doubly linked list. **Parameters:**

Name

Description
entry Indicates the pointer to the node to insert. For details, see DListHead. The parameter cannot be empty.
head Indicates the pointer to the linked list DListHead. The parameter cannot be empty.
## DListInsertTail\(\) ``` static void DListInsertTail (struct [DListHead](dlisthead.md) * entry, struct [DListHead](dlisthead.md) * head ) ``` **Description:** Inserts a node from the tail of a doubly linked list. **Parameters:**

Name

Description
entry Indicates the pointer to the node to insert. For details, see DListHead. The parameter cannot be empty.
head Indicates the pointer to the linked list DListHead. The parameter cannot be empty.
## DListIsEmpty\(\) ``` static bool DListIsEmpty (const struct [DListHead](dlisthead.md) * head) ``` **Description:** Checks whether a doubly linked list is empty. **Parameters:**

Name

Description
head Indicates the pointer to the linked list DListHead. The parameter cannot be empty.
## DListMerge\(\) ``` static void DListMerge (struct [DListHead](dlisthead.md) * list, struct [DListHead](dlisthead.md) * head ) ``` **Description:** Merges two linked lists by adding the list specified by **list** to the head of the list specified by **head** and initializes the merged list. **Parameters:**

Name

Description
list Indicates the pointer to the linked list DListHead. The parameter cannot be empty.
head Indicates the pointer to the linked list DListHead. The parameter cannot be empty.
## DListRemove\(\) ``` static void DListRemove (struct [DListHead](dlisthead.md) * entry) ``` **Description:** Removes a node from a doubly linked list. **Parameters:**

Name

Description
entry Indicates the pointer to the node to remove. For details, see DListHead. The parameter cannot be empty.
## HdfAddDelayedWork\(\) ``` bool HdfAddDelayedWork ([HdfWorkQueue](hdfworkqueue.md) * queue, [HdfWork](hdfwork.md) * work, unsigned long ms ) ``` **Description:** Adds a delayed work item to a work queue. A delayed work item is added to a work queue after the configured delayed time \(ms\), and the thread of the work queue executes the work function. **Parameters:**

Name

Description
queue Indicates the pointer to the work queue HdfWorkQueue.
work Indicates the pointer to the delayed work item HdfWork.
**Returns:** Returns **true** if the operation is successful; returns **false** otherwise. ## HdfAddWork\(\) ``` bool HdfAddWork ([HdfWorkQueue](hdfworkqueue.md) * queue, [HdfWork](hdfwork.md) * work ) ``` **Description:** Adds a work item to a work queue. After a work item is added to a work queue, the thread of the work queue executes the function of the work item. **Parameters:**

Name

Description
queue Indicates the pointer to the work queue HdfWorkQueue.
work Indicates the pointer to the work item HdfWork.
**Returns:** Returns **true** if the operation is successful; returns **false** otherwise. ## HdfCancelDelayedWorkSync\(\) ``` bool HdfCancelDelayedWorkSync ([HdfWork](hdfwork.md) * work) ``` **Description:** Cancels a delayed work item. **Parameters:**

Name

Description
work Indicates the pointer to the delayed work item HdfWork.
**Returns:** Returns **true** if the operation is successful; returns **false** otherwise. ## HdfCancelWorkSync\(\) ``` bool HdfCancelWorkSync ([HdfWork](hdfwork.md) * work) ``` **Description:** Cancels a work item. This function waits until the work item is complete. **Parameters:**

Name

Description
work Indicates the pointer to the work item HdfWork.
**Returns:** Returns **true** if the operation is successful; returns **false** otherwise. ## HdfDelayedWorkDestroy\(\) ``` void HdfDelayedWorkDestroy ([HdfWork](hdfwork.md) * work) ``` **Description:** Destroys a delayed work item. **Parameters:**

Name

Description
work Indicates the pointer to the delayed work item HdfWork.
## HdfDelayedWorkInit\(\) ``` int32_t HdfDelayedWorkInit ([HdfWork](hdfwork.md) * work, [HdfWorkFunc](driverutils.md#ga30665d61b03fae4a2ebc778c3d775ce5) func, void * arg ) ``` **Description:** Initializes a delayed work item. This function uses **func** and **arg** to initialize a work item. The work item is added to a work queue after the configured delayed time. The thread of the work queue executes this function, and **arg** is passed to **func**. **Parameters:**

Name

Description
work Indicates the pointer to the delayed work item HdfWork.
func Indicates the work execution function.
arg Indicates the pointer to the argument of the work execution function.
**Returns:** Returns a value listed below:

HDF_STATUS

Description

HDF_SUCCESS

The operation is successful.

HDF_ERR_INVALID_PARAM

Invalid parameter.

HDF_ERR_MALLOC_FAIL

Memory allocation fails.

## HdfWorkBusy\(\) ``` unsigned int HdfWorkBusy ([HdfWork](hdfwork.md) * work) ``` **Description:** Obtains the status of a work item or delayed work item. **Parameters:**

Name

Description
work Indicates the pointer to the work item or delayed work item HdfWork.
**Returns:** Returns **HDF\_WORK\_BUSY\_PENDING** if the work item is pending; returns **HDF\_WORK\_BUSY\_RUNNING** if the work item is running. ## HdfWorkDestroy\(\) ``` void HdfWorkDestroy ([HdfWork](hdfwork.md) * work) ``` **Description:** Destroys a work item. **Parameters:**

Name

Description
work Indicates the pointer to the work item HdfWork.
## HdfWorkInit\(\) ``` int32_t HdfWorkInit ([HdfWork](hdfwork.md) * work, [HdfWorkFunc](driverutils.md#ga30665d61b03fae4a2ebc778c3d775ce5) func, void * arg ) ``` **Description:** Initializes a work item. This function uses **func** and **arg** to initialize a work item. After the work item is added to a work queue, the thread of the work queue executes this function, and **arg** is passed to **func**. **Parameters:**

Name

Description
work Indicates the pointer to the work item HdfWork.
func Indicates the work execution function.
arg Indicates the pointer to the argument of the work execution function.
**Returns:** Returns a value listed below:

HDF_STATUS

Description

HDF_SUCCESS

The operation is successful.

HDF_ERR_INVALID_PARAM

Invalid parameter.

HDF_ERR_MALLOC_FAIL

Memory allocation fails.

## HdfWorkQueueDestroy\(\) ``` void HdfWorkQueueDestroy ([HdfWorkQueue](hdfworkqueue.md) * queue) ``` **Description:** Destroys a work queue. **Parameters:**

Name

Description
queue Indicates the pointer to the work queue HdfWorkQueue.
## HdfWorkQueueInit\(\) ``` int32_t HdfWorkQueueInit ([HdfWorkQueue](hdfworkqueue.md) * queue, char * name ) ``` **Description:** Initializes a work queue. When a work queue is initialized, a thread is created. The thread cyclically executes the work items in the work queue, that is, executes their functions. **Parameters:**

Name

Description
queue Indicates the pointer to the work queue OsalWorkQueue.
name Indicates the pointer to the work queue name.
**Returns:** Returns a value listed below:

HDF_STATUS

Description

HDF_SUCCESS

The operation is successful.

HDF_ERR_INVALID_PARAM

Invalid parameter.

HDF_ERR_MALLOC_FAIL

Memory allocation fails.