Browse Source

Introduce API and firmware files for the sysmoBTS v1 and v2.

hardware/rev-b
Holger Hans Peter Freyther 9 years ago
commit
aeedfeb703
  1. 4
      LICENSE
  2. 6
      README
  3. 526
      api/gsml1const.h
  4. 174
      api/gsml1dbg.h
  5. 101
      api/gsml1link.h
  6. 877
      api/gsml1prim.h
  7. 87
      api/gsml1rf.h
  8. 135
      api/gsml1serv.h
  9. 142
      api/gsml1types.h
  10. 479
      api/superfemto.h
  11. BIN
      firmware/sysmobts-v1.bit
  12. BIN
      firmware/sysmobts-v1.out
  13. BIN
      firmware/sysmobts-v2.bit
  14. BIN
      firmware/sysmobts-v2.out

4
LICENSE

@ -0,0 +1,4 @@
The firmware is copyrighted and may only be used by owners of a sysmoBTS.
TODO: Clarify these terms.

6
README

@ -0,0 +1,6 @@
This is to be used with the sysmoBTS of sysmocom s.f.m.c. GmbH
This firmware contains:
- header files to communicate with the Layer1 implementation
- firmware for DSP/FPGA for HW v1 and v2

526
api/gsml1const.h

@ -0,0 +1,526 @@
#ifndef GSML1CONST_H__
#define GSML1CONST_H__
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/* V1 and V2 firmware supports EFR */
#define L1_HAS_EFR
/* V2 allows to select If2/RTP for the payload */
#ifndef HW_SYSMOBTS_V1
#define L1_HAS_RTP_MODE
#endif
/****************************************************************************
* Public macro *
****************************************************************************/
/****************************************************************************
* Macro : CALL_GSML1
************************************************************************//**
*
* This macro calls a GsmL1 function and jump to the gsml1_error label if the
* returned value is different from GsmL1_Status_Success.
*
* @note A gsml1_error label must be defined in the function.
*
* @ingroup gsml1_api_const
*
***************************************************************************/
#define CALL_GSML1(x) if( ( status = x ) != GsmL1_Status_Success ) goto gsml1_error;
/****************************************************************************
* Public constants *
****************************************************************************/
/****************************************************************************
* Enum: : GsmL1_SubCh_t
************************************************************************//**
*
* GSM Layer 1 sub-channel identifiers.
*
* @ingroup gsml1_api_const
*
***************************************************************************/
typedef enum GsmL1_SubCh_t
{
GsmL1_SubCh_0 = 0, ///< Sub-channel 0
GsmL1_SubCh_1, ///< Sub-channel 1
GsmL1_SubCh_2, ///< Sub-channel 2
GsmL1_SubCh_3, ///< Sub-channel 3
GsmL1_SubCh_4, ///< Sub-channel 4
GsmL1_SubCh_5, ///< Sub-channel 5
GsmL1_SubCh_6, ///< Sub-channel 6
GsmL1_SubCh_7, ///< Sub-channel 7
GsmL1_SubCh_8, ///< Sub-channel 8
GsmL1_SubCh_9, ///< Sub-channel 9
GsmL1_SubCh_10, ///< Sub-channel 10
GsmL1_SubCh_11, ///< Sub-channel 11
GsmL1_SubCh_12, ///< Sub-channel 12
GsmL1_SubCh_13, ///< Sub-channel 13
GsmL1_SubCh_14, ///< Sub-channel 14
GsmL1_SubCh_15, ///< Sub-channel 15
GsmL1_SubCh_NA = 0x1F ///< No sub-channel (not applicable)
} GsmL1_SubCh_t;
/****************************************************************************
* typedef : GsmL1_Sapi_t
************************************************************************//**
*
* Service Access Point Identifier (SAPI).
*
* An SAPI is used to identifie a specific Service Access Point (SAP)
*
* @ingroup gsml1_api_const
*
***************************************************************************/
typedef enum GsmL1_Sapi_t
{
GsmL1_Sapi_Idle = 0, ///< Idle burst pseudo-channel
GsmL1_Sapi_Fcch, ///< Frequency correction burst pseudo-channel
GsmL1_Sapi_Sch, ///< Synchronization channel
GsmL1_Sapi_Sacch, ///< Slow associated control channel
GsmL1_Sapi_Sdcch, ///< Stand-alone dedicated control channel
GsmL1_Sapi_Bcch, ///< Broadcast control channel
GsmL1_Sapi_Pch, ///< Paging channel
GsmL1_Sapi_Agch, ///< Access grant channel
GsmL1_Sapi_Cbch, ///< Cell Broadcast Channel
GsmL1_Sapi_Rach, ///< Random access channel
GsmL1_Sapi_TchF, ///< Full rate speech traffic channel
GsmL1_Sapi_FacchF, ///< Fast associated control channel at full rate
GsmL1_Sapi_TchH, ///< Half rate speech traffic channel
GsmL1_Sapi_FacchH, ///< Fast associated control channel at half rate
GsmL1_Sapi_Nch, ///< Notification Channel
GsmL1_Sapi_Pdtch, ///< Packet data traffic channel
GsmL1_Sapi_Pacch, ///< Packet associated control channel
GsmL1_Sapi_Pbcch, ///< Packet broadcast control channel
GsmL1_Sapi_Pagch, ///< Packet access grant channel
GsmL1_Sapi_Ppch, ///< Packet paging channel
GsmL1_Sapi_Pnch, ///< Packet notification channel
GsmL1_Sapi_Ptcch, ///< Packet timing advance control channel
GsmL1_Sapi_Prach, ///< Packet random access channel
GsmL1_Sapi_NUM ///< Only used to retrieve the last SAPI number
} GsmL1_Sapi_t;
/****************************************************************************
* Enum: GsmL1_Status_t
************************************************************************//**
*
* Status used by layer 1 functions.
*
* @ingroup gsml1_api_const
*
****************************************************************************/
typedef enum GsmL1_Status_t
{
GsmL1_Status_Success = 0, ///< No error
GsmL1_Status_Generic = -1, ///< Generic error
GsmL1_Status_NoMemory = -2, ///< Not enough memory error
GsmL1_Status_Timeout = -3, ///< Timeout error
GsmL1_Status_InvalidParam = -4, ///< Invalid parameter error
GsmL1_Status_Busy = -5, ///< Busy ressource error
GsmL1_Status_NoRessource = -6, ///< No more ressource available error
GsmL1_Status_Uninitialized = -7, ///< Trying to use an unitialized resource
GsmL1_Status_NullInterface = -8, ///< Trying to call a NULL interface
GsmL1_Status_NullFctnPtr = -9, ///< Trying to call a NULL function ptr
GsmL1_Status_BadCrc = -10, ///< Bad CRC error
GsmL1_Status_BadUsf = -11, ///< Bad USF error
GsmL1_Status_InvalidCPS = -12, ///< Invalid CPS field
GsmL1_Status_UnexpectedBurst = -13, ///< Unexpected Burst
GsmL1_Status_UnavailCodec = -14, ///< AMR codec is unavailable
GsmL1_Status_CriticalError = -15, ///< Critical error
GsmL1_Status_OverheatError = -16, ///< Overheat error
GsmL1_Status_DeviceError = -17, ///< Device error
GsmL1_Status_FacchError = -18, /**< Trying to activate a Facch prior activating a Tch logCh or
Trying to deactivate a Tch logCh prior deactivating all active Facch blocks */
GsmL1_Status_AlreadyDeactivated = -19, ///< Trying to deactivate an already deactivated LogCh
GsmL1_Status_TxBurstFifoOvrn = -20, ///< Trying to write into a Full Fifo
GsmL1_Status_TxBurstFifoUndr = -21, ///< Fifo underrun
GsmL1_Status_NotSynchronized = -22, ///< Not synchronized
GsmL1_Status_Unsupported = -23, ///< Unsupported feature
GSML1_STATUS_NUM = 24
} GsmL1_Status_t;
/****************************************************************************
* Enum: GsmL1_LogChComb_t
************************************************************************//**
*
* Permitted logical channel combinations over a physical channel.
*
* @ingroup gsml1_api_const
*
****************************************************************************/
typedef enum GsmL1_LogChComb_t
{
GsmL1_LogChComb_0 = 0, ///< UNUSED (DUMMY BURST)
GsmL1_LogChComb_I, ///< TCH/F + FACCH/F + SACCH/TF
GsmL1_LogChComb_II, ///< TCH/H(0,1) + FACCH/H(0,1) + SACCH/TH(0,1)
GsmL1_LogChComb_IV, ///< FCCH + SCH + BCCH + CCCH
GsmL1_LogChComb_V, ///< FCCH + SCH + BCCH + CCCH + SDCCH/4(0..3) + SACCH/C4(0..3)
GsmL1_LogChComb_VII, ///< SDCCH/8(0 .7) + SACCH/C8(0 . 7)
GsmL1_LogChComb_XIII ///< PDTCH/F + PACCH/F + PTCCH/F
} GsmL1_LogChComb_t;
/****************************************************************************
* Enum : GsmL1_DevType_t
************************************************************************//**
*
* PHY device type.
*
* @ingroup gsml1_api_const
*
****************************************************************************/
typedef enum GsmL1_DevType_t
{
GsmL1_DevType_TxdRxu = 0x06, ///< Base station type (TX downlink, RX uplink)
GsmL1_DevType_TxuRxd = 0x09, ///< Mobile station type (TX uplink, RX downlink)
GsmL1_DevType_Rxd = 0x01, ///< Monitor type (RX downlink only)
GsmL1_DevType_Rxu = 0x02, ///< Monitor type (RX uplink only)
GsmL1_DevType_Txd = 0x04, ///< Jammer type (TX downlink only)
GsmL1_DevType_Txu = 0x08 ///< Jammer type (TX uplink only)
} GsmL1_DevType_t;
/****************************************************************************
* Enum : GsmL1_Dir_t
************************************************************************//**
*
* Indicate the path of the transmission.
*
* @ingroup gsml1_api_const
*
****************************************************************************/
typedef enum GsmL1_Dir_t
{
GsmL1_Dir_None = 0x00, ///< No path
GsmL1_Dir_RxDownlink = 0x01, ///< Receive transmission path from Bts to the mobile station
GsmL1_Dir_RxUplink = 0x02, ///< Receive transmission path from mobile station to the Bts
GsmL1_Dir_TxDownlink = 0x04, ///< Transmit on transmission path from Bts to the mobile station
GsmL1_Dir_TxUplink = 0x08 ///< Transmit on transmission path from mobile station to the Bts
} GsmL1_Dir_t;
/****************************************************************************
* Enum : GsmL1_CipherId_t
************************************************************************//**
*
* Ciphering algorithm ID.
*
* @ingroup gsml1_api_const
*
****************************************************************************/
typedef enum GsmL1_CipherId_t
{
GsmL1_CipherId_A50 = 0x00, ///< No encryption
GsmL1_CipherId_A51 = 0x01, ///< A5/1
GsmL1_CipherId_A52 = 0x02, ///< A5/2
GsmL1_CipherId_A53 = 0x03 ///< A5/3
} GsmL1_CipherId_t;
/****************************************************************************
* Enum : GsmL1_FreqBand_t
************************************************************************//**
*
* GSM frequency bands.
*
* @ingroup gsml1_api_const
*
****************************************************************************/
typedef enum GsmL1_FreqBand_t
{
GsmL1_FreqBand_850 = 0, ///< GSM-850 frequency band
GsmL1_FreqBand_900, ///< GSM-900 frequency band
GsmL1_FreqBand_1800, ///< GSM-1800 frequency band
GsmL1_FreqBand_1900, ///< GSM-1900 frequency band
Num_GsmL1_FreqBand ///< Number of frequency bands
} GsmL1_FreqBand_t;
/****************************************************************************
* Enum : GsmL1_TchFormat_t
************************************************************************//**
*
* TCH message packin format.
*
* @ingroup gsml1_api_const
*
****************************************************************************/
typedef enum GsmL1_TchFormat_t
{
GsmL1_TchFormat_Rtp = 0, ///< RTP format
GsmL1_TchFormat_If2 ///< IF2 format (AMR), custom (HR, FR, EFR)
} GsmL1_TchFormat_t;
/****************************************************************************
* Enum : GsmL1_PrimId_t
************************************************************************//**
*
* Inter-layer communication primitives ID definitions
*
* @ingroup gsml1_api_const
*
****************************************************************************/
typedef enum GsmL1_PrimId_t
{
GsmL1_PrimId_MphInitReq = 0, ///< Initialize the base station.
GsmL1_PrimId_MphCloseReq, ///< Closes the base station.
GsmL1_PrimId_MphConnectReq, ///< Connect a physical channel.
GsmL1_PrimId_MphDisconnectReq, ///< Disconnect a physical channel.
GsmL1_PrimId_MphActivateReq, ///< Activate a logical channel over a physical channel.
GsmL1_PrimId_MphDeactivateReq, ///< Deactivate a logical channel from a physical channel.
GsmL1_PrimId_MphConfigReq, ///< Configure a physical channel.
GsmL1_PrimId_MphMeasureReq, ///< Measure the received signal strenght indication on a device.
GsmL1_PrimId_MphInitCnf, ///< Confirm the reception of a MPH-INIT_REQ primitive.
GsmL1_PrimId_MphCloseCnf, ///< Confirm the reception of a MPH-CLOSE_REQ primitive.
GsmL1_PrimId_MphConnectCnf, ///< Returns an handle pointing to the connected physical channel.
GsmL1_PrimId_MphDisconnectCnf, ///< Confirm the reception of a MPH-DISCONNECT_REQ primitive.
GsmL1_PrimId_MphActivateCnf, ///< Confirm the reception of a MPH-ACTIVATE_REQ primitive.
GsmL1_PrimId_MphDeactivateCnf, ///< Confirm the reception of a MPH-DEACTIVATE_REQ primitive.
GsmL1_PrimId_MphConfigCnf, ///< Confirm the reception of a MPH-CONFIG_REQ primitive.
GsmL1_PrimId_MphMeasureCnf, ///< Returns the measurement made on the reception of a MPH-MEASURE-REQ primitive.
GsmL1_PrimId_MphTimeInd, ///< Infom upper layer of the actual timeslot and frame number.
GsmL1_PrimId_MphSyncInd, ///< Synchronization status indication
GsmL1_PrimId_PhEmptyFrameReq, ///< Layer 2 has nothing to transmit on a PH-READY-TO-SEND.
GsmL1_PrimId_PhDataReq, ///< Transfer a message frame unit to the layer 1.
GsmL1_PrimId_PhConnectInd, ///< Inform layer 2 that a logical channel has connected on layer 1.
GsmL1_PrimId_PhReadyToSendInd, ///< Ask layer 3 for something to transmit.
GsmL1_PrimId_PhDataInd, ///< Transmit a message frame unit to layer 2.
GsmL1_PrimId_PhRaInd, ///< Inform the layer 2 of a random access initiated by the MS.
GsmL1_PrimId_NUM ///< Only used to validate parameters
} GsmL1_PrimId_t;
/****************************************************************************
* enum: GsmL1_BurstType_t
************************************************************************//**
*
* GSM Burst Types
*
* @see
* TS 3GPP 45.002 - 5.0
*
* @ingroup gsml1_common_const
*
***************************************************************************/
typedef enum GsmL1_BurstType_t
{
GsmL1_BurstType_Sync = 0, ///< Synchronization Burst
GsmL1_BurstType_Normal = 1, ///< Normal Burst
GsmL1_BurstType_Dummy = 2, ///< Dummy Burst
GsmL1_BurstType_Normal8Psk = 3, ///< Normal Burst (8PSK)
GsmL1_BurstType_Access_0 = 4, ///< Access Burst (Training sequence 0)
GsmL1_BurstType_Access_1 = 5, ///< Access Burst (Training sequence 1)
GsmL1_BurstType_Access_2 = 6, ///< Access Burst (Training sequence 2)
GsmL1_BurstType_Freq = 7, ///< Frequency Correction Burst
GsmL1_BurstType_NUM ///< Only used to validate parameters
} GsmL1_BurstType_t;
/****************************************************************************
* typedef enum : GsmL1_If2FrTypeIdx_t
************************************************************************//**
*
* List of every IF2 frame types.
*
* @ingroup gsml1_api_const
*
***************************************************************************/
typedef enum GsmL1_If2FrTypeIdx_t
{
GsmL1_If2FrTypeIdx_4_75 = 0, ///< AMR 4,75
GsmL1_If2FrTypeIdx_5_15, ///< AMR 5,15
GsmL1_If2FrTypeIdx_5_9, ///< AMR 5,9
GsmL1_If2FrTypeIdx_6_7, ///< AMR 6,7
GsmL1_If2FrTypeIdx_7_4, ///< AMR 7,4
GsmL1_If2FrTypeIdx_7_95, ///< AMR 7,95
GsmL1_If2FrTypeIdx_10_2, ///< AMR 10,2
GsmL1_If2FrTypeIdx_12_2, ///< AMR 12,2
GsmL1_If2FrTypeIdx_SID, ///< AMR SID
GsmL1_If2FrTypeIdx_NoData = 15 ///< NO DATA
} GsmL1_If2FrTypeIdx_t;
/****************************************************************************
* typedef enum : GsmL1_TchPlType_t
************************************************************************//**
*
* List of every payload type supported on a TCH physical channel.
*
* @ingroup gsml1_api_const
*
***************************************************************************/
typedef enum GsmL1_TchPlType_t
{
GsmL1_TchPlType_NA = 0, ///< Not applicable, unknown, invalid
GsmL1_TchPlType_Fr, ///< Compacted ETSI full-rate traffic speech frame
GsmL1_TchPlType_Hr, ///< Compacted ETSI half-rate traffic speech frame
GsmL1_TchPlType_Efr, ///< Compacted ETSI enhanced full-rate traffic speech frame
GsmL1_TchPlType_Amr, ///< RTP/IF2 adaptive multi-rate traffic speech frame
// These cannot be formatted using IF2 format !!
GsmL1_TchPlType_Amr_SidBad, ///< Indicates that errors are detected
GsmL1_TchPlType_Amr_Onset, ///< Used to signal the Codec mode for the first speech frame after DTX
GsmL1_TchPlType_Amr_Ratscch, ///< Frames used to convey RATSCCH messages
GsmL1_TchPlType_Amr_SidUpdateInH, ///< Used to inhibit the second part of a SID_UPDATE frame if there is a speech onset
GsmL1_TchPlType_Amr_SidFirstP1, ///< First part of marker to define end of speech, start of DTX
GsmL1_TchPlType_Amr_SidFirstP2, ///< Second part of marker to define end of speech, start of DTX
GsmL1_TchPlType_Amr_SidFirstInH, ///< Used to inhibit the second part of a SID_FIRST_P1 frame if there is a speech onset
GsmL1_TchPlType_Amr_RatscchMarker, ///< Marker to identify Ratscch frames
GsmL1_TchPlType_Amr_RatscchData ///< Frame that conveys the actual Ratscch message
} GsmL1_TchPlType_t;
/****************************************************************************
* Enum : GsmL1_TchPlFmt_t
************************************************************************//**
*
* List of every payload packing format supported on a TCH physical channel.
*
* @ingroup gsml1_api_const
*
****************************************************************************/
typedef enum GsmL1_TchPlFmt_t
{
GsmL1_TchPlFmt_Rtp = 0, ///< RFC XXXX - RTP format
GsmL1_TchPlFmt_If2 ///< Etsi IF2 format (AMR), custom (HR, FR, EFR)
} GsmL1_TchPlFmt_t;
/****************************************************************************
* typedef enum : GsmL1_PdtchPlType_t
************************************************************************//**
*
* List of every payload type supported on a PDTCH physical channel.
*
* @ingroup gsml1_api_const
*
***************************************************************************/
typedef enum GsmL1_PdtchPlType_t
{
GsmL1_PdtchPlType_NA = 0x00, ///< Not applicable, unknown, invalid
GsmL1_PdtchPlType_Hdr = 0x01, ///< Header only is present and valid
GsmL1_PdtchPlType_Hdr_Data1 = 0x03, ///< Header and 1st half of data (2nd half is present but invalid)
GsmL1_PdtchPlType_Hdr_Data2 = 0x05, ///< Header and 2nd half of data (1st half is present but invalid)
GsmL1_PdtchPlType_Full = 0x07 ///< Full data present and valid
} GsmL1_PdtchPlType_t;
/****************************************************************************
* typedef enum : GsmL1_AmrCodec_t
************************************************************************//**
*
* List of every supported codecs of a TCH/AMR active codec set.
*
* @ingroup gsml1_api_const
*
***************************************************************************/
typedef enum GsmL1_AmrCodec_t
{
GsmL1_AmrCodec_Unset = 0, ///< Used to indicate that a slot of the Active Codec Slot is unset
GsmL1_AmrCodec_4_75, ///< 4,75 Kbits/s codec
GsmL1_AmrCodec_5_15, ///< 5,15 Kbits/s codec
GsmL1_AmrCodec_5_9, ///< 5,9 Kbits/s codec
GsmL1_AmrCodec_6_7, ///< 6,7 Kbits/s codec
GsmL1_AmrCodec_7_4, ///< 7,4 Kbits/s codec
GsmL1_AmrCodec_7_95, ///< 7,95 Kbits/s codec
GsmL1_AmrCodec_10_2, ///< 10,2 Kbits/s codec
GsmL1_AmrCodec_12_2, ///< 12,2 Kbits/s codec
GsmL1_AmrCodec_NUM ///< Only used to retrieve the last Codec number
} GsmL1_AmrCodec_t;
/****************************************************************************
* typedef enum : GsmL1_AmrCmiPhase_t
************************************************************************//**
*
* Available codec mode indication phase.
*
* @ingroup gsml1_api_const
*
***************************************************************************/
typedef enum GsmL1_AmrCmiPhase_t
{
GsmL1_AmrCmiPhase_NA = 0, ///< AMR CMI phase is not applicable
GsmL1_AmrCmiPhase_Odd, ///< AMR odd phase codec mode indication (default)
GsmL1_AmrCmiPhase_Even ///< AMR even phase codec mode indication
} GsmL1_AmrCmiPhase_t;
/****************************************************************************
* typedef enum : GsmL1_AmrCodecMode_t
************************************************************************//**
*
* Available codec modes of a TCH/AFS or TCH/AHS active codec set.
*
* @ingroup gsml1_api_const
*
***************************************************************************/
typedef enum GsmL1_AmrCodecMode_t
{
GsmL1_AmrCodecMode_1 = 0, ///< AMR Codec Mode 1
GsmL1_AmrCodecMode_2, ///< AMR Codec Mode 2
GsmL1_AmrCodecMode_3, ///< AMR Codec Mode 3
GsmL1_AmrCodecMode_4, ///< AMR Codec Mode 4
GsmL1_AmrCodecMode_Unset ///< Unset AMR Codec Mode
} GsmL1_AmrCodecMode_t;
/****************************************************************************
* typedef : GsmL1_ConfigParamId_t
************************************************************************//**
*
* Id used to identify which parameter is configured through a MPH-CONFIG-REQ.
*
* @ingroup gsml1_api_const
*
***************************************************************************/
typedef enum GsmL1_ConfigParamId_t
{
GsmL1_ConfigParamId_SetNbTsc, ///< Set the normal burst TSC of the specified RF device
GsmL1_ConfigParamId_SetTxPowerLevel, ///< Set the TX power level of the specified RF device
GsmL1_ConfigParamId_SetLogChParams, ///< Configure the logical channel specific parameters
GsmL1_ConfigParamId_SetCipheringParams, ///< Configure the ciphering parameters
GsmL1_ConfigParamId_NUM ///< Only used to validate parameters
} GsmL1_ConfigParamId_t;
/****************************************************************************
* Public constant *
****************************************************************************/
/// Maximum length of a layer 2 message unit.
#define MAX_L2MSGSIZE 160 // ( Based on a PDTCH block type 13 (MCS-9) [155 bytes] )
/// Advance taken by the library (counted in frames where 1 frame = 8 timeslots )
#define GSML1_FN_ADVANCE 6
///< Size (in byte) of a Traffic Channel header located at the start of every msg unit
#define TCH_HEADER_SIZE 1
#ifdef __cplusplus
}
#endif // extern "C"
#endif // GSML1CONST_H__

