common_lib.h 12 KB
Newer Older
1
/*******************************************************************************
2
    OpenAirInterface
3 4 5 6 7 8 9 10 11 12 13 14 15 16
    Copyright(c) 1999 - 2014 Eurecom

    OpenAirInterface is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.


    OpenAirInterface is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
17 18
    along with OpenAirInterface.The full GNU General Public License is
    included in this distribution in the file called "COPYING". If not,
19 20 21 22 23
    see <http://www.gnu.org/licenses/>.

   Contact Information
   OpenAirInterface Admin: openair_admin@eurecom.fr
   OpenAirInterface Tech : openair_tech@eurecom.fr
24
   OpenAirInterface Dev  : openair4g-devel@lists.eurecom.fr
25

ghaddab's avatar
ghaddab committed
26
   Address      : Eurecom, Campus SophiaTech, 450 Route des Chappes, CS 50193 - 06904 Biot Sophia Antipolis cedex, FRANCE
27 28

 *******************************************************************************/
29 30 31 32 33 34 35 36 37 38
/*! \file common_lib.h 
 * \brief common APIs for different RF frontend device 
 * \author HongliangXU, Navid Nikaein
 * \date 2015
 * \version 0.2
 * \company Eurecom
 * \maintainer:  navid.nikaein@eurecom.fr
 * \note
 * \warning
 */
39

knopp's avatar
knopp committed
40 41 42
#ifndef COMMON_LIB_H
#define COMMON_LIB_H
#include <stdint.h>
43
#include <sys/types.h>
knopp's avatar
knopp committed
44

45 46 47 48 49
/* name of shared library implementing the radio front end */
#define OAI_RF_LIBNAME        "liboai_device.so"
/* name of shared library implementing the transport */
#define OAI_TP_LIBNAME        "liboai_transpro.so"

50 51 52
/* flags for BBU to determine whether the attached radio head is local or remote */
#define BBU_LOCAL_RADIO_HEAD  0
#define BBU_REMOTE_RADIO_HEAD 1
53

54 55 56
#define MAX_CARDS 8


knopp's avatar
knopp committed
57
typedef int64_t openair0_timestamp;
58
typedef volatile int64_t openair0_vtimestamp;
59

60
 
Rohit Gupta's avatar
Rohit Gupta committed
61
/*!\brief structrue holds the parameters to configure USRP devices*/
knopp's avatar
knopp committed
62
typedef struct openair0_device_t openair0_device;
63

knopp's avatar
knopp committed
64

65 66 67



68

69
//#define USRP_GAIN_OFFSET (56.0)  // 86 calibrated for USRP B210 @ 2.6 GHz to get equivalent RS EPRE in OAI to SMBV100 output
knopp's avatar
knopp committed
70

knopp's avatar
knopp committed
71 72 73 74
typedef enum {
  max_gain=0,med_gain,byp_gain
} rx_gain_t;

75 76 77 78 79
typedef enum {
  duplex_mode_TDD=1,duplex_mode_FDD=0
} duplex_mode_t;


80

81
/** @addtogroup _GENERIC_PHY_RF_INTERFACE_
82 83
 * @{
 */
84 85 86 87 88 89 90 91 92 93 94 95
/*!\brief RF device types
 */
typedef enum {
  MIN_RF_DEV_TYPE = 0,
  /*!\brief device is ExpressMIMO */
  EXMIMO_DEV,
  /*!\brief device is USRP B200/B210*/
  USRP_B200_DEV,
  /*!\brief device is USRP X300/X310*/
  USRP_X300_DEV,
  /*!\brief device is BLADE RF*/
  BLADERF_DEV,
96 97
  /*!\brief device is LMSSDR (SoDeRa)*/
  LMSSDR_DEV,
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
  /*!\brief device is NONE*/
  NONE_DEV,
  MAX_RF_DEV_TYPE

} dev_type_t;

/*!\brief transport protocol types
 */
typedef enum {
  MIN_TRANSP_TYPE = 0,
  /*!\brief transport protocol ETHERNET */
  ETHERNET_TP,
  /*!\brief no transport protocol*/
  NONE_TP,
  MAX_TRANSP_TYPE

} transport_type_t;


/*!\brief  openair0 device host type */
typedef enum {
  MIN_HOST_TYPE = 0,
 /*!\brief device functions within a BBU */
  BBU_HOST,
 /*!\brief device functions within a RRH */
  RRH_HOST,
  MAX_HOST_TYPE

}host_type_t;

