/******************************************************************************
*
*  File name:              zl5011xCet.h
*
*  Version:                42
*
*  Author:                 AOC
*
*  Date created:           1/11/2002
*
*  Copyright 2002, 2003, 2004, 2005, Zarlink Semiconductor Limited.
*  All rights reserved.
*  The timing algorithms implemented in the software code are Patent Pending.
*
*  Module Description:
*        This header file contains definitions of Functions, Data Structures,
*        Constants and Macro Functions used by Circuit Emulation Services
*
*
*  Revision History:
*
*  Rev:  Date:       Author:  Comments:
*  1     14/11/2002  AOC      initial version
*  2     14/11/2002  AOC      Removed static prototypes
*  3     21/11/2002  AOC      Added interrrupt code
*  4     28/01/2003  MRC      Added algorithms
*  5     07/02/2003  MRC      Added CET queue functionality
*  6     14/02/2003  MRC      Added out of band differential clock recovery
*  7     07/03/2003  MRC      Review actions
*  8     10/03/2003  MRC      Added inBand differential increment to structure
*  9     07/05/2003  MRC      Added extra slew filtering for adaptive mode
*  10    22/05/2003  MRC      Added packet loss holdover
*  11    11/06/2003  MRC      Added frequency lock state to adaptive mode
*  12    18/06/2003  MRC      Added transit time offset zero'ing to the
*                             frequency lock state
*  13    26/06/2003  MRC      Adaptive clock recovery always uses OS for timing
*  14    09/07/2003  MRC      Added adaptive holdover
*  15    21/07/2003  MRC      Updated parameters
*  16    25/07/2003  MRC      Added parameter to allow the averaging to be set
*                             to the maximum level for adaptive mode
*  17    29/07/2003  MRC      The internal definitions have been moved to file
*                             CetInternal.h
*  18    26/02/2004  APL      Functions added to allow adaptive holdover
*                             limits to be changed
*  19    23/03/2004  APL      Corrected file version history
*  20    20/04/2004  MRC      Merged from branch
*  21    21/04/2004  MRC      Allow packet payload size to be specified in bytes
*  22    05/05/2004  MRC      Renamed the enhanced variable for no timestamp
*  23    20/05/2004  MRC      Adding differential Rx/Tx mode
*  24    07/06/2004  MRC      Added check value for Differential mode
*  25    25/06/2004  MRC      Adaptive task delay is now performed in a
*                             seperate task to the processing
*  26    20/07/2004  MRC      Added clock recovery status functionality
*  27    20/10/2004  MRC      Added queue depth adjust functionality following a
*                             reset of the TDM queue.
*  28    20/10/2004  MRC      Added function to set ppm limit dynamically
*  29    03/11/2004  MRC      Added task priority constant
*  30    16/12/2004  MRC      Added timestamp increment variable to SetMode fn
*  31    28/01/2005  MRC      Added non CES clocking options
*  32    31/01/2005  MRC      Modified clocking function
*  33    07/02/2005  APL      Added control for mutual exclusion on device access
*  34    24/02/2005  MRC      Added statistics functions
*  35    25/02/2005  MRC      Renamed statistics variable
*  36    03/03/2005  MRC      Added async notification mechanism
*  37    09/03/2005  MRC      Added reconfigure function
*  38    14/03/2005  MRC      Added clock quality variable
*  39    17/03/2005  MRC      Added lost packets and max PDV stats
*  40    01/04/2005  MRC      Changed parameters to CET statistics fn
*  41    10/05/2005  MRC      Added option to resume lock
*  42    20/05/2005  MRC      Added variable to count number of adjusts
*
******************************************************************************/

#ifndef _ZL5011X_CET_H
#define _ZL5011X_CET_H

