* FUNCTION:         XsAc97CtrlLockAcLink
*
* DESCRIPTION:      Try to lock the AC Link for command/status accesses to a
*                   codec.
*
* INPUT PARAMETERS: None
*
* RETURNS:          TRUE if the attempt was successful; FALSE if not.
*
* GLOBAL EFFECTS:   If TRUE, the hardware indicator will show that the AC Link
*                   is locked until either a codec command or status I/O 
*                   operation has completed, or XsAc97CtrlReleaseAcLink 
*                   is called.
*
* ASSUMPTIONS:      
*
* CALLS:            
*
* CALLED BY:        
*
* PROTOTYPE:        BOOL XsAc97CtrlLockAcLink (void);
*
*******************************************************************************
*/

BOOL XsAc97CtrlLockAcLink (void)
{
    int status = TRUE;
    VUINT32 carTmp;

    carTmp = XsAc97CtrlRegsP->CAR;
    if (carTmp & XS_AC97CTRL_CAIP_MSK)  // "1" in CAIP bit means lock failed.
    {
        status = FALSE;
    }
    return (status);

} // XsAc97CtrlLockAcLink ()

/*
*******************************************************************************
*
* FUNCTION:         XsAc97CtrlReleaseAcLink
*
* DESCRIPTION:      Forced release of AC Link lock set by XsAc97CtrlLockAcLink
*
* INPUT PARAMETERS: None
*
* RETURNS:          None
*
* GLOBAL EFFECTS:   
*
* ASSUMPTIONS:      Only used if the link has been locked but SW does not
*                   initiate a command or status query I/O on the link.
*
* CALLS:            
*
* CALLED BY:        Probably never used.
*
* PROTOTYPE:        void XsAc97CtrlReleaseAcLink (void);
*
*******************************************************************************
*/

void XsAc97CtrlReleaseAcLink (void)
{
    XsAc97CtrlRegsP->CAR = XS_AC97CTRL_CAIP_MSK;
}


/*
*******************************************************************************
*
* FUNCTION:         XsAc97CtrlClearStatus 
*
* DESCRIPTION:      Clears the specified status indicator, if possible.  (Some
*                   are, by design, unclearable).  (Can't verify that the
*                   indication has cleared because the clearing mechanism
*                   is not always the same as the reporting mechanism.)
*
*                   Should not be used for status types that are currently in 
*                   use as interrupt triggers.
*
* INPUT PARAMETERS: XsAc97CtrlStatusIdT statusId: ID of indicator to clear
*
* RETURNS:          Success: 0 (ERR_NONE)
*                   Failure: ERR_T_ILLPARAM - Status indicator ID out of range
*
* GLOBAL EFFECTS:   1) Because the status indicator is cleared, it will not be 
*                       available to trigger an interrupt.
*                   2) If the specified status ID is invalid, an error is 
*                       logged in the error log and the context structure.
*
* ASSUMPTIONS:      - Assumes that interrupt protection exists when called.
*                   - We don't have to double-check the hardware by making sure
*                     that a clearable status actually cleared.
*
* CALLS:            
*
* CALLED BY:        
*
* PROTOTYPE:        UINT32 XsAc97CtrlGetStatus (XsAc97CtrlStatusIdT);
*
*******************************************************************************
*/


UINT32 XsAc97CtrlClearStatus (XsAc97CtrlStatusIdT statusId)
{
    UINT32                  status;
    XsAc97CtrlStatusEntryT* statusTableEntryP; 


    status = XsAc97CtrlRangeCheckStatusId (statusId);

    if (status)
    {
//        LOGERROR ( XsAc97CtrlContext.loggedError, 
  //          ERR_L_XSAC97CTRL,
    //        ERR_S_XSAC97CTRL_CLEAR_STATUS,
      //      status, 0, 0, 0)
    }
    else
    {
        statusTableEntryP = XsAc97CtrlStatusTable + statusId;

        // Clear the indication if it can be cleared
        // NULL clear register means it can't be cleared.
        if (statusTableEntryP->clearRegisterP)
        {   
            //  Write a shifted "1" to clear the status.  Don't "OR" it in.
            *statusTableEntryP->clearRegisterP = 
                1u << statusTableEntryP->clearBitShift;
        }
    }  // else (rangeCheckResult)

    return (status);

} // XsAc97CtrlClearStatus()




/*
*******************************************************************************
*
* FUNCTION:         XsAc97CtrlRangeCheckIntTypeId
*
* DESCRIPTION:      Report whether the interrupt type ID is valid.
*
* INPUT PARAMETERS: XsAc97CtrlIntIdT   intTypeId  - AC '97 interrupt type ID
*                                                   to range-check
*
* RETURNS:          Success: 0 (ERR_NONE)
*                   Failure: ERR_T_ILLPARAM  - Interrupt type ID out of range
*                            ERR_T_NOT_AVAIL - Interrupt type ID unsupported
*
* GLOBAL EFFECTS:   None
*
* ASSUMPTIONS:      None
*
* CALLS:            
*
* CALLED BY:        
*
* PROTOTYPE:        UINT32 XsAc97CtrlRangeCheckIntTypeId (XsAc97CtrlIntIdT);
*
*******************************************************************************
*/
UINT32 XsAc97CtrlRangeCheckIntTypeId (XsAc97CtrlIntIdT interruptTypeId)
{
    UINT32 status       = ERR_NONE;
    BOOL   isSupported;

    if ((interruptTypeId < 0 )|| (interruptTypeId > XS_AC97CTRL_INT_MAX))
    {
        status = ERR_T_ILLPARAM;
    }
    else
    {
        // Map interrupt type ID onto status IDs and get supported status
        isSupported = XsAc97CtrlStatusTable
            [ XsAc97CtrlIntToStatusTransTbl [ interruptTypeId ]]
            .intIsSupported;
        if (FALSE == isSupported)
        {
            status = ERR_T_NOT_AVAIL;
        }
    }
    return(status);

} // XsAc97CtrlRangeCheckIntTypeId ()

