/*****************************************************************************
**
**             TEXAS INSTRUMENTS PROPRIETARY INFORMATION
**
**  (c) Copyright, Texas Instruments Incorporated, 2002-2004.
**      All Rights Reserved.
**
**  Property of Texas Instruments Incorporated. Restricted Rights -
**  Use, duplication, or disclosure is subject to restrictions set
**  forth in TI's program license agreement and associated documentation.
******************************************************************************/
/*************************************************************
* THIS PROGRAM IS PROVIDED "AS IS." TI MAKES NO WARRANTIES OR
* REPRESENTATIONS, EITHER EXPRESS, IMPLIED OR STATUTORY,
* INCLUDING ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE, LACK OF VIRUSES, ACCURACY OR
* COMPLETENESS OF RESPONSES, RESULTS AND LACK OF NEGLIGENCE.
* TI DISCLAIMS ANY WARRANTY OF TITLE, QUIET ENJOYMENT, QUIET
* POSSESSION, AND NON-INFRINGEMENT OF ANY THIRD PARTY
* INTELLECTUAL PROPERTY RIGHTS WITH REGARD TO THE PROGRAM OR
* YOUR USE OF THE PROGRAM.
*
* IN NO EVENT SHALL TI BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
* CONSEQUENTIAL OR INDIRECT DAMAGES, HOWEVER CAUSED, ON ANY
* THEORY OF LIABILITY AND WHETHER OR NOT TI HAS BEEN ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGES, ARISING IN ANY WAY OUT
* OF THIS AGREEMENT, THE PROGRAM, OR YOUR USE OF THE PROGRAM.
* EXCLUDED DAMAGES INCLUDE, BUT ARE NOT LIMITED TO, COST OF
* REMOVAL OR REINSTALLATION, COMPUTER TIME, LABOR COSTS, LOSS
* OF GOODWILL, LOSS OF PROFITS, LOSS OF SAVINGS, OR LOSS OF
* USE OR INTERRUPTION OF BUSINESS.  IN NO EVENT WILL TI'S
* AGGREGATE LIABILITY UNDER THIS AGREEMENT OR ARISING OUT OF
* YOUR USE OF THE PROGRAM EXCEED FIVE HUNDRED DOLLARS
* (U.S.$500).
*
* Unless otherwise stated, the Program is written and copyrighted
* by Texas Instruments is distributed as "freeware."  You may,
* only under TI's copyright in the Program, use and modify the
* Program without any charge or restriction.  You may
* distribute to third parties, provided that you transfer a
* copy of this license to the third party and the third party
* agrees to these terms by its first use of the Program.  In
* jurisdictions in which use is not deemed acceptance of these
* terms, no license is granted and no use is permitted.  You
* must reproduce the copyright notice and any other legend of
* ownership on each copy or partial copy of the Program.
*
* You acknowledge and agree that the Program contains
* copyrighted material, trade secrets and other TI proprietary
* information and is protected by copyright laws,
* international copyright treaties, and trade secret laws, as
* well as other intellectual property laws.  You agree that in
* no event will you alter, remove or destroy any copyright
* notice included in the Program.  TI reserves all rights not
* specifically granted under this license.  Except as 
* specifically provided herein, nothing in this agreement
* shall be construed as conferring upon you, by implication,
* estoppel, or otherwise, any license or other right under any
* TI patents, copyrights or trade secrets.
*************************************************************/
/**
 *
 * @file     adc.h
 *
 * @brief    Driver for AD9882 and AD9887. 
 *
 * This file contains type definitions, macros, and function 
 * prototypes necessary to drive the Analog Devices parts, AD9882
 * and AD9887. Many of the functions described here are called
 * by the AutoLock APIs and from the AutoLock task functions.
 * The majority, however, are provided for completeness. As the
 * AutoLock algorithm matures, functions may switch between
 * these two categories. The functions currently called by 
 * AutoLock are as follows:
 *
 * - ADC_CfgADC()
 * - ADC_InitADC()
 * - ADC_GetMaxSampleFreqInMHz()
 * - ADC_SetPhase()
 * - ADC_GetPhase()
 * - ADC_GetPhaseLimits()
 * - ADC_SetGain()
 * - ADC_GetGain() 
 * - ADC_GetGainLimits()
 * - ADC_SetOffset()
 * - ADC_GetOffset() 
 * - ADC_GetOffsetLimits() 
 * - ADC_SetGainAndOffset()
 * - ADC_SetInputHSYNCPolarity()
 * - ADC_SetActiveHSYNC()
 * - ADC_SetActiveVSYNC()
 * - ADC_SetRedClampLevel()
 * - ADC_SetBlueClampLevel()
 * - ADC_SetClampDuration()
 * - ADC_SetClampPlacement()
 * - ADC_SetPreCoast()
 * - ADC_SetPostCoast()
 * - ADC_SetSampleClock()
 * - ADC_SetPLLDivider()
 * - ADC_GetPLLDivider()
 * - ADC_GetPLLLimits()
 * - ADC_IsI2CDead()
 * 
 * Any OEM developed ADC drivers must include the functions
 * listed above. Descriptions of these functions' use can be
 * found in the documentation below. Note the supported
 * functions return a variety of error codes. OEM supplied
 * functions may limit return codes to PASS or FAIL. 
 *
 * This driver stores the ADC default values in an array
 * when the function ADC_InitADC() is called. Subsequent
 * calls to these driver functions will operate on the 
 * stored value followed by a register write rather than 
 * performing a register read-modify-write. Therefore, any
 * changes to register settings through any method other than
 * the use of these driver functions may be overwritten. 
 * 
 * It is recommended that OEM supplied drivers and OEM
 * application code make use of RTOS semaphores to reserve 
 * and protect communications resources. The implementation 
 * of this driver requires the successful reservation of the 
 * I2C bus resource semaphore before initiating an I2C transaction. 
 * This is a meaningless exercise unless the OEM application
 * respects semaphore ownership. The API function I2C_Init()
 * creates an I2C semaphore via a call to RTA_SemCreate(). The
 * semaphore ID can be obtained by calling I2C_GetSemaphoreID().  
 *
 * I2C communications are executed with the following I2C API 
 * function calls:
 *
 * - I2C_PolledMasterWrite()
 * - I2C_PolledMasterWriteRestartRead() 						
 *
 * Please refer to API documentation for descriptions of these
 * functions.
 */