174
api/gsml1dbg.h

@ -0,0 +1,174 @@
#ifndef GSMDBG_H__
#define GSMDBG_H__
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/****************************************************************************
* Includes *
****************************************************************************/
#include <stdint.h>
#include <stdio.h>
#include "gsml1types.h" // GsmL1_RxBurst_t
/****************************************************************************
* Defines *
****************************************************************************/
// Debugging system's verbosity level flags
#define DBG_NONE 0x00000000
#define DBG_ALL 0xFFFFFFFF
#define DBG_DEBUG 0x80000000
#define DBG_L1WARNING 0x40000000
#define DBG_ERROR 0x20000000
#define DBG_L1RXMSG 0x10000000
#define DBG_L1RXMSGBYTE 0x08000000
#define DBG_L1TXMSG 0x04000000
#define DBG_L1TXMSGBYTE 0x02000000
#define DBG_MPHCNF 0x01000000
#define DBG_MPHIND 0x00800000
#define DBG_MPHREQ 0x00400000
#define DBG_PHIND 0x00200000
#define DBG_PHREQ 0x00100000
#define DBG_PHYRF 0x00080000
#define DBG_PHYRFMSGBYTE 0x00040000
#define DBG_MODE 0x00020000
#define DBG_TDMAINFO 0x00010000
#define DBG_BADCRC 0x00008000
#define DBG_PHINDBYTE 0x00004000
#define DBG_PHREQBYTE 0x00002000
#define DBG_DEVICEMSG 0x00000800
#define DBG_RACHINFO 0x00000040
#define DBG_LOGCHINFO 0x00000020
#define DBG_MEMORY 0x00000010
#define DBG_PROFILING 0x00000008
#define DBG_TESTCOMMENT 0x00000004
#define DBG_TEST 0x00000002
#define DBG_STATUS 0x00000001
#define DBG_RSSI_THRESHOLD -60.0f ///< Minimum RSSI to be considered a valid burst
/****************************************************************************
* Public functions *
****************************************************************************/
/****************************************************************************
* Function : GsmL1Dbg_Init
************************************************************************//**
*
* Print a debug string to the standard output.
*
* @param [in] u32Level
* Verbosity level of the printed message.
*
* @param [in] pExtPrintfCb
* Function pointer to an external routine able to print the formated string.
*
* @param [out] pstrOutputFileName
* Name of the output file ( Set to NULL in order to disable this feature )
*
* @return
* None.
*
* @ingroup gsm_common_debug
*
***************************************************************************/
void GsmL1Dbg_Init( uint32_t u32Level,
void (*pExtPrintfCb) ( char *pString),
char *pstrOutputFileName );
/****************************************************************************
* Function : GsmL1Dbg_SetLevel
************************************************************************//**
*
* Set the verbosity level.
*
* @param [in] u32Level
* Verbosity level of the printed message.
*
* @return
* None.
*
* @ingroup gsm_common_debug
*
***************************************************************************/
void GsmL1Dbg_SetLevel( uint32_t u32Level );
/****************************************************************************
* Function : GsmL1Dbg_Close
************************************************************************//**
*
* Close the debugging system.
*
* @return
* None.
*
* @ingroup gsm_common_debug
*
***************************************************************************/
void GsmL1Dbg_Close();
/****************************************************************************
* Function : GsmL1Dbg_Printf
************************************************************************//**
*
* Print a debug string to the standard output.
*
* @param [in] u32Level
* Verbosity level of the printed message.
*
* @param [in] *format
* String that contains the text to be written to the stdout.
*
* @return
* None.
*
* @ingroup gsm_common_debug
*
***************************************************************************/
void GsmL1Dbg_Printf( uint32_t u32Level, char const *format, ... );
/****************************************************************************
* Function : GsmL1Dbg_DumpBuffer
************************************************************************//**
*
* Dump a generic uint8_t buffer.
*
* @param [in] u32Level
* Verbosity level of the printed message.
*
* @param [in] u32FirstByte
* Starting byte index
*
* @param [in] u32Length
* Number of bytes to dump
*
* @param [in] pu8Buffer
* Pointer to the dumped buffer
*
* @return
* None.
*
* @ingroup gsm_common_debug
*
***************************************************************************/
void GsmL1Dbg_DumpBuffer( uint32_t u32Level,
uint32_t u32FirstByte,
uint32_t u32Length,
uint8_t *pu8Buffer );
#ifdef __cplusplus
}
#endif // extern "C"
#endif // GSMDBG_H__

