source: svn/trunk/newcon3bcm2_21bu/nexus/modules/frontend/common/src/nexus_frontend.c

/***************************************************************************
*     (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.c $
* $brcm_Revision: 32 $
* $brcm_Date: 11/17/11 4:43p $
*
* API Description:
*   API name: Frontend
*    Generic Frontend APIs.
*
* Revision History:
*
* $brcm_Log: X:/win_views/7425_3.5/nexus/modules/frontend/common/src/nexus_frontend.c $
* 
* 32   11/17/11 4:43p vishk
* SW3461-96: Remove GetLockStatus and replace it with GetFastStatus
* 
* 31   11/1/11 3:09p vishk
* SW3461-55: Means of returning BCM3461 chip revsion and firmware
*  revision via NEXUS i/f
* 
* 30   10/6/11 5:21p jtna
* SW7425-1327: add NEXUS_Frontend_Get/SetTransportSettings()
* 
* 29   10/6/11 9:53a jtna
* SW7425-1189: change NEXUS_Frontend_GetTsmfSettings() to return void
* 
* 28   10/5/11 12:24p jtna
* SW7425-1189: add transport and frontend TSMF support
* 
* 27   9/21/11 5:26p vishk
* SW3461-53: 3461 interrupt line 'stuck low' after multiple tune events.
* 
* 26   1/6/11 7:42p shyi
* SW35230-2441: Moved out channel scan API to platform specific location
* 
* 25   11/18/10 11:39a mward
* SW7125-737:  In NEXUS_Frontend_Close(), don't automatically untune if
*  frontends are defined for standby.  Explicit untune should be used for
*  increased flexibility.
* 
* 24   9/2/10 11:45a shyi
* SW35230-1020: Merging to main branch
* 
* SW35230-1020/1   8/26/10 12:01p shyi
* SW35230-1020: Added frequency scanning for DVB-T signal
* 
* 23   8/20/09 4:48p erickson
* PR57770: convert FTM extension into more generic customer extension
*
* 22   7/21/09 10:00a erickson
* PR56958: fix NEXUS_Frontend_SetUserParameters, add comments to
*  NEXUS_Frontend_ScanFrequency
*
* 21   7/21/09 9:00a erickson
* PR56765: add ftm state and uninit
*
* 20   7/14/09 3:47p erickson
* PR56789: remove NEXUS_Frontend_SetPowerState. unimplemented and unused.
*
* 19   7/8/09 3:13p erickson
* PR56607: remove unused NEXUS_Frontend_P_Register function
*
* 18   7/8/09 6:53a erickson
* PR56607: add optional registerExtension operator so that callbacks can
*  be recreated with the handle that the user gets. this allows
*  NEXUS_StopCallbacks to work.
*
* 17   7/2/09 2:29p haisongw
* PR52808: No  Untune() for upstream
*
* 16   6/24/09 9:37a erickson
* PR53078: add support for frontend handle extensions in 73xx public API
*  implementations
*
* 15   5/15/09 12:01p erickson
* PR54843: untune on close
*
* 14   5/11/09 4:29p erickson
* PR53078: get time of tune or resetStatus so that elapsed time can be
*  returned with status
*
* 13   2/23/09 3:42p katrep
* PR52409: Fixed error messages due AST during nexus shutdown
*
* 12   2/11/09 3:38p jgarrett
* PR 51457: Renaming destroy extension routine
*
* 11   1/23/09 3:32p jgarrett
* PR 51457: Adding frontend extension hooks for tuners and
*  frontends/demods
*
* 10   12/11/08 4:07p erickson
* PR49556: separate frontend power management into analog and digital,
*  guarantee correct refcnt
*
* 9   10/8/08 1:12a erickson
* PR40799: provided untune takes precedence over dummy acquire. needed
*  for power down.
*
* 8   10/2/08 11:27a erickson
* PR40799: add optional untune function pointer
*
* 7   8/5/08 11:25a erickson
* PR45427: add NEXUS_Frontend_Untune
*
* 6   4/11/08 9:53a erickson
* PR41246: convert BDBG_OBJECT_UNSET to BDBG_OBJECT_DESTROY if freeing
*  memory
*
* 5   3/14/08 12:55p jgarrett
* PR 40108: Adding NEXUS_Frontend_ScanFrequency
*
* 4   3/14/08 11:31a jgarrett
* PR 40109: Adding NEXUS_Frontend_ResetStatus
*
* 3   3/12/08 10:25a erickson
* PR39584: added BDBG_OBJECT_ASSERT's
*
* 2   2/7/08 5:36p jgarrett
* PR 39407: Converting to common close functions
*
* 1   1/18/08 2:19p jgarrett
* PR 38808: Merging to main branch
*
* Nexus_Devel/2   11/5/07 2:58p erickson
* PR36725: remove Get and GetCount
*
* Nexus_Devel/1   10/5/07 5:51p jgarrett
* PR 35551: Adding initial version
*
***************************************************************************/