Rohit Gupta's avatar
Rohit Gupta committed
128 129

/*! \brief RF Gain clibration */ 
130 131 132 133 134 135
typedef struct {
  //! Frequency for which RX chain was calibrated
  double freq;
  //! Offset to be applied to RX gain
  double offset;
} rx_gain_calib_table_t;
knopp's avatar
knopp committed
136

Rohit Gupta's avatar
Rohit Gupta committed
137
/*! \brief RF frontend parameters set by application */
knopp's avatar
knopp committed
138
typedef struct {
gauthier's avatar
gauthier committed
139
  //! Module ID for this configuration
140
  int Mod_id;
Rohit Gupta's avatar
Rohit Gupta committed
141
  //! device log level
142
  int log_level;
143 144
  //! duplexing mode
  duplex_mode_t duplex_mode;
145 146 147 148
  //! number of downlink resource blocks
  int num_rb_dl;
  //! number of samples per frame 
  unsigned int  samples_per_frame;
gauthier's avatar
gauthier committed
149
  //! the sample rate for both transmit and receive.
knopp's avatar
knopp committed
150
  double sample_rate;
151 152
  //! flag to indicate that the device is doing mmapped DMA transfers
  int mmapped_dma;
153 154
  //! offset in samples between TX and RX paths
  int tx_sample_advance;
155 156
  int samples_per_packet;
  int tx_scheduling_advance;
gauthier's avatar
gauthier committed
157
  //! number of RX channels (=RX antennas)
knopp's avatar
knopp committed
158
  int rx_num_channels;
gauthier's avatar
gauthier committed
159
  //! number of TX channels (=TX antennas)
knopp's avatar
knopp committed
160
  int tx_num_channels;
Raymond Knopp's avatar
Raymond Knopp committed
161 162 163 164
  //! \brief RX base addresses for mmapped_dma
  int32_t* rxbase[4];
  //! \brief TX base addresses for mmapped_dma
  int32_t* txbase[4];
gauthier's avatar
gauthier committed
165 166
  //! \brief Center frequency in Hz for RX.
  //! index: [0..rx_num_channels[
knopp's avatar
knopp committed
167
  double rx_freq[4];
gauthier's avatar
gauthier committed
168 169
  //! \brief Center frequency in Hz for TX.
  //! index: [0..rx_num_channels[ !!! see lte-ue.c:427 FIXME iterates over rx_num_channels
knopp's avatar
knopp committed
170
  double tx_freq[4];
171
  //! \brief memory
172 173 174
  //! \brief Pointer to Calibration table for RX gains
  rx_gain_calib_table_t *rx_gain_calib_table;

175
  //! mode for rxgain (ExpressMIMO2) 
knopp's avatar
knopp committed
176
  rx_gain_t rxg_mode[4];
gauthier's avatar
gauthier committed
177
  //! \brief Gain for RX in dB.
178
  //! index: [0..rx_num_channels]
knopp's avatar
knopp committed
179
  double rx_gain[4];
180 181 182
  //! \brief Gain offset (for calibration) in dB
  //! index: [0..rx_num_channels]
  double rx_gain_offset[4];
gauthier's avatar
gauthier committed
183
  //! gain for TX in dB
knopp's avatar
knopp committed
184
  double tx_gain[4];
gauthier's avatar
gauthier committed
185
  //! RX bandwidth in Hz
knopp's avatar
knopp committed
186
  double rx_bw;
gauthier's avatar
gauthier committed
187
  //! TX bandwidth in Hz
knopp's avatar
knopp committed
188
  double tx_bw;
189 190
  //! Auto calibration flag
  int autocal[4];
191 192 193 194 195 196 197 198 199 200 201 202
  //! rf devices work with x bits iqs when oai have its own iq format
  //! the two following parameters are used to convert iqs 
  int iq_txshift;
  int iq_rxrescale;
  //! remote IP/MAC addr for Ethernet interface
  char *remote_addr;
  //! remote port number for Ethernet interface
  unsigned int remote_port;
  //! local IP/MAC addr for Ethernet interface (eNB/BBU, UE)
  char *my_addr;
  //! local port number for Ethernet interface (eNB/BBU, UE)
  unsigned int my_port;
203 204
  //! Configuration file for LMS7002M
  char *configFilename;
knopp's avatar
knopp committed
205 206
} openair0_config_t;

