/******************************************************************************
**
**  COPYRIGHT (C) 2000, 2001 Intel Corporation.
**
**  This software as well as the software described in it 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 Intel Corporation. Intel Corporation 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 Intel Corporation. 
**
**  FILENAME:       XsAc97CtrlApi.h
**
**  PURPOSE:        Constants, structure and variable declarations for the 
**                  Application Programming (public) Interface of the main 
**                  processor's on-board AC'97 Controller device driver.
**
**  Valid for    :  Subset of AC '97 Rev 2.1
**
**  Valid for    :  Cotulla processor
**
**  EAS VERSION  :  2.1
**
**  $Modtime: 6/22/01 8:06a $ 
******************************************************************************/
#include "systypes.h"

#ifndef _XSAC97CTRLAPI_H
#define _XSAC97CTRLAPI_H

#ifdef  _DEFINING_XSAC97CTRL
#define EXTRN
#else
#define EXTRN   extern
#endif


/*
*******************************************************************************
*******************************************************************************
***   AC97CTRL constant definitions
*******************************************************************************
*******************************************************************************
*/

                                // Number of AC '97 codec and modem devices
                                //  controlled by the main processor AC'97
                                //  Controller in this system

#define XS_AC97CTRL_NUM_CODECS  1   // This system has only a primary codec.


// Bit mask and values for CAIP bit in CAR register.

#define XS_AC97CTRL_CAIP_MSK        (1u << 0)
#define XS_AC97CTRL_CAIP_LOCKED      1

/*
*******************************************************************************
    Codec and Modem selector IDs for command writes and status reads
*******************************************************************************
*/

typedef enum XsAc97CtrlCodecModemIdE 
{
    XS_AC97CTRL_CM_ID_PRI_CODEC = 0 ,
    XS_AC97CTRL_CM_ID_SEC_CODEC,
    XS_AC97CTRL_CM_ID_PRI_MODEM,
    XS_AC97CTRL_CM_ID_SEC_MODEM,
    XS_AC97CTRL_CM_ID_NUM,

    XS_AC97CTRL_CM_ID_MAX       = (XS_AC97CTRL_CM_ID_NUM - 1)

} XsAc97CtrlCodecModemIdT ; 


/*
*******************************************************************************
    AC97 Controller FIFO IDs.
*******************************************************************************
*/

typedef enum XsAc97CtrlFifoIdE 
{
    XS_AC97CTRL_FIFO_AUDIO_IN   = 0,   // TS 3 & 4
    XS_AC97CTRL_FIFO_AUDIO_OUT,        // TS 3 & 4
    XS_AC97CTRL_FIFO_MIC_IN,           // TS 6
    XS_AC97CTRL_FIFO_MODEM_IN,         // TS 5
    XS_AC97CTRL_FIFO_MODEM_OUT,        // TS 5
    XS_AC97CTRL_FIFO_NUM,

    XS_AC97CTRL_FIFO_MAX        =  (XS_AC97CTRL_FIFO_NUM-1)

} XsAc97CtrlFifoIdT ; 

/*
*******************************************************************************
    AC97CTRL interrupt and status definitions
*******************************************************************************
*/

// Types of interrupts for which handlers can be registered with the main
//  processor AC'97 Controller module

typedef enum XsAc97CtrlIntIdE 
{
    XS_AC97CTRL_INT_GSCI = 0,   // CODEC GPI Status Change Interrupt (GSCI)
    XS_AC97CTRL_INT_MIINT,      // MODEM In Interrupt (MIINT) 
    XS_AC97CTRL_INT_MOINT,      // MODEM Out Interrupt (MOINT)
    XS_AC97CTRL_INT_PIINT,      // PCM In Interrupt    (PIINT)
    XS_AC97CTRL_INT_POINT,      // PCM Out Interrupt   (POINT)
    XS_AC97CTRL_INT_MINT,       // Mic In Interrupt    (MINT) 
    XS_AC97CTRL_INT_PCRDY,      // Primary CODEC Ready (PCR)
    XS_AC97CTRL_INT_SCRDY,      // Secondary CODEC Ready (SCR)
    XS_AC97CTRL_INT_PCRSM,      // Primary Resume Interrupt
    XS_AC97CTRL_INT_SCRSM,      // Secondary Resume Interrupt
    XS_AC97CTRL_INT_SDONE,      // Status Done (SDONE)
    XS_AC97CTRL_INT_CDONE,      // Command Done (CDONE)
    XS_AC97CTRL_INT_NUM,

    XS_AC97CTRL_INT_MAX  =     (XS_AC97CTRL_INT_NUM - 1)

} XsAc97CtrlIntIdT ; 

