layer1-api/include/superfemto.h

#ifndef SUPERFEMTO_H__
#define SUPERFEMTO_H__

#ifdef __cplusplus
    extern "C" {
#endif // __cplusplus 

/****************************************************************************
 *                                  Includes                                *
 ****************************************************************************/
#include <stdint.h>

#include "gsml1const.h"

#define SUPERFEMTO_API(x,y,z)    ((x << 16) | (y << 8) | z)
#define SUPERFEMTO_API_VERSION   SUPERFEMTO_API(1,0,0)

/****************************************************************************
 *                                   Const                                  *
 ****************************************************************************/

/****************************************************************************
 * Enum: SuperFemto_Status_t
 ************************************************************************//** 
 * 
 * Status used by the SuperFemto.
 * 
 * @ingroup superfemto_api
 *
 ****************************************************************************/
typedef GsmL1_Status_t SuperFemto_Status_t;

 
/****************************************************************************
 * Enum : SuperFemto_PrimId_t
 ************************************************************************//**
 *   
 *   System management primitives.
 *
 *   @ingroup superfemto_api
 *   
 ****************************************************************************/
typedef enum SuperFemto_PrimId_t
{ 
    SuperFemto_PrimId_SystemInfoReq,      ///< Request system information    
    SuperFemto_PrimId_SystemInfoCnf,      ///< Confirm system information
    SuperFemto_PrimId_SystemFailureInd,   ///< System failure indication    
    SuperFemto_PrimId_ActivateRfReq,      ///< Request activation of the RF section
    SuperFemto_PrimId_ActivateRfCnf,      ///< Confirm activation of the RF section
    SuperFemto_PrimId_DeactivateRfReq,    ///< Request deactivation of the RF section
    SuperFemto_PrimId_DeactivateRfCnf,    ///< Confirm deactivation of the RF section    
    SuperFemto_PrimId_SetTraceFlagsReq,   ///< Set the verbosity of the system    
    SuperFemto_PrimId_RfClockInfoReq,     ///< Request information about the RF clock sub-system
    SuperFemto_PrimId_RfClockInfoCnf,     ///< Returns the RF clock sub-system information
    SuperFemto_PrimId_RfClockSetupReq,    ///< Configure the RF clock sub-system
    SuperFemto_PrimId_RfClockSetupCnf,    ///< Confirm the configuration of the RF clock sub-system
    SuperFemto_PrimId_Layer1ResetReq,     ///< Trigger a reset of the GSM layer 1 library
    SuperFemto_PrimId_Layer1ResetCnf,     ///< Confirm that the GSM layer 1 library was reset
    SuperFemto_PrimId_NUM
} SuperFemto_PrimId_t;


/****************************************************************************
 *                                  Types                                   *
 ****************************************************************************/

/****************************************************************************
 * Struct : SuperFemto_SystemInfoCnf_t
 ************************************************************************//**
 * 
 * Structure is used to confirm the information about the system.
 * 
 * @ingroup superfemto_api_prim_sys
 *
****************************************************************************/
typedef struct SuperFemto_SystemInfoCnf
{
    SuperFemto_Status_t status;       ///< Status
   
    struct
    {
        uint8_t major;              ///< DSP firmware major version number 
        uint8_t minor;              ///< DSP firmware minor version number
        uint8_t build;              ///< DSP firmware build version number
    } dspVersion;

    struct
    {
        uint8_t major;              ///< FPGA firmware major version number 
        uint8_t minor;              ///< FPGA firmware minor version number
        uint8_t build;              ///< FPGA firmware build version number
    } fpgaVersion;
    
} SuperFemto_SystemInfoCnf_t;
 
/****************************************************************************
 * Struct : SuperFemto_SystemFailureInd_t
 ************************************************************************//**
 * 
 * Structure is used to indicate a system failure.
 * 
 * @ingroup superfemto_api_prim_sys
 *
****************************************************************************/
typedef struct SuperFemto_SystemFailureInd
{
   SuperFemto_Status_t status;          ///< Status

} SuperFemto_SysemFailureInd_t;

/****************************************************************************
 * Struct : SuperFemto_ActivateRfReq_t
 ************************************************************************//**
 *
 * This primitive is used to request the activation the RF section of the system.
 *
 * @ingroup superfemto_api
 *
 ***************************************************************************/
typedef struct SuperFemto_ActivateRfReq
{
    // Timing source (FN/TN)
    struct
    {
        uint8_t u8TimSrc;               ///< Timing source (0:Slave/Get timing from remote master BTS, 1:Master/Generates its own timing)
    } timing;
    
    // Message queue options
    struct {
        uint8_t u8UseTchMsgq;           ///< Set to '1' to use a separate MSGQUEUE for TCH primitives
        uint8_t u8UsePdtchMsgq;         ///< Set to '1' to use a separate MSGQUEUE for PDTCH primitives
    } msgq;
    
    // TRX RF clock options
    struct
    {
        int iClkCor;                    ///< Clock correction value in PPB.
        uint8_t u8ClkSrc;               ///< Clock source (0:None, 1:OCXO, 2:TCXO, 3:External, 4:GPS PPS, 5:reserved, 6:RX)
    } rfTrx;
    
    // RX RF clock options
    struct
    {
        int iClkCor;                    ///< Clock calibration value in PPB.
        uint8_t u8ClkSrc;               ///< Clock source (0:None, 1:OCXO, 2:TCXO, 3:External, 4:GPS PPS, 5:TRX, 6:reserved)
    } rfRx;

} SuperFemto_ActivateRfReq_t;

/****************************************************************************
 * Struct : SuperFemto_ActivateRfCnf_t
 ************************************************************************//**
 *
 * This primitive is used to confirm the activation the RF section of the system.
 *
 * @ingroup superfemto_api
 *
 ***************************************************************************/
typedef struct SuperFemto_ActivateRfCnf
{
     SuperFemto_Status_t status;      ///< Status
    
} SuperFemto_ActivateRfCnf_t;

/****************************************************************************
 * Struct : SuperFemto_DeactivateRfCnf_t
 ************************************************************************//**
 *
 * This primitive is used to confirm the deactivation the RF section of the system.
 *
 * @ingroup superfemto_api
 *
 ***************************************************************************/
typedef struct SuperFemto_DeactivateRfCnf
{
     SuperFemto_Status_t status;      ///< Status
    
} SuperFemto_DeactivateRfCnf_t;

/****************************************************************************
 * Struct : SuperFemto_SetTraceFlagsReq_t
 ************************************************************************//**
 *
 * This primitive is used to setup the trace flag values. 
 *
 * @ingroup superfemto_api_prim_dbg
 *
 ***************************************************************************/
typedef struct SuperFemto_SetTraceFlagsReq
{
    uint32_t u32Tf;                 ///< Trace flag level 
} SuperFemto_SetTraceFlagsReq_t;

/****************************************************************************
 * Struct : SuperFemto_RfClockInfoReq
 ************************************************************************//**
 *
 * This primitive is used to retrive information about the RF clock
 *
 * @ingroup superfemto_api_prim_dbg
 *
 ***************************************************************************/
typedef struct SuperFemto_RfClockInfoReq
{        
    uint8_t u8RstClkCal;                ///< Set to '1' to reset the calibration module

} SuperFemto_RfClockInfoReq_t;

/****************************************************************************
 * Struct : SuperFemto_RfClockSetupReq
 ************************************************************************//**
 *
 * This primitive is used to configure the RF clock sub-system.
 *
 * @ingroup superfemto_api_prim_dbg
 *
 ***************************************************************************/
typedef struct SuperFemto_RfClockSetupReq
{       
    // TRX RF clock options
    struct
    {
        int iClkCor;                    ///< Clock correction value in PPB.
        uint8_t u8ClkSrc;               ///< Clock source (0:None, 1:OCXO, 2:TCXO, 3:External, 4:GPS PPS, 5:reserved, 6:RX)
    } rfTrx;
    
    // RX RF clock options
    struct
    {
        int iClkCor;                    ///< Clock calibration value in PPB.
        uint8_t u8ClkSrc;               ///< Clock source (0:None, 1:OCXO, 2:TCXO, 3:External, 4:GPS PPS, 5:TRX, 6:reserved)
    } rfRx;

    // RF clock calibration
    struct {
        uint8_t u8ClkSrc;               ///< Reference clock source (0:Off, 1:OCXO, 2:TCXO, 3:External, 4:GPS PPS, 5:reserved, 6:reserved, 7:NL)
    } rfTrxClkCal;    

} SuperFemto_RfClockSetupReq_t;

/****************************************************************************
 * Struct : SuperFemto_RfClockSetupCnf
 ************************************************************************//**
 *
 * This primitive is sent back to confirm the configuration of the RF clock sub-system.
 *
 * @ingroup superfemto_api_prim_dbg
 *
 ***************************************************************************/
typedef struct SuperFemto_RfClockSetupCnf
{        
     SuperFemto_Status_t status;   ///< Status of the RF-CLOCK-SETUP-REQ

} SuperFemto_RfClockSetupCnf_t;


/****************************************************************************
 * Struct : SuperFemto_RfClockInfoCnf
 ************************************************************************//**
 *
 * This primitive is used to send back information on the RF clock sub-system.
 *
 * @ingroup superfemto_api_prim_dbg
 *
 ***************************************************************************/
typedef struct SuperFemto_RfClockInfoCnf
{
   // TRX RF clock options
    struct
    {
        int iClkCor;                    ///< Clock correction value in PPB.
        uint8_t u8ClkSrc;               ///< Clock source (0:None, 1:OCXO, 2:TCXO, 3:External, 4:GPS PPS, 5:reserved, 6:RX)
    } rfTrx;
    
    // RX RF clock options
    struct
    {
        int iClkCor;                    ///< Clock calibration value in PPB.
        uint8_t u8ClkSrc;               ///< Clock source (0:None, 1:OCXO, 2:TCXO, 3:External, 4:GPS PPS, 5:TRX, 6:reserved)
    } rfRx;

    // RF clock calibration
    struct {
        uint8_t u8ClkSrc;               ///< Reference clock source (0:Off, 1:OCXO, 2:TCXO, 3:External, 4:GPS PPS, 5:reserved, 6:reserved, 7:NL)
    
        int     iClkErr;                ///< RF clock error (PPB).
        int     iClkErrRes;             ///< Clock error resolution (PPT).
    } rfTrxClkCal;      

} SuperFemto_RfClockInfoCnf_t;

/****************************************************************************
 * Struct : SuperFemto_Layer1ResetReq_t
 ************************************************************************//**
 *
 * Structure is used to request a reset of the layer 1 module.
 *
 * @ingroup superfemto_api_prim_sys
 *
****************************************************************************/
typedef struct SuperFemto_Layer1ResetReq
{
    uint32_t u32Reserved;

} SuperFemto_Layer1ResetReq_t;

/****************************************************************************
 * Struct : SuperFemto_Layer1ResetCnf_t
 ************************************************************************//**
 * 
 * Structure is used to confirm the reset of the layer 1 module.
 * 
 * @ingroup superfemto_api_prim_sys
 *
****************************************************************************/
typedef struct SuperFemto_Layer1ResetCnf
{
    GsmL1_Status_t status;

} SuperFemto_Layer1ResetCnf_t;

/****************************************************************************
 * Struct : SuperFemto_Primt_t
 ************************************************************************//**
 * 
 * System level primitive definition.
 * 
 * @ingroup superfemto_api_prim_sys
 *
****************************************************************************/
typedef struct SuperFemto_Prim
{
    SuperFemto_PrimId_t id;                               ///< Primitive ID

    union 
    {     
        SuperFemto_SystemInfoCnf_t    systemInfoCnf;      ///< Confirm system information
        SuperFemto_SysemFailureInd_t  sysemFailureInd;    ///< System failure indication   
        SuperFemto_ActivateRfReq_t    activateRfReq;      ///< Request activation of the RF section
        SuperFemto_ActivateRfCnf_t    activateRfCnf;      ///< Confirm activation of the RF section
        SuperFemto_DeactivateRfCnf_t  deactivateRfCnf;    ///< Confirm deactivation of the RF section 
        SuperFemto_SetTraceFlagsReq_t setTraceFlagsReq;   ///< Set the verbosity of the system        
        SuperFemto_RfClockInfoReq_t   rfClockInfoReq;     ///< Request information about the RF clock
        SuperFemto_RfClockInfoCnf_t   rfClockInfoCnf;     ///< Returns information about the RF clock
        SuperFemto_RfClockSetupReq_t  rfClockSetupReq;    ///< Setup the RF clock
        SuperFemto_RfClockSetupCnf_t  rfClockSetupCnf;    ///< Confirm the setup of the RF clock
        SuperFemto_Layer1ResetReq_t   layer1ResetReq;     ///< Request a reset of the layer 1 module
        SuperFemto_Layer1ResetCnf_t   layer1ResetCnf;     ///< Conrifm that the layer 1 module was reset
    } u;

} SuperFemto_Prim_t;


#ifdef _TMS320C6400
 
/****************************************************************************
 *                               Public Functions                           * 
 ****************************************************************************/

/****************************************************************************
 * Function : SuperFemto_RxPrimCallback
 ************************************************************************//**
 * 
 * SuperFemto primitive reception callback routine. Process primitives sent
 * by the ARM processor.
 *
 * @param [in] pPrim
 *      Address of the buffer containing the received primitive.
 *
 * @return
 *      GsmL1_Status_Success or the error code
 *  
 * @ingroup superfemto_api_prim_sys
 *
 ****************************************************************************/ 
void SuperFemto_RxPrimCallback( SuperFemto_Prim_t *pPrim );
 
 
#endif  // _TMS320C6400

#ifdef __cplusplus
}
#endif  // extern "C"

#endif  // SUPERFEMTO_H__