#include "nexus_frontend_module.h"

BDBG_MODULE(nexus_frontend);

BDBG_OBJECT_ID(NEXUS_Frontend);

/***************************************************************************
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] */
    )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);
    BDBG_ASSERT(NULL != pCapabilities);

    *pCapabilities = handle->capabilities;
}

/***************************************************************************
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, /* [out, size_is(length)] array of soft decisions */
    size_t length                           /* number of NEXUS_FrontendSoftDecision's to get */
    )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);
    BDBG_ASSERT(NULL != handle->pDeviceHandle);
    BDBG_ASSERT(NULL != pDecisions);

    if ( NULL == handle->getSoftDecisions )
    {
        if ( handle->pParentFrontend )
        {
            return NEXUS_Frontend_GetSoftDecisions(handle->pParentFrontend, pDecisions, length);
        }
        else
        {
            return BERR_TRACE(BERR_NOT_SUPPORTED);
        }
    }
    else
    {
        return handle->getSoftDecisions(handle->pDeviceHandle, pDecisions, length);
    }
}

NEXUS_Error NEXUS_Frontend_GetUserParameters( NEXUS_FrontendHandle handle, NEXUS_FrontendUserParameters *pParams )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);
    BDBG_ASSERT(NULL != pParams);
    *pParams = handle->userParameters;
    return BERR_SUCCESS;
}

NEXUS_Error NEXUS_Frontend_SetUserParameters( NEXUS_FrontendHandle handle, const NEXUS_FrontendUserParameters *pParams )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);
    BDBG_ASSERT(NULL != pParams);
    handle->userParameters = *pParams;
    return BERR_SUCCESS;
}

void NEXUS_Frontend_P_Init(void)
{
}

NEXUS_FrontendHandle NEXUS_Frontend_P_Create(void *pDeviceHandle)
{
    NEXUS_FrontendHandle handle;
    BDBG_ASSERT(NULL != pDeviceHandle);
    handle = BKNI_Malloc(sizeof(NEXUS_Frontend));
    if ( NULL != handle )
    {
        BKNI_Memset(handle, 0, sizeof(NEXUS_Frontend));
        BDBG_OBJECT_SET(handle, NEXUS_Frontend);
        handle->pDeviceHandle = pDeviceHandle;
    }
    return handle;
}

void NEXUS_Frontend_P_Destroy(NEXUS_FrontendHandle handle)
{
    BDBG_OBJECT_DESTROY(handle, NEXUS_Frontend);
    BKNI_Free(handle);
}

/***************************************************************************
Summary:
    Close a frontend handle
***************************************************************************/
void NEXUS_Frontend_Close(
    NEXUS_FrontendHandle handle
    )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);
    BDBG_ASSERT(NULL != handle->close);
    if ( handle->numExtensions > 0 )
    {
        BDBG_ERR(("Can not close a frontend with open extensions."));
        BDBG_ASSERT(handle->numExtensions == 0);
    }

