diff options
Diffstat (limited to 'drivers/staging/nmf-cm/cm/engine/os_adaptation_layer/inc/os_adaptation_layer.h')
| -rw-r--r-- | drivers/staging/nmf-cm/cm/engine/os_adaptation_layer/inc/os_adaptation_layer.h | 498 |
1 files changed, 498 insertions, 0 deletions
diff --git a/drivers/staging/nmf-cm/cm/engine/os_adaptation_layer/inc/os_adaptation_layer.h b/drivers/staging/nmf-cm/cm/engine/os_adaptation_layer/inc/os_adaptation_layer.h new file mode 100644 index 00000000000..c9ec864795f --- /dev/null +++ b/drivers/staging/nmf-cm/cm/engine/os_adaptation_layer/inc/os_adaptation_layer.h @@ -0,0 +1,498 @@ +/* + * Copyright (C) ST-Ericsson SA 2010 + * Author: Jean-Philippe FASSINO <jean-philippe.fassino@stericsson.com> for ST-Ericsson. + * License terms: GNU General Public License (GPL) version 2. + */ +/*! + * \brief OS Adaptation Layer API + * + * \defgroup CM_ENGINE_OSAL_API CM Engine OSAL (Operating System Abstraction Layer) API + * \ingroup CM_ENGINE_MODULE + */ +#ifndef __INC_CM_OSAL_H +#define __INC_CM_OSAL_H + +#include <cm/inc/cm_type.h> +#include <cm/engine/communication/inc/communication_type.h> +#include <cm/engine/component/inc/instance.h> + +/*! + * \brief Identifier of a trace channel (id in [0..255]) + * \ingroup CM_ENGINE_OSAL_API + */ +typedef t_uint8 t_nmf_trace_channel; + +/*! + * \brief Identifier of lock create by OSAL + * \ingroup CM_ENGINE_OSAL_API + */ +typedef t_uint32 t_nmf_osal_sync_handle; + +/*! + * \brief Identifier of semaphore create by OSAL + * \ingroup CM_ENGINE_OSAL_API + */ +typedef t_uint32 t_nmf_osal_sem_handle; + +/*! + * \brief Identifier of semaphore wait error return by semaphore OSAL API + * \ingroup CM_ENGINE_OSAL_API + */ +typedef t_uint8 t_nmf_osal_sync_error; +#define SYNC_ERROR_TIMEOUT ((t_nmf_osal_sync_error)-1) +#define SYNC_OK ((t_nmf_osal_sync_error)0) +#define SEM_TIMEOUT_NORMAL 3000 +#define SEM_TIMEOUT_DEBUG 300000 + +/*! + * \brief Operations used to support additionnal OS-specific debug feature + * \ingroup CM_ENGINE_OSAL_API + */ +struct osal_debug_operations { + void (*component_create)(t_component_instance *component); + void (*component_destroy)(t_component_instance *component); + void (*domain_create)(t_cm_domain_id id); + void (*domain_destroy)(t_cm_domain_id id); +}; + +extern struct osal_debug_operations osal_debug_ops; + +/*! + * \brief Description of the Scheduling part of the OS Adaptation Layer + * + * <B>Goal:</B> Support of uplink communication path (from Media Processors to Host (ARM)) + * + * Post a function call outside of Host CPU Interrupt mode in order to minimize ISR execution time + * \param[in] upLayerTHIS : this one provided by user when calling CM_ENGINE_BindComponentToCMCore() (first field of the interface context) \n + * \param[in] methodIndex : index method to be called \n + * \param[in] anyPtr : internal NMF marshaled parameters block (to be passed as second parameter when calling the previous pSkeleton method) \n + * \param[in] ptrSize : size of anyPtr in bytes \n + * + * Called by: + * - CM_ProcessMpcEvent() call (shall be bound by OS integrator to HSEM IRQ) + * + * \ingroup CM_ENGINE_OSAL_API + */ + +PUBLIC void OSAL_PostDfc( + t_nmf_mpc2host_handle upLayerTHIS, + t_uint32 methodIndex, + t_event_params_handle anyPtr, + t_uint32 ptrSize); + + +/*! + * \brief Description of the Synchronization part of the OS Adaptation Layer + * + * <B>Goal:</B> Use by CM to protect global variable against multiple call. Interrupt and scheduler function are use when + * we take hardware/local semaphore. Scheduler lock functions can have empty implementation but this may + * impact performance (dsp waiting semaphore because host thread was preempted whereas it has already take semaphore + * but not yet release it). + * + * \return handle of the Mutex created + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC t_nmf_osal_sync_handle OSAL_CreateLock(void); + +/*! + * \brief Description of the Synchronization part of the OS Adaptation Layer + * + * <B>Goal:</B> Use by CM to protect global variable against multiple call. Interrupt and scheduler function are use when + * we take hardware/local semaphore. Scheduler lock functions can have empty implementation but this may + * impact performance (dsp waiting semaphore because host thread was preempted whereas it has already take semaphore + * but not yet release it). + * + * \param[in] handle handle of the Mutex to be locked + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_Lock( + t_nmf_osal_sync_handle handle); + +/*! + * \brief Description of the Synchronization part of the OS Adaptation Layer + * + * <B>Goal:</B> Use by CM to protect global variable against multiple call. Interrupt and scheduler function are use when + * we take hardware/local semaphore. Scheduler lock functions can have empty implementation but this may + * impact performance (dsp waiting semaphore because host thread was preempted whereas it has already take semaphore + * but not yet release it). + * + * \param[in] handle handle of the Mutex to be unlocked + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_Unlock( + t_nmf_osal_sync_handle handle); + +/*! + * \brief Description of the Synchronization part of the OS Adaptation Layer + * + * <B>Goal:</B> Use by CM to protect global variable against multiple call. Interrupt and scheduler function are use when + * we take hardware/local semaphore. Scheduler lock functions can have empty implementation but this may + * impact performance (dsp waiting semaphore because host thread was preempted whereas it has already take semaphore + * but not yet release it). + * + * \param[in] handle handle of the Mutex to be destroyed + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_DestroyLock( + t_nmf_osal_sync_handle handle); + +/*! + * \brief Description of the Synchronization part of the OS Adaptation Layer + * + * <B>Goal:</B> Use by CM to allow to synchronize with code running on mpc side. + * + * \param[in] value : Initial value of semaphore. + * + * \return handle of the Semaphore created + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC t_nmf_osal_sem_handle OSAL_CreateSemaphore( + t_uint32 value); + +/*! + * \brief Description of the Synchronization part of the OS Adaptation Layer + * + * <B>Goal:</B> Use by CM to allow to synchronize with code running on mpc side. This function can be call under + * Irq context by CM. + * + * \param[in] handle handle of the Semaphore for which we increase value and so potentially wake up thread. + * + * \param[in] aCtx is a hint to indicate to os that we are in a none normal context (e.g under interruption). + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_SemaphorePost( + t_nmf_osal_sem_handle handle, + t_uint8 aCtx); + +/*! + * \brief Description of the Synchronization part of the OS Adaptation Layer + * + * <B>Goal:</B> Use by CM to allow to synchronize with code running on mpc side. + * + * \param[in] handle of the Semaphore for which we decrease value and so potentially block current thread. + * + * \param[in] timeOutInMs maximun time in ms after which the block thread is wake up. In this case function return SYNC_ERROR_TIMEOUT value. + * + * \return error number: SYNC_ERROR_TIMEOUT in case semaphore is not release withing timeOutInMs. + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC t_nmf_osal_sync_error OSAL_SemaphoreWaitTimed( + t_nmf_osal_sem_handle handle, + t_uint32 timeOutInMs); + +/*! + * \brief Description of the Synchronization part of the OS Adaptation Layer + * + * <B>Goal:</B> Use by CM to allow to synchronize with code running on mpc side. + * + * \param[in] handle handle of the Semaphore to be destroyed + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_DestroySemaphore( + t_nmf_osal_sem_handle handle); + +/*! + * \brief Description of the System Memory Allocator part of the OS Adaptation Layer + * + * <B>Goal:</B> Allocate CM some cacheable and bufferable memory (SDRAM) for internal usage \n + * This memory will be accessed only by Host CPU (ARM) + * + * This function provide a simple, general-purpose memory allocation. The + * OSAL_Alloc macro returns a pointer to a block of at least size bytes + * suitably aligned for any use. If there is no available memory, this + * function returns a null pointer. + * + * \param[in] size size in bytes, of memory to be allocated + * \return pointer on the beginning of the allocated memory + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void* OSAL_Alloc( + t_cm_size size); + +/*! + * \brief Description of the System Memory Allocator part of the OS Adaptation Layer with memory set to zero + * + * Compare to \see OSAL_Alloc, same allocation is done but memory is set with zero before returning. + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void* OSAL_Alloc_Zero( + t_cm_size size); + +/*! + * \brief Description of the System Memory Allocator part of the OS Adaptation Layer + * + * <B>Goal:</B> Free CM some cacheable and bufferable memory (SDRAM) for internal usage \n + * This memory will be accessed only by Host CPU (ARM) + * + * \param[in] pHandle pointer on the begining of the memory previously allocated + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_Free( + void *pHandle); + +/*! + * \brief Clean data cache in DDR in order to be accessible from peripheral. + * + * This method must be synchronized with MMDSP Code cache attribute. + * Strongly Ordered -> nothing + * Shared device -> dsb + L2 Write buffer drain + * Non cacheable, Bufferable -> dsb + L2 Write buffer drain + * WT or WB -> Flush cache range + dsb + L2 Write buffer drain + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_CleanDCache( + t_uint32 startAddr, //!< [in] Start data address of range to clean + t_uint32 Size //!< [in] Size of range to clean + ); + +/*! + * \brief Flush write buffer. + * + * This method must be synchronized with MMDSP Data cache attribute. + * Strongly Ordered -> nothing + * Shared device -> dsb + L2 Write buffer drain + * Non cacheable, Bufferable -> dsb + L2 Write buffer drain + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_mb(void); + +/*! + * \brief Description of the System Memory part of the OS Adaptation Layer + * + * <B>Goal:</B> Copy some cacheable and bufferable memory (SDRAM) provided by a client to\n + * internal memory. + * + * \param[in] dst : pointer on the begining of the internal memory previously allocated + * \param[in] src : pointer on the begining of the client's memory + * \param[in] size : The size of the data to copy + * + * Called by: + * - CM_ENGINE_PushComponent() + * + * \note This API is mainly provided for the OS were the client application does execute in the same + * address space as the CM. + * For example in Linux or Symbian, the client's address space is userland but the CM execute in + * kernel space. Thus, 'dst' is supposed to be a kernel address but src is supposed to be a user + * space address + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC t_cm_error OSAL_Copy( + void *dst, + const void *src, + t_cm_size size); + +/*! + * \brief Description of the internal log traces configuration of the Component Manager + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_Log( + const char *format, + int param1, + int param2, + int param3, + int param4, + int param5, + int param6); + +/*! + * \brief Generate an OS-Panic. Called in from CM_ASSERT(). + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_Panic(void); + +/*! + * \brief Description of the configuration of the trace features + * + * (trace output itself is provided by user through his custom implementation of the generic APIs) + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_Write64( + t_nmf_trace_channel channel, + t_uint8 isTimestamped, + t_uint64 value); + +/*! + * \brief Power enabling/disabling commands description. + * + * \ingroup CM_ENGINE_OSAL_API + */ +typedef enum +{ + CM_OSAL_POWER_SxA_CLOCK, //!< SxA Power & Clock, firstParam contains Core ID + CM_OSAL_POWER_SxA_AUTOIDLE, //!< SxA AutoIdle, firstParam contains Core ID + CM_OSAL_POWER_SxA_HARDWARE, //!< SxA Hardware Power, firstParam contains Core ID + CM_OSAL_POWER_HSEM, //!< HSEM Power + CM_OSAL_POWER_SDRAM, //!< SDRAM memory, firstParam contains physical resource address, secondParam contains size + CM_OSAL_POWER_ESRAM //!< ESRAM memory, firstParam contains physical resource address, secondParam contains size +} t_nmf_power_resource; + +/*! + * \brief Description of the Power Management part of the OS Adaptation Layer + * + * Use by CM engine to disable a logical power domain (see \ref t_nmf_power_resource) + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_DisablePwrRessource( + t_nmf_power_resource resource, //!< [in] Describe the domain which must be disabled + t_uint32 firstParam, //!< [in] Eventual first parameter to power to disable + t_uint32 secondParam //!< [in] Eventual second parameter to power to disable + ); + +/*! + * \brief Description of the Power Management part of the OS Adaptation Layer + * + * Use by CM engine to enable a logical power domain (see \ref t_nmf_power_resource) + * + * \return + * - \ref CM_OK + * - \ref CM_PWR_NOT_AVAILABLE A specified power domain is not managed (see returned value in aPowerMask) + * + * Called by: + * - any CM API call + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC t_cm_error OSAL_EnablePwrRessource( + t_nmf_power_resource resource, //!< [in] Describing the domains which must be enabled + t_uint32 firstParam, //!< [in] Eventual first parameter to power to disable + t_uint32 secondParam //!< [in] Eventual second parameter to power to disable + ); + + +/*! + * \brief return prcmu timer value. + * + * This is need for perfmeter api (see \ref t_nmf_power_resource) + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC t_uint64 OSAL_GetPrcmuTimer(void); + +/*! + * \brief Disable the service message handling (panic, etc) + * + * It must disable the handling of all service messages + * If a service message is currently handled, it must wait till the end + * of its managment before returning. + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_DisableServiceMessages(void); + +/*! + * \brief Enable the service message handling (panic, etc) + * + * It enables the handling of all service messages + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_EnableServiceMessages(void); + +/*! + * \brief Generate 'software' panic due to dsp crash + * + * We request that the os part generate a panic to notify cm users +* that a problem occur but not dsp panic has been sent (for example +* a dsp crash) + * + * \param[in] t_nmf_core_id : core_id is the id of dsp for which we need to generate a panic. + * \param[in] reason : additional information. Today only 0 is valid. + * + * \ingroup CM_ENGINE_OSAL_API + */ +PUBLIC void OSAL_GeneratePanic(t_nmf_core_id coreId, t_uint32 reason); + +extern /*const*/ t_nmf_osal_sync_handle lockHandleApi; +extern /*const*/ t_nmf_osal_sync_handle lockHandleCom; +extern /*const*/ t_nmf_osal_sem_handle semHandle; + +/*! + * \brief Take a lock before entering critical section. Can suspend current thread if lock already taken. \n + * Use this macro in api function. For com function use OSAL_LOCK_COM. + * + * \ingroup CM_ENGINE_OSAL_API + */ +#define OSAL_LOCK_API() OSAL_Lock(lockHandleApi) + +/*! + * \brief Release lock before leaving critical section. + * + * \ingroup CM_ENGINE_OSAL_API + */ +#define OSAL_UNLOCK_API() OSAL_Unlock((lockHandleApi)) + +/*! + * \brief Take a lock before entering critical section. Can suspend current thread if lock already taken. \n + * Use this macro in com function. For com function use OSAL_LOCK_API. + * + * \ingroup CM_ENGINE_OSAL_API + */ +#define OSAL_LOCK_COM() OSAL_Lock(lockHandleCom) + +/*! + * \brief Release lock before leaving critical section. + * + * \ingroup CM_ENGINE_OSAL_API + */ +#define OSAL_UNLOCK_COM() OSAL_Unlock((lockHandleCom)) + +/*! + * \brief Go to sleep untill post done on semaphore or timeout expire. In that case SYNC_ERROR_TIMEOUT is return. + * + * \ingroup CM_ENGINE_OSAL_API + */ +#define OSAL_SEMAPHORE_WAIT_TIMEOUT(semHandle) OSAL_SemaphoreWaitTimed(semHandle, (cm_PWR_GetMode() == NORMAL_PWR_MODE)?SEM_TIMEOUT_NORMAL:SEM_TIMEOUT_DEBUG) + +/****************/ +/* Generic part */ +/****************/ +t_cm_error cm_OSAL_Init(void); +void cm_OSAL_Destroy(void); + +#endif /* __INC_CM_OSAL_H */ |