/******************************************************************************
**
**  COPYRIGHT (C) 2001 Intel Corporation.
**
**  This file and the software 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:       Ac97Api.h
**
**  PURPOSE:        Constants, structure and variable declarations for the 
**                  Application Programming (public) Interface of the AC'97 
**                  device driver.
**
**  Valid for    :  Subset of AC '97 Rev 2.1
**
**  $Modtime: 7/17/03 1:01p $ 
******************************************************************************/
#ifndef _AC97API_H
#define _AC97API_H

#ifdef  _DEFINING_AC97API
#define EXTRN
#else
#define EXTRN   extern
#endif


/*
*******************************************************************************
*******************************************************************************
    Common mixer register constants 
*******************************************************************************
*******************************************************************************
*/

#define AC97_MR_MUTE_ENAB_USUAL_SHFT   15  // Mute is usually in MSB of a reg.
#define AC97_MR_MUTE_ENAB_USUAL_MSK   (1u << AC97_MR_MUTE_ENAB_USUAL_SHFT)


/*
*******************************************************************************
*******************************************************************************
    Original mixer register (0x00 .. 0x26) constants 
*******************************************************************************
*******************************************************************************
*/

/*
*******************************************************************************
    mixer reg 0x00 bits and bit fields
*******************************************************************************
*/
// defines for capability id bits (D0..D9) in mixer reg 0x00

#define AC97_MR_ID_CPBLTY_MIC_PCM            (1u << 0)  // reg 0x00:ID0
#define AC97_MR_ID_CPBLTY_RESERVED           (1u << 1)  // reg 0x00:ID1
#define AC97_MR_ID_CPBLTY_BASS_TREBLE_CTRL   (1u << 2)  // reg 0x00:ID2
#define AC97_MR_ID_CPBLTY_SIMULATED_STEREO   (1u << 3)  // reg 0x00:ID3
#define AC97_MR_ID_CPBLTY_HEADPHONE_OUT      (1u << 4)  // reg 0x00:ID4
#define AC97_MR_ID_CPBLTY_BASS_BOOST         (1u << 5)  // reg 0x00:ID5
#define AC97_MR_ID_CPBLTY_18_BIT_DAC         (1u << 6)  // reg 0x00:ID6
#define AC97_MR_ID_CPBLTY_20_BIT_DAC         (1u << 7)  // reg 0x00:ID7
#define AC97_MR_ID_CPBLTY_18_BIT_ADC         (1u << 8)  // reg 0x00:ID8
#define AC97_MR_ID_CPBLTY_20_BIT_ADC         (1u << 9)  // reg 0x00:ID9

#define AC97_MR_ID_CPBLTY_MAX                AC97_MR_ID_CPBLTY_20_BIT_ADC

#define AC97_MR_ID_CPBLTY_NUM                 10

// defines for 3D Stereo Enhancement Technique id field 
//  (SE0..SE4 = D10..D14) in mixer reg 0x00)  
#define AC97_MR_3DSET_NONE                    0x00     // reg 0x00:SE (00)  
#define AC97_MR_3DSET_AD_PHAT                 0x01     // reg 0x00:SE (01)  
#define AC97_MR_3DSET_CREATIVE                0x02     // reg 0x00:SE (02)  
#define AC97_MR_3DSET_NATIONAL_SEMI           0x03     // reg 0x00:SE (03)  
#define AC97_MR_3DSET_YMERSION                0x04     // reg 0x00:SE (04)  
#define AC97_MR_3DSET_BBE                     0x05     // reg 0x00:SE (05)  
#define AC97_MR_3DSET_CRYSTAL_SEMI            0x06     // reg 0x00:SE (06)  
#define AC97_MR_3DSET_QSOUND                  0x07     // reg 0x00:SE (07)  
#define AC97_MR_3DSET_SPATIALIZER             0x08     // reg 0x00:SE (08)  
#define AC97_MR_3DSET_SRS                     0x09     // reg 0x00:SE (09)  
#define AC97_MR_3DSET_PLATFORM_TECH           0x0A     // reg 0x00:SE (10)  
#define AC97_MR_3DSET_AKM                     0x0B     // reg 0x00:SE (11)  
#define AC97_MR_3DSET_AUREAL                  0x0C     // reg 0x00:SE (12)  
#define AC97_MR_3DSET_AZTECH                  0x0D     // reg 0x00:SE (13)  
#define AC97_MR_3DSET_BINAURA                 0x0E     // reg 0x00:SE (14)  
#define AC97_MR_3DSET_ESS_TECH                0x0F     // reg 0x00:SE (15)  
#define AC97_MR_3DSET_HARMAN                  0x10     // reg 0x00:SE (16)  
#define AC97_MR_3DSET_NVIDEA                  0x11     // reg 0x00:SE (17)  
#define AC97_MR_3DSET_PHILIPS                 0x12     // reg 0x00:SE (18)  
#define AC97_MR_3DSET_TI                      0x13     // reg 0x00:SE (19)  
#define AC97_MR_3DSET_VLSI_TECH               0x14     // reg 0x00:SE (20)  
#define AC97_MR_3DSET_TRITECH                 0x15     // reg 0x00:SE (21)  
#define AC97_MR_3DSET_REALTEK                 0x16     // reg 0x00:SE (22)  
#define AC97_MR_3DSET_SAMSUNG                 0x17     // reg 0x00:SE (23)  
#define AC97_MR_3DSET_WOLFSON                 0x18     // reg 0x00:SE (24)  
#define AC97_MR_3DSET_DELTA_INTEG             0x19     // reg 0x00:SE (25)  
#define AC97_MR_3DSET_SIGMATEL                0x1A     // reg 0x00:SE (26)  
#define AC97_MR_3DSET_RESERVED27              0x1B     // reg 0x00:SE (27)  
#define AC97_MR_3DSET_ROCKWELL                0x1C     // reg 0x00:SE (28)  
#define AC97_MR_3DSET_RESERVED29              0x1D     // reg 0x00:SE (29)  
#define AC97_MR_3DSET_RESERVED30              0x1E     // reg 0x00:SE (30)  
#define AC97_MR_3DSET_RESERVED31              0x1F     // reg 0x00:SE (31)  

