source: svn/trunk/newcon3bcm2_21bu/nexus/modules/frontend/common/include/nexus_frontend.h

/***************************************************************************
*     (c)2004-2011 Broadcom Corporation
*
*  This program is the proprietary software of Broadcom Corporation and/or its licensors,
*  and may only be used, duplicated, modified or distributed pursuant to the terms and
*  conditions of a separate, written license agreement executed between you and Broadcom
*  (an "Authorized License").  Except as set forth in an Authorized License, Broadcom grants
*  no license (express or implied), right to use, or waiver of any kind with respect to the
*  Software, and Broadcom expressly reserves all rights in and to the Software and all
*  intellectual property rights therein.  IF YOU HAVE NO AUTHORIZED LICENSE, THEN YOU
*  HAVE NO RIGHT TO USE THIS SOFTWARE IN ANY WAY, AND SHOULD IMMEDIATELY
*  NOTIFY BROADCOM AND DISCONTINUE ALL USE OF THE SOFTWARE.
*
*  Except as expressly set forth in the Authorized License,
*
*  1.     This program, including its structure, sequence and organization, constitutes the valuable trade
*  secrets of Broadcom, and you shall use all reasonable efforts to protect the confidentiality thereof,
*  and to use this information only in connection with your use of Broadcom integrated circuit products.
*
*  2.     TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
*  AND WITH ALL FAULTS AND BROADCOM MAKES NO PROMISES, REPRESENTATIONS OR
*  WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH RESPECT TO
*  THE SOFTWARE.  BROADCOM SPECIFICALLY DISCLAIMS ANY AND ALL IMPLIED WARRANTIES
*  OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE,
*  LACK OF VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET POSSESSION
*  OR CORRESPONDENCE TO DESCRIPTION. YOU ASSUME THE ENTIRE RISK ARISING OUT OF
*  USE OR PERFORMANCE OF THE SOFTWARE.
*
*  3.     TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL BROADCOM OR ITS
*  LICENSORS BE LIABLE FOR (i) CONSEQUENTIAL, INCIDENTAL, SPECIAL, INDIRECT, OR
*  EXEMPLARY DAMAGES WHATSOEVER ARISING OUT OF OR IN ANY WAY RELATING TO YOUR
*  USE OF OR INABILITY TO USE THE SOFTWARE EVEN IF BROADCOM HAS BEEN ADVISED OF
*  THE POSSIBILITY OF SUCH DAMAGES; OR (ii) ANY AMOUNT IN EXCESS OF THE AMOUNT
*  ACTUALLY PAID FOR THE SOFTWARE ITSELF OR U.S. $1, WHICHEVER IS GREATER. THESE
*  LIMITATIONS SHALL APPLY NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF
*  ANY LIMITED REMEDY.
*
* $brcm_Workfile: nexus_frontend.h $
* $brcm_Revision: 26 $
* $brcm_Date: 11/17/11 4:33p $
*
* API Description:
*   API name: Frontend
*    Generic Frontend APIs.
*
* Revision History:
*
* $brcm_Log: /nexus/modules/frontend/common/include/nexus_frontend.h $
* 
* 26   11/17/11 4:33p erickson
* SW3461-96: Remove GetLockStatus and replace it with GetFastStatus
* 
* 25   11/1/11 3:07p erickson
* SW3461-55: add NEXUS_Frontend_GetType, NEXUS_FrontendType,
*  NEXUS_FrontendChipType, and NEXUS_FrontendVersion
* 
* 24   10/13/11 4:28p erickson
* SW3461-55: add comment to deprecate/freeze NEXUS_FrontendUserParameters
* 
* 23   10/6/11 5:21p jtna
* SW7425-1327: add NEXUS_Frontend_Get/SetTransportSettings()
* 
* 22   10/6/11 9:53a jtna
* SW7425-1189: change NEXUS_Frontend_GetTsmfSettings() to return void
* 
* 21   10/5/11 12:23p jtna
* SW7425-1189: add transport and frontend TSMF support
* 
* 20   9/21/11 5:25p bandrews
* SW3461-53: add common GetLockStatus
* 
* 19   8/30/11 4:17p erickson
* SW7425-1129: add NEXUS_FrontendCapabilities.docsis
* 
* 18   1/26/11 11:08a jgarrett
* SW7125-769: Merge to main branch
* 
* SW7125-769/1   1/24/11 10:59a mward
* SW7125-769:  Add id, chipId, and chipRevision to
*  NEXUS_FrontendUserParameters.
* 
* 17   1/6/11 5:20p jhaberf
* SW35230-2441: Moved channel scan API to platform specific location
* 
* 16   9/10/10 4:21p erickson
* SW35230-1306: deprecate NEXUS_FrontendBandwidth. use unsigned integer
*  in units of Hz instead.
*
* 15   9/1/10 4:15p erickson
* SW7325-800: add NEXUS_FrontendCapabilities.diseqc and use for internal
*  configuration as well
*
* 14   9/1/10 3:48p jhaberf
* SW35230-1024: Merged SW35230-1024 branch into main line
*
* SW35230-1020/4   9/1/10 6:03p shyi
* SW35230-857: Adding ifFrequency to NEXUS_FrontendScanSettings to allow
*  applications to specify dynamically changing IF
*
* SW35230-1020/3   8/30/10 6:29p shyi
* SW35230-1020: Adding flexibility of specifying bandwidths to search
*
* SW35230-1020/2   8/26/10 12:01p shyi
* SW35230-1020: Added frequency scanning for DVB-T signal
*
* SW35230-1020/1   8/26/10 11:19a shyi
* SW35230-1020: Porting changes made under SW35230-900 to quickly prepare
*  release
*
* 12   7/21/09 10:00a erickson
* PR56958: fix NEXUS_Frontend_SetUserParameters, add comments to
*  NEXUS_Frontend_ScanFrequency
*
* 11   7/14/09 3:47p erickson
* PR56789: remove NEXUS_Frontend_SetPowerState. unimplemented and unused.
*
* 10   7/6/09 4:50p erickson
* PR56607: clarify comment on callbacks after NEXUS_Frontend_Untune
*
* 9   2/25/09 4:39p jgarrett
* PR 51839: Fix for kernel mode
*
* 8   8/5/08 11:25a erickson
* PR45427: add NEXUS_Frontend_Untune
*
* 7   3/14/08 12:55p jgarrett
* PR 40108: Adding NEXUS_Frontend_ScanFrequency
*
* 6   3/14/08 11:31a jgarrett
* PR 40109: Adding NEXUS_Frontend_ResetStatus
*
* 5   2/8/08 6:36p jgarrett
* PR 39408: Adding daughtercard support
*
* 4   2/7/08 5:35p jgarrett
* PR 39407: Converting to common close functions
*
* 3   1/23/08 8:37p vobadm
* PR35457: update docs
*
* 2   1/23/08 5:16p erickson
* PR35457: update docs
*
* 1   1/18/08 2:19p jgarrett
* PR 38808: Merging to main branch
*
* Nexus_Devel/6   1/10/08 2:33p jgarrett
* PR 38653: Initial version
*
* Nexus_Devel/5   11/5/07 2:58p erickson
* PR36725: remove Get and GetCount
*
* Nexus_Devel/4   10/10/07 11:29a jgarrett
* PR 35551: Adding IFD
*
* Nexus_Devel/3   10/5/07 5:51p jgarrett
* PR 35551: successful build
*
* Nexus_Devel/2   10/4/07 2:51p jgarrett
* PR 35551: Removing Register and Configuration -- part of device
*
* Nexus_Devel/1   10/4/07 2:41p jgarrett
* PR 35551: Adding initial version
*
***************************************************************************/
#ifndef NEXUS_FRONTEND_H__
#define NEXUS_FRONTEND_H__