#ifndef __ADC_H
#define __ADC_H

#ifdef __cplusplus
extern "C" {
#endif


/*****************************************************************************/
/* Error codes ***************************************************************/
/*****************************************************************************/

/* Error codes generated by the ADC driver */
#define ADC_FUNCTION_NOT_SUPPORTED		-1
#define ADC_FIELD_LIMITS_UNSPECIFIED	-2
#define ADC_VALUE_OOR_MIN				-3
#define ADC_VALUE_OOR_MAX				-4

/* Error code specifying an I2C driver error */
#define ADC_I2C_DRIVER_ERROR			-5
#define ADC_I2C_DRIVER_TERMINAL_ERROR   -8

/* Error code specifying RTA errors */
#define ADC_RTA_SEM_IN_USE				-6
#define ADC_RTA_ERROR		   		    -7

/*****************************************************************************/
/* Macros defining function arguments ****************************************/
/*****************************************************************************/

/* Color */
#define ADC_RED     0
#define ADC_GREEN   1
#define ADC_BLUE    2

/* Output drive level */
#define ADC_HIGH_DRIVE      3
#define ADC_MEDIUM_DRIVE    2
#define ADC_LOW_DRIVE       1

/* Pixel clock source */
#define ADC_INTERNAL_PCLK   0
#define ADC_EXTERNAL_PCLK   1

/* Output phase */
#define ADC_FIRST_PIXEL_ON_A    0
#define ADC_FIRST_PIXEL_ON_B    1

/* Output width */
#define ADC_24_BIT  0
#define ADC_48_BIT  1

/* Output mode */
#define ADC_INTERLEAVED  0
#define ADC_PARALLEL     1

/* Clamp source */
#define ADC_INTERNAL_CLAMP  0
#define ADC_EXTERNAL_CLAMP  1

/* External clamp polarity */
#define ADC_CLAMP_NEGATIVE    0
#define ADC_CLAMP_POSITIVE   1

/* Coast source */
#define ADC_EXTERNAL_COAST     0
#define ADC_INTERNAL_COAST  1

/* External coast polarity */
#define ADC_COAST_IN_NEGATIVE   0
#define ADC_COAST_IN_POSITIVE  1

/* Input HSYNC polarity */
#define ADC_HSYNC_IN_NEGATIVE   0
#define ADC_HSYNC_IN_POSITIVE   1

/* Output HSYNC polarity */
#define ADC_HSYNC_OUT_NEGATIVE   0
#define ADC_HSYNC_OUT_POSITIVE   1

/* Output VSYNC invert */
#define ADC_VSYNC_OUT_INVERTED      0
#define ADC_VSYNC_OUT_NOT_INVERTED  1

/* Clamp select */
#define ADC_CLAMP_TO_GROUND     0
#define ADC_CLAMP_TO_MIDLEVEL   1

/* Active HSYNC source */
#define ADC_HSYNC_SRCD_BY_HSYNC_INPUT   0
#define ADC_HSYNC_SRCD_BY_SOG_INPUT     1    

/* Active VSYNC source */
#define ADC_VSYNC_SRCD_BY_VSYNC_INPUT   0
#define ADC_VSYNC_SRCD_BY_SEPARATOR     1    

/* Video output mode */
#define ADC_VIDEO_OUT_444   0
#define ADC_VIDEO_OUT_422   1

/* Output power */
#define ADC_OUTPUTS_NOT_TRISTATED   0
#define ADC_OUTPUTS_TRISTATED       1

/* Active interface select mode */
#define ADC_AUTO_IF_SELECT    0
#define ADC_MANUAL_IF_SELECT  1