common_lib.h 12.1 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

Raymond Knopp's avatar
 
Raymond Knopp committed
40 41 42
#ifndef COMMON_LIB_H
#define COMMON_LIB_H
#include <stdint.h>
43
#include <sys/types.h>
Raymond Knopp's avatar
 
Raymond 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


Raymond Knopp's avatar
 
Raymond 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*/
Raymond Knopp's avatar
 
Raymond Knopp committed
62
typedef struct openair0_device_t openair0_device;
63

Raymond Knopp's avatar
 
Raymond 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
Raymond Knopp's avatar
 
Raymond Knopp committed
70

Raymond Knopp's avatar
 
Raymond 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;
Raymond Knopp's avatar
 
Raymond Knopp committed
136

Rohit Gupta's avatar
Rohit Gupta committed
137
/*! \brief RF frontend parameters set by application */
Raymond Knopp's avatar
 
Raymond Knopp committed
138
typedef struct {
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;
149
  //! the sample rate for both transmit and receive.
Raymond Knopp's avatar
 
Raymond 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
  //! samples per packet on the fronthaul interface
156
  int samples_per_packet;
157
  //! number of RX channels (=RX antennas)
Raymond Knopp's avatar
 
Raymond Knopp committed
158
  int rx_num_channels;
159
  //! number of TX channels (=TX antennas)
Raymond Knopp's avatar
 
Raymond 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];
165 166
  //! \brief Center frequency in Hz for RX.
  //! index: [0..rx_num_channels[
Raymond Knopp's avatar
 
Raymond Knopp committed
167
  double rx_freq[4];
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
Raymond Knopp's avatar
 
Raymond 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) 
Raymond Knopp's avatar
 
Raymond Knopp committed
176
  rx_gain_t rxg_mode[4];
177
  //! \brief Gain for RX in dB.
178
  //! index: [0..rx_num_channels]
Raymond Knopp's avatar
 
Raymond 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];
183
  //! gain for TX in dB
Raymond Knopp's avatar
 
Raymond Knopp committed
184
  double tx_gain[4];
185
  //! RX bandwidth in Hz
Raymond Knopp's avatar
 
Raymond Knopp committed
186
  double rx_bw;
187
  //! TX bandwidth in Hz
Raymond Knopp's avatar
 
Raymond 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;
Raymond Knopp's avatar
 
Raymond 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 */
Raymond Knopp's avatar
 
Raymond Knopp committed
248
struct openair0_device_t {
249
  /*!brief Module ID of this device */
250
  int Mod_id;
251 252 253

  /*!brief Component Carrier ID of this device */
  int CC_id;
254
  
255
  /*!brief Type of this device */
256 257
  dev_type_t type;

258 259 260 261 262
  /*!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;
263

Aikaterini's avatar
Aikaterini committed
264
  /* !brief RF frontend parameters set by application */
265
  openair0_config_t *openair0_cfg;
266

267
  /*!brief Can be used by driver to hold internal structure*/
Raymond Knopp's avatar
 
Raymond Knopp committed
268 269 270 271
  void *priv;

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

272 273 274
  /*! \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
  */
Raymond Knopp's avatar
 
Raymond Knopp committed
275 276
  int (*trx_start_func)(openair0_device *device);

277 278 279 280 281
  /*! \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  
  */  
282
  int (*trx_request_func)(openair0_device *device, void *msg, ssize_t msg_len);
283

284 285 286 287 288
  /*! \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
289
  int (*trx_reply_func)(openair0_device *device, void *msg, ssize_t msg_len);
290

291 292 293 294 295 296 297 298
  /*! \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
  */   
299
  int (*trx_write_func)(openair0_device *device, openair0_timestamp timestamp, void **buff, int nsamps,int antenna_id, int flags);
Raymond Knopp's avatar
 
Raymond Knopp committed
300

301 302
  /*! \brief Receive samples from hardware.
   * Read \ref nsamps samples from each channel to buffers. buff[0] is the array for
Raymond Knopp's avatar
 
Raymond Knopp committed
303 304
   * the first channel. *ptimestamp is the time at which the first sample
   * was received.
305 306
   * \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
307
   * \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.
308
   * \param nsamps Number of samples. One sample is 2 byte I + 2 byte Q => 4 byte.
Rohit Gupta's avatar
Rohit Gupta committed
309
   * \param antenna_id Index of antenna for which to receive samples
310 311
   * \returns the number of sample read
   */
312 313 314 315 316 317 318 319 320 321 322 323 324
  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);
Raymond Knopp's avatar
 
Raymond Knopp committed
325

Rohit Gupta's avatar
Rohit Gupta committed
326 327 328
  /*! \brief Terminate operation of the transceiver -- free all associated resources 
   * \param device the hardware to use
   */
Raymond Knopp's avatar
 
Raymond Knopp committed
329
  void (*trx_end_func)(openair0_device *device);
330

Rohit Gupta's avatar
Rohit Gupta committed
331 332
  /*! \brief Stop operation of the transceiver 
   */
333
  int (*trx_stop_func)(openair0_device *device);
334 335 336 337

  /* Functions API related to UE*/

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

Raymond Knopp's avatar
 
Raymond Knopp committed
352 353
};

354
/* type of device init function, implemented in shared lib */
355 356 357
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);
Raymond Knopp's avatar
 
Raymond Knopp committed
358 359 360 361

#ifdef __cplusplus
extern "C"
{
362 363
#endif

364 365

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

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

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

383
/*@}*/
384

385
#ifdef __cplusplus
Raymond Knopp's avatar
 
Raymond Knopp committed
386 387 388
}
#endif

Raymond Knopp's avatar
 
Raymond Knopp committed
389
#endif // COMMON_LIB_H
390