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 DListHeadhead)

static void 

Initializes a doubly linked list.

DListIsEmpty (const struct DListHead head)

static bool 

Checks whether a doubly linked list is empty.

DListRemove (struct DListHeadentry)

static void 

Removes a node from a doubly linked list.

DListInsertHead (struct DListHeadentry, struct DListHeadhead)

static void 

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

DListInsertTail (struct DListHeadentry, struct DListHeadhead)

static void 

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

DListMerge (struct DListHead list, struct DListHeadhead)

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 (HdfWorkQueuequeue)

void 

Destroys a work queue.

HdfDelayedWorkDestroy (HdfWork work)

void 

Destroys a delayed work item.

HdfAddWork (HdfWorkQueuequeue, HdfWorkwork)

bool 

Adds a work item to a work queue.

HdfAddDelayedWork (HdfWorkQueuequeue, HdfWorkwork, unsigned long ms)

bool 

Adds a delayed work item to a work queue.

HdfWorkBusy (HdfWorkwork)

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

  1. #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

ptrIndicates the structure member address.
typeIndicates the structure type.
memberIndicates the structure member.

DLIST_FIRST_ENTRY

  1. #define DLIST_FIRST_ENTRY( ptr, type, member )[CONTAINER_OF]($api-api-SmartVision-Devices-DriverUtils.md#ga818b9cca761fe7bc18e4e417da772976)((ptr)->next, type, member)

Description:

Obtains the first node of a doubly linked list.

Parameters:

Name

Description

ptrIndicates the structure member address.
typeIndicates the structure type.
memberIndicates the structure member.