/*
*******************************************************************************
*
* FUNCTION:         XsAc97CtrlRangeCheckStatusId
*
* DESCRIPTION:      Report whether the status indicator ID is valid.
*
* INPUT PARAMETERS: XsAc97CtrlStatusIdT   statusIndicatorId  
*                                   - AC '97 status indicator ID to range-check
*
* RETURNS:          Success: 0 (ERR_NONE)
*                   Failure: ERR_T_ILLPARAM - Status indicator ID out of range
*
* GLOBAL EFFECTS:   None
*
* ASSUMPTIONS:      None
*
* CALLS:            
*
* CALLED BY:        
*
* PROTOTYPE:        UINT32 XsAc97CtrlRangeCheckStatusId (XsAc97CtrlStatusIdT);
*
*******************************************************************************
*/
UINT32 XsAc97CtrlRangeCheckStatusId (XsAc97CtrlStatusIdT statusIndicatorId)
{
    UINT32 status = ERR_NONE;
    if ((statusIndicatorId < 0 )|| (statusIndicatorId > XS_AC97CTRL_STAT_MAX))
    {
        status = ERR_T_ILLPARAM;
    }
    return(status);

} // XsAc97CtrlRangeCheckStatusId ()


/*
*******************************************************************************
*
* FUNCTION:         XsAc97CtrlSetStatusEntry
*
* DESCRIPTION:      Initialize one entry in the XsAc97CtrlStatusTable.
*                   Force to disabled, with no registered handler or param.
*                   All other entry values come from parameters.
*
* INPUT PARAMETERS: None
*
* RETURNS:          None
*
* GLOBAL EFFECTS:   None
*
* ASSUMPTIONS:      
*
* CALLS:            
*
* CALLED BY:        Only XsAc97CtrlSWInit
*
* PROTOTYPE:        void XsAc97CtrlSetStatusEntry ( XsAc97CtrlStatusEntryT*,
*                                                   INT,
*                                                   VUINT32*,
*                                                   INT,
*                                                   UINT32,
*                                                   INT,
*                                                   VUINT32*,
*                                                   INT);
*
*******************************************************************************
*/

// Helper function to initialize the entries in XsAc97CtrlStatusTable[].
// All entries are set to int disabled, with no registered handler or param.

static
void XsAc97CtrlSetStatusEntry ( XsAc97CtrlStatusEntryT* targetEntryP,
                                BOOL                    intIsSupported,
                                VUINT32*                enableRegisterP,
                                INT                     enableBitShift,
                                UINT32                  reportBitMaskGsr,
                                INT                     reportBitShiftGsr,
                                VUINT32*                clearRegisterP,
                                INT                     clearBitShift)
{
    targetEntryP->intIsSupported       = intIsSupported;
    targetEntryP->intIsEnabled         = FALSE;             // Forced
    targetEntryP->registeredParamP     = NULL;              // Forced
    targetEntryP->enableRegisterP      = enableRegisterP;
    targetEntryP->enableBitShift       = enableBitShift;
    targetEntryP->reportBitMaskGsr     = reportBitMaskGsr;
    targetEntryP->reportBitShiftGsr    = reportBitShiftGsr;
    targetEntryP->clearRegisterP       = clearRegisterP;
    targetEntryP->clearBitShift        = clearBitShift;

} // XsAc97CtrlSetStatusEntry()


UINT32 XsAc97CtrlGetStats (XsAc97CtrlCodecModemIdT targetCodec,
                                      XsAc97CtrlStatsT*       statsP)
{
    UINT32 status = ERR_NONE;

    if ((targetCodec < 0) || (targetCodec > XS_AC97CTRL_CM_ID_MAX))
    {
         status = ERR_T_ILLPARAM;
    }
    else
    {
        *statsP = XsAc97CtrlContext.statistics[targetCodec];
    }
    return(status);

} // XsAc97CtrlGetStats


UINT32 XsAc97CtrlClearStats (XsAc97CtrlCodecModemIdT targetCodec)
{
    UINT32 status = ERR_NONE;

    if ((targetCodec < 0) || (targetCodec > XS_AC97CTRL_CM_ID_MAX))
    {
         status = ERR_T_ILLPARAM;
    }
    else
    {
        memset (&XsAc97CtrlContext.statistics[targetCodec],
                0,
                sizeof (XsAc97CtrlContext.statistics[targetCodec]));
    }
    return(status);
    
} // XsAc97CtrlClearStats ()