wmdevice.h

WM9713 audio codec driver for WinCE 5.0

/*-----------------------------------------------------------------------------
 * Copyright (c) Wolfson Microelectronics plc.  All rights reserved.
 *
 * This software as well as any related documentation is furnished under 
 * license and may only be used or copied in accordance with the terms of the 
 * license. The information in this file is furnished for informational use 
 * only, is subject to change without notice, and should not be construed as 
 * a commitment by Wolfson Microelectronics plc. Wolfson Microelectronics plc
 * assumes no responsibility or liability for any errors or inaccuracies that
 * may appear in this document or any software that may be provided in
 * association with this document. 
 *
 * Except as permitted by such license, no part of this document may be 
 * reproduced, stored in a retrieval system, or transmitted in any form or by 
 * any means without the express written consent of Wolfson Microelectronics plc. 
 *
 * $Id: WMDevice.h 2112 2005-08-31 18:25:18Z ian $
 *
 * This file contains platform-independent routines for communicating with
 * Wolfson codecs.
 *
 * Warning:
 *  This driver is specifically written for Wolfson Codecs. It is not a 
 *  general CODEC device driver.
 *
 *---------------------------------------------------------------------------*/
#ifndef __WMDEVICE_H__
#define __WMDEVICE_H__

/*
 * Include files
 */
#include "WMTypes.h"

/*
 * Definitions
 */

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

/*-----------------------------------------------------------------------------
 * Function:    WMOpenDevice
 *
 * Initialises the use of the Wolfson device by a given driver.
 *
 * Parameters:
 *      devId               The device ID (e.g. WM_DEV_AC97_PRIMARY)
 *		driverId            The driver ID (e.g. WM_DRIVER_TOUCH)
 *      phDevice            A variable to receive the handle to the device
 *
 * Returns:     WMSTATUS
 *		See WMStatus.h.
 *---------------------------------------------------------------------------*/
WMSTATUS WMOpenDevice( WM_DEVICE_ID       devID,
                       WM_DRIVER_ID       driverID,
                       WM_DEVICE_HANDLE   *phDevice
                       );

/*-----------------------------------------------------------------------------
 * Function:    WMOpenAudioDevice
 *
 * Initialises the use of the Wolfson device by a given audio driver.
 *
 * Parameters:
 *      devId               The device ID (e.g. WM_DEV_AC97_PRIMARY)
 *      phDevice            A variable to receive the handle to the device
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h.
 *---------------------------------------------------------------------------*/
#define WMOpenAudioDevice( devID, phDevice )                            \
                WMOpenDevice( devID, WM_DRIVER_AUDIO, phDevice )

/*-----------------------------------------------------------------------------
 * Function:    WMOpenTouchDevice
 *
 * Initialises the use of the Wolfson device by a given touch driver.
 *
 * Parameters:
 *      devId               The device ID (e.g. WM_DEV_AC97_PRIMARY)
 *      phDevice            A variable to receive the handle to the device
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h.
 *---------------------------------------------------------------------------*/
#define WMOpenTouchDevice( devID, phDevice )                            \
                WMOpenDevice( devID, WM_DRIVER_TOUCH, phDevice )

/*-----------------------------------------------------------------------------
 * Function:    WMOpenBatteryDevice
 *
 * Initialises the use of the Wolfson device by a given battery driver.
 *
 * Parameters:
 *      devId               The device ID (e.g. WM_DEV_AC97_PRIMARY)
 *      phDevice            A variable to receive the handle to the device
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h.
 *---------------------------------------------------------------------------*/
#define WMOpenBatteryDevice( devID, phDevice )                            \
                WMOpenDevice( devID, WM_DRIVER_BATTERY, phDevice )

/*-----------------------------------------------------------------------------
 * Function:    WMOpenAuxADCDevice
 *
 * Initialises the use of the Wolfson device by a given Auxiliary ADC driver.
 *
 * Parameters:
 *      devId               The device ID (e.g. WM_DEV_AC97_PRIMARY)
 *      phDevice            A variable to receive the handle to the device
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h.
 *---------------------------------------------------------------------------*/
#define WMOpenAuxADCDevice( devID, phDevice )                            \
                WMOpenDevice( devID, WM_DRIVER_AUXADC, phDevice )