DLIST_FOR_EACH_ENTRY

  1. #define DLIST_FOR_EACH_ENTRY( pos, head, type, member )
  1. Values:for((pos)=[CONTAINER_OF]($api-api-SmartVision-Devices-DriverUtils.md#ga818b9cca761fe7bc18e4e417da772976)((head)->next, type, member); \
  2. &(pos)->member !=(head); \
  3. (pos)=[CONTAINER_OF]($api-api-SmartVision-Devices-DriverUtils.md#ga818b9cca761fe7bc18e4e417da772976)((pos)->member.next, type, member))

Description:

Traverses all nodes in a doubly linked list.

Parameters:

Name

Description

posIndicates the pointer to the structure variable.
headIndicates the pointer to the linked list head.
typeIndicates the structure type.
memberIndicates the member type of the structure.

DLIST_FOR_EACH_ENTRY_SAFE

  1. #define DLIST_FOR_EACH_ENTRY_SAFE( pos, tmp, head, type, member )
  1. Values:for((pos)=[CONTAINER_OF]($api-api-SmartVision-Devices-DriverUtils.md#ga818b9cca761fe7bc18e4e417da772976)((head)->next, type, member), \
  2. (tmp)=[CONTAINER_OF]($api-api-SmartVision-Devices-DriverUtils.md#ga818b9cca761fe7bc18e4e417da772976)((pos)->member.next, type, member); \
  3. &(pos)->member !=(head); \
  4. (pos)=(tmp),(tmp)=[CONTAINER_OF]($api-api-SmartVision-Devices-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

posIndicates the pointer to the structure variable.
tmpIndicates the pointer to the structure variable, pointing to the next node of pos.
headIndicates the pointer to the linked list head.
typeIndicates the structure type.
memberIndicates the member type of the structure.

DLIST_LAST_ENTRY

  1. #define DLIST_LAST_ENTRY( ptr, type, member )[CONTAINER_OF]($api-api-SmartVision-Devices-DriverUtils.md#ga818b9cca761fe7bc18e4e417da772976)((ptr)->prev, type, member)

Description:

Obtains the last node of a doubly linked list.

Parameters:

Name

Description

ptrIndicates the structure member address.
typeIndicates the structure type.
memberIndicates the structure member.

HDF_LOGD

  1. #define HDF_LOGD( fmt, arg...)[printf]($api-api-SmartVision-Devices-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

  1. #define HDF_LOGE( fmt, arg...)[printf]($api-api-SmartVision-Devices-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

  1. #define HDF_LOGI( fmt, arg...)[printf]($api-api-SmartVision-Devices-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

  1. #define HDF_LOGV( fmt, arg...)[printf]($api-api-SmartVision-Devices-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

  1. #define HDF_LOGW( fmt, arg...)[printf]($api-api-SmartVision-Devices-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

  1. #define LOG_TAG_MARK_EXTEND( HDF_TAG)#HDF_TAG

Description:

Add quotation mark

Typedef Documentation

HdfWorkFunc

  1. typedefvoid(*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

  1. 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

  1. enum[HDF_STATUS]($api-api-SmartVision-Devices-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()

  1. staticvoidDListHeadInit(struct[DListHead]($api-api-SmartVision-Devices-DListHead.md)* head)

Description:

Initializes a doubly linked list.

Parameters:

Name

Description

headIndicates the pointer to the linked list DListHead. The parameter cannot be empty.

DListInsertHead()

  1. staticvoidDListInsertHead(struct[DListHead]($api-api-SmartVision-Devices-DListHead.md)* entry,struct[DListHead]($api-api-SmartVision-Devices-DListHead.md)* head )

Description:

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

Parameters:

Name

Description

entryIndicates the pointer to the node to insert. For details, see DListHead. The parameter cannot be empty.
headIndicates the pointer to the linked list DListHead. The parameter cannot be empty.

DListInsertTail()

  1. staticvoidDListInsertTail(struct[DListHead]($api-api-SmartVision-Devices-DListHead.md)* entry,struct[DListHead]($api-api-SmartVision-Devices-DListHead.md)* head )

Description:

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

Parameters:

Name

Description

entryIndicates the pointer to the node to insert. For details, see DListHead. The parameter cannot be empty.
headIndicates the pointer to the linked list DListHead. The parameter cannot be empty.

DListIsEmpty()

  1. staticboolDListIsEmpty(conststruct[DListHead]($api-api-SmartVision-Devices-DListHead.md)* head)

Description:

Checks whether a doubly linked list is empty.

Parameters:

Name

Description

headIndicates the pointer to the linked list DListHead. The parameter cannot be empty.

DListMerge()

  1. staticvoidDListMerge(struct[DListHead]($api-api-SmartVision-Devices-DListHead.md)* list,struct[DListHead]($api-api-SmartVision-Devices-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

listIndicates the pointer to the linked list DListHead. The parameter cannot be empty.
headIndicates the pointer to the linked list DListHead. The parameter cannot be empty.

DListRemove()

  1. staticvoidDListRemove(struct[DListHead]($api-api-SmartVision-Devices-DListHead.md)* entry)

Description:

Removes a node from a doubly linked list.

Parameters:

Name

Description

entryIndicates the pointer to the node to remove. For details, see DListHead. The parameter cannot be empty.

HdfAddDelayedWork()

  1. boolHdfAddDelayedWork([HdfWorkQueue]($api-api-SmartVision-Devices-HdfWorkQueue.md)* queue,[HdfWork]($api-api-SmartVision-Devices-HdfWork.md)* work,unsignedlong 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

queueIndicates the pointer to the work queue HdfWorkQueue.
workIndicates the pointer to the delayed work item HdfWork.

Returns:

Returns true if the operation is successful; returns false otherwise.

HdfAddWork()

  1. boolHdfAddWork([HdfWorkQueue]($api-api-SmartVision-Devices-HdfWorkQueue.md)* queue,[HdfWork]($api-api-SmartVision-Devices-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

queueIndicates the pointer to the work queue HdfWorkQueue.
workIndicates the pointer to the work item HdfWork.

Returns:

Returns true if the operation is successful; returns false otherwise.

HdfCancelDelayedWorkSync()

  1. boolHdfCancelDelayedWorkSync([HdfWork]($api-api-SmartVision-Devices-HdfWork.md)* work)

Description:

Cancels a delayed work item.

Parameters:

Name

Description

workIndicates the pointer to the delayed work item HdfWork.

Returns:

Returns true if the operation is successful; returns false otherwise.

HdfCancelWorkSync()

  1. boolHdfCancelWorkSync([HdfWork]($api-api-SmartVision-Devices-HdfWork.md)* work)

Description:

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

Parameters:

Name

Description

workIndicates the pointer to the work item HdfWork.

Returns:

Returns true if the operation is successful; returns false otherwise.

HdfDelayedWorkDestroy()

  1. voidHdfDelayedWorkDestroy([HdfWork]($api-api-SmartVision-Devices-HdfWork.md)* work)

Description:

Destroys a delayed work item.

Parameters:

Name

Description

workIndicates the pointer to the delayed work item HdfWork.

HdfDelayedWorkInit()

  1. int32_tHdfDelayedWorkInit([HdfWork]($api-api-SmartVision-Devices-HdfWork.md)* work,[HdfWorkFunc]($api-api-SmartVision-Devices-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

workIndicates the pointer to the delayed work item HdfWork.
funcIndicates the work execution function.
argIndicates 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()

  1. unsignedintHdfWorkBusy([HdfWork]($api-api-SmartVision-Devices-HdfWork.md)* work)

Description:

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

Parameters:

Name

Description

workIndicates 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()

  1. voidHdfWorkDestroy([HdfWork]($api-api-SmartVision-Devices-HdfWork.md)* work)

Description:

Destroys a work item.

Parameters:

Name

Description

workIndicates the pointer to the work item HdfWork.

HdfWorkInit()

  1. int32_tHdfWorkInit([HdfWork]($api-api-SmartVision-Devices-HdfWork.md)* work,[HdfWorkFunc]($api-api-SmartVision-Devices-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

workIndicates the pointer to the work item HdfWork.
funcIndicates the work execution function.
argIndicates 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()

  1. voidHdfWorkQueueDestroy([HdfWorkQueue]($api-api-SmartVision-Devices-HdfWorkQueue.md)* queue)

Description:

Destroys a work queue.

Parameters:

Name

Description

queueIndicates the pointer to the work queue HdfWorkQueue.

HdfWorkQueueInit()

  1. int32_tHdfWorkQueueInit([HdfWorkQueue]($api-api-SmartVision-Devices-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

queueIndicates the pointer to the work queue OsalWorkQueue.
nameIndicates 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.