Thread HAL

Updated at:

This topic describes the interfaces for the Thread Hardware Abstraction Layer (HAL).

HAL_MutexCreate

  • Prototype
    void *HAL_MutexCreate(void);
  • Description Creates a mutex object for synchronized access. For single-threaded applications, this function can be an empty function.
  • Parameters This function has no input parameters.
  • Response description: This operation returns no parameters.

HAL_MutexDestroy

  • Prototype
    void HAL_MutexDestroy(_IN_ void *mutex);
  • Description Destroys a mutex object to release its associated resources.
  • Parameters
    ParameterData typeDirectionDescription
    mutexvoid *InputA pointer to the mutex.
  • Return values This function has no return values.

HAL_MutexLock

  • Prototype
    void HAL_MutexLock(_IN_ void *mutex);      
  • Description Locks a mutex.
  • Parameters
    ParameterData typeDirectionDescription
    mutexvoid *InputA pointer to the mutex.
  • Return values This function has no return values.

HAL_MutexUnlock

  • Prototype
    void HAL_MutexUnlock(_IN_ void *mutex);     
  • Description Unlocks a mutex.
  • Parameters
    ParameterData typeDirectionDescription
    mutexvoid *InputA pointer to the mutex.
  • Return values This function has no return values.

HAL_SemaphoreCreate

  • Prototype
    void *HAL_SemaphoreCreate(void); 
  • Description Creates a counting semaphore. The implementation of this function must be an atomic operation. For single-threaded applications, this function can be an empty function.
  • Parameters This function has no input parameters.
  • Return values
    ResultDescription
    NULLCreation failed.
    Not NULLThe semaphore was created. The handle of the semaphore is returned.

HAL_SemaphoreDestroy

  • Prototype
    void HAL_SemaphoreDestroy(_IN_ void *sem);
  • Description Destroys the semaphore specified by the sem parameter. The implementation of this function must be an atomic operation.
  • Parameters
    ParameterData typeDirectionDescription
    semvoid *InputA pointer to the semaphore.
  • Return values This function has no return values.

HAL_SemaphorePost

  • Prototype
    void HAL_SemaphorePost(_IN_ void *sem);
  • Description Performs an auto-increment operation on the specified counting semaphore to unblock other waiting threads. The implementation of this function must be an atomic operation. For single-threaded applications, this function can be an empty function.
  • Parameters
    ParameterData typeDirectionDescription
    semvoid *InputThe handle of the semaphore.
  • Return values This function has no return values.

HAL_SemaphoreWait

  • Prototype
    int HAL_SemaphoreWait(_IN_ void *sem, _IN_ uint32_t timeout_ms);
  • Description Waits on the specified counting semaphore and performs a decrement operation. The implementation of this function must be an atomic operation. For single-threaded applications, this function can be an empty function.
  • Parameters
    ParameterData typeDirectionDescription
    semvoid *InputThe handle of the semaphore.
    timeout_msuint32_tInputThe timeout period for waiting on the semaphore, in milliseconds.
    Note If you set this parameter to PLATFORM_WAIT_INFINITE, the function returns only when the semaphore is acquired and never times out.
  • Return values
    Return ValueDescription
    0The function returns because the semaphore is triggered.
    -1The function returns because the operation times out.

HAL_ThreadCreate

  • Prototype
    int HAL_ThreadCreate(
                _OU_ void **thread_handle,
                _IN_ void *(*work_routine)(void *),
                _IN_ void *arg,
                _IN_ hal_os_thread_param_t *hal_os_thread_param,
                _OU_ int *stack_used);
  • Description Creates a thread with the specified input parameters.
  • Parameters
    ParameterData typeDirectionDescription
    thread_handlevoid **OutputA pointer to the thread handle variable.
    work_routinevoid *(*work_routine)(void *)InputA pointer to the function that the thread executes.
    argvoid *InputA single parameter passed to the running program.
    hal_os_thread_paramhal_os_thread_param_t *InputA pointer to the thread initialization parameters.
    stack_usedint *OutputIndicates whether the platform uses the stack buffer.
    • 0: Unused
    • Use
    The thread initialization parameters are defined as follows:
    typedef struct _hal_os_thread {
        hal_os_thread_priority_t priority;     /* The initial priority of the thread. */
        void                    *stack_addr;   /* The thread stack address allocated by the caller. If this parameter is empty, the system stack is used. */
        size_t                   stack_size;   /* The required stack size in bytes. A value of 0 specifies the default stack size. */
        int                      detach_state; /* The detached state. 0: not detached. Other values: detached. */
        char                    *name;         /* The name of the thread. */
    } hal_os_thread_param_t;
    The thread priorities are defined as follows:
    typedef enum {
        os_thread_priority_idle = -3,        /* Priority: idle (lowest) */
        os_thread_priority_low = -2,         /* Priority: low */
        os_thread_priority_belowNormal = -1, /* Priority: below normal */
        os_thread_priority_normal = 0,       /* Priority: normal (default) */
        os_thread_priority_aboveNormal = 1,  /* Priority: above normal */
        os_thread_priority_high = 2,         /* Priority: high */
        os_thread_priority_realtime = 3,     /* Priority: real-time (highest) */
        os_thread_priority_error = 0x84,     /* The system cannot determine the priority or the thread has an illegal priority. */
    } hal_os_thread_priority_t;
  • Return values
    Return valueDescription
    -1Creation failed.
    0The resource was created successfully.

HAL_ThreadDelete

  • Prototype
    void HAL_ThreadDelete(_IN_ void *thread_handle);
  • Description Deletes the specified thread.
  • Parameters
    ParameterData typeDirectionDescription
    thread_handlevoid *InputThe handle of the thread. A value of NULL specifies the current thread.
  • Return values This function has no return values.

HAL_ThreadDetach

  • Prototype
    void HAL_ThreadDetach(_IN_ void *thread_handle);
  • Description Sets the specified thread to the detached state.
  • Parameters
    ParameterData typeDirectionDescription
    thread_handlevoid *InputThe handle of the thread. A value of NULL specifies the current thread.
  • Return values This function has no return values.