#if (0==(NEXUS_HOST_CONTROL_EXTERNAL_FRONTEND_STANDBY+NEXUS_HOST_CONTROL_INTERNAL_FRONTEND_STANDBY))
    /* These standby use cases need to separate untune and close. Otherwise... */
    /* untune before closing. may result in power savings. */
    NEXUS_Frontend_Untune(handle);
#endif

#ifdef NEXUS_FRONTEND_CUSTOMER_EXTENSION
    NEXUS_Frontend_P_UninitExtension(handle);
#endif

    handle->close(handle);
}

void NEXUS_Frontend_Untune( NEXUS_FrontendHandle handle )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);

    if ( handle->untune )
    {
        handle->untune(handle->pDeviceHandle);
    }
    else if ( handle->pParentFrontend && handle->pParentFrontend->untune )
    {
        NEXUS_Frontend_Untune(handle->pParentFrontend);
    }
    else
    {
        /* This is a simple way to reset the app callback. In the future, we may want
                a chip-specific way of reseting state. */
        if ( handle->capabilities.qam )
        {
            NEXUS_FrontendQamSettings settings;
            NEXUS_Frontend_GetDefaultQamSettings(&settings);
            (void)NEXUS_Frontend_TuneQam(handle, &settings);
        }
        else if ( handle->capabilities.vsb )
        {
            NEXUS_FrontendVsbSettings settings;
            NEXUS_Frontend_GetDefaultVsbSettings(&settings);
            (void)NEXUS_Frontend_TuneVsb(handle, &settings);
        }
        else if ( handle->capabilities.satellite )
        {
            NEXUS_FrontendSatelliteSettings settings;
            NEXUS_Frontend_GetDefaultSatelliteSettings(&settings);
            settings.frequency=950000000UL;
            (void)NEXUS_Frontend_TuneSatellite(handle, &settings);
        }
        else if ( handle->capabilities.ofdm )
        {
            NEXUS_FrontendOfdmSettings settings;
            NEXUS_Frontend_GetDefaultOfdmSettings(&settings);
            (void)NEXUS_Frontend_TuneOfdm(handle, &settings);
        }
        else if ( handle->capabilities.analog )
        {
            NEXUS_FrontendAnalogSettings settings;
            NEXUS_Frontend_GetDefaultAnalogSettings(&settings);
            (void)NEXUS_Frontend_TuneAnalog(handle, &settings);
        }
        else if ( handle->capabilities.outOfBand )
        {
            NEXUS_FrontendOutOfBandSettings settings;
            NEXUS_Frontend_GetDefaultOutOfBandSettings(&settings);
            (void)NEXUS_Frontend_TuneOutOfBand(handle, &settings);
        }
        else if ( handle->capabilities.upstream )
        {
            /* no untune for upstream*/
        }
        else
        {
            BDBG_ERR(("Unable to untune. No tuner capabilities found."));
        }
    }
}

/***************************************************************************
Summary:
    Reset status values for a frontend
***************************************************************************/
void NEXUS_Frontend_ResetStatus(
    NEXUS_FrontendHandle handle
    )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);
    NEXUS_Time_Get(&handle->resetStatusTime);
    if ( handle->resetStatus )
    {
        handle->resetStatus(handle->pDeviceHandle);
    }
    else if ( handle->pParentFrontend )
    {
        NEXUS_Frontend_ResetStatus(handle->pParentFrontend);
    }
}

/***************************************************************************
Summary:
    Get the Synchronous lock status of a frontend.
 ***************************************************************************/