Rohit Gupta's avatar
Rohit Gupta committed
207
/*! \brief RF mapping */ 
208
typedef struct {
Rohit Gupta's avatar
Rohit Gupta committed
209
  //! card id
210
  int card;
Rohit Gupta's avatar
Rohit Gupta committed
211
  //! rf chain id
212 213 214 215
  int chain;
} openair0_rf_map;


216 217 218
typedef struct {
  char *remote_addr;
  //! remote port number for Ethernet interface
219
  uint16_t remote_port;
220 221 222
  //! local IP/MAC addr for Ethernet interface (eNB/BBU, UE)
  char *my_addr;
  //! local port number for Ethernet interface (eNB/BBU, UE)
223 224
  uint16_t  my_port;
  //! local Ethernet interface (eNB/BBU, UE)
225
  char *local_if_name;
226 227 228 229 230 231 232
  //! tx_sample_advance for RF + ETH
  uint8_t tx_sample_advance;
  //! tx_scheduling_advance for RF + ETH
  uint8_t tx_scheduling_advance;
  //! iq_txshift  for RF + ETH
  uint8_t iq_txshift;
  //! transport type preference  (RAW/UDP)
233
  uint8_t transp_preference;
234 235
  //! radio front end preference (EXMIMO,USRP, BALDERF,LMSSDR)
  uint8_t rf_preference;
236
} eth_params_t;
237 238


239 240 241 242 243 244 245 246
typedef struct {
  //! Tx buffer for if device
  void *tx;
  //! Rx buffer for if device
  void *rx;
} if_buffer_t;


247
/*!\brief structure holds the parameters to configure USRP devices */
knopp's avatar
knopp committed
248
struct openair0_device_t {
249
  /*!brief Module ID of this device */
250
  int Mod_id;
251
  
252
  /*!brief Type of this device */
253 254
  dev_type_t type;

255 256 257 258 259
  /*!brief Transport protocol type that the device suppports (in case I/Q samples need to be transported) */
  transport_type_t transp_type;

   /*!brief Type of the device's host (BBU/RRH) */
  host_type_t host_type;
260

261
  /* !brief RF frontend parameters set by application */
262
  openair0_config_t *openair0_cfg;
263

264
  /*!brief Can be used by driver to hold internal structure*/
knopp's avatar
knopp committed
265 266 267 268
  void *priv;

  /* Functions API, which are called by the application*/

269 270 271
  /*! \brief Called to start the transceiver. Return 0 if OK, < 0 if error
      @param device pointer to the device structure specific to the RF hardware target
  */
knopp's avatar
knopp committed
272 273
  int (*trx_start_func)(openair0_device *device);

274 275 276 277 278
  /*! \brief Called to send a request message between BBU-RRH
      @param device pointer to the device structure specific to the RF hardware target
      @param msg pointer to the message structure passed between BBU-RRH
      @param msg_len length of the message  
  */  
279
  int (*trx_request_func)(openair0_device *device, void *msg, ssize_t msg_len);
280

281 282 283 284 285
  /*! \brief Called to send a reply  message between BBU-RRH
      @param device pointer to the device structure specific to the RF hardware target
      @param msg pointer to the message structure passed between BBU-RRH
      @param msg_len length of the message  
  */  
Rohit Gupta's avatar
Rohit Gupta committed
286
  int (*trx_reply_func)(openair0_device *device, void *msg, ssize_t msg_len);
287

288 289 290 291 292 293 294 295
  /*! \brief Called to send samples to the RF target
      @param device pointer to the device structure specific to the RF hardware target
      @param timestamp The timestamp at whicch the first sample MUST be sent 
      @param buff Buffer which holds the samples
      @param nsamps number of samples to be sent
      @param antenna_id index of the antenna if the device has multiple anteannas
      @param flags flags must be set to TRUE if timestamp parameter needs to be applied
  */   
296
  int (*trx_write_func)(openair0_device *device, openair0_timestamp timestamp, void **buff, int nsamps,int antenna_id, int flags);
knopp's avatar
knopp committed
297

gauthier's avatar
gauthier committed
298 299
  /*! \brief Receive samples from hardware.
   * Read \ref nsamps samples from each channel to buffers. buff[0] is the array for
knopp's avatar
knopp committed
300 301
   * the first channel. *ptimestamp is the time at which the first sample
   * was received.
gauthier's avatar
gauthier committed
302 303
   * \param device the hardware to use
   * \param[out] ptimestamp the time at which the first sample was received.
Rohit Gupta's avatar
Rohit Gupta committed
304
   * \param[out] buff An array of pointers to buffers for received samples. The buffers must be large enough to hold the number of samples \ref nsamps.
gauthier's avatar
gauthier committed
305
   * \param nsamps Number of samples. One sample is 2 byte I + 2 byte Q => 4 byte.
Rohit Gupta's avatar
Rohit Gupta committed
306
   * \param antenna_id Index of antenna for which to receive samples
gauthier's avatar
gauthier committed
307 308
   * \returns the number of sample read
   */
309 310 311 312 313 314 315 316 317 318 319 320 321
  int (*trx_read_func)(openair0_device *device, openair0_timestamp *ptimestamp, void **buff, int nsamps,int antenna_id);

