wmplatform_os.h

WM9713 audio codec driver for WinCE 5.0

 * Macro:    ALLOC_BUFFER_MEMORY
 *
 * Allocate an area of physical memory and return both physical and virtual
 * addresses.
 * 
 * If this is available, define ALLOC_BUFFER_MEMORY_AVAILABLE to TRUE.
 * If this is not available, define ALLOC_BUFFER_MEMORY_AVAILABLE to FALSE.
 *
 * Parameters:
 *      _hDevice        handle to the device (from WMOpenDevice)
 *      _type           data type of the memory being mapped
 *      _size           The size, in bytes, to map
 *      _ppPhysAddr     Variable to receive physical address
 *      _comment        Error message string indicating what was being allocated
 *
 * Returns:     _type *
 *      The virtual address of the mapped area, or NULL on error.
 *---------------------------------------------------------------------------*/
#if ( _WIN32_WCE >= 500 )
#define ALLOC_BUFFER_MEMORY_AVAILABLE     TRUE
#define ALLOC_BUFFER_MEMORY( _hDevice, _type, _size, _ppPhysAddr, _comment )    \
                (_type *) WMAllocateBufferMemory( _hDevice,                     \
                                                  _size,                        \
                                                  (char *) _comment,            \
                                                  (void **) _ppPhysAddr         \
                                                 )
#else
/* Buffer memory allocation not available before CE 5.0 */
#define ALLOC_BUFFER_MEMORY_AVAILABLE     FALSE
#endif

/*-----------------------------------------------------------------------------
 * Macro:    ALLOC_OR_MAP_BUFFER
 *
 * This macro uses dynamic buffer allocation if it's available, using static
 * allocation otherwise (where the caller provides the physical address).  This
 * allows code to use a single call to support both systems where the buffers
 * are statically allocated at build time and systems where the buffers get
 * allocated on the fly.
 * 
 * Parameters:
 *      _hDevice        handle to the device (from WMOpenDevice)
 *      _type           data type of the memory being mapped
 *      _physAddr       Physical address to map
 *      _size           The size, in bytes, to map
 *      _ppPhysAddr     Variable to receive physical address
 *      _comment        Error message string indicating what was being allocated
 *
 * Returns:     _type *
 *      The virtual address of the mapped area, or NULL on error.
 *---------------------------------------------------------------------------*/
#if ALLOC_BUFFER_MEMORY_AVAILABLE
#   define ALLOC_OR_MAP_BUFFER( _hDevice, _type, _physAddr, _size, _ppPhysAddr, _comment ) \
                      ALLOC_BUFFER_MEMORY( _hDevice,                            \
                                  _type,                                        \
                                  _size,                                        \
                                  (void **)_ppPhysAddr,                         \
                                  _comment                                      \
                                )
#else   /* ALLOC_BUFFER_MEMORY_AVAILABLE */
#   define ALLOC_OR_MAP_BUFFER( _hDevice, _type, _physAddr, _size, _ppPhysAddr, _comment ) \
                    ( *((void **)(_ppPhysAddr)) = (void *)(_physAddr),          \
                      ( _physAddr ?                                             \
                        MAP_MEMORY( _hDevice,                                   \
                                    _type,                                      \
                                    _physAddr,                                  \
                                    _size,                                      \
                                    _comment                                    \
                                    ) :                                         \
                        NULL                                                    \
                      )                                                         \
                    )
#endif  /* ALLOC_BUFFER_MEMORY_AVAILABLE */

/*-----------------------------------------------------------------------------
 * Macro:    FREE_BUFFER_MEMORY
 *
 * Free the memory previously allocated using ALLOC_OR_MAP_BUFFER.
 * 
 * Parameters:
 *      _pVirtAddr      pointer to the virtual memory to be released.
 *      _pPhysAddr      pointer to the physical memory to be released.      
 *      _size           size of the memory to be released.
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
#define FREE_BUFFER_MEMORY( _pVirtAddr, _pPhysAddr, _size ) do {                \
            WMFreeBufferMemory( (void *)_pVirtAddr, (void *)_pPhysAddr, _size );\
            _pVirtAddr = NULL;                                                  \
} while ( 0 )

/*
 * Function prototypes
 */
