wmdma.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: WMDMA.h 2460 2005-11-28 15:03:58Z ian $
 *
 * The header file contains function headers for control of the Intel XScale
 * DMA Controller.
 *
 * Warning:
 *  This driver is specifically written for Wolfson Codecs. It is not a 
 *  general CODEC device driver.
 *
 *---------------------------------------------------------------------------*/
#ifndef __WMDMA_H__
#define __WMDMA_H__

/*
 * Include files
 */
#include "WMAudioInternal.h"
#include "WMPlatform_OS.h"


/*
 * Only build this if we're doing Audio support.
 */
#if WM_AUDIO_STREAM

/*
 * Definitions
 */
typedef void *WMDMA_CHAN_HANDLE;

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

/*-----------------------------------------------------------------------------
 * Function:    WMDMAInit
 *
 * Prepares the DMA subsystem for use.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h
 *---------------------------------------------------------------------------*/
WMSTATUS WMDMAInit( WM_DEVICE_HANDLE hDevice );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAShutdown
 *
 * Cleans up the DMA subsystem.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *		channel     the channel to clean up.
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMDMAShutdown( WM_DEVICE_HANDLE hDevice );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAInitChannel
 *
 * Prepares the DMA channel for transferring data.
 *
 * Parameters:
 *      hDevice         handle to the device (from WMOpenDevice)
 *		APIchannel      the channel to prepare.
 *      bufsize         the size of the DMA buffer(s).
 *
 * Returns:     WMSTATUS
 *      See WMStatus.h
 *---------------------------------------------------------------------------*/
WMDMA_CHAN_HANDLE WMDMAInitChannel( WM_DEVICE_HANDLE hDevice, 
									WMAUDIO_CHANNEL APIchannel, 
									unsigned int bufsize
								  );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAShutdownChannel
 *
 * Cleans up the given DMA channel.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *		channel     the channel to clean up.
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMDMAShutdownChannel( WM_DEVICE_HANDLE hDevice, WMDMA_CHAN_HANDLE channel );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAGetChannelBuffer
 *
 * Returns a pointer to the current DMA buffer for the channel.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *		channel     the channel to return the buffer for.
 *
 * Returns:     void *
 *      A pointer to the DMA buffer (of size as configured in WMDMAInit).
 *---------------------------------------------------------------------------*/
void *WMDMAGetChannelBuffer( WM_DEVICE_HANDLE hDevice, WMDMA_CHAN_HANDLE channel );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAMarkBufferFull
 *
 * Marks the current DMA buffer as full and awaiting transfer.  This will
 * start the DMA if necessary.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      channel     the channel ID.
 *      pBuffer     the buffer to mark as full (from WMDMAGetChannelBuffer).
 *
 * Returns:     void 
 *---------------------------------------------------------------------------*/
void WMDMAMarkBufferFull( WM_DEVICE_HANDLE hDevice,
                          WMDMA_CHAN_HANDLE channel,
                          void *pBuffer
                        );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAMarkBufferEmpty
 *
 * Marks the given DMA buffer as empty and ready to receive more data.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      channel     the channel ID.
 *      pBuffer     the buffer to mark as empty (from WMDMAGetChannelBuffer).
 *
 * Returns:     void 
 *---------------------------------------------------------------------------*/
void WMDMAMarkBufferEmpty( WM_DEVICE_HANDLE hDevice,
                           WMDMA_CHAN_HANDLE channel,
                           void *pBuffer
                         );
                         
/*-----------------------------------------------------------------------------
 * Function:    WMDMAStartChannel
 *
 * Sets the channel running.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *		channel     the channel to start.
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMDMAStartChannel( WM_DEVICE_HANDLE hDevice, WMDMA_CHAN_HANDLE channel );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAStopChannel
 *
 * Stops the channel.  Any outstanding data in the DMA buffers is lost.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *		channel     the channel to stop.
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMDMAStopChannel( WM_DEVICE_HANDLE hDevice, WMDMA_CHAN_HANDLE channel );

/*-----------------------------------------------------------------------------
 * Function:    WMDMACheckChannelInterrupts
 *
 * This function checks what interrupts have happened and clears them.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      channel     the channel to check.  This must have been initialised
 *                  using WMDMAInitChannel.
 *
 * Returns:     WMAUDIO_INTSTATE
 *      bitmask listing the interrupts
 *---------------------------------------------------------------------------*/
