#ifndef GSML1PRIM_H__ #define GSML1PRIM_H__ #ifdef __cplusplus extern "C" { #endif // __cplusplus /**************************************************************************** * Includes * ****************************************************************************/ #ifndef WIN32 #include #endif #include "gsml1const.h" #include "gsml1types.h" /**************************************************************************** * Types (Primitive Parameters) * ****************************************************************************/ /**************************************************************************** * typedef : GsmL1_MsgUnitParam_t ************************************************************************//** * * Buffer structure used to transfer all messages frame units between * the layers. * * @ingroup gsml1_api_prim_params * ***************************************************************************/ typedef struct GsmL1_MsgUnitParam_t { uint8_t u8Size; ///< Size of the msg. unit uint8_t u8Buffer[MAX_L2MSGSIZE]; ///< Buffer containing the msg. unit // uint32_t u32Control; ///< Control word associated with the MsgUnit (0 if not applicable) } GsmL1_MsgUnitParam_t; /**************************************************************************** * typedef : GsmL1_MeasParam_t ************************************************************************//** * * Used to report library specific measured informations. * * @ingroup gsml1_api_prim_params * ***************************************************************************/ typedef struct GsmL1_MeasParam_t { float fRssi; ///< Received Signal Strength Indication (in dBm) int16_t i16BurstTiming; ///< Burst timing (in quarter of bits) float fLinkQuality; ///< Link quality of the communication (dB) float fBer; ///< Bit error rate of the last decoded frame [0..1] } GsmL1_MeasParam_t; /**************************************************************************** * typedef : GsmL1_DeviceParam_t ************************************************************************//** * * TRX device parameters * * @ingroup gsml1_api_prim_params * ***************************************************************************/ typedef struct GsmL1_DeviceParam_t { GsmL1_DevType_t devType; ///< Device type GsmL1_FreqBand_t freqBand; ///< GSM Frequency band used by the TRX device uint16_t u16Arfcn; ///< Radio frequency channel number uint16_t u16BcchArfcn; ///< Associated beacon radio frequency channel number uint8_t u8NbTsc; ///< Training sequence code to be used for normal bursts uint8_t u8AutoTA; ///< Automatic timing advance (0:TA is handled by upper layers, 1:TA is handled by layer 1) float fRxPowerLevel; ///< Nominal RX power level in dBm (use 0 if the control is handled by upper layers) float fTxPowerLevel; /**< Transmission power level if applicable (in dBm). @see Verify the values supported by the hardware. */ } GsmL1_DeviceParam_t; /**************************************************************************** * Types (Primitives) * ****************************************************************************/ /**************************************************************************** * Struct : GsmL1_MphInitReq_t ************************************************************************//** * * This structure contains every necessary parameters to initialize a * Base Tranceiver Station on a specific GSM Radio Frequency band. * * Primitive : MPH-INIT-REQ (L3 -> L1) * * @ingroup gsml1_api_prim_mph * ****************************************************************************/ typedef struct GsmL1_MphInitReq_t { HANDLE hLayer3; ///< Handle to a layer 3 entity GsmL1_DeviceParam_t deviceParam; ///< TRX Device parameters } GsmL1_MphInitReq_t; /*************************************************************************** * Struct : GsmL1_MphInitCnf ************************************************************************//** * * This structure is sent back to the layer 3 in order to confirm the * reception of a MPH-INIT-REQ primitive. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphInitCnf_t { HANDLE hLayer3; /**< Handle to the layer 3 entity. The layer 3 handle received in the MPH-INIT-REQ primitive is sent back to the layer 3 (unmodified). */ HANDLE hLayer1; ///< Handle to the initialized Layer1 entity GsmL1_FreqBand_t freqBand; ///< GSM Frequency band used by the TRX device GsmL1_Status_t status; ///< Status of the MPH-INIT-REQ primitive } GsmL1_MphInitCnf_t; /*************************************************************************** * Struct : GsmL1_MphCloseReq ************************************************************************//** * * This structure contains every necessary parameters to close a * Base Tranceiver Station using a specific GSM Radio Frequency band. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphCloseReq_t { HANDLE hLayer3; ///< Handle to the layer 3 entity HANDLE hLayer1; ///< Handle of the Layer1 entity to close } GsmL1_MphCloseReq_t; /*************************************************************************** * Struct : GsmL1_MphCloseCnf ************************************************************************//** * * This structure is sent back to the layer 3 in order to confirm the * reception of a MPH-CLOSE-REQ primitive. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphCloseCnf_t { HANDLE hLayer3; ///< Handle to the layer 3 entity GsmL1_Status_t status; ///< Status of the MPH-CLOSE-REQ primitive } GsmL1_MphCloseCnf_t; /**************************************************************************** * Struct : GsmL1_MphConnectReq_t ************************************************************************//** * * This structure contains all the necessary parameters to connect a physical * channel on an layer 1 entity. * * Primitive : MPH-CONNECT-REQ (L3 -> L1) * * @ingroup gsml1_api_prim_mph * ****************************************************************************/ typedef struct GsmL1_MphConnectReq_t { HANDLE hLayer3; ///< Handle to a layer 3 entity HANDLE hLayer1; /**< Handle to the layer1 on which the physical channel is connected. */ uint8_t u8Tn; ///< Time-slot [0..7] GsmL1_LogChComb_t logChComb; /**< Logical channel multiplexing over the physical channel */ } GsmL1_MphConnectReq_t; /*************************************************************************** * Struct : GsmL1_MphConnectCnf ************************************************************************//** * * This structure is sent back to the layer 3 in order to confirm the * reception of a MPH-CONNECT-REQ primitive. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphConnectCnf_t { HANDLE hLayer3; /**< The layer 3 handle received from in MPH-CONNECT-REQ primitive is sent back to the layer 3 (unmodified). */ HANDLE hLayer1; /**< Handle to the layer1 on which the physical channel is connected. */ GsmL1_Status_t status; ///< Status of the MPH-INIT-CONNECT-REQ primitive uint8_t u8Tn; ///< Time-slot [0..7] } GsmL1_MphConnectCnf_t; /*************************************************************************** * Struct : GsmL1_MphDisconnectReq_t ************************************************************************//** * * This structure contains all the necessary parameters to disconnect a * physical channel on an layer 1 entity. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphDisconnectReq_t { HANDLE hLayer3; ///< Handle to a layer 3 entity HANDLE hLayer1; /**< Handle to the layer1 on which the physical channel is disconnected. */ uint8_t u8Tn; ///< Time-slot [0..7] } GsmL1_MphDisconnectReq_t; /*************************************************************************** * Struct : GsmL1_MphDisconnectCnf ************************************************************************//** * * This structure is sent back to the layer 3 in order to confirm the * reception of a MPH-DISCONNECT-REQ primitive. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphDisconnectCnf_t { HANDLE hLayer3; /**< The layer 3 handle received from in MPH-DISCONNECT-REQ primitive is sent back to the layer 3 (unmodified). */ HANDLE hLayer1; /**< Handle to the layer1 on which the physical channel is disconnected. */ GsmL1_Status_t status; ///< Status of the MPH-DISCONNECT-REQ primitive uint8_t u8Tn; ///< Time-slot [0..7] } GsmL1_MphDisconnectCnf_t; /**************************************************************************** * Struct : GsmL1_MphActivateReq_t ************************************************************************//** * * This structure contains all the necessary parameters to activate a * logical channel over a connected physical channel. * * Primitive : MPH-ACTIVATE-REQ (L3 -> L1) * * @ingroup gsml1_api_prim_mph * ****************************************************************************/ typedef struct GsmL1_MphActivateReq_t { HANDLE hLayer3; ///< Layer 3 entity HANDLE hLayer2; ///< Layer 2 entity HANDLE hLayer1; /**< Handle of the Layer 1 entity on which the logical channel is activated */ uint8_t u8Tn; ///< Time-slot [0..7] GsmL1_SubCh_t subCh; ///< Sub-channel number (1Fh if not applicable) GsmL1_Sapi_t sapi; ///< Service access point identifier GsmL1_Dir_t dir; ///< Direction path to configure float fBFILevel; /**< Bad Frame Indication RX power level in dBm (use 0 do disable BFI) */ GsmL1_LogChParam_t logChPrm; ///< Additional configuration parameters } GsmL1_MphActivateReq_t; /*************************************************************************** * Struct : GsmL1_MphActivateCnf ************************************************************************//** * * This structure is sent back to the layer 3 in order to confirm the * reception of a MPH-ACTIVATE-REQ primitive. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphActivateCnf { HANDLE hLayer3; /**< The layer 3 handle received from in MPH-ACTIVATE-REQ primitive is sent back to the layer 3 (unmodified). */ HANDLE hLayer1; /**< Handle of the Layer 1 entity on which the logical channel is activated */ GsmL1_Status_t status; ///< Status of the MPH-INIT-ACTIVATE-REQ primitive uint8_t u8Tn; ///< Time-slot [0..7] GsmL1_SubCh_t subCh; ///< Sub-channel number (1Fh if not applicable) GsmL1_Sapi_t sapi; ///< Service access point identifier GsmL1_Dir_t dir; ///< Uplink/Downlink } GsmL1_MphActivateCnf_t; /**************************************************************************** * Struct : GsmL1_MphDeactivateReq_t ************************************************************************//** * * This structure contains all the necessary parameters to deactivate a * logical channel from a connected physical channel. * * Primitive : MPH-DEACTIVATE-REQ (L3 -> L1) * * @ingroup gsml1_api_prim_mph * ****************************************************************************/ typedef struct GsmL1_MphDeactivateReq_t { HANDLE hLayer3; ///< Layer 3 entity HANDLE hLayer1; /**< Handle of the Layer 1 entity on which the logical channel is activated */ uint8_t u8Tn; ///< Time-slot [0..7] GsmL1_SubCh_t subCh; ///< Sub-channel number (1Fh if not applicable) GsmL1_Sapi_t sapi; ///< Service access point identifier GsmL1_Dir_t dir; ///< Uplink/Downlink/Both } GsmL1_MphDeactivateReq_t; /*************************************************************************** * Struct : GsmL1_MphDeactivateCnf ************************************************************************//** * * This structure is sent back to the layer 3 in order to confirm the * reception of a MPH-DEACTIVATE-REQ primitive. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphDeactivateCnf { HANDLE hLayer3; /**< The layer 3 handle received from in MPH-DEACTIVATE-REQ primitive is sent back to the layer 3 (unmodified). */ HANDLE hLayer1; /**< Handle of the Layer 1 entity on which the logical channel is activated */ GsmL1_Status_t status; ///< Status of the MPH-INIT-DEACTIVATE-REQ primitive uint8_t u8Tn; ///< Time-slot [0..7] GsmL1_SubCh_t subCh; ///< Sub-channel number (1Fh if not applicable) GsmL1_Sapi_t sapi; ///< Service access point identifier GsmL1_Dir_t dir; ///< Uplink/Downlink } GsmL1_MphDeactivateCnf_t; /**************************************************************************** * Struct : GsmL1_MphConfigReq_t ************************************************************************//** * * This structure contains all the necessary parameters to configure * physical channel parameters through the SACCH burst. * * Primitive : MPH-CONFIG-REQ (L3 -> L1) * * @ingroup gsml1_api_prim_mph * ****************************************************************************/ typedef struct GsmL1_MphConfigReq_t { HANDLE hLayer3; ///< Layer 3 instance handle HANDLE hLayer1; /**< Handle of the Layer 1 entity which has the physical channel on which the configuration is done. */ GsmL1_ConfigParamId_t cfgParamId; ///< Configuration parameter ID GsmL1_ConfigParam_t cfgParams; ///< Configuration parameters } GsmL1_MphConfigReq_t; /*************************************************************************** * Struct : GsmL1_MphConfigCnf ************************************************************************//** * * This structure is sent back to the layer 3 in order to confirm the * reception of a MPH-CONFIG-REQ primitive. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphConfigCnf_t { GsmL1_Status_t status; ///< Status of the MPH-CONFIG-REQ primitive HANDLE hLayer3; ///< Layer 3 instance handle HANDLE hLayer1; /**< Handle of the Layer 1 entity which has the physical channel on which the configuration is done. */ GsmL1_ConfigParamId_t cfgParamId; ///< Configuration parameter ID GsmL1_ConfigParam_t cfgParams; ///< Configuration parameters } GsmL1_MphConfigCnf_t; /**************************************************************************** * Struct : GsmL1_MphMeasureReq_t ************************************************************************//** * * This structure contains all the necessary parameters to measure the * RSSI on a RF channel. * * Primitive : MPH-MEASURE-REQ (L3 -> L1) * * @ingroup gsml1_api_prim_mph * * ****************************************************************************/ typedef struct GsmL1_MphMeasureReq_t { HANDLE hLayer3; ///< Layer 3 instance handle HANDLE hLayer1; /**< Handle of the Layer 1 entity which has the physical channel on which the configuration is done. */ uint32_t u32Duration; ///< Duration of the measurement (in number of frames, 0:now) } GsmL1_MphMeasureReq_t; /**************************************************************************** * Struct : GsmL1_MphMeasureCnf_t ************************************************************************//** * * This structure is sent back to the layer 3 in order to confirm the * reception of a MPH-MEASURE-REQ primitive. * * Primitive : MPH-MEASURE-CNF (L3 -> L1) * * @ingroup gsml1_api_prim_mph * * ****************************************************************************/ typedef struct GsmL1_MphMeasureCnf_t { HANDLE hLayer3; ///< Layer 3 instance handle HANDLE hLayer1; /**< Handle of the Layer 1 entity which has the physical channel on which the configuration is done. */ GsmL1_Status_t status; ///< Status of the MPH-MEASURE-REQ primitive float fMeanRssi; ///< RF channel mean received signal strength (dBm) float fPeakRssi; ///< RF channel maximum received signal strength (dBm) struct { float fMeanRssi; ///< Timeslot N mean received signal strength (dBm) float fPeakRssi; ///< Timeslot N maximum received signal strength (dBm) } tn[8]; } GsmL1_MphMeasureCnf_t; /*************************************************************************** * Struct : GsmL1_MphTimeInd ************************************************************************//** * * This structure is sent to the layer 3 at the beginning of every frame. * It is sent when u8Tn is equal to 0. * * @ingroup gsml1_api_prim_mph * ***************************************************************************/ typedef struct GsmL1_MphTimeInd_t { HANDLE hLayer1; /**< Handle of the Layer 1 entity sending the MphTimeInd primitive */ uint32_t u32Fn; ///< Current frame number [0 .. 2 715 647] uint8_t u8Tn; ///< Current timeslot [0..7] } GsmL1_MphTimeInd_t; /**************************************************************************** * Struct : GsmL1_MphSyncInd_t ************************************************************************//** * * This structure is sent back to the layer 3 in order indicate when the * RF device is synchronized to a surrounding BTS or also when it looses its * synchronization. * * Primitive : MPH-SYNC-IND (L1 -> L3) * * @ingroup gsml1_api_prim_mph * * ****************************************************************************/ typedef struct GsmL1_MphSyncInd_t { HANDLE hLayer1; ///< Handle of the device which is sync/unsynced uint8_t u8Synced; ///< Indicates if the RF device is synchronized to a BTS. } GsmL1_MphSyncInd_t; /****************************************************************************** * Struct : GsmL1_PhDataInd_t **************************************************************************//** * * This structure is sent to the layer 2 to pass message units containing * frames used by the data link layer or RLC/MAC peer-to-peer communications. * * @ingroup gsml1_api_prim_ph * *****************************************************************************/ typedef struct GsmL1_PhDataInd_t { HANDLE hLayer2; /**< Layer 2 instance handle. This handle is sent through the MPH-CONNECT-REQ primitive. */ HANDLE hLayer1; /**< Handle of the Layer 1 entity on which the logical channel is activated */ GsmL1_Sapi_t sapi; ///< Service access point identifier GsmL1_Dir_t dir; ///< Uplink/Downlink GsmL1_MeasParam_t measParam; ///< Measurement parameters infos GsmL1_MsgUnitParam_t msgUnitParam; ///< Message unit sent from the MS uint16_t u16Arfcn; ///< Absolute radio frequency number uint8_t u8Tn; ///< Time-slot [0..7] GsmL1_SubCh_t subCh; ///< Sub-channel number (1Fh if not applicable) uint32_t u32Fn; ///< Frame number of the 1st RX burst uint8_t u8BlockNbr; ///< Block number } GsmL1_PhDataInd_t; /****************************************************************************** * Struct : GsmL1_PhConnectInd_t **************************************************************************//** * * This structure is sent to the layer 2 in order to indicate that a * specific type of logical channel has been connected on a physical channel. * * @ingroup gsml1_api_prim_ph * *****************************************************************************/ typedef struct GsmL1_PhConnectInd_t { HANDLE hLayer2; /**< Layer 2 instance handle. This handle is sent in the MPH-ACTIVATE-REQ primitive. */ HANDLE hLayer1; /**< Handle of the Layer 1 entity on which the logical channel is activated */ uint16_t u16Arfcn; ///< Absolute radio frequency number uint8_t u8Tn; ///< Time-slot [0..7] GsmL1_SubCh_t subCh; ///< Sub-channel number (1Fh if not applicable) GsmL1_Sapi_t sapi; ///< Service access point identifier GsmL1_Dir_t dir; ///< Indicate the path of the transmission. } GsmL1_PhConnectInd_t; /****************************************************************************** * Struct : GsmL1_PhReadyToSendInd_t **************************************************************************//** * * This structure is sent to allow the data link or the RLC/MAC layer * to synchronize to the next instant of physical transmission. * * @ingroup gsml1_api_prim_ph * *****************************************************************************/ typedef struct GsmL1_PhReadyToSendInd_t { HANDLE hLayer1; /**< Handle of the Layer 1 entity on which the logical channel is activated */ HANDLE hLayer2; /**< Layer 2 instance handle. This handle is sent in the MPH-ACTIVATE-REQ primitive. */ GsmL1_Sapi_t sapi; ///< Service access point identifier uint32_t u32Fn; ///< Frame number of the 1st TX burst uint16_t u16Arfcn; ///< Absolute radio frequency number uint8_t u8Tn; ///< Timeslot number [0..7] GsmL1_SubCh_t subCh; ///< Sub-channel number (1Fh if not applicable) uint8_t u8BlockNbr; ///< Block number } GsmL1_PhReadyToSendInd_t; /****************************************************************************** * Struct : GsmL1_PhEmptyFrameReq_t **************************************************************************//** * * This structure is sent back to the layer 1 when no frame has to be * transmitted on the reception of a PH-READY-TO-SEND-IND primitive. * * @ingroup gsml1_api_prim_ph * *****************************************************************************/ typedef struct GsmL1_PhEmptyFrameReq_t { HANDLE hLayer1; /**< Handle of the Layer 1 entity on which the logical channel is activated */ uint32_t u32Fn; ///< Frame number of the 1st TX burst uint8_t u8Tn; ///< Timeslot number GsmL1_SubCh_t subCh; ///