Function:
   zl5011xContextAddChannelTx

 Description:
   Adds a channel to a context.

 Inputs:
   zl5011xParams   Pointer to the structure for this device instance
   par            Pointer to the structure for configuration items. See below:

 Structure inputs:
   context        context to be used
   tdm.stream     the stream that the channel to be added is from
   tdm.channel    which channel to add
   underrunMode   for structured operation, the behaviour on packet underrun
                  can be set to repeat or playout a fixed pattern
   underrunByte   the fixed pattern to playout during underrun
   osExclusionEnable ZL5011X_TRUE to enable OS exclusion

 Structure outputs:
   None

 Returns:
   zlStatusE

 Remarks:
   None

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

zlStatusE zl5011xContextAddChannelTx(zl5011xParamsS *zl5011xParams,
      zl5011xContextAddChannelTxS *par)
{
   zlStatusE status = ZL5011X_OK;
   Uint32T loop, chanIndex;
   zl5011xWanChannelS tdm;
   zl5011xBooleanE gotDevice = ZL5011X_FALSE;

   /* do some parameter checking */
   status = ZL5011X_CHECK_POINTERS(zl5011xParams, par);

   if (status == ZL5011X_OK)
   {
      status = ZL5011X_CHECK_RUNNING(zl5011xParams);
   }

   if ((status == ZL5011X_OK) && (par->osExclusionEnable == ZL5011X_TRUE))
   {
      /* get access to the device */
      status = zl5011xGetDevice(zl5011xParams, ZL5011X_GET_DEVICE_TIMEOUT_MODE);

      if (status == ZL5011X_OK)
      {
         gotDevice = ZL5011X_TRUE;
      }
   }

   /* check that the Wan Tx context is valid */
   if (status == ZL5011X_OK)
   {
      status = zl5011xContextCheckTx(zl5011xParams, par->context, ZL5011X_CHECK_CONTEXT_MODIFY);
   }

   /* main function code starts */

   if (status == ZL5011X_OK)
   {
      ZL5011X_TRACE_CONTEXT(ZL5011X_TDM_FN_ID, par->context,
            "zl5011xContextAddChannelTx: ctxt %3d",
            par->context, 0, 0, 0, 0, 0);
   }

   if (par->checkChannelCombination == ZL5011X_TRUE)
   {
      if (status == ZL5011X_OK)
      {
         /* check that a valid stream / channel combination has been provided before
            making any further checks */
         status = zl5011xCheckTdm(zl5011xParams, par->tdm, &chanIndex);
      }

      tdm.channel = par->tdm.channel;

      /* check that no other channels of this number have been configured so far */
      for (loop = 0; loop < zl5011xParams->wanIf.wanNumStreams; loop++)
      {
         if (status != ZL5011X_OK)
         {
            break;
         }

         tdm.stream = (Uint8T)loop;
         status = zl5011xCalcChanIndex(zl5011xParams, tdm, &chanIndex);

         if (status == ZL5011X_OK)
         {
            if (zl5011xParams->wanIf.tfmCurrent.channel[chanIndex].context == par->context)
            {
               if (par->tdm.stream != tdm.stream)
               {
                  status = ZL5011X_CHANNEL_INVALID;
               }
            }
         }
      }
   }

   if (status == ZL5011X_OK)
   {
      status = zl5011xTfmAddChan(zl5011xParams, par->context, par->tdm);
   }

   if (status == ZL5011X_OK)
   {
      /* the channel defaults to the last byte when added by the TFM.
         If the underrun byte is specified, then set it */
      if (par->underrunMode == ZL5011X_WAN_USE_FIXED_BYTE)
      {
         status = zl5011xTfmSetChanUnderrun(zl5011xParams, par->tdm,
               par->underrunByte, par->underrunMode);
      }
   }

   if (gotDevice == ZL5011X_TRUE)
   {
      if (status == ZL5011X_OK)
      {
         status = zl5011xReleaseDevice(zl5011xParams);
      }
      else
      {
         /* already have an error code, so don't overwrite it */
         (void)zl5011xReleaseDevice(zl5011xParams);
      }
   }

   return status;
}

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

 Function:
   zl5011xWanTxQueueConfigStructInit

 Description:
   Initialises structure used by zl5011xWanTxQueueConfig function.

 Inputs:
   zl5011xParams   Pointer to the structure for this device instance
   par            Pointer to the structure for configuration items.
                  See main function

 Returns:
   zlStatusE

 Remarks:
   None

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