#include "nexus_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/***************************************************************************
Summary:
Handle for a generic frontend object
***************************************************************************/
typedef struct NEXUS_Frontend *NEXUS_FrontendHandle;


#ifdef __cplusplus
}
#endif

#include "nexus_frontend_qam.h"
#include "nexus_frontend_vsb.h"
#include "nexus_frontend_satellite.h"
#include "nexus_frontend_ofdm.h"
#include "nexus_frontend_oob.h"
#include "nexus_frontend_upstream.h"
#include "nexus_frontend_analog.h"
#include "nexus_tuner.h"
#include "nexus_amplifier.h"
#include "nexus_ifd.h"
#include "nexus_frontend_card.h"

#ifdef __cplusplus
extern "C" {
#endif

/***************************************************************************
Summary:
Frontend Capabilities -- Allows capabilities of generic frontend objects to be queried by the application.
***************************************************************************/
typedef struct NEXUS_FrontendCapabilities
{
    bool powerDownSupported;                        /* If true, this tuner supports a power-down mode */
    bool analog;                                    /* If true, this tuner can support analog/NTSC tuning */
    bool ifd;                                       /* If true, this tuner can demodulate an analog signal with the IFD */
    bool qam;                                       /* If true, at least one QAM mode is supported */
    bool docsis;                                    /* If true, DOCSIS is supported */
    bool vsb;                                       /* If true, at least one VSB mode is supported */
    bool satellite;                                 /* If true, at least one satellite mode is supported */
    bool outOfBand;                                 /* If true, at least one out of band mode is supported */
    bool upstream;                                  /* If true, at least one upstream mode is supported */
    bool ofdm;                                      /* If true, OFDM modulation is supported */
    bool scan;                                      /* If true, NEXUS_Frontend_ScanFrequency is supported for this frontend */
    bool qamModes[NEXUS_FrontendQamMode_eMax];      /* For each QAM mode, the mode is supported if true and unsupported if false */
    bool vsbModes[NEXUS_FrontendVsbMode_eMax];      /* For each VSB mode, the mode is supported if true and unsupported if false */
    bool satelliteModes[NEXUS_FrontendSatelliteMode_eMax];  /* For each satellite mode, the mode is supported if true and unsupported if false */
    bool outOfBandModes[NEXUS_FrontendOutOfBandMode_eMax];  /* For each out-of-band mode, the mode is supported if true and unsupported if false */
    bool upstreamModes[NEXUS_FrontendUpstreamMode_eMax];    /* For each upstream mode, the mode is supported if true and unsupported if false */
    bool ofdmModes[NEXUS_FrontendOfdmMode_eMax];    /* For each OFDM mode, the mode is supported if true and unsupported if false */
    bool diseqc;
} NEXUS_FrontendCapabilities;

/***************************************************************************
Summary:
    Return a list of capabilities for a given frontend object.

Description:
    This call returns a list of capabilities for a frontend object.  Because
    many frontends support multiple types of modulation schemes, this
    allows the application to distinguish the capabilities of one tuner
    versus another.  If a tuner has multiple capabilities, only one of
    the modes may be used at any one time.
See Also:
    NEXUS_Frontend_Get
***************************************************************************/
void NEXUS_Frontend_GetCapabilities(
    NEXUS_FrontendHandle handle,
    NEXUS_FrontendCapabilities *pCapabilities   /* [out] */
    );

/***************************************************************************
Summary:
Frontend Soft Decisions
***************************************************************************/
typedef struct NEXUS_FrontendSoftDecision
{
    int16_t i;
    int16_t q;
} NEXUS_FrontendSoftDecision;

/***************************************************************************
Summary:
    Get an array of soft decisions for a constellation.

Description:
    I and Q range from 32767 to -32768 for all devices, however precision
    may vary per device.
***************************************************************************/
NEXUS_Error NEXUS_Frontend_GetSoftDecisions(
    NEXUS_FrontendHandle handle,
    NEXUS_FrontendSoftDecision *pDecisions, /* attr{nelem=length;reserved=100} [out, size_is(length)] array of soft decisions */
    size_t length                           /* number of NEXUS_FrontendSoftDecision's to get */
    );

/***************************************************************************
Summary:
Frontend User Parameters -- Optional values that platform may bind to a
                            specific device/channel to pass information
                            to the application (such as input band)
                            
This struct is deprecated. It should not be extended. If additional frontend
information is needed from the platform, the NEXUS_PlatformConfiguration struct should
be extended so the info can be communicated directly, not through a tunnel.
***************************************************************************/
typedef struct NEXUS_FrontendUserParameters
{
    int param1;
    void *pParam2;
    unsigned id; /* platform-assigned id for this frontend instance */
    uint16_t chipId; /* demod chip, in hex, e.g. 0x3117 */
    uint16_t chipRevision; /* demod chip revision, in hex, e.g. 0x0010 = A0, 0x0021 = B1 
                              0 = "not needed" or "not available" */
} NEXUS_FrontendUserParameters;

/***************************************************************************
Summary:
    Get user parameters provided by NEXUS_Frontend_SetUserParameters.

Description:
    This is an optional call that allows the platform layer to attach some
    user parameters to a frontend object.  The application can, in turn,
    retrieve these parameters to get some data from platform such as
    input band.
See Also:
    NEXUS_Frontend_SetUserParameters
***************************************************************************/
NEXUS_Error NEXUS_Frontend_GetUserParameters(
    NEXUS_FrontendHandle handle,
    NEXUS_FrontendUserParameters *pParams   /* [out] */
    );

/***************************************************************************
Summary:
    Set user parameters for a frontend.

Description:
    This is an optional call that allows the platform layer to attach some
    user parameters to a frontend object.  The application can, in turn,
    retrieve these parameters to get some data from platform such as
    input band.
See Also:
    NEXUS_Frontend_GetUserParameters
***************************************************************************/
NEXUS_Error NEXUS_Frontend_SetUserParameters(
    NEXUS_FrontendHandle handle,
    const NEXUS_FrontendUserParameters *pParams
    );


/***************************************************************************
Summary: 
Major/minor version code

Examples:
For silicon, 
major=0x01 and minor=0x00, denotes A0.
major=0x01 and minor=0x01, denotes A1.
major=0x02 and minor=0x02, denotes B2.

For firmware:
major=0x00 and minor=0x05, denotes 0.5.
major=0x01 and minor=0x01, denotes 1.1.
major=0x02 and minor=0x02, denotes 2.2.
***************************************************************************/
typedef struct NEXUS_FrontendVersion
{
    unsigned major;
    unsigned minor;
} NEXUS_FrontendVersion;

/***************************************************************************
Summary: Frontend Chip Info.
***************************************************************************/
typedef struct NEXUS_FrontendChipType
{
    unsigned familyId; /* Chip's family Id. In hex, e.g. 0x3128. */
    unsigned id;       /* Chip's Id or Bondout Id. In hex, e.g. 0x3128/ 0x3124/ 0x3123. */
    NEXUS_FrontendVersion version;
} NEXUS_FrontendChipType;

/***************************************************************************
Summary: Frontend Chip and Firmware Info.
***************************************************************************/
typedef struct NEXUS_FrontendType
{
    NEXUS_FrontendChipType chip;
    NEXUS_FrontendVersion firmwareVersion;
} NEXUS_FrontendType;

/***************************************************************************
Summary: 
    Retrieve the chip family id, chip id, chip version and firmware version.
***************************************************************************/
void NEXUS_Frontend_GetType(
    NEXUS_FrontendHandle handle,
    NEXUS_FrontendType *pType
    );

/***************************************************************************
Summary:
    Close a frontend handle
***************************************************************************/
void NEXUS_Frontend_Close(
    NEXUS_FrontendHandle handle
    );

/***************************************************************************
Summary:
    Reset state after a tune

Description:
    After this function is called, no new lock callback will be generated.
    It's possible that a pending lock callback will still be issued. If you cannot process another
    callback after NEXUS_Frontend_Untune, call NEXUS_StopCallbacks befor calling NEXUS_Frontend_Untune and
    call NEXUS_StartCallbacks from any subsequent Tune function.

    The demodulator and tuner cores may be reset or powered down as well.
***************************************************************************/
void NEXUS_Frontend_Untune(
    NEXUS_FrontendHandle handle
    );

/***************************************************************************
Summary:
    Reset accumulated status values for a frontend
***************************************************************************/
void NEXUS_Frontend_ResetStatus(
    NEXUS_FrontendHandle handle
    );

/***************************************************************************
Summary:
Frontend Lock Status
****************************************************************************/
typedef enum NEXUS_FrontendLockStatus
{           
    NEXUS_FrontendLockStatus_eUnknown,  /* no status available */
    NEXUS_FrontendLockStatus_eUnlocked, /* not locked, but there is a signal. */
    NEXUS_FrontendLockStatus_eLocked,   /* locked */
    NEXUS_FrontendLockStatus_eNoSignal, /* no signal; therefore not locked */
    NEXUS_FrontendLockStatus_eMax 
} NEXUS_FrontendLockStatus;

/***************************************************************************
Summary:
Status returned by NEXUS_Frontend_GetFastStatus
***************************************************************************/
typedef struct NEXUS_FrontendFastStatus {
    NEXUS_FrontendLockStatus lockStatus;
} NEXUS_FrontendFastStatus;

/***************************************************************************
Summary:
Get fast status for the frontend

Descriptoin:
Frontends may not populate all status.
Usually fast status happens from direct register reads from the SoC, 
not FW transactions.
***************************************************************************/
NEXUS_Error NEXUS_Frontend_GetFastStatus(
    NEXUS_FrontendHandle handle,
    NEXUS_FrontendFastStatus *pStatus /* [out] */
    );

/***************************************************************************
Summary:
Get current TSMF settings for a frontend
***************************************************************************/
void NEXUS_Frontend_GetTsmfSettings(
    NEXUS_FrontendHandle handle,
    NEXUS_TsmfSettings *pTsmfSettings  /* [out] */
    );

/***************************************************************************
Summary:
Set TSMF settings for a frontend
***************************************************************************/
NEXUS_Error NEXUS_Frontend_SetTsmfSettings(
    NEXUS_FrontendHandle handle,
    const NEXUS_TsmfSettings *pTsmfSettings
    );

/*********************************************************************************
Summary: 
NEXUS_FrontendTransportSettings 
**********************************************************************************/
typedef struct NEXUS_FrontendTransportSettings 
{   
    struct {
        unsigned virtualParserBandNum;
        bool virtualParserIsPlayback;
    } bandmap; /* parser band remapping */
} NEXUS_FrontendTransportSettings;

/***************************************************************************
Summary:
Get current parser band mapping for a tuner.
***************************************************************************/
void NEXUS_Frontend_GetTransportSettings(
    NEXUS_FrontendHandle handle,
    NEXUS_FrontendTransportSettings *pSettings  /* [out] */
    );

/***************************************************************************
Summary:
Set new parser band mapping for a tuner.
***************************************************************************/
NEXUS_Error NEXUS_Frontend_SetTransportSettings(
    NEXUS_FrontendHandle handle,
    const NEXUS_FrontendTransportSettings *pSettings
    );


/***************************************************************************
The NEXUS_FrontendBandwidth enum has been deprecated. It is an unsigned integer in units of Hz now.
The following #defines are for backward compatibility only.
***************************************************************************/
#define NEXUS_FrontendBandwidth_e5Mhz 5000000
#define NEXUS_FrontendBandwidth_e6Mhz 6000000
#define NEXUS_FrontendBandwidth_e7Mhz 7000000
#define NEXUS_FrontendBandwidth_e8Mhz 8000000
#define NEXUS_FrontendBandwidth_eMax  4

#ifdef __cplusplus
}
#endif

#endif /* #ifndef NEXUS_FRONTEND_H__ */