#define AC97_MR_3DSET_MAX                     AC97_MR_3DSET_RESERVED31
#define AC97_MR_3DSET_NUM                     31

#define AC97_MR_3DSET_SHFT                    10

/*
*******************************************************************************
    mixer reg 0x02 - 0x06 bit fields: Master volume output controls
*******************************************************************************
*/

// Actually control attenuations in master volume registers.
// Note: 1.5 dB attenuation per increment
// Note: If optional attenuation not supported, driver must clamp to required.
//       The driver must determine whether clamping is required.

#define AC97_MR_MSTR_VOL_ATTN_MAX_OPT   0x3F   // MSB support is optional, try 1st
#define AC97_MR_MSTR_VOL_ATTN_MAX_RQD   0x1F   // Required. (46.5 dB)

#define AC97_MR_MSTR_VOL_MSK            0x3F   // Mask for master vol bits

#define AC97_MR_MSTR_VOL_R_SHFT         0      // For Right side, no shift needed.
#define AC97_MR_MSTR_VOL_L_SHFT         8      // For Left side, start at D8
#define AC97_MR_MSTR_VOL_MONO_SHFT      0      // For Mono, no shift needed.


/*
*******************************************************************************
    mixer reg 0x08 bit fields: Master tone for both stereo sides  (optional)
*******************************************************************************
*/

// Starts a +10.5 dB for 0 and attenuates at 1.5 dB per increment
// Except for no-gain and bypass, bit 0 support is optional.

#define AC97_MR_MSTR_TONE_MAX_GAIN     0x00     // +10.5 dB gain
#define AC97_MR_MSTR_TONE_NO_GAIN      0x07     // +0 dB gain
#define AC97_MR_MSTR_TONE_MIN_GAIN     0x0E     // -10.5 dB gain
#define AC97_MR_MSTR_TONE_BYPASS       0x0F     // Not in circuit

#define AC97_MR_MSTR_TONE_MSK          0x0F     // Also works as max for range chk

#define AC97_MR_MSTR_TONE_TREBLE_SHFT  0        // For Treble, no shift needed.
#define AC97_MR_MSTR_TONE_BASE_SHFT    8        // For Base side, start at D8


/*
*******************************************************************************
    mixer reg 0x0A bit field: PC Beep volume (optional register)
*******************************************************************************
*/

#define AC97_MR_PCBEEP_VOL_ATTN_MAX   0x0F  // 45 dB attenuation

#define AC97_MR_PCBEEP_VOL_SHFT        1

/*
*******************************************************************************
    mixer reg 0x0C - 0x18 bit fields: Analog mixer input gain
*******************************************************************************
*/

#define AC97_MR_ANLG_MXR_IN_GAIN_MAX         0x00   // +12 dB gain
#define AC97_MR_ANLG_MXR_IN_GAIN_NONE        0x00   // no gain
#define AC97_MR_ANLG_MXR_IN_GAIN_MIN         0x1F   // -34.5 dB gain

#define AC97_MR_ANLG_MXR_IN_GAIN_MSK         0x1F   // For range checking

#define AC97_MR_ANLG_MXR_IN_GAIN_R_SHFT      0      // For Right side, no shift
#define AC97_MR_ANLG_MXR_IN_GAIN_L_SHFT      8      // For Left side, start at D8
#define AC97_MR_ANLG_MXR_IN_GAIN_MIC_SHFT    0      // For MIC, no shift needed.
#define AC97_MR_ANLG_MXR_IN_GAIN_BST_SHFT    6      // For MIC 20 dB boost

/*
*******************************************************************************
    mixer reg 0x1A bit field (Record Select)
*******************************************************************************
*/

