sysmo-bts
/
femtobts-firmware
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

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

hardware/rev-b
Holger Hans Peter Freyther 10 years ago
commit
aeedfeb703
14 changed files with 2531 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  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
View File

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

6
README
View File

@ -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
View File

@ -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
View File

@ -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
View File

@ -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
View File

@ -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
{
<