zlStatusE zl5011xWanTxQueueConfigStructInit(zl5011xParamsS *zl5011xParams,
      zl5011xWanTxQueueConfigS *par)
{
   zlStatusE status = ZL5011X_OK;

   /* do some parameter checking */
   status = ZL5011X_CHECK_POINTERS(zl5011xParams, par);

   if (status == ZL5011X_OK)
   {
      ZL5011X_TRACE(ZL5011X_TDM_FN_ID,
            "zl5011xWanTxQueueConfigStructInit:",
            0, 0, 0, 0, 0, 0);

      par->context = (Uint32T)ZL5011X_INVALID_CONTEXT;

      par->queueSize = ZL5011X_WAN_TX_QUEUE_SIZE_4;
      par->queueMode = ZL5011X_WAN_TX_QUEUE_RESEQUENCE_8;

      /* default setting for the jitter buffer of 3 frames.
         That is 3 * 125us, since 1 frame @ 8kHz is 125 micro-seconds */
      par->jitterBufferSizeUs = 3 * 125;
      par->osExclusionEnable = ZL5011X_TRUE;
   }

   return status;
}

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

 Function:
   zl5011xWanTxQueueConfig

 Description:
   Configures a Wan Tx queue. Packet memory for the queue is allocated from the
   packet memory heap for the device.

 Inputs:
   zl5011xParams   Pointer to the structure for this device instance
   par            Pointer to the structure for configuration items. See below:

 Structure inputs:
   context        context to be used
   queueMode      sets the mode of the queue - FIFO or resequencing
   queueSize      sets how large the queue should be in packets.
                  i.e. queue size in frames = queue size * frames per packet
                       queue size in us = queue size in frames * 125
                  The queue size should be sufficient to handle the expected
                  packet delay variation, and the jitter buffer size is used
                  to set the initial depth of the queue.
   jitterBufferSizeUs   the jitter buffer is used to set the initial queue
                        depth in micro-seconds (us). Each frame is 125us.
   osExclusionEnable ZL5011X_TRUE to enable OS exclusion

 Structure outputs:
   None

 Returns:
   zlStatusE

 Remarks:
   At initialisation time, each queue is marked as uninitialised. When a queue
   is configured, memory from the heap is used. This remains allocated to this
   queue until it is reconfigured. That is tearing down a queue DOES NOT free
   up the memory used by the queue.
   The queue can only be configured when the context is in the INIT state.

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