// End AC97CTRL interrupt type definitions



// Status indicator IDs for the main processor AC'97 Controller

typedef enum XsAc97CtrlStatusIdE 
{
    XS_AC97CTRL_STAT_GSCI = 0,      // CODEC GPI Status Change
    XS_AC97CTRL_STAT_MDM_IN,        // MODEM In FIFO error
    XS_AC97CTRL_STAT_MDM_OUT,       // MODEM Out FIFO error
    XS_AC97CTRL_STAT_PCM_IN,        // PCM In FIFO error
    XS_AC97CTRL_STAT_PCM_OUT,       // PCM Out FIFO error
    XS_AC97CTRL_STAT_MIC_IN,        // Mic In FIFO error
    XS_AC97CTRL_STAT_PCRDY,         // Primary CODEC Ready	
    XS_AC97CTRL_STAT_SCRDY,         // Secondary CODEC Ready	
    XS_AC97CTRL_STAT_PCRSM,         // Primary CODEC Resume Interrupt
    XS_AC97CTRL_STAT_SCRSM,         // Secondary CODEC Resume Interrupt
    XS_AC97CTRL_STAT_SLT12_B1_3,    // Bits1..3 of Slot 12
    XS_AC97CTRL_STAT_RCS_ERR,       // Read Completion Status (error)
    XS_AC97CTRL_STAT_SDONE,         // Status Done
    XS_AC97CTRL_STAT_CDONE,         // Command Done
    XS_AC97CTRL_STAT_NUM,

    XS_AC97CTRL_STAT_MAX      =     (XS_AC97CTRL_STAT_NUM-1)

} XsAc97CtrlStatusIdT ;

// End AC97CTRL status indicator ID definitions



/*
*******************************************************************************
    Context structure definitions
*******************************************************************************
*/

typedef struct XsAc97CtrlStatsS
{
    UINT32 readCodecNumInvocations;
    UINT32 readCodecTotalRetries;
    UINT32 readCodecNumFailures;     // Invocations where retries exceeded limit
    
} XsAc97CtrlStatsT;




typedef struct XsAc97CtrlContextS
{
    UINT32           loggedError;
    UINT32           isrError;
    XsAc97CtrlStatsT statistics[XS_AC97CTRL_CM_ID_NUM];

}  XsAc97CtrlContextT ;



EXTRN XsAc97CtrlContextT  XsAc97CtrlContext;

/*
*******************************************************************************
      Function prototypes in standard driver API of main processor
                        on-board AC97 controller
*******************************************************************************
*/

extern void   XsAc97CtrlSWInit          (void);
extern UINT32 XsAc97CtrlHWSetup         (void);

extern UINT32 XsAc97CtrlGetStatus       (XsAc97CtrlStatusIdT);


/*extern UINT32 XsAc97CtrlWriteCodecReg   (XsAc97CtrlCodecModemIdT, 
                                         AC97MixerRegisterIdT,
                                         UINT32);

extern UINT32 XsAc97CtrlReadCodecReg    (XsAc97CtrlCodecModemIdT,
                                         AC97MixerRegisterIdT, 
                                         PUINT32);
*/
extern UINT32 XsAc97CtrlRangeCheckIntTypeId (XsAc97CtrlIntIdT);

// End Fn prototypes in standard driver API of main processor 
//     on-board AC97CTRL handler

/*
*******************************************************************************
    Function prototypes in non-standard, test-oriented API of main processor 
        on-board AC97CTRL driver.  Lower level access provided.
*******************************************************************************
*/

extern UINT32  XsAc97CtrlColdReset  (void);

extern BOOL    XsAc97CtrlLockAcLink (void); // TRUE = success; FALSE = failure

                                       // Only needed if Codec access not done.
extern void    XsAc97CtrlReleaseAcLink(void); 

extern UINT32 XsAc97CtrlGetStats (XsAc97CtrlCodecModemIdT, XsAc97CtrlStatsT*);
extern UINT32 XsAc97CtrlClearStats (XsAc97CtrlCodecModemIdT);

/*
*******************************************************************************
    General AC97CTRL utility function prototypes
*******************************************************************************
*/


// End Fn prototypes in nonstandard driver API of main processor on-board AC97CTRL handler

#undef EXTRN

#endif // #ifndef _XSAC97CTRLAPI_H