#ifdef __cplusplus
extern "C" {
#endif

/*-----------------------------------------------------------------------------
 * Function:    WMMapMemory
 *
 * Allocate an area of memory and copy from the specified physical address.
 *
 * Parameters:
 *      hDevice handle to the device (from WMOpenDevice)
 *      size            The size, in bytes, of the region.
 *      str             Error message string indicating what was being mapped
 *		pAddress		Pointer to the physical memory.
 *
 * Returns:     void *
 *              The base address of the allocated region of pages 
 *              indicates success.
 *                NULL indicates failure.
 *---------------------------------------------------------------------------*/
void * WMMapMemory( WM_DEVICE_HANDLE hDevice,
                    unsigned size,
                    char *str,
                    void *pAddress
                  );

/*-----------------------------------------------------------------------------
 * Function:    WMAllocateSharedMemory
 *
 * Allocate memory which is shared across all processes (i.e. so all processes
 * can access the same area of memory and have a shared common state).
 *
 * Parameters:
 *      hDevice        handle to the device (from WMOpenDevice)
 *      size           The size, in bytes, to allocate
 *      name           The "name", or unique identifier, of the shared memory.
 *
 * Returns:     void *
 *      The virtual address, or NULL on failure.
 *---------------------------------------------------------------------------*/
void *WMAllocateSharedMemory( WM_DEVICE_HANDLE hDevice,
                              unsigned size,
                              const TCHAR *name
                            );

/*-----------------------------------------------------------------------------
 * Function:    WMFreeSharedMemory
 *
 * Free memory allocated using ALLOC_SHARED_MEMORY.
 *
 * Parameters:
 *      pAddr       pointer to the virtual memory to be released.
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMFreeSharedMemory( void *pAddr );

/*-----------------------------------------------------------------------------
 * Function:    WMAllocateBufferMemory
 *
 * Allocate an area of physical memory and return both physical and virtual
 * addresses.
 *
 * Parameters:
 *      hDevice         handle to the device (from WMOpenDevice)
 *      size            The size, in bytes, to allocate.
 *      str             Error message string indicating what was being allocated
 *      ppPhysicalAddr  Variable to receive physical address
 *
 * Returns:     void *
 *      The virtual address, or NULL on failure.
 *---------------------------------------------------------------------------*/
void *WMAllocateBufferMemory( WM_DEVICE_HANDLE hDevice,
                                unsigned size,
                                char *str,
                                void **ppPhysicalAddr
                              );

/*-----------------------------------------------------------------------------
 * Function:    WMFreeBufferMemory
 *
 * Releases the buffer memory allocated using ALLOC_OR_MAP_BUFFER.
 *
 * Parameters:
 *      pVirtualAddr    pointer to the virtual memory to be released.
 *      pPhysicalAddr   pointer to the physical memory to be released.      
 *      size            size of the memory to be released.
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMFreeBufferMemory( void *pVirtualAddr, 
                         void *pPhysicalAddr, 
                         unsigned long size 
                       );

/*-----------------------------------------------------------------------------
 * Function:    WMGetNamedEvent
 *
 * returns an event based on the name that is passed it.
 *
 * Parameters:
 *      hDevice handle to the device (from WMOpenDevice)
 *      name    The name of the event.
 *
 * Returns:     handle to the event.
 *---------------------------------------------------------------------------*/
WMEvent_t WMGetNamedEvent( WM_DEVICE_HANDLE hDevice, char *name );

#ifdef __cplusplus
}   /* extern "C" */
#endif

#endif	/* __WMPLATFORM_OS_H__ */
/*------------------------------ END OF FILE ---------------------------------*/