openmv/lib/alif/Alif_CMSIS/Include/Driver_HWSEM.h
iabdalkader daf2bb30da misc: Restructure repo.
Signed-off-by: iabdalkader <i.abdalkader@gmail.com>
2025-04-13 08:28:34 +02:00

138 lines
5.7 KiB
C

/* Copyright (C) 2022 Alif Semiconductor - All Rights Reserved.
* Use, distribution and modification of this code is permitted under the
* terms stated in the Alif Semiconductor Software License Agreement
*
* You should have received a copy of the Alif Semiconductor Software
* License Agreement with this file. If not, please write to:
* contact@alifsemi.com, or visit: https://alifsemi.com/license
*
*/
/**************************************************************************//**
* @file Driver_HWSEM.h
* @author Khushboo Singh
* @email khushboo.singh@alifsemi.com
* @version V1.0.0
* @date 16-June-2022
* @brief Header file for hardware semaphore driver.
******************************************************************************/
#ifndef DRIVER_HWSEM_H_
#define DRIVER_HWSEM_H_
/* Driver Includes */
#include "Driver_Common.h"
#ifdef __cplusplus
extern "C"
{
#endif
#define ARM_HWSEM_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(1, 0) /* API version */
#define _ARM_Driver_HWSEM_(n) DRIVER_HWSEM##n
#define ARM_Driver_HWSEM_(n) _ARM_Driver_HWSEM_(n)
/* HWSEM Event */
#define HWSEM_AVAILABLE_CB_EVENT (1U << 0) ///< HWSEM Available
// Function Documentation
/**
\fn ARM_DRIVER_VERSION ARM_HWSEM_GetVersion(void)
\brief Returns the Driver Version
\param[in] void
\return ARM_DRIVER_VERSION : Driver version
*/
/**
\fn ARM_HWSEM_CAPABILITIES ARM_HWSEM_GetCapabilities(void)
\brief Returns the Driver Capabilities
\param[in] void
\return ARM_HWSEM_CAPABILITIES : Driver Capabilities
*/
/**
\fn int32_t ARM_HWSEM_Initialize(ARM_HWSEM_SignalEvent_t cb_event)
\brief Initializes the driver instance with a call back function. The
(optional) callback function will be invoked (with HWSEM_AVAILABLE_CB_EVENT)
when the hwsem instance becomes available again after an unsuccessful
TryLock attempt.
\param[in] cb_event : Optional call back function provided by the user.
\return ARM_DRIVER_OK : On successful initialization.
\ ARM_DRIVER_ERROR_BUSY : Driver has already been initialized.
*/
/**
\fn int32_t ARM_HWSEM_Uninitialize(void)
\brief Uninitializes the driver instance.
\return ARM_DRIVER_OK : On success.
\ ARM_DRIVER_ERROR : If the driver instance has not been initialized before.
*/
/**
\fn int32_t ARM_HWSEM_Lock(void)
\brief Acquire the hw semaphore. If the semaphore is not available, spin until
it becomes available.
\return ARM_DRIVER_OK : If the hwsem is acquired successfully.
\ ARM_DRIVER_ERROR : If the driver is not initialized.
*/
/**
\fn int32_t ARM_HWSEM_TryLock(void)
\brief Try to acquire the hw semaphore. If the semaphore is not available, return an error
code indicating the lock is busy.
\return ARM_DRIVER_OK : If the semaphore is acquired successfully.
\ ARM_DRIVER_ERROR_BUSY : If the semaphore is not available.
\ ARM_DRIVER_ERROR : If the driver is not initialized.
*/
/**
\fn int32_t ARM_HWSEM_Unlock(void)
\brief Release the hw semaphore
\return ARM_DRIVER_OK : On a successful unlock.
\ ARM_DRIVER_ERROR : If the driver is not initialized or the hwsem
has not been locked before.
*/
/**
\fn int32_t ARM_HWSEM_GetCount(void)
\brief Get the semaphore lock count.
\return The current lock count of the semaphore instance.
\ ARM_DRIVER_ERROR : if driver is not initialized
*/
/**
\fn void ARM_HWSEM_SignalEvent(int32_t event, uint8_t sem_id)
\brief Callback function that signals an HW semaphore event.
\param[in] event event notification mask
\return none
*/
typedef void (*ARM_HWSEM_SignalEvent_t) (int32_t event, uint8_t sem_id);
/**
\brief HW Semaphore Device Driver Capabilities.
*/
typedef struct _ARM_HWSEM_CAPABILITIES {
uint32_t event_device_available : 1; ///< supports HWSEM Event Callback
uint32_t reserved : 31; ///< Reserved (must be zero)
} ARM_HWSEM_CAPABILITIES;
/**
\brief Access structure of the Hardware Semaphore Driver
*/
typedef struct _ARM_DRIVER_HWSEM {
ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_HWSEM_GetVersion : Get driver version.
ARM_HWSEM_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_HWSEM_GetCapabilities : Get driver capabilities.
int32_t (*Initialize) (ARM_HWSEM_SignalEvent_t cb_event); ///< Pointer to \ref ARM_HWSEM_Initialize : Initialize HW semaphore Device.
int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_HWSEM_Uninitialize : De-initialize HW Semaphore Device.
int32_t (*Lock) (void); ///< Pointer to \ref ARM_HWSEM_Lock : Spin until the semaphore is successfully locked.
int32_t (*TryLock) (void); ///< Pointer to \ref ARM_HWSEM_TryLock : Try to lock the semaphore.
int32_t (*Unlock) (void); ///< Pointer to \ref ARM_HWSEM_Unlock : Unlock the semaphore.
int32_t (*GetCount) (void); ///< Pointer to \ref ARM_HWSEM_GetCount : Get the semaphore lock count.
}const ARM_DRIVER_HWSEM;
#ifdef __cplusplus
}
#endif
#endif /* DRIVER_HWSEM_H_ */