101
api/gsml1link.h

@ -0,0 +1,101 @@
#ifndef GSML1LINK_H__
#define GSML1LINK_H__
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/****************************************************************************
* Includes *
****************************************************************************/
#include "gsml1serv.h"
#include "gsml1prim.h"
#include "gsml1const.h"
#include "gsml1types.h"
/****************************************************************************
* Types *
****************************************************************************/
/****************************************************************************
* Public Functions *
****************************************************************************/
/****************************************************************************
* Function : GsmL1Link_Init
************************************************************************//**
*
* Initialise the GSM layer 1 library.
*
* @return
* GsmL1_Status_Success or the error code
*
* @ingroup gsml1_api_services
*
****************************************************************************/
GsmL1_Status_t GsmL1Link_Init( void );
/****************************************************************************
* Function : GsmL1Link_SetExternalServices
************************************************************************//**
*
* Set every services provided to the layer 1 by external libraries
*
* @param [in] pL3ProvidedServices
* Points to a structure containing all Layer 3 external services
*
* @param [in] pL2ProvidedServices
* Points to a structure containing all Layer 3 external services
*
* @param [in] pPhyRfProvidedServices
* Points to a structure containing all PhyRf external services
*
* @return
* GsmL1_Status_Success or the error code
*
* @ingroup gsml1_api_services
*
****************************************************************************/
GsmL1_Status_t GsmL1Link_SetExternalServices( Gsm_L3ProvidedServices_t *pL3ProvidedServices,
Gsm_L2ProvidedServices_t *pL2ProvidedServices,
Gsm_PhyRfProvidedServices_t *pPhyRfProvidedServices );
/****************************************************************************
* Function : GsmL1Link_GetProvidedServices
************************************************************************//**
*
* Return a strucuture containing all service functions pointer provided
* by the physical link layer library to the external context.
*
* @param [out] pPhyLinkProvidedServices
* Points to a structure of all GSM layer 1 library services function pointer.
*
* @return
* GsmL1_Status_Success or the error code
*
* @ingroup gsml1_api_services
*
****************************************************************************/
GsmL1_Status_t GsmL1Link_GetProvidedServices( Gsm_PhyLinkProvidedServices_t *pPhyLinkProvidedServices );
/****************************************************************************
* Function : GsmL1Link_Close
************************************************************************//**
*
* Close the GSM layer 1 instance and free every allocated ressources.
*
* @return
* GsmL1_Status_Success or the error code
*
* @ingroup gsml1_api_services
*
****************************************************************************/
GsmL1_Status_t GsmL1Link_Close( void );
#ifdef __cplusplus
}
#endif // extern "C"
#endif // GSML1_H__

877
api/gsml1prim.h

@ -0,0 +1,877 @@
#ifndef GSML1PRIM_H__
#define GSML1PRIM_H__
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/****************************************************************************
* Includes *
****************************************************************************/
#ifndef WIN32
#include <stdint.h>
#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]
#ifndef HW_SYSMOBTS_V1
uint8_t u8AutoDummy; /**< Automatically transmit dummy burst
when there is nothing else to transmit. */
#endif
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
{