/*******************************************************************************
*
*  File name:              zl5011xUtilLib.c
*
*  Version:                18
*
*  Author:                 MRC
*
*  Date created:           08/02/2002
*
*  Copyright 2002, 2003, 2004, 2005, Zarlink Semiconductor Limited.
*  All rights reserved.
*
*  Module Description:
*
*  This file contains common utility functions for checking parameters and
*  accessing the device.
*
*  Revision History:
*
*  Rev:  Date:       Author:  Comments:
*  1     08/02/2002  MRC      Creation
*  9     27/09/2002  DJA      SOS version updated
*                             File header updated
*  10    27/09/2002  JFE      Added definition for zl5011xSendFunctionReport
*  11    27/09/2002  JFE      Made changes to zl5011xSendFunctionReport
*  11    30/09/2002  JFE      Moved zl5011xSendFunctionReport to debug_src file
*  12    31/10/2002  MRC      Added variants + minor fixes
*  14    09/06/2003  DJA      SOS version updated
*                                         Performed pre-audit actions
*  15    08/08/2003  APL      Version number updated
*  16    11/02/2005  APL      zl5011xCheckStreamRange now allows use of
*                             auxiliary clock if device is non-CES variant
*  17    16/06/2005  APL      Specified initialiser for intDisableKey
*  18    04/07/2005  MRC      Added stream range check for clock only function
*
*******************************************************************************/

/*****************   INCLUDE FILES   ******************************************/

#include "zl5011x.h"
#include "zl5011xUtilLib.h"

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

 Function:
    zl5011xUpdateRegisters

 Description:
    This function will update some (or all) of the bits in the device and
    structure registers.

 Inputs:
    zl5011xParams            Pointer to the structure for this device instance
    addr                Device register address to be updated
    structureRegister   Structure register read and then updated
                            NULL may be specified in the situation where the
                        structure registers is not to be read (or updated)
    data                Bits to be updated
    mask                        Mask for bits to be changed. '1' should be written for
                        each bit updated
 Outputs:
    None

 Returns:
   zlStatusE

 Remarks:
    The function has 2 modes of operation, dependent on structureRegister.
    When this register is not NULL, the function will read the structure
    register, and use the mask and new bit values to update the structure
    and device registers. The structure is only updated after a successful
    write to the device.

    When structureRegister is NULL, the function will assume that newBits
    contains the entire new value of the register and will write it to the
    device. This mode permits the updating of the device alone.

    This function is not intended to be  used directly by the application. It
    is designed to be used by the API functions to reduce code duplication.

    Warning: This function assumes the structure and device are synchronisied.
             It will perform no synchronisation checking.

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

zlStatusE zl5011xUpdateRegisters(zl5011xParamsS *zl5011xParams, AddressT addr,
                                Uint32T *structureRegister, Uint32T data, Uint32T mask)
{
   zlStatusE status = ZL5011X_OK;
   Uint32T tmp;

   if (structureRegister != NULL)
   {
      /* Register bits are to be read from structure */
      tmp = (*structureRegister & ~mask) | (data & mask);
   }
   else
   {
      tmp = data;
   }

   status = zl5011xWrite(zl5011xParams, addr, tmp);
   if ((status == ZL5011X_OK) && (structureRegister != NULL))
   {
      *structureRegister =  tmp;
   }

   return (status);
}

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

Function:
   zl5011xReadModWrite

Description:
   Performs a Read / Modify / Write sequence to a single hardware register

Inputs:
   zl5011xParams     Pointer to the structure for this device instance
   addr                 Address to be updates
   data                 Value to be written
   mask                 Indicates which bits in the register are to be changed

Ouputs:
   None

Returns:
   zlStatusE

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

zlStatusE zl5011xReadModWrite(zl5011xParamsS *zl5011xParams, AddressT addr,
                             Uint32T data, Uint32T mask)
{
   zlStatusE status = ZL5011X_OK;
   Uint32T tmp;

   status = zl5011xRead(zl5011xParams, addr, &tmp);
   if (status == ZL5011X_OK)
   {
       tmp = (tmp & (~mask)) | (data & mask);
       status = zl5011xWrite(zl5011xParams, addr, tmp);
   }
   return (status);
}

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

 Function:
    zl5011xCheckClockRange

 Description:
    This function will check that the stream clock number is in range

 Inputs:
    zl5011xParams        Pointer to the structure for this device instance
    streamNumber        Stream number

 Outputs:
    None

 Returns:
    zlStatusE

 Remarks:
    None

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

zlStatusE zl5011xCheckClockRange(zl5011xParamsS *zl5011xParams, Uint8T streamNumber)
{
   zlStatusE status = ZL5011X_OK;

   /* the number of E1 streams gives the maximum available clock pins for this device */
   if (streamNumber >= zl5011xParams->devLimits.wanNumStreamsE1)
   {
      if (zl5011xParams->devLimits.cesAvailable == ZL5011X_FALSE)
      {
         /* non CES part, so auxiliary clock is a valid option */
         if (streamNumber != zl5011xParams->devLimits.wanAuxClockNum)
         {
            status = ZL5011X_STREAM_RANGE;
         }
      }
      else
      {  /* CES capable part, so stream must be less than number of device streams */
         status = ZL5011X_STREAM_RANGE;
      }
   }

   return status;
}

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

 Function:
    zl5011xCheckStreamRange

 Description:
    This function will check that the stream number is in range

 Inputs:
    zl5011xParams        Pointer to the structure for this device instance
    streamNumber        Stream number

 Outputs:
    None

 Returns:
    zlStatusE

 Remarks:
    None

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

