/*************************************************************************** * Copyright (c) 2005-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: baob.h $ * $brcm_Revision: Hydra_Software_Devel/5 $ * $brcm_Date: 3/12/12 10:35a $ * * Module Description: * * Revision History: * * $brcm_Log: /magnum/portinginterface/aob/7552/baob.h $ * * Hydra_Software_Devel/5 3/12/12 10:35a farshidf * SW3128-1: add callback to tuner through Nexus * * Hydra_Software_Devel/4 12/14/11 3:58p farshidf * SW7552-170: fix the AOB interface * * Hydra_Software_Devel/3 12/12/11 2:41p farshidf * SW7552-170: add get default settings * * Hydra_Software_Devel/2 12/12/11 12:00p farshidf * SW7552-170: fix the AOB pi * * Hydra_Software_Devel/2 4/15/11 4:33p vishk * SW7422-413: Nexus support for the 3128 OOB core for 7422 board * * Hydra_Software_Devel/1 4/14/11 5:02p atanugul * SW3128-2: Add 3128 AOB Support * ****************************************************************************/ /*= Module Overview ********************************************************* Overview The Advanced Qam Out Of Band (AOB) Downstream receiver is responsible for taking an Out-of-Band RF signal (70-130 MHz), down converting into IF signal. This IF signal is then digitalized, demodulated and error corrected. This error corrected data stream can be then routed to Davic MAC. Design The design for BAOB PI API is broken into three parts. o Part 1 (open/close/configuration): These APIs are used for opening and closing BAOB device. When a device is opened, the device can be configured. o Part 2 (acquire/get/set): These APIs are used for getting and setting runtime attributes of BAOB. Along with get and set APIs, an acquire API is also provided. The acquire API is used to acquire (lock) OutOfBand Downstream signal. o Part 3 (process): This API is used to process notification. Usage The usage of BAOB involves the following: * Configure/Open of BQOB * Configure BAOB device for the target system * Open BAOB device * Program/Acquire device * Try to acquire OutOfBand Downstream signal * Check status of acquisition * Wait for Lock/Unlock ntotification sent from 325X * Process Lock/Unlock Notification Interrupt Requirements No interrrupt processing is done by this module. Sample Code: // // NOTE: The following sample code does not do any error checking. // // In this example, the target H/W board is configured for an // Out-of-Band Downstream DVS 178 application, with a Crystal Frequency of 24.00 MHz // static BAOB_Handle aobDev; static BCHP_Handle hChip3128; static BREG_Handle hReg3128; static BRPC_Handle hRpc; static BAOB_CallbackFunc cbLockChangeFunc( BAOB_Handle hIbChn, void *pParam ) { bool *lockStatus = (bool *) pParam; BAOB_GetLockStatus( hIbChn, lockStatus ); return; } main( void ) { BAOB_Settings aobDevSettings; bool isLock; // Initialize hChip3128, hReg3128, and hRpc . . . // Initialize BTNR_3128Ob // BAOB initialization for BCM3128 BAOB_GetDefaultSetting( &aobDevSettings ); // Configure the Crystal Frequency of H/W board. aobDevSettings.xtalFreq = 24000000; aobDevSettings.enableFEC = true; // false: CableCARD will do FEC // true: legacy OOB needs FEC aobDevSettings.hRpc = hRpc; BAOB_Open( &aobDev, hChip3128, hReg3128, &aobDevSettings ); // Now startup the RPC Notificiation Background thread/task . . . // Install callback for state change event, where last parameter // is for general use. BAOB_InstallCallback( aobDev, BAOB_Callback_eLockChange, cbLockChangeFunc, (void *) &isLock ); // Tune Tuner . . . // Acquire OutOfBand Downstream Signal, DVS 178 QPSK modulation with a // symbol rate of 777 KBaud. BAOB_Set_Spectrum( aobDev, BAOB_SpectrumMode_eNoInverted); BAOB_Acquire( aobDev, BAOB_ModulationType_eDvs178Qpsk, 777000 ); while(1) { // Print the lock status every second BKNI_Sleep(1000); BAOB_GetLOckStatus(aobDev, &isLock); printf("Lock Status: %s\n", (isLock==true): "locked", "not lock"); } } void checkRpcNotificationThread(. . .) { while (!system_terminated) { uint32_t device_id, event; BRPC_CheckNotification(hRpc, &device_id, &event, 0); if ((BRPC_GET_NOTIFICATION_EVENT(event)) { switch (device_id) { case BRPC_DevId_3128_DS0: break; case BRPC_DevId_3128_DS1: break; case BRPC_DevId_3128_OB0: BAOB_ProcessNotification(aobDev); break; default: // device not used break; } } else { BKNI_Sleep(100); } } } ***************************************************************************/ #ifndef BAOB_H__ #define BAOB_H__ #include "bchp.h" #include "breg_mem.h" #include "bint.h" #include "bkni.h" #include "berr_ids.h" #include "bmem.h" #ifdef __cplusplus extern "C" { #endif /*************************************************************************** Summary: Error Codes specific to BAOB Description: See Also: ****************************************************************************/ #define BAOB_ERR_NOTAVAIL_MODULATION_TYPE BERR_MAKE_CODE(BERR_AOB_ID, 0) /*************************************************************************** Summary: The handles for Qam Out-of-Band Downstream module. Description: An opaque handle for BAOB device. See Also: BAOB_Open() ****************************************************************************/ typedef struct BAOB_P_Handle *BAOB_Handle; typedef struct BAOB_P_3x7x_Handle *BAOB_3x7x_Handle; /*************************************************************************** Summary: Enumeration for modulation type Description: This enumeration defines the valid modulation types. See Also: BAOB_Acquire(), BAOB_GetStatus() ****************************************************************************/ typedef enum BAOB_ModulationType { BAOB_ModulationType_eDvs167Qpsk, /*Annex A*/ BAOB_ModulationType_eDvs178Qpsk, /*Annex B*/ BAOB_ModulationType_ePod_Dvs167Qpsk, BAOB_ModulationType_ePod_Dvs178Qpsk, BAOB_ModulationType_eLast } BAOB_ModulationType; /*************************************************************************** Summary: Enumeration for BERT Source Description: This enumeration defines the valid BERT input Sources See Also: BAOB_Acquire() ****************************************************************************/ typedef enum BAOB_BerInputSrc { BAOB_BerInputSrc_eRcvIChOutput, /* BERT input source is the receiver I-channel output */ BAOB_BerInputSrc_eRcvQChOutput, /* BERT input source is the receiver Q-channel output */ BAOB_BerInputSrc_eRcvIQChOutputIntrlv, /* BERT input source is the receiver I-channel and Q-channel output interleaved */ BAOB_BerInputSrc_eFecOutput /* BERT input source is the FEC output */ } BAOB_BerInputSrc; /*************************************************************************** Summary: Enumeration for QPSK OOB spectrum setting Description: This enumeration defines the valid spectrum setting. See Also: BAOB_Get_Spectrum(), BAOB_Set_Spectrum() ****************************************************************************/ typedef enum BAOB_SpectrumMode { BAOB_SpectrumMode_eAuto, BAOB_SpectrumMode_eNoInverted, BAOB_SpectrumMode_eInverted } BAOB_SpectrumMode; /*************************************************************************** Summary: This structure represents the AOB Status for a Qam Out-of-Band Downstream module. Description: This structure is returned when BAOB_GetStatus() is called. This structure contains the complete status of Qam Out-of-Band Downstream module. See Also: BAOB_GetStatus() ****************************************************************************/ typedef struct BAOB_Status { 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 */ } BAOB_Status; /*************************************************************************** Summary: Enumeration for Nyquist Filter Description: This enumeration represents the Nyquist Filter modes of an AOB channel. See Also: ****************************************************************************/ typedef enum BAOB_NyquistFilter { BAOB_NyquistFilter_eRaisedCosine_50, /* Raised Cosine Nyquist Filter with 50% Roll Off */ BAOB_NyquistFilter_eRootRaisedCosine_50, /* Root Raised Cosine Nyquist Filter with 50% Roll Off */ BAOB_NyquistFilter_eRootRaisedCosine_30, /* Root Raised Cosine Nyquist Filter with 30% Roll Off */ BAOB_NyquistFilter_eLast } BAOB_NyquistFilter; /*************************************************************************** Summary: Required default settings structure for QPSK Out-of_Band module. Description: The default setting structure defines the default configuration of QPSK Out-of_Band when the device is opened. See Also: BAOB_Open() ****************************************************************************/ #define BAOB_SETTINGS_XTALFREQ (24000000) /* 24.00 MHz */ typedef struct BAOB_Settings { unsigned int devId; /* generic device ID */ void *hGeneric; /* generic handle can be used for anything */ uint32_t xtalFreq; /* Crystal Freqency in Hertz */ bool enableFEC; /* use OOB FEC or not */ bool isOpenDrain; /* true = Open Drain mode, false = Normal mode. */ bool serialData; /* true = transport data is serial, false = transport data is parallel and is output on 3128_GPIO[0:7]*/ BTMR_Handle hTmr; /* for peridic check equired for 7552 */ BMEM_Heap_Handle hHeap; BAOB_NyquistFilter nyquist; /* specifies Nyquist filter rolloff */ } BAOB_Settings; /*************************************************************************** Summary: This structure represents AOB Qam In-Band Downstream acquisition parameters. Description: See Also: BAOB_Acquire() ****************************************************************************/ typedef struct BAOB_AcquireParam { BAOB_ModulationType modType; /* Modulation type */ uint32_t symbolRate; /* in Baud */ bool autoAcquire; BAOB_SpectrumMode spectrum; /*default Spectrum setting*/ BAOB_BerInputSrc berSrc; /* BERT Input Source */ } BAOB_AcquireParam; /*************************************************************************** Summary: Data for the AOB callback ****************************************************************************/ /*This is a single NON-channelized structure called on demand then sent through the HAB*/ /*Each sub-structure is completely filled by an appropriate function call*/ typedef enum BAOB_CallbackMode { /* Most of these are currently not supported, are here for future use */ BAOB_CallbackMode_eSetMode = 0, BAOB_CallbackMode_eRequestMode = 1, BAOB_CallbackMode_eLast } BAOB_CallbackMode; typedef struct BAOB_P_AobCallbackData_s { void* hTunerChn; uint16_t Mode; /*Callback is to send data on eSetMode, Callback is to get data on eRequestMode*/ uint32_t Symbol_Rate; /*Upper Symbol_Rate currently being scanned on eSetMode: return last value sent on eRequestMode*/ int32_t Freq_Offset; /*Front end offset to use on eSetMode: return last value sent on eRequestMode*/ uint32_t RF_Freq; /*RF frequency of the tuner on eRequestMode: set to 0 if unknown*/ int32_t Total_Mix_After_ADC; /*Sum of mixer frequencies after ADC on eRequestMode*/ int16_t PreADC_Gain_x256db ; /*Gain in db*256 before ADC on eRequestMode: set to 0x8000 if unknown*/ int16_t PostADC_Gain_x256db; /*Gain in db*256 after ADC on eRequestMode: set to 0x8000 if unknown*/ int16_t External_Gain_x256db; /*Gain in db*256 external to chip (like external LNA) on eRequestMode: set to 0x8000 if unknown*/ }BAOB_P_AobCallbackData_t; typedef enum BAOB_Callback { BAOB_Callback_eLockChange, /* Callback to notify application of lock change */ BAOB_Callback_eAsyncStatusReady, /* Callback to notify application there is no signal */ BAOB_Callback_eTuner, /* callback to tuner to get Tuner status */ BAOB_Callback_eLast /* More may be required */ } BAOB_Callback; /*************************************************************************** Summary: Callback used for event notification. Description: When this PI wants to notify an application, it will call this callback function the callback function is registered. See Also: BAOB_InstallLockStateChangeCallback() ****************************************************************************/ typedef BERR_Code (*BAOB_CallbackFunc)(void *pParam ); /*************************************************************************** Summary: This function returns the default settings for QPSK Out-of_Band module. Description: This function is responsible for returns the default setting for BAOB module. The returning default setting should be when opening the device. Returns: TODO: See Also: BAOB_Open() ****************************************************************************/ BERR_Code BAOB_GetDefaultSettings( BAOB_Settings *pDefSettings, /* [out] Returns default setting */ BCHP_Handle hChip /* [in] Chip handle */ ); /*************************************************************************** Summary: This function opens Qam Out-of-Band Downstream module. Description: This function is responsible for opening BAOB module. When BAOB is opened, it will create a module handle and configure the module based on the default settings. Once the device is opened, it must be closed before it can be opened again. Returns: TODO: See Also: BAOB_Close(), BAOB_GetDefaultSettings() ****************************************************************************/ BERR_Code BAOB_Open( BAOB_Handle *pAob, /* [out] Returns handle */ BCHP_Handle hChip, /* [in] Chip handle */ BREG_Handle hRegister, /* [in] Register handle */ BINT_Handle hInterrupt, /* [in] Interrupt handle, Bcm3250 */ const BAOB_Settings *pDefSettings /* [in] Default settings */ ); /*************************************************************************** Summary: This function closes Qam Out-of-Band Downstream module. Description: This function is responsible for closing BAOB module. Closing BAOB will free main BAOB handle. Returns: TODO: See Also: BAOB_Open() ****************************************************************************/ BERR_Code BAOB_Close( BAOB_Handle hAob /* [in] Device handle */ ); /*************************************************************************** Summary: This function tries to acquire downstream lock for the specific Qam Out-of-Band Downstream module. Description: This function is responsible for trying to acquire downstream lock of the input Out-of-Band signal. Acquiring Out-of-Band downstream lock involves configuring the H/W to desire configuration, then running a Qam Out-of-Band downstream acquisition script. If this is the first acquisition for the current annex mode, then a Qam Out-of-Band downstream configuration script will be run prior to running acquisition script. This function will automatically enable the downstream receiver if the receiver was in power-saver mode. Returns: TODO: See Also: BAOB_GetLock(), BAOB_GetStatus(), BAOB_GetSoftDecision() ****************************************************************************/ BERR_Code BAOB_Acquire( BAOB_Handle hDev, /* [in] Device handle */ BAOB_AcquireParam *obParams /* [in] Out of band acquire parameters to use */ ); /*************************************************************************** Summary: This function gets the status synchronously of Qam Out-of-Band Downstream module. Description: This function is responsible for synchronously getting the complete status for a Qam Out-of-Band Downstream module. Returns: TODO: See Also: BAOB_RequestAsyncStatus(), BAOB_GetAsyncStatus(). ****************************************************************************/ BERR_Code BAOB_GetStatus( BAOB_Handle hDev, /* [in] Device handle */ BAOB_Status *pStatus /* [out] Returns status */ ); /*************************************************************************** Summary: This function gets the status asynchronously of Qam Out-of-Band Downstream module. Description: This function is responsible for asynchronously getting the complete status for a Qam Out-of-Band Downstream module channel. BAOB_RequestAsyncStatus() is called before to notify the frontend to calculate the status and notify the backend asynchronously that the status is ready then BAOB_GetAsyncStatus() needs to be called to retrieve the status. Returns: TODO: See Also: BAOB_RequestAsyncStatus(), BAOB_GetStatus(). ****************************************************************************/ BERR_Code BAOB_GetAsyncStatus( BAOB_Handle hDev, /* [in] Device handle */ BAOB_Status *pStatus /* [out] Returns status */ ); /*************************************************************************** Summary: This function requests the status asynchronously of Qam Out-of-Band Downstream module. Description: This function is responsible for requesting the status to be calculated asynchronously for a Qam Out-of-Band Downstream module channel. The Qam frontend is responsible to inform the backend when the status is ready either through an interrupt or by any other predetermined method. Returns: TODO: See Also: BAOB_GetAsyncStatus BAOB_GetStatus ****************************************************************************/ BERR_Code BAOB_RequestAsyncStatus( BAOB_Handle hDev /* [in] Device handle */ ); /*************************************************************************** Summary: This function gets the lock status for a Qam Out-of-Band Downstream module. Description: This function is responsible for getting the lock status for a BAOB module. Returns: TODO: See Also: BAOB_GetStatus() ****************************************************************************/ BERR_Code BAOB_GetLockStatus( BAOB_Handle hDev, /* [in] Device handle */ bool *isLock /* [out] Returns lock status, 0=not lock, 1=locked */ ); /*************************************************************************** Summary: This function gets the I and Q values for soft decision of a Qam Out-of-Band Downstream module. Description: This function is responsible for getting the I and Q values for soft decision of a BAOB module. Returns: TODO: See Also: ****************************************************************************/ BERR_Code BAOB_GetSoftDecision( BAOB_Handle hDev, /* [in] Device handle */ int16_t nbrToGet, /* [in] Number values to get */ int16_t *iVal, /* [out] Ptr to array to store output I soft decision */ int16_t *qVal, /* [out] Ptr to array to store output Q soft decision */ int16_t *nbrGotten /* [out] Number of values gotten/read */ ); /*************************************************************************** Summary: This function enable the power-saver mode. Description: This function is responsible for enabling the OOB downstream receiver power-saver mode. When the BAOB is in the power-saver mode, the Qam/QPSK OOB Downstream receiver is shutdown. BAOB_Acquire() will disable power-saver mode automatically. Also BAOB_DisablePowerSaver() can be used to disable power-saver mode. Returns: TODO: See Also: BAOB_DisablePowerSaver() BAOB_Acquire() ****************************************************************************/ BERR_Code BAOB_EnablePowerSaver( BAOB_Handle hDev /* [in] Device handle */ ); /*************************************************************************** Summary: This function disables the power-saver mode. Description: This function is responsible for disabling the OOB downstream receiver power-saver mode. When the BAOB is in the power-saver mode, the Qam/QPSK OOB Downstream receiver is shutdown. Returns: TODO: See Also: BAOB_EnablePowerSaver() BAOB_Acquire() ****************************************************************************/ BERR_Code BAOB_DisablePowerSaver( BAOB_Handle hDev /* [in] Device handle */ ); /*************************************************************************** Summary: This function is responsible for processing a notificiation for the specific Qam Out-of-Band Downstream module channel. Description: This function needs to called when notification is received. Returns: TODO: See Also: ****************************************************************************/ BERR_Code BAOB_ProcessNotification( BAOB_Handle hDev, /* [in] Device handle */ unsigned int event /* [in] Event code and event data*/ ); /*************************************************************************** Summary: This function is responsible for installing a callback function. Description: This function installs a callback function. Returns: TODO: See Also: ****************************************************************************/ BERR_Code BAOB_InstallCallback( BAOB_Handle hDev, /* [in] Device handle */ BAOB_Callback callbackType, /* [in] Type of callback */ BAOB_CallbackFunc pCallback, /* [in] Function Ptr to callback */ void *pParam /* [in] Generic parameter send on callback */ ); /*************************************************************************** Summary: This functionclears the corrBlockCount and ucorrBlockCount counters in BAOB_OobStatus. Description: Returns: TODO: See Also: ****************************************************************************/ BERR_Code BAOB_ResetStatus( BAOB_Handle hDev /* [in] Device handle */ ); /*************************************************************************** Summary: This function returns the default settings for QPSK Out-of_Band module. Description: This function is responsible for returns the default setting for BAOB module. The returning default setting should be when opening the device. Returns: TODO: See Also: BAOB_Open() ****************************************************************************/ BERR_Code BAOB_GetDefaultSettings( BAOB_Settings *pDefSettings, /* [out] Returns default setting */ BCHP_Handle hChip /* [in] Chip handle */ ); /*************************************************************************** Summary: Function called by upper to get the inetrrupt handle BAOB_GetInterruptEventHandle ****************************************************************************/ BERR_Code BAOB_GetInterruptEventHandle(BAOB_Handle h, BKNI_EventHandle* hEvent); void BAOB_ProcessInterruptEvent (BAOB_Handle hDev); void BAOB_P_TimerFunc(void *myParam1, int myParam2); #ifdef __cplusplus } #endif #endif