/*-----------------------------------------------------------------------------
 * Function:    WMCloseDevice
 *
 * Marks the end of use of the library by this driver.
 *
 * Parameters:
 *      hDevice             handle to the device (from WMOpenDevice)
 *      driverId            The driver ID (e.g. WM_DRIVER_TOUCH)
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMCloseDevice( WM_DEVICE_HANDLE hDevice, WM_DRIVER_ID driverID );

/*-----------------------------------------------------------------------------
 * Function:    WMCloseAudioDevice
 *
 * Marks the end of use of the library by the given audio driver.
 *
 * Parameters:
 *      devId               The device ID (e.g. WM_DEV_AC97_PRIMARY)
 *      phDevice            A variable to receive the handle to the device
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h.
 *---------------------------------------------------------------------------*/
#define WMCloseAudioDevice( devID, phDevice )                            \
                WMCloseDevice( devID, WM_DRIVER_AUDIO, phDevice )

/*-----------------------------------------------------------------------------
 * Function:    WMInitDeviceId
 *
 * Initialise our device type information.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h
 *---------------------------------------------------------------------------*/
WMSTATUS WMInitDeviceId( WM_DEVICE_HANDLE hDevice );

/*-----------------------------------------------------------------------------
 * Function:    WMGetDeviceType
 *
 * Returns the chip type and revision.  Note: this assumes the hardware will
 * not be changing on the fly.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      pChipType   variable to receive the type of chip (one of the
 *                  WM_CHIP_XXX constants.  Can be NULL.
 *      pRevision   variable to receive the chip revision.  Can be NULL.
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h
 *---------------------------------------------------------------------------*/
WMSTATUS WMGetDeviceType( WM_DEVICE_HANDLE  hDevice,
                          WM_CHIPTYPE       *pChipType,
                          WM_CHIPREV        *pRevision
                        );
/*-----------------------------------------------------------------------------
 * Function:    WMEnterSleep
 *
 * Enters sleep mode - powers down the device and does any state preservation
 * needed for restoring later.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h.
 *---------------------------------------------------------------------------*/
WMSTATUS WMEnterSleep( WM_DEVICE_HANDLE hDevice );

/*-----------------------------------------------------------------------------
 * Function:    WMLeaveSleep
 *
 * Leaves sleep mode - powers the device back on again and restores any
 * settings which couldn't be preserved.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h.
 *---------------------------------------------------------------------------*/
WMSTATUS WMLeaveSleep( WM_DEVICE_HANDLE hDevice );

/*-----------------------------------------------------------------------------
 * Function:    WMRewriteShadowRegisters
 *
 * Writes the current shadow register values back to those registers.
 *
 * Parameters:
 *      hDevice             handle to the device (from WMOpenDevice)
 *
 * Returns:     WMSTATUS
 *		See WMStatus.h.
 *---------------------------------------------------------------------------*/
//WMSTATUS WMRewriteShadowRegisters( WM_DEVICE_HANDLE hDevice );

/*-----------------------------------------------------------------------------
 * Function:    WMPreventSystemCalls
 *
 * Tells this module whether we can allow system calls.
 * Note this is re-entrant - you must allow as many times as you prevent.
 * Note this assumes that it is called under the power manager and that the 
 * power manager is single-threaded. Therefore calls to WMPreventSystemCalls 
 * and WMSystemCallsAllowed will not interfere with themselves/each other.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      prevent     Whether to prevent or allow.
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMPreventSystemCalls( WM_DEVICE_HANDLE hDevice, WM_BOOL prevent );

/*-----------------------------------------------------------------------------
 * Function:    WMSystemCallsAllowed
 *
 * Tells this module whether we can make system calls.
 * Note this assumes that it is called under the power manager and that the 
 * power manager is single-threaded. Therefore calls to WMPreventSystemCalls 
 * and WMSystemCallsAllowed will not interfere with themselves/each other.
 *
 * Parameters:
 *      hDevice             handle to the device (from WMOpenDevice)
 *
 * Returns:     WM_BOOL
 *      Whether the driver has been told to allow system calls.
 *---------------------------------------------------------------------------*/
WM_BOOL WMSystemCallsAllowed( WM_DEVICE_HANDLE hDevice );

/*-----------------------------------------------------------------------------
 * Function:    WMBeNice
 *
 * Allows other tasks to continue in a way which is safe for the power handler.
 *
 * Parameters:
 *      hDevice             handle to the device (from WMOpenDevice)
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMBeNice( WM_DEVICE_HANDLE hDevice );

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

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