  /*! \brief print the device statistics  
   * \param device the hardware to use
   * \returns  0 on success
   */
  int (*trx_get_stats_func)(openair0_device *device);

  /*! \brief Reset device statistics  
   * \param device the hardware to use
   * \returns 0 in success 
   */
  int (*trx_reset_stats_func)(openair0_device *device);
knopp's avatar
knopp committed
322

Rohit Gupta's avatar
Rohit Gupta committed
323 324 325
  /*! \brief Terminate operation of the transceiver -- free all associated resources 
   * \param device the hardware to use
   */
knopp's avatar
knopp committed
326
  void (*trx_end_func)(openair0_device *device);
327

Rohit Gupta's avatar
Rohit Gupta committed
328 329 330
  /*! \brief Stop operation of the transceiver 
   * \param card RF Card to use
   */
331 332 333 334 335
  int (*trx_stop_func)(int card);

  /* Functions API related to UE*/

  /*! \brief Set RX feaquencies 
Rohit Gupta's avatar
Rohit Gupta committed
336 337 338
   * \param device the hardware to use
   * \param openair0_cfg RF frontend parameters set by application
   * \param exmimo_dump_config  dump EXMIMO configuration 
339 340 341
   * \returns 0 in success 
   */
  int (*trx_set_freq_func)(openair0_device* device, openair0_config_t *openair0_cfg,int exmimo_dump_config);
342
  
343
  /*! \brief Set gains
Rohit Gupta's avatar
Rohit Gupta committed
344 345
   * \param device the hardware to use
   * \param openair0_cfg RF frontend parameters set by application
346 347 348 349
   * \returns 0 in success 
   */
  int (*trx_set_gains_func)(openair0_device* device, openair0_config_t *openair0_cfg);

knopp's avatar
knopp committed
350 351
};

352
/* type of device init function, implemented in shared lib */
353 354 355
typedef int(*oai_device_initfunc_t)(openair0_device *device, openair0_config_t *openair0_cfg);
/* type of transport init function, implemented in shared lib */
typedef int(*oai_transport_initfunc_t)(openair0_device *device, openair0_config_t *openair0_cfg, eth_params_t * eth_params);
knopp's avatar
knopp committed
356 357 358 359

#ifdef __cplusplus
extern "C"
{
gauthier's avatar
gauthier committed
360 361
#endif

362 363

  /*! \brief Initialize openair RF target. It returns 0 if OK */
364 365
  int openair0_device_load(openair0_device *device, openair0_config_t *openair0_cfg);  
  /*! \brief Initialize transport protocol . It returns 0 if OK */
366
  int openair0_transport_load(openair0_device *device, openair0_config_t *openair0_cfg, eth_params_t * eth_params);
367

368
  
369
 /*! \brief Get current timestamp of USRP
Rohit Gupta's avatar
Rohit Gupta committed
370 371
  * \param device the hardware to use
  */
372
  openair0_timestamp get_usrp_time(openair0_device *device);
373

374
 /*! \brief Set RX frequencies 
Rohit Gupta's avatar
Rohit Gupta committed
375 376
  * \param device the hardware to use
  * \param openair0_cfg RF frontend parameters set by application
377
  * \returns 0 in success 
Rohit Gupta's avatar
Rohit Gupta committed
378
  */
379
  int openair0_set_rx_frequencies(openair0_device* device, openair0_config_t *openair0_cfg);
Rohit Gupta's avatar
Rohit Gupta committed
380

381
/*@}*/
382

gauthier's avatar
gauthier committed
383
#ifdef __cplusplus
knopp's avatar
knopp committed
384 385 386
}
#endif

knopp's avatar
knopp committed
387
#endif // COMMON_LIB_H
388