NEXUS_Error NEXUS_Frontend_GetFastStatus(
    NEXUS_FrontendHandle handle,
    NEXUS_FrontendFastStatus *pStatus 
    )
{
    BDBG_ASSERT(NULL != handle);

    if ( NULL == handle->getFastStatus )
    {
        if ( handle->pParentFrontend )
        {
            return NEXUS_Frontend_GetFastStatus(handle->pParentFrontend, pStatus);
        }
        else
        {
            return BERR_TRACE(BERR_NOT_SUPPORTED);
        }
    }
    else
    {
        return handle->getFastStatus(handle->pDeviceHandle, pStatus);
    }
}

/***************************************************************************
Summary:
    Retrieve the chip family id, chip id, chip version and firmware version.
 ***************************************************************************/
void NEXUS_Frontend_GetType(
    NEXUS_FrontendHandle handle,
    NEXUS_FrontendType *pType    /* [out] */
    )
{
    BDBG_ASSERT(NULL != handle);

    if ( NULL == handle->getType )
    {
        if ( handle->pParentFrontend )
        {
            NEXUS_Frontend_GetType(handle->pParentFrontend, pType);
        }
        else
        {
            BERR_TRACE(BERR_NOT_SUPPORTED);
        }
    }
    else
    {
        handle->getType(handle->pDeviceHandle, pType);
    }
}

void NEXUS_Frontend_GetTsmfSettings(
    NEXUS_FrontendHandle handle,
    NEXUS_TsmfSettings *pSettings /* [out] */
    )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);

    if (NULL == handle->getTsmfSettings) {
        if (handle->pParentFrontend) {
            NEXUS_Frontend_GetTsmfSettings(handle->pParentFrontend, pSettings);
            return;
        }
        else {
            BERR_TRACE(BERR_NOT_SUPPORTED);
            return;
        }
    }
    else {
        handle->getTsmfSettings(handle->pDeviceHandle, pSettings);
        return;
    }
}

NEXUS_Error NEXUS_Frontend_SetTsmfSettings(
    NEXUS_FrontendHandle handle,
    const NEXUS_TsmfSettings *pSettings
    )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);

    if (NULL == handle->setTsmfSettings) {
        if (handle->pParentFrontend) {
            return NEXUS_Frontend_SetTsmfSettings(handle->pParentFrontend, pSettings);
        }
        else {
            return BERR_TRACE(BERR_NOT_SUPPORTED);
        }
    }
    else {
        return handle->setTsmfSettings(handle->pDeviceHandle, pSettings);
    }
}

void NEXUS_Frontend_GetTransportSettings(
    NEXUS_FrontendHandle handle,
    NEXUS_FrontendTransportSettings *pSettings /* [out] */
    )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);

    if (NULL == handle->getTransportSettings) {
        if (handle->pParentFrontend) {
            NEXUS_Frontend_GetTransportSettings(handle->pParentFrontend, pSettings);
            return;
        }
        else {
            BERR_TRACE(BERR_NOT_SUPPORTED);
            return;
        }
    }
    else {
        handle->getTransportSettings(handle->pDeviceHandle, pSettings);
        return;
    }
}

NEXUS_Error NEXUS_Frontend_SetTransportSettings(
    NEXUS_FrontendHandle handle,
    const NEXUS_FrontendTransportSettings *pSettings
    )
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);
    
    if (NULL == handle->setTransportSettings) {
        if (handle->pParentFrontend) {
            return NEXUS_Frontend_SetTransportSettings(handle->pParentFrontend, pSettings);
        }
        else {
            return BERR_TRACE(BERR_NOT_SUPPORTED);
        }
    }
    else {
        return handle->setTransportSettings(handle->pDeviceHandle, pSettings);
    }
}

void NEXUS_Frontend_P_SetPower(NEXUS_FrontendHandle handle, NEXUS_PowerManagementCore core, bool poweredUp)
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);

    /* the nexus power management code requires strict reference counting. the frontend tune/untune api
    does not require strict balancing. this code provides that balancing. */
    if (core == NEXUS_PowerManagementCore_eDigitalFrontend) {
        if (handle->power.digital != poweredUp) {
            NEXUS_PowerManagement_SetCoreState(core, poweredUp);
            handle->power.digital = poweredUp;
        }
    }
    else if (core == NEXUS_PowerManagementCore_eAnalogFrontend) {
        if (handle->power.analog != poweredUp) {
            NEXUS_PowerManagement_SetCoreState(core, poweredUp);
            handle->power.analog = poweredUp;
        }
    }
}

