source: svn/trunk/newcon3bcm2_21bu/dta/src/settop_api/bsettop_tuner_aob.h

/***************************************************************************
 *     Copyright (c) 2012, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile:  $
 * $brcm_Revision:  $
 * $brcm_Date: $
 *
 * Module Description:
 *
 * Revision History:
 *
 * $brcm_Log:  $
 *
 ***************************************************************************/

#ifndef BSETTOP_AOB_TUNER_H__
#define BSETTOP_AOB_TUNER_H__

#include "bsettop_types.h"
#include "btmr.h"

typedef enum btuner_aob_qpsk_mode
{
    eDvs167Qpsk,        /*Annex A*/
    eDvs178Qpsk,        /*Annex B, default*/
    ePod_Dvs167Qpsk,
    ePod_Dvs178Qpsk,
} btuner_aob_qpsk_mode;

typedef enum btuner_aob_SpectrumMode
{
    SpectrumMode_eAuto,         
    SpectrumMode_eNoInverted,   /* default? */
    SpectrumMode_eInverted
} btuner_aob_SpectrumMode;

typedef enum btuner_aob_BerInputSrc
{
    BerInputSrc_eRcvIChOutput,                  /* BERT input source is the receiver I-channel output */
    BerInputSrc_eRcvQChOutput,                  /* BERT input source is the receiver Q-channel output */
    BerInputSrc_eRcvIQChOutputIntrlv,   /* BERT input source is the receiver I-channel and Q-channel output interleaved */
    BerInputSrc_eFecOutput                              /* BERT input source is the FEC output, default? */
} btuner_aob_BerInputSrc;

typedef struct btuner_aob_params {
        btuner_aob_qpsk_mode mode;
        unsigned symbol_rate;
        btuner_aob_SpectrumMode spectrum;
        btuner_aob_BerInputSrc  ber_input_src;
        bool auto_acquire;
        bool no_signal;

        bool wait_for_lock;
        unsigned timeout; 
        /* TODO, may not need these callbacks */
        bsettop_callback lock_callback;         /* called when the tuner comes in or out of lock. call btuner_aob_get_status to determine
                                                                                   the state. */
        void *callback_context;                         /* passed as parameter to lock_callback */
        bsettop_callback cancel_callback;       /* Called so higher level software can cancel blocking operation. */
        void *cancel_callback_context;          /* passed as parameter to lock_callback */
        bool cancel;
} btuner_aob_params;

typedef struct btuner_aob_status {
        bool lock;                                                      /* Locked state */
        btuner_aob_qpsk_mode mode;                      /* Current QPSK mode */
        uint32_t snr;                                           /* converted from snrEstimate / 256 */

        bool isPowerSaverEnabled;           /* Enable=1, Disable=0 */
        //BAOB_ModulationType modType;        /* Modulation Type */
        uint32_t sysXtalFreq;               /* in Hertz, Sys. Xtal freq. */
        uint32_t symbolRate;                /* in Baud */
        bool isFecLock;                     /* lock=1, unlock=0 */
        bool isQamLock;                     /* lock=1, unlock=0 */
        int32_t snrEstimate;                /* in 1/256 db */
        int32_t agcIntLevel;                /* in 1/10 percent */
        int32_t agcExtLevel;                /* in 1/10 percent */
        int32_t carrierFreqOffset;          /* in 1/1000 Hz */
        int32_t carrierPhaseOffset;         /* in 1/1000 Hz */
        uint32_t uncorrectedCount;          /* not self-clearing  */
        uint32_t correctedCount;            /* not self-clearing*/
        uint32_t berErrorCount;             /* not self-clearing */
} btuner_aob_status;

typedef struct btuner_aob *btuner_aob_t;

#ifdef __cplusplus
extern "C"
{
#endif

/*
Summary:
        Open an AOB tuner.

Description:
        On most platforms, the tuner_id is simply an index of the tuners.

        On platforms with more frontend options (e.g. 97038), please see bsettop_ids.txt 
        for documentation on special numbers.
        
*/
btuner_aob_t btuner_aob_open( bobject_t tuner_id        /* - handle used to identify a particular tuner */);

/*
Summary:
        Close an AOB tuner.
*/
void btuner_aob_close( btuner_aob_t tuner_aob   /* - handle returned by btuner_open */);

/*
Summary:
        Required to initialize VSB parameters to defaults
*/
void btuner_aob_params_init(
        btuner_aob_t tuner_aob,                 /* - required for possible resource-dependent defaults */
        btuner_aob_params *aob_params   /* - [out] */
);

/*
Summary:
        Tune and acquire an OOB channel
*/
bband_t btuner_aob_tune(
        btuner_aob_t tuner_aob,
        unsigned int freq,
        btuner_aob_params *aob_params    /* - parameters needed to tune and acquire */
);

/*
Summary:
        Get the status of OOB receiver
*/
bresult btuner_aob_get_status(
        btuner_aob_t tuner_aob,
        btuner_aob_status *status       /* - [out] Current status of the OOB */
);

typedef struct btuner_aob_softdecision {
        int16_t i;      
        int16_t q;
} btuner_aob_softdecision_t;

/*
 * Summary:
 *      Get an arry of soft decision for a constellation for OOB channel
 * Description:
 *      I and Q range from 32767 to -32768 for all devices
 */
bresult btuner_aob_get_softdecisions(
        btuner_aob_t tuner_aob, 
        btuner_aob_softdecision_t *pdec,        /* - [out] array of soft decisions */
        size_t length                                           /* number of soft decisions to get */
);

/* enable TUNER_AOB_TEST to compile test function in */
#ifdef TUNER_AOB_TEST
void btuner_aob_tune_test(unsigned int freq, int mode);
#endif

/*
 * Summary:
 *      get tuned frequency
 * Description:
 *      get tuned frequency
 */
uint32_t btuner_aob_get_frequency(btuner_aob_t tuner_aob);

/*
 * Summary:
 *      reset OOB tuner status
 * Description:
 *      reset OOB tuner status
 */
bresult btuner_aob_reset_status(btuner_aob_t tuner_aob);

#ifdef __cplusplus
}
#endif

#endif /* BSETTOP_AOB_TUNER_H__ */