#ifdef __cplusplus
extern "C" {
#endif

/*****************   # DEFINES   **********************************************/

/* task settings */

#define ZL5011X_CET_TASK_PRIORITY                 60
#define ZL5011X_CET_TASK_STACK_SIZE               20000

#define ZL5011X_CET_DIFF_TASK_PRIORITY            70
#define ZL5011X_CET_DIFF_TASK_STACK_SIZE          20000

#define ZL5011X_CET_AD_TASK_PRIORITY              80
#define ZL5011X_CET_AD_TASK_STACK_SIZE            20000

#define ZL5011X_CET_AD_ENH_TASK_PRIORITY          200

#define ZL5011X_CET_DIFF_RX_TASK_PRIORITY         110
#define ZL5011X_CET_DIFF_RX_TASK_STACK_SIZE       20000
#define ZL5011X_CET_DIFF_MAX_FRACT_DIFFERENCE     (1 << 15)

#define ZL5011X_CET_QUEUE_TASK_PRIORITY           120
#define ZL5011X_CET_QUEUE_TASK_STACK_SIZE         20000

#define ZL5011X_CET_MOD_TASK_PRIORITY             130
#define ZL5011X_CET_MOD_TASK_STACK_SIZE           20000

/* misc settings */
#define ZL5011X_CET_QUEUE_SIZE                    100
#define ZL5011X_CET_MAX_NUMBER_DEVICES            16
#define ZL5011X_CET_MUTEX_TIMEOUT_MS              2000

#define ZL5011X_CET_MIN_PPM_LIMIT                 1
#define ZL5011X_CET_MAX_PPM_LIMIT                 200
#define ZL5011X_CET_DEFAULT_PPM_LIMIT             75

#define ZL5011X_CET_QUEUE_MIN_PERIOD_LIMIT_MS     20
#define ZL5011X_CET_QUEUE_MAX_PERIOD_LIMIT_MS     60000
#define ZL5011X_CET_QUEUE_DEFAULT_PERIOD_MS       1000

#define ZL5011X_CET_QUEUE_MAX_CONSECUTIVE_ADJUSTS 6

#define ZL5011X_CET_STATISTICS_NUM_BINS           6
#define ZL5011X_CET_STATISTICS_DELAY_AVERAGE      32

/*****************   DATA TYPES AND STRUCTURES   ******************************/

#define ZL5011X_CET_NUM_MODES   (ZL5011X_CET_DIFFERENTIAL_RX_TX + 1)

#define ZL5011X_CHECK_CET_MODE(X) \
            ((X < ZL5011X_CET_DISABLED) || (X > ZL5011X_CET_DIFFERENTIAL_RX_TX)) ? \
               ZL5011X_PARAMETER_INVALID : ZL5011X_OK

typedef enum
{
   ZL5011X_CET_DISABLED,
   ZL5011X_CET_DIFFERENTIAL_RX,
   ZL5011X_CET_DIFFERENTIAL_TX,
   ZL5011X_CET_DIFFERENTIAL_IN_BAND,
   ZL5011X_CET_ADAPTIVE,
   ZL5011X_CET_ADAPTIVE_ENHANCED,
   ZL5011X_CET_DIFFERENTIAL_RX_TX
} zl5011xCetModeE;

#define ZL5011X_CET_NUM_OSCILLATOR_TYPES    (ZL5011X_CET_OSCILLATOR_TCXO_FAST + 1)

#define ZL5011X_CHECK_OSCILLATOR_TYPE(X) \
            ((X < ZL5011X_CET_OSCILLATOR_OCXO) || (X > ZL5011X_CET_OSCILLATOR_TCXO_FAST)) ? \
               ZL5011X_PARAMETER_INVALID : ZL5011X_OK

typedef enum
{
   ZL5011X_CET_OSCILLATOR_OCXO,
   ZL5011X_CET_OSCILLATOR_TCXO,
   ZL5011X_CET_OSCILLATOR_TCXO_FAST
} zl5011xCetOscillatorTypeE;

#define ZL5011X_CHECK_CET_NETWORK_TYPE(X) \
            ((X < ZL5011X_CET_NETWORK_DEDICATED) || (X > ZL5011X_CET_NETWORK_LOOPBACK)) ? \
               ZL5011X_PARAMETER_INVALID : ZL5011X_OK

typedef enum
{
   ZL5011X_CET_NETWORK_DEDICATED,
   ZL5011X_CET_NETWORK_METROPOLITAN,
   ZL5011X_CET_NETWORK_CONTINENTAL,
   ZL5011X_CET_NETWORK_LOOPBACK
} zl5011xCetNetworkTypeE;

#define ZL5011X_CET_NUM_NETWORK_TYPES    (ZL5011X_CET_NETWORK_LOOPBACK + 1)

typedef enum
{
   ZL5011X_CET_STATUS_FREERUN,
   ZL5011X_CET_STATUS_HOLDOVER,
   ZL5011X_CET_STATUS_ACQUIRING,
   ZL5011X_CET_STATUS_ACQUIRED
} zl5011xCetStatusE;

typedef enum
{
   ZL5011X_CET_ADAPTIVE_FREQ_8HZ,
   ZL5011X_CET_ADAPTIVE_FREQ_4HZ,
   ZL5011X_CET_ADAPTIVE_FREQ_2HZ,
   ZL5011X_CET_ADAPTIVE_FREQ_1HZ,
   ZL5011X_CET_ADAPTIVE_FREQ_0_5HZ,
   ZL5011X_CET_ADAPTIVE_FREQ_0_25HZ,
   ZL5011X_CET_ADAPTIVE_FREQ_0_125HZ
} zl5011xCetAdaptiveFreqE;

#define ZL5011X_CHECK_CET_NOTIFICATION_TYPE(X) \
            ((X < ZL5011X_CET_STATUS_DISABLE) || (X > ZL5011X_CET_STATUS_ENABLE)) ? \
               ZL5011X_PARAMETER_INVALID : ZL5011X_OK

typedef enum
{
   ZL5011X_CET_STATUS_DISABLE,
   ZL5011X_CET_STATUS_STATE_CHANGE,
   ZL5011X_CET_STATUS_FLAG_CHANGE,
   ZL5011X_CET_STATUS_ENABLE
} zl5011xCetStatusNotificationE;

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

/* CET queue management structures / enums */

typedef enum
{
   ZL5011X_CET_QUEUE_DISABLE,
   ZL5011X_CET_QUEUE_ENABLE
} zl5011xCetQueueModeE;

typedef enum
{
   ZL5011X_CET_QUEUE_STATE_INIT,
   ZL5011X_CET_QUEUE_STATE_RUN
} zl5011xCetQueueStateE;

typedef struct
{
   zl5011xCetQueueModeE mode;
   zl5011xCetQueueStateE state;
   Uint32T resetPktDepth;
   Sint32T resetPktAdjust;
   Sint32T currPktAdjust;

   Uint32T prevUnderrun;
   Uint32T prevEarly;
   Uint32T prevLate;
   Uint32T prevSeq;
   zl5011xBooleanE prevEmpty;
   Sint32T prevAdjusts;
} zl5011xCetQueueS;

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

typedef struct
{
   zl5011xParamsS *zl5011xParams;
   Uint8T numStreams;
   Uint32T numContexts;

   zl5011xCetQueueS queue[ZL5011X_MAX_NUMBER_CONTEXTS];
} zl5011xCetExtensionDeviceS;

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

typedef struct
{
   /* number of devices supported by CET */
   Uint32T deviceCount;

   /* individual device settings */
   zl5011xCetExtensionDeviceS device[ZL5011X_CET_MAX_NUMBER_DEVICES];

   /* queue buffer management settings */
   OS_TASK_ID queueTaskId;
   Uint32T queueCurrDevice;
   Uint32T queueManagePeriodMs;

   /* clock recovery status change notification */
   OS_MSG_Q_ID clockStatusQueueId;
   zl5011xCetStatusNotificationE clockStatusMode;
   zl5011xBooleanE clockStatusHoldoverOnly;
} zl5011xCetExtensionTableS;

/*****************  DATA STRUCTURES and FUNCTION DECLARATIONS   **************/

typedef struct
{
   Uint32T unused;
} zl5011xCetAddDeviceS;

zlStatusE zl5011xCetAddDeviceStructInit(zl5011xParamsS *zl5011xParams,
      zl5011xCetAddDeviceS *par);
zlStatusE zl5011xCetAddDevice(zl5011xParamsS *zl5011xParams,
      zl5011xCetAddDeviceS *par);

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

typedef struct
{
   Uint32T unused;
} zl5011xCetRemoveDeviceS;

zlStatusE zl5011xCetRemoveDeviceStructInit(zl5011xParamsS *zl5011xParams,
      zl5011xCetRemoveDeviceS *par);
zlStatusE zl5011xCetRemoveDevice(zl5011xParamsS *zl5011xParams,
      zl5011xCetRemoveDeviceS *par);

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

typedef struct