#define AC97_MR_REC_SEL_MIC            0   // Same for L+R
#define AC97_MR_REC_SEL_CD_IN          1
#define AC97_MR_REC_SEL_VIDEO_IN       2
#define AC97_MR_REC_SEL_AUX_IN         3
#define AC97_MR_REC_SEL_LINE_IN        4
#define AC97_MR_REC_SEL_STEREO_MIX     5
#define AC97_MR_REC_SEL_MONO_MIX       6   // Same for L+R
#define AC97_MR_REC_SEL_PHONE          7   // Same for L+R

#define AC97_MR_REC_SEL_MAX            AC97_MR_REC_SEL_PHONE

#define AC97_MR_REC_SEL_MSK            7

#define AC97_MR_REC_SEL_R_SHFT         0   // For Right side, no shift
#define AC97_MR_REC_SEL_L_SHFT         8   // For Left side, start at D8

/*
*******************************************************************************
    mixer reg 0x1C (stereo) and 0x1E (mic) bit field (Record Gain)
*******************************************************************************
*/

#define AC97_MR_REC_GAIN_NONE        0x00  // no gain
#define AC97_MR_REC_GAIN_MIN         0x00  // no gain
#define AC97_MR_REC_GAIN_MAX         0x0F  // +22.5 dB gain

#define AC97_MR_REC_GAIN_MSK         0x0F  // Supported bits mask

#define AC97_MR_REC_GAIN_R_SHFT      0     // For Right side, no shift
#define AC97_MR_REC_GAIN_L_SHFT      8     // For Left side, start at D8
#define AC97_MR_REC_GAIN_MIC_SHFT    0     // For MIC, no shift needed.

/*
*******************************************************************************
    mixer reg 0x20 bit definitions: General Purpose Register
*******************************************************************************
*/

#define AC97_MR_GPR_LPBK_ENAB      (1 <<  7)   // 1 = ADC DAC loopback enable

#define AC97_MR_GPR_MS_MIC_1       (0 <<  8)   // Mic select: Mic 1
#define AC97_MR_GPR_MS_MIC_2       (1 <<  8)   // Mic select: Mic 2
#define AC97_MR_GPR_MS_MSK         (1 <<  8) 

#define AC97_MR_GPR_MIX_MIX        (0 <<  9)   // Mono out select: mix
#define AC97_MR_GPR_MIX_MIC        (1 <<  9)   // Mono out select: mic
#define AC97_MR_GPR_MIX_MSK        (1 <<  9) 


#define AC97_MR_GPR_LD_ENAB        (1 << 12)    // 1 = Bass boost enable
#define AC97_MR_GPR_3D_ENAB        (1 << 13)    // 1 = 3D Stereo Enhancement on
#define AC97_MR_GPR_ST_ENAB        (1 << 14)    // 1 = Simulated Stereo on

#define AC97_MR_GPR_POP_PRE_3D     (0 << 15)    // PCM out path & mute, pre-3D   
#define AC97_MR_GPR_POP_POST_3D    (1 << 15)    // PCM out path & mute, pre-3D
#define AC97_MR_GPR_POP_MSK        (1 << 15)

#define AC97_MR_GPR_MSK            0xF380       // All valid bits

/*
*******************************************************************************
    mixer reg 0x22 bit definitions: 3D Control Register
*******************************************************************************
*/

#define AC97_MR_3D_CTRL_MAX_VAL   0x0F       // Max value for either bit field

#define AC97_MR_3D_CTRL_CR_SHFT   8          // Center control starts in D8
#define AC97_MR_3D_CTRL_DP_SHFT   0          // Depth control starts in D0

/*
*******************************************************************************
    mixer reg 0x26 standard bit definitions: Powerdown Status and Control
*******************************************************************************
*/

// Read-only
#define AC97_MR_PWRDN_ADC_RDY            (1 <<  0)
#define AC97_MR_PWRDN_DAC_RDY            (1 <<  1)
#define AC97_MR_PWRDN_ANL_RDY            (1 <<  2)
#define AC97_MR_PWRDN_REF_RDY            (1 <<  3)

#define AC97_MR_PWRDN_ALL_RDY            0x0F

// Read-write: 1 = power down.
// PR0, PR1 and PR2 must not be combined with each other in any way.
#define AC97_MR_PWRDN_PR0_PCM_IN         (1 <<  8)
#define AC97_MR_PWRDN_PR1_PCM_OUT        (1 <<  9)
#define AC97_MR_PWRDN_PR2_MXR_VREF_ON    (1 << 10)

#define AC97_MR_PWRDN_PR3_MXR_VREF_OFF   (1 << 11)
#define AC97_MR_PWRDN_PR4_ACLINK         (1 << 12)  // Note: loss of comm!
#define AC97_MR_PWRDN_PR5_INTL_CLK       (1 << 13)
#define AC97_MR_PWRDN_PR6_HP_AMP         (1 << 14)
#define AC97_MR_PWRDN_EAPD_EXT_AMP       (1 << 15)


#define AC97_MR_PWRDN_MSK           0xFF0F  // All valid bits
#define AC97_MR_PWRDN_WR_MSK        0xFF00  // All writeable bits

/*
*******************************************************************************