zlStatusE zl5011xCheckStreamRange(zl5011xParamsS *zl5011xParams, Uint8T streamNumber)
{
   zlStatusE status = ZL5011X_OK;

   if (streamNumber >= zl5011xParams->wanIf.wanNumStreams)
   {
      if (zl5011xParams->devLimits.cesAvailable == ZL5011X_FALSE)
      {
         /* non CES part, so auxiliary clock is a valid option */
         if (streamNumber != zl5011xParams->devLimits.wanAuxClockNum)
         {
            status = ZL5011X_STREAM_RANGE;
         }
      }
      else
      {  /* CES capable part, so stream must be less than number of device streams */
         status = ZL5011X_STREAM_RANGE;
      }
   }

   return status;
}

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

 Function:
    zl5011xCheckChannelRange

 Description:
    This function will check that the channel number is in range

 Inputs:
    zl5011xParams        Pointer to the structure for this device instance
    channelNumber    Channel number

 Outputs:
    None

 Returns:
    zlStatusE

 Remarks:
    None

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

zlStatusE zl5011xCheckChannelRange(zl5011xParamsS *zl5011xParams, Uint8T channelNumber)
{
   if (channelNumber >= zl5011xParams->wanIf.wanNumChannels)
   {
      return(ZL5011X_CHANNEL_RANGE);
   }

   return (ZL5011X_OK);
}


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

Function:
   zl5011xCalcChanIndex

Description:
   This function calculates the index for the channel into the channel array.

Inputs:
   zl5011xParams Pointer to the structure for this device instance
   tdm              stream + channel

Outputs:
   tdmIndex         The index into the lookup tables for this slot

Returns:
   zlStatusE

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

zlStatusE zl5011xCalcChanIndex(zl5011xParamsS *zl5011xParams, zl5011xWanChannelS tdm,
                              Uint32T* tdmIndex)
{
   if (zl5011xParams->wanIf.wanNumChannels <= 32)
   {
      *tdmIndex = (tdm.stream << 5) + tdm.channel;
   }
   else
   {
      *tdmIndex = (tdm.stream << 7) + tdm.channel;
   }

   return (ZL5011X_OK);
}


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

Function:
   zl5011xCheckTdm

Description:
   This function checks that the stream and channel parameters have valid values
   and then calculates lutIndex and tdmSlot. lutIndex is the value used to
   index the lookup tables in the device hardware and the API structure. tdmSlot
   is a number that indicates the time that this slot will be accessed by the
   WAN interface.

Inputs:
   zl5011xParams     Pointer to the structure for this device instance
   tdm                  stream + channel

Outputs:
   tdmIndex             The index into the lookup tables for this slot

Returns:
   zlStatusE

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

zlStatusE zl5011xCheckTdm(zl5011xParamsS *zl5011xParams, zl5011xWanChannelS tdm,
                         Uint32T* tdmIndex)
{
   zlStatusE status = ZL5011X_OK;

   /* check if valid stream and channel and context */
   if (zl5011xCheckChannelRange(zl5011xParams, tdm.channel) != ZL5011X_OK)
   {
    return ZL5011X_CHANNEL_RANGE;
    }

   if (zl5011xCheckStreamRange(zl5011xParams, tdm.stream) != ZL5011X_OK)
   {
    return ZL5011X_STREAM_RANGE;
    }

   status = zl5011xCalcChanIndex(zl5011xParams, tdm, tdmIndex);

   return(status);
}


/*****************************************************************************
   Interrupt statics.

   intDisableKey        This is a return value from the OS when disabling the interrupt.
                        This value is kept, so that it can be used in subsequent calls to
                        enable the interrupt.

   intDisableLevel  This is used to hold the depth of interrupt disable.
                        i.e. when the level is 0, the interrupt is enabled.

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

static Uint32T intDisableKey = 0;
static Uint32T intDisableLevel = 0;

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

Function:
   zl5011xHostInterruptDisable

Description:
   Disables the interrupts on the host. This uses a counter to detect when the
   enables and disables are nested. That is, multiple disables may be called,
   then the interrupt will not be enabled until the enable function has been
   called a corresponding number of times.

Inputs:
   None

Outputs:
   None

Returns:
   zlStatusE

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

zlStatusE zl5011xHostInterruptDisable(void)
{
   zlStatusE status = ZL5011X_OK;

   if (intDisableLevel == 0)
   {
    intDisableKey = OS_INTERRUPT_LOCK();
    }

   intDisableLevel++;

   return (status);
}


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

Function:
   zl5011xHostInterruptEnable

Description:
   Enables the interrupts on the host. This uses a counter to detect when the
   enables and disables are nested. That is, multiple disables may be called,
   then the interrupt will not be enabled until the enable function has been
   called a corresponding number of times.

Inputs:
   None

Outputs:
   None

Returns:
   zlStatusE

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

zlStatusE zl5011xHostInterruptEnable(void)
{
   zlStatusE status = ZL5011X_OK;

   /* stop the level from going below 0. */
   if (intDisableLevel != 0)
   {
      intDisableLevel--;

      /* if the level is now 0, then the interrupts need to be enabled. */
      if (intDisableLevel == 0)
      {
        OS_INTERRUPT_UNLOCK(intDisableKey);
        }
   }

   return (status);
}



/*****************   END   ****************************************************/