zlStatusE zl5011xWanTxQueueConfig(zl5011xParamsS *zl5011xParams,
      zl5011xWanTxQueueConfigS *par)
{
   zlStatusE status = ZL5011X_OK;
   Uint32T queueSizeBytes, queueBaseAddress;
   zl5011xBooleanE gotDevice = ZL5011X_FALSE;

   /* do some parameter checking */
   status = ZL5011X_CHECK_POINTERS(zl5011xParams, par);

   if (status == ZL5011X_OK)
   {
      status = ZL5011X_CHECK_RUNNING(zl5011xParams);
   }

   if ((status == ZL5011X_OK) && (par->osExclusionEnable == ZL5011X_TRUE))
   {
      /* get access to the device */
      status = zl5011xGetDevice(zl5011xParams, ZL5011X_GET_DEVICE_TIMEOUT_MODE);

      if (status == ZL5011X_OK)
      {
         gotDevice = ZL5011X_TRUE;
      }
   }

   /* check that the Wan Tx context is valid */
   if (status == ZL5011X_OK)
   {
      status = zl5011xContextCheckTx(zl5011xParams, par->context, ZL5011X_CHECK_CONTEXT_INIT);
   }

   /* main function code starts */

   if (status == ZL5011X_OK)
   {
      ZL5011X_TRACE_CONTEXT(ZL5011X_TDM_FN_ID, par->context,
            "zl5011xWanTxQueueConfig: ctxt %3d",
            par->context, 0, 0, 0, 0, 0);
   }

   if (status == ZL5011X_OK)
   {
      status = ZL5011X_CHECK_WAN_TX_QUEUE_SIZE(par->queueSize);
   }

   if (status == ZL5011X_OK)
   {
      if (zl5011xParams->wanIf.txQueue[par->context].queueBaseAddress != (Uint32T)ZL5011X_NOT_INITIALISED)
      {
         /* if the queue has already been initialised then free the currently
            allocated memory */
         status = zl5011xMmFree(zl5011xParams, zl5011xParams->wanIf.txQueue[par->context].queueBaseAddress);

         if (status == ZL5011X_OK)
         {
            /* if the queue was free'd, then keep track in the structure */
            zl5011xParams->wanIf.txQueue[par->context].queueBaseAddress = (Uint32T)ZL5011X_NOT_INITIALISED;
         }
      }
   }

   if (status == ZL5011X_OK)
   {
      /* calculate the required queue size */
      queueSizeBytes = ZL5011X_1BIT_MASK << par->queueSize;
      queueSizeBytes *= ZL5011X_TFQ_MESSAGE_SIZE_WORDS;

      /* convert this to bytes from 32 bit words */
      queueSizeBytes *= sizeof(Uint32T);
   }

   if (status == ZL5011X_OK)
   {
      status = zl5011xMmAlloc(zl5011xParams, queueSizeBytes, &queueBaseAddress);
   }

   if (status == ZL5011X_OK)
   {
      status = zl5011xTfqConfigure(zl5011xParams, par->context, queueBaseAddress,
            par->queueSize, par->queueMode);

      if (status != ZL5011X_OK)
      {
         /* failed to configure the queue, so free up the memory that was
            previously allocated. Ignore the return code from the free fn */
         (void)zl5011xMmFree(zl5011xParams, queueBaseAddress);
      }
   }

   if (status == ZL5011X_OK)
   {
      /* set the TFQ averager to a value that gives resolution to .5 packet */
      status = zl5011xTfqSetACP(zl5011xParams, par->context, ZL5011X_WAN_TX_QUEUE_AVG_512);
   }

   if (status == ZL5011X_OK)
   {
      status = zl5011xTfmSetJitterBufferTime(zl5011xParams, par->context, par->jitterBufferSizeUs);
   }

   if (status == ZL5011X_OK)
   {
      zl5011xParams->wanIf.txQueue[par->context].queueInitialised = ZL5011X_TRUE;
   }

   if (gotDevice == ZL5011X_TRUE)
   {
      if (status == ZL5011X_OK)
      {
         status = zl5011xReleaseDevice(zl5011xParams);
      }
      else
      {
         /* already have an error code, so don't overwrite it */
         (void)zl5011xReleaseDevice(zl5011xParams);
      }
   }

   return status;
}

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

 Function:
   zl5011xContextRemoveChannelRxStructInit

 Description:
   Initialises structure used by zl5011xContextRemoveChannelRx function.

 Inputs:
   zl5011xParams   Pointer to the structure for this device instance
   par            Pointer to the structure for configuration items.
                  See main function

 Returns:
   zlStatusE

 Remarks:
   None

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

zlStatusE zl5011xContextRemoveChannelRxStructInit(zl5011xParamsS *zl5011xParams,
      zl5011xContextRemoveChannelS *par)
{
   zlStatusE status = ZL5011X_OK;

   /* do some parameter checking */
   status = ZL5011X_CHECK_POINTERS(zl5011xParams, par);

   if (status == ZL5011X_OK)
   {
      ZL5011X_TRACE(ZL5011X_TDM_FN_ID,
            "zl5011xContextRemoveChannelRxStructInit:",
            0, 0, 0, 0, 0, 0);

      par->context = (Uint32T)ZL5011X_INVALID_CONTEXT;
      par->tdm.stream = (Uint8T)ZL5011X_INVALID_STREAM;
      par->tdm.channel = (Uint8T)ZL5011X_INVALID_CHANNEL;
      par->osExclusionEnable = ZL5011X_TRUE;
   }

   return status;
}

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

 Function:
   zl5011xContextRemoveChannelRx

 Description:
   Removes a channel from a context.

 Inputs:
   zl5011xParams   Pointer to the structure for this device instance
   par            Pointer to the structure for configuration items. See below:

 Structure inputs:
   context        context to be used