/*---------------------------------------------------------------------------*
  Project:  NitroSDK - SPI - include
  File:     api.h

  Copyright 2003,2004 Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Log: mic.h,v $
  Revision 1.8  2004/11/04 07:12:12  terui
  Revised comments.

  Revision 1.7  2004/11/02 04:30:47  terui
  Corrected comments

  Revision 1.6  2004/09/17 09:36:03  terui
  Revisions reflecting changes in MIC_StartAutoSampling (Async) parameters.

  Revision 1.5  2004/07/13 09:21:21  terui
  Changes reflecting addition of symbolic sampling types.

  Revision 1.4  2004/06/03 04:09:09  terui
  Changed definition of shortest sampling rate.

  Revision 1.3  2004/06/01 02:02:08  terui
  Added typical sampling rate definitions to MICSamplingRate.

  Revision 1.2  2004/06/01 00:54:39  terui
  Deleted sampling rate definitions.
  Defined shortest sampling period that is supported.

  Revision 1.1  2004/05/31 08:39:06  terui
  Initial upload.

  $NoKeywords: $
 *---------------------------------------------------------------------------*/

#ifndef NITRO_SPI_ARM9_MIC_H_
#define NITRO_SPI_ARM9_MIC_H_

#ifdef  __cplusplus
extern "C" {
#endif

/*===========================================================================*/

#include    <nitro/spi/common/type.h>
#include    <nitro/pxi.h>


/*---------------------------------------------------------------------------*
    Constant definitions
 *---------------------------------------------------------------------------*/
// Processing result definitions
typedef enum MICResult
{
    MIC_RESULT_SUCCESS = 0 ,            // Successful
    MIC_RESULT_BUSY ,                   // Busy
    MIC_RESULT_ILLEGAL_PARAMETER ,      // Illegal parameter
    MIC_RESULT_SEND_ERROR ,             // Transmission failure due to PXI
    MIC_RESULT_INVALID_COMMAND ,        // Invalid command
    MIC_RESULT_ILLEGAL_STATUS ,         // Status does not permit execution
    MIC_RESULT_FATAL_ERROR ,            // Other error
    MIC_RESULT_MAX

} MICResult;

// Sampling type definitions
typedef enum MICSamplingType
{
    MIC_SAMPLING_TYPE_8BIT = 0 ,        //  8 bit sampling
    MIC_SAMPLING_TYPE_12BIT ,           // 12 bit sampling
    MIC_SAMPLING_TYPE_SIGNED_8BIT ,
    MIC_SAMPLING_TYPE_SIGNED_12BIT ,
    MIC_SAMPLING_TYPE_MAX

} MICSamplingType;

// Typical sampling periods are defined in ARM7 clock ticks
typedef enum MICSamplingRate
{
    MIC_SAMPLING_RATE_8K    = ( HW_CPU_CLOCK_ARM7 /  8000 ) ,   // Approx.  8.0  kHz
    MIC_SAMPLING_RATE_11K   = ( HW_CPU_CLOCK_ARM7 / 11025 ) ,   // Approx. 11.025 kHz
    MIC_SAMPLING_RATE_16K   = ( HW_CPU_CLOCK_ARM7 / 16000 ) ,   // Approx. 16.0 kHz
    MIC_SAMPLING_RATE_22K   = ( HW_CPU_CLOCK_ARM7 / 22050 ) ,   // Approx. 22.05 kHz
    MIC_SAMPLING_RATE_32K   = ( HW_CPU_CLOCK_ARM7 / 32000 ) ,   // Approx. 32.0 kHz
    MIC_SAMPLING_RATE_LIMIT = 1024

} MICSamplingRate;

/*---------------------------------------------------------------------------*
    Structure definitions
 *---------------------------------------------------------------------------*/
// Callback function definitions
typedef void ( *MICCallback )( MICResult result , void* arg );

// Auto-sampling setting definitions
typedef struct MICAutoParam
{
    MICSamplingType     type;               // Sampling type
    void*               buffer;             // Pointer to result storage buffer
    u32                 size;               // Buffer size
    u32                 rate;               // Sampling period (ARM7 clock count)
    BOOL                loop_enable;        // Enable loop when buffer is full
    MICCallback         full_callback;      // Callback when buffer is full
    void*               full_arg;           // Argument that specifies the above callback.

} MICAutoParam;


/*---------------------------------------------------------------------------*
    Function definitions
 *---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*
  Name:         MIC_Init

  Description:  Initializes microphone library.

  Arguments:    None.

  Returns:      None.
 *---------------------------------------------------------------------------*/
void        MIC_Init( void );

/*---------------------------------------------------------------------------*
  Name:         MIC_DoSamplingAsync

  Description:  Performs a single async sample of the mic.

  Arguments:    type      - The sampling type.
                buf       - The buffer that stores the sampling data.
                callback  - Function called when async processing completes.
                arg       - Argument used when the callback function is called.

  Returns:      MICResult - Returns the result of the start of async device operation.
 *---------------------------------------------------------------------------*/
MICResult   MIC_DoSamplingAsync( MICSamplingType type , void* buf , MICCallback callback , void* arg );

/*---------------------------------------------------------------------------*
  Name:         MIC_StartAutoSamplingAsync

  Description:  Starts mic auto sampling asynchronously.

  Arguments:    MICAutoParam - Pointer to the structure with auto-sampling settings.
                callback     - Called when async processing completes.
                arg          - Argument used when callback function is called.

  Returns:      MICResult    - Returns the result of the start of async device operation.
 *---------------------------------------------------------------------------*/
MICResult   MIC_StartAutoSamplingAsync( const MICAutoParam* param , MICCallback callback , void* arg );

/*---------------------------------------------------------------------------*
  Name:         MIC_StopAutoSamplingAsync

  Description:  Stops auto-sampling with the mic asynchronously.

  Arguments:    callback  - Function called when async processing completes.
                arg       -  Argument used when the callback function is called.

  Returns:      MICResult - Returns the result of the start of async device operation.
 *---------------------------------------------------------------------------*/
MICResult   MIC_StopAutoSamplingAsync( MICCallback callback , void* arg );

/*---------------------------------------------------------------------------*
  Name:         MIC_GetLastSamplingAddress

  Description:  Gets the storage address of the most recent mic sample.

  Arguments:    None.

  Returns:      void* - Returns the storage address of the sampling result.
                        Returns NULL if not yet sampling.
 *---------------------------------------------------------------------------*/
void*       MIC_GetLastSamplingAddress( void );

/*---------------------------------------------------------------------------*
  Name:         MIC_DoSampling

  Description:  Samples the mic once.

  Arguments:    type      - The sampling type.
                buf       - Buffer that stores the sampling data.

  Returns:      MICResult - Returns the result of the device operation.
 *---------------------------------------------------------------------------*/
MICResult   MIC_DoSampling( MICSamplingType type , void* buf );

/*---------------------------------------------------------------------------*
  Name:         MIC_StartAutoSampling

  Description:  Starts auto-sampling with the mic.

  Arguments:    MICAutoParam - Pointer to structure that holds auto-sampling parameters.

  Returns:      MICResult - Returns the result of the device operation.
 *---------------------------------------------------------------------------*/
MICResult   MIC_StartAutoSampling( const MICAutoParam* param );

/*---------------------------------------------------------------------------*
  Name:         MIC_StopAutoSampling

  Description:  Stops auto-sampling with the mic.
                If a loop was not specified at the start of auto-sampling,
                it stops sampling automatically at the point where the buffer is full.

  Arguments:    None.

  Returns:      MICResult - Returns the result of the device operation.
   *---------------------------------------------------------------------------*/
MICResult   MIC_StopAutoSampling( void );


/*===========================================================================*/

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

#endif  /* NITRO_RTC_ARM9_API_H_ */

/*---------------------------------------------------------------------------*
  End of file
 *---------------------------------------------------------------------------*/