WMAUDIO_INTSTATE WMDMACheckChannelInterrupts( WM_DEVICE_HANDLE hDevice, 
											  WMDMA_CHAN_HANDLE channel 
											);

/*-----------------------------------------------------------------------------
 * Function:    WMDMAHandleInterrupt
 *
 * This function allows the library to do any processing required when an
 * interrupt is received on an audio channel.  This _must_ be called
 * when an interrupt is received to allow the library to keep its internal
 * state correct.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      channel     the channel ID.
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMDMAHandleInterrupt( WM_DEVICE_HANDLE hDevice, WMDMA_CHAN_HANDLE channel );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAGetMaxBufferSize
 *
 * This function returns the maximum size for a DMA buffer in bytes.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *
 * Returns:     unsigned int
 *      the number of bytes in an audio sample for the given channel
 *---------------------------------------------------------------------------*/
unsigned int WMDMAGetMaxBufferSize( WM_DEVICE_HANDLE hDevice );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAGetBytesPerSample
 *
 * This function returns the number of bytes per sample on the given channel.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      channel     the channel to check.
 *
 * Returns:     unsigned int
 *      the number of bytes in an audio sample for the given channel
 *---------------------------------------------------------------------------*/
unsigned int WMDMAGetBytesPerSample( WM_DEVICE_HANDLE hDevice,
                                     WMAUDIO_CHANNEL channel
                                   );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAIsStereo
 *
 * This function returns whether or not the given channel is stereo.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      APIChannel  the channel to check.
 *
 * Returns:     WM_BOOL
 *      TRUE if the given channel is stereo
 *      FALSE for all other situations (including error conditions)
 *---------------------------------------------------------------------------*/
WM_BOOL WMDMAIsStereo( WM_DEVICE_HANDLE hDevice, 
					   WMAUDIO_CHANNEL  APIChannel 
					 );

/*-----------------------------------------------------------------------------
 * Function:    WMDMAIsInput
 *
 * This function returns whether or not the given channel is an input.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      APIChannel  the channel to check.
 *
 * Returns:     WM_BOOL
 *      TRUE if the given channel is  an input
 *      FALSE for all other situations (including error conditions)
 *---------------------------------------------------------------------------*/
WM_BOOL WMDMAIsInput( WM_DEVICE_HANDLE hDevice, 
					  WMAUDIO_CHANNEL  APIChannel 
					);

/*-----------------------------------------------------------------------------
 * Function:    WMDMAIsWide
 *
 * This function returns whether or not the given channel is 32 bits wide.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *      APIChannel  the channel to check.
 *
 * Returns:     WM_BOOL
 *      TRUE if the given channel is wide
 *      FALSE for all other situations (including error conditions)
 *---------------------------------------------------------------------------*/
WM_BOOL WMDMAIsWide( WM_DEVICE_HANDLE hDevice, 
					 WMAUDIO_CHANNEL  APIChannel 
				   );

#if WM_USE_DYNAMIC_DMA_CHANNEL
/*-----------------------------------------------------------------------------
 * Function:    WMDMAGetEventHandle
 *
 * This function returns the DMA interrupt event handle for the given channel
 * (if relevant for this platform).
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *		channel     the channel ID.
 *
 * Returns:     WMEvent_t
 *      the DMA event interrupt handle, or NULL if this is not relevant.
 *---------------------------------------------------------------------------*/
WMEvent_t WMDMAGetEventHandle( WM_DEVICE_HANDLE hDevice,
                               WMDMA_CHAN_HANDLE channel
                             ); 
#endif /* WM_USE_DYNAMIC_DMA_CHANNEL */

/*-----------------------------------------------------------------------------
 * Function:    WMDMAEnableInterrupts
 *
 * This function enables DMA interrupts.
 * NOTE: This function is intended for use only by the Wolfson test
 *       code and should not be used by standard library code.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMDMAEnableInterrupts( WM_DEVICE_HANDLE hDevice );

/*-----------------------------------------------------------------------------
 * Function:    WMDMADisableInterrupts
 *
 * This function disables DMA interrupts.
 * NOTE: This function is intended for use only by the Wolfson test
 *       code and should not be used by standard library code.
 *
 * Parameters:
 *      hDevice     handle to the device (from WMOpenDevice)
 *
 * Returns:     void
 *---------------------------------------------------------------------------*/
void WMDMADisableInterrupts( WM_DEVICE_HANDLE hDevice );

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

#endif  /* WM_AUDIO_STREAM */

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