void NEXUS_Frontend_P_GetDefaultExtensionSettings(
    NEXUS_FrontendExtensionSettings *pSettings          /* [out] */
    )
{
    BDBG_ASSERT(NULL != pSettings);
    BKNI_Memset(pSettings, 0, sizeof(*pSettings));
}

NEXUS_FrontendHandle NEXUS_Frontend_P_CreateExtension(
    const NEXUS_FrontendExtensionSettings *pSettings    /* Functions to override.  The close function is required, all other functions are optional.
                                                           If you do not want to extend a function, leave it in the default state and the parent's
                                                           handler will be called instead. */
    )
{
    NEXUS_Frontend *pFrontend;

    BDBG_ASSERT(NULL != pSettings);
    BDBG_ASSERT(NULL != pSettings->close);
    BDBG_ASSERT(NULL != pSettings->parent);
    NEXUS_ASSERT_MODULE();

    pFrontend = NEXUS_Frontend_P_Create(pSettings->pDeviceHandle);
    if ( NULL == pFrontend )
    {
        (void)BERR_TRACE(BERR_OUT_OF_SYSTEM_MEMORY);
        return NULL;
    }

    if (pSettings->parent->registerExtension) {
        (*pSettings->parent->registerExtension)(pSettings->parent, pFrontend);
    }

    pFrontend->capabilities = pSettings->parent->capabilities;
    pFrontend->userParameters = pSettings->parent->userParameters;
    pFrontend->pParentFrontend = pSettings->parent;
    pFrontend->close = pSettings->close;
    pFrontend->tuneAnalog = pSettings->tuneAnalog;
    pFrontend->tuneOutOfBand = pSettings->tuneOutOfBand;
    pFrontend->tuneQam = pSettings->tuneQam;
    pFrontend->tuneUpstream = pSettings->tuneUpstream;
    pFrontend->tuneVsb = pSettings->tuneVsb;
    pFrontend->tuneSatellite = pSettings->tuneSatellite;
    pFrontend->getDiseqcSettings = pSettings->getDiseqcSettings;
    pFrontend->setDiseqcSettings = pSettings->setDiseqcSettings;
    pFrontend->sendDiseqcMessage = pSettings->sendDiseqcMessage;
    pFrontend->getDiseqcReply = pSettings->getDiseqcReply;
    pFrontend->sendDiseqcAcw = pSettings->sendDiseqcAcw;
    pFrontend->resetDiseqc = pSettings->resetDiseqc;
    pFrontend->tuneOfdm = pSettings->tuneOfdm;
    pFrontend->untune = pSettings->untune;

    pSettings->parent->numExtensions++;

    return pFrontend;
}

void NEXUS_Frontend_P_DestroyExtension(
    NEXUS_FrontendHandle handle
    )
{
    NEXUS_ASSERT_MODULE();
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);
    BDBG_ASSERT(NULL != handle->pParentFrontend);
    BDBG_ASSERT(handle->pParentFrontend->numExtensions > 0);
    handle->pParentFrontend->numExtensions--;

    if (handle->pParentFrontend->registerExtension) {
        (*handle->pParentFrontend->registerExtension)(handle->pParentFrontend, NULL);
    }

    NEXUS_Frontend_P_Destroy(handle);
}

NEXUS_FrontendHandle NEXUS_Frontend_P_GetParentHandle(NEXUS_FrontendHandle handle)
{
    BDBG_OBJECT_ASSERT(handle, NEXUS_Frontend);
    return handle->pParentFrontend;
}