common_lib.h 14.9 KB
Newer Older
1 2 3 4 5
/*
 * Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The OpenAirInterface Software Alliance licenses this file to You under
6
 * the OAI Public License, Version 1.1  (the "License"); you may not use this file
7 8 9 10 11 12 13 14 15 16 17 18 19 20
 * except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.openairinterface.org/?page_id=698
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *-------------------------------------------------------------------------------
 * For more information about the OpenAirInterface (OAI) Software Alliance:
 *      contact@openairinterface.org
 */
21

22 23
/*! \file common_lib.h
 * \brief common APIs for different RF frontend device
24 25 26 27 28 29 30 31
 * \author HongliangXU, Navid Nikaein
 * \date 2015
 * \version 0.2
 * \company Eurecom
 * \maintainer:  navid.nikaein@eurecom.fr
 * \note
 * \warning
 */
32

Raymond Knopp's avatar
 
Raymond Knopp committed
33 34 35
#ifndef COMMON_LIB_H
#define COMMON_LIB_H
#include <stdint.h>
36
#include <sys/types.h>
Raymond Knopp's avatar
 
Raymond Knopp committed
37

38
/* name of shared library implementing the radio front end */
39
#define OAI_RF_LIBNAME        "oai_device"
40
/* name of shared library implementing the transport */
41
#define OAI_TP_LIBNAME        "oai_transpro"
42

43
/* flags for BBU to determine whether the attached radio head is local or remote */
44 45
#define RAU_LOCAL_RADIO_HEAD  0
#define RAU_REMOTE_RADIO_HEAD 1
46

47
#ifndef MAX_CARDS
48
  #define MAX_CARDS 8
49
#endif
50

Raymond Knopp's avatar
 
Raymond Knopp committed
51
typedef int64_t openair0_timestamp;
52
typedef volatile int64_t openair0_vtimestamp;
53

54

Rohit Gupta's avatar
Rohit Gupta committed
55
/*!\brief structrue holds the parameters to configure USRP devices*/
Raymond Knopp's avatar
 
Raymond Knopp committed
56
typedef struct openair0_device_t openair0_device;
57

58
//#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
59

Raymond Knopp's avatar
 
Raymond Knopp committed
60 61 62 63
typedef enum {
  max_gain=0,med_gain,byp_gain
} rx_gain_t;

laurent's avatar
laurent committed
64 65 66
#if OCP_FRAMEWORK
#include <enums.h>
#else
67 68 69
typedef enum {
  duplex_mode_TDD=1,duplex_mode_FDD=0
} duplex_mode_t;
laurent's avatar
laurent committed
70
#endif
71

72

73
/** @addtogroup _GENERIC_PHY_RF_INTERFACE_
74 75
 * @{
 */
76 77 78 79 80 81 82 83 84 85 86 87
/*!\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,
88 89
  /*!\brief device is LMSSDR (SoDeRa)*/
  LMSSDR_DEV,
90 91
  /*!\brief device is NONE*/
  NONE_DEV,
root's avatar
root committed
92 93 94 95
  /*!\brief device is ADRV9371_ZC706 */
  ADRV9371_ZC706_DEV,
  /*!\brief device is UEDv2 */
  UEDv2_DEV,
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
  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,
116
  /*!\brief device functions within a RAU */
117
  RAU_HOST,
118
  /*!\brief device functions within a RRU */
119
  RRU_HOST,
120 121
  MAX_HOST_TYPE

122
} host_type_t;
123

Rohit Gupta's avatar
Rohit Gupta committed
124

125
/*! \brief RF Gain clibration */
126 127 128 129 130 131
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
132

133 134 135 136 137
/*! \brief Clock source types */
typedef enum {
  //! This tells the underlying hardware to use the internal reference
  internal=0,
  //! This tells the underlying hardware to use the external reference
138 139 140
  external=1,
  //! This tells the underlying hardware to use the gpsdo reference
  gpsdo=2
141 142
} clock_source_t;

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

181
  //! mode for rxgain (ExpressMIMO2)
Raymond Knopp's avatar
 
Raymond Knopp committed
182
  rx_gain_t rxg_mode[4];
183
  //! \brief Gain for RX in dB.
184
  //! index: [0..rx_num_channels]
Raymond Knopp's avatar
 
Raymond Knopp committed
185
  double rx_gain[4];
186 187 188
  //! \brief Gain offset (for calibration) in dB
  //! index: [0..rx_num_channels]
  double rx_gain_offset[4];
189
  //! gain for TX in dB
Raymond Knopp's avatar
 
Raymond Knopp committed
190
  double tx_gain[4];
191
  //! RX bandwidth in Hz
Raymond Knopp's avatar
 
Raymond Knopp committed
192
  double rx_bw;
193
  //! TX bandwidth in Hz
Raymond Knopp's avatar
 
Raymond Knopp committed
194
  double tx_bw;
195
  //! clock source
196
  clock_source_t clock_source;
197
  //! Manual SDR IP address
198
  //#if defined(EXMIMO) || defined(OAI_USRP) || defined(OAI_BLADERF) || defined(OAI_LMSSDR)
199
  char *sdr_addrs;
200 201
  //! Auto calibration flag
  int autocal[4];
202
  //! rf devices work with x bits iqs when oai have its own iq format
203
  //! the two following parameters are used to convert iqs
204 205
  int iq_txshift;
  int iq_rxrescale;
206 207
  //! Configuration file for LMS7002M
  char *configFilename;
208 209 210 211 212 213 214 215
  //! 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;
216 217 218 219 220 221 222 223
#if defined(USRP_REC_PLAY)
  unsigned short sf_mode;           // 1=record, 2=replay
  char           sf_filename[1024]; // subframes file path
  unsigned int   sf_max;            // max number of recorded subframes
  unsigned int   sf_loops;          // number of loops in replay mode
  unsigned int   sf_read_delay;     // read delay in replay mode
  unsigned int   sf_write_delay;    // write delay in replay mode
  unsigned int   eth_mtu;           // ethernet MTU
224
#endif
root's avatar
root committed
225 226 227 228 229 230 231

  //! number of samples per tti
  unsigned int  samples_per_tti;
  //! the sample rate for receive.
  double rx_sample_rate;
  //! the sample rate for transmit.
  double tx_sample_rate;
232 233
  //! check for threequarter sampling rate
  int8_t threequarter_fs;
root's avatar
root committed
234

Raymond Knopp's avatar
 
Raymond Knopp committed
235 236
} openair0_config_t;

237
/*! \brief RF mapping */
238
typedef struct {
Rohit Gupta's avatar
Rohit Gupta committed
239
  //! card id
240
  int card;
Rohit Gupta's avatar
Rohit Gupta committed
241
  //! rf chain id
242 243 244 245
  int chain;
} openair0_rf_map;


246 247
typedef struct {
  char *remote_addr;
248 249 250 251
  //! remote port number for Ethernet interface (control)
  uint16_t remote_portc;
  //! remote port number for Ethernet interface (user)
  uint16_t remote_portd;
252
  //! local IP/MAC addr for Ethernet interface (eNB/RAU, UE)
253
  char *my_addr;
254 255 256 257
  //! local port number (control) for Ethernet interface (eNB/RAU, UE)
  uint16_t  my_portc;
  //! local port number (user) for Ethernet interface (eNB/RAU, UE)
  uint16_t  my_portd;
258
  //! local Ethernet interface (eNB/RAU, UE)
259
  char *local_if_name;
260
  //! transport type preference  (RAW/UDP)
261
  uint8_t transp_preference;
262 263
  //! compression enable (0: No comp/ 1: A-LAW)
  uint8_t if_compress;
264
} eth_params_t;
265 266


267
typedef struct {
268 269
  //! Tx buffer for if device, keep one per subframe now to allow multithreading
  void *tx[10];
270 271
  //! Tx buffer (PRACH) for if device
  void *tx_prach;
272 273 274 275 276
  //! Rx buffer for if device
  void *rx;
} if_buffer_t;


277
/*!\brief structure holds the parameters to configure USRP devices */
Raymond Knopp's avatar
 
Raymond Knopp committed
278
struct openair0_device_t {
279
  /*!brief Module ID of this device */
280
  int Mod_id;
281 282 283

  /*!brief Component Carrier ID of this device */
  int CC_id;
284

285
  /*!brief Type of this device */
286 287
  dev_type_t type;

288 289 290
  /*!brief Transport protocol type that the device suppports (in case I/Q samples need to be transported) */
  transport_type_t transp_type;

291
  /*!brief Type of the device's host (RAU/RRU) */
292
  host_type_t host_type;
293

Aikaterini's avatar
Aikaterini committed
294
  /* !brief RF frontend parameters set by application */
295
  openair0_config_t *openair0_cfg;
296

297 298 299
  /* !brief ETH params set by application */
  eth_params_t *eth_params;

300
  /*!brief Can be used by driver to hold internal structure*/
Raymond Knopp's avatar
 
Raymond Knopp committed
301 302 303 304
  void *priv;

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

305 306 307
  /*! \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
308 309
  int (*trx_start_func)(openair0_device *device);

310
  /*! \brief Called to send a request message between RAU-RRU on control port
311
      @param device pointer to the device structure specific to the RF hardware target
312
      @param msg pointer to the message structure passed between RAU-RRU
313 314
      @param msg_len length of the message
  */
315
  int (*trx_ctlsend_func)(openair0_device *device, void *msg, ssize_t msg_len);
316

317
  /*! \brief Called to receive a reply  message between RAU-RRU on control port
318
      @param device pointer to the device structure specific to the RF hardware target
319
      @param msg pointer to the message structure passed between RAU-RRU
320 321
      @param msg_len length of the message
  */
322
  int (*trx_ctlrecv_func)(openair0_device *device, void *msg, ssize_t msg_len);
323

324 325
  /*! \brief Called to send samples to the RF target
      @param device pointer to the device structure specific to the RF hardware target
326
      @param timestamp The timestamp at whicch the first sample MUST be sent
327 328 329 330
      @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
331
  */
332
  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
333

334 335
  /*! \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
336 337
   * the first channel. *ptimestamp is the time at which the first sample
   * was received.
338 339
   * \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
340
   * \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.
341
   * \param nsamps Number of samples. One sample is 2 byte I + 2 byte Q => 4 byte.
Rohit Gupta's avatar
Rohit Gupta committed
342
   * \param antenna_id Index of antenna for which to receive samples
343 344
   * \returns the number of sample read
   */
345 346
  int (*trx_read_func)(openair0_device *device, openair0_timestamp *ptimestamp, void **buff, int nsamps,int antenna_id);

347
  /*! \brief print the device statistics
348 349 350 351 352
   * \param device the hardware to use
   * \returns  0 on success
   */
  int (*trx_get_stats_func)(openair0_device *device);

353
  /*! \brief Reset device statistics
354
   * \param device the hardware to use
355
   * \returns 0 in success
356 357
   */
  int (*trx_reset_stats_func)(openair0_device *device);
Raymond Knopp's avatar
 
Raymond Knopp committed
358

359
  /*! \brief Terminate operation of the transceiver -- free all associated resources
Rohit Gupta's avatar
Rohit Gupta committed
360 361
   * \param device the hardware to use
   */
Raymond Knopp's avatar
 
Raymond Knopp committed
362
  void (*trx_end_func)(openair0_device *device);
363

364
  /*! \brief Stop operation of the transceiver
Rohit Gupta's avatar
Rohit Gupta committed
365
   */
366
  int (*trx_stop_func)(openair0_device *device);
367 368 369

  /* Functions API related to UE*/

370
  /*! \brief Set RX feaquencies
Rohit Gupta's avatar
Rohit Gupta committed
371 372
   * \param device the hardware to use
   * \param openair0_cfg RF frontend parameters set by application
373 374
   * \param exmimo_dump_config  dump EXMIMO configuration
   * \returns 0 in success
375
   */
376 377
  int (*trx_set_freq_func)(openair0_device *device, openair0_config_t *openair0_cfg,int exmimo_dump_config);

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

385 386 387 388
  /*! \brief RRU Configuration callback
   * \param idx RU index
   * \param arg pointer to capabilities or configuration
   */
389
  void (*configure_rru)(int idx, void *arg);
Raymond Knopp's avatar
 
Raymond Knopp committed
390 391
};

392
/* type of device init function, implemented in shared lib */
393 394
typedef int(*oai_device_initfunc_t)(openair0_device *device, openair0_config_t *openair0_cfg);
/* type of transport init function, implemented in shared lib */
395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420
typedef int(*oai_transport_initfunc_t)(openair0_device *device, openair0_config_t *openair0_cfg, eth_params_t *eth_params);
#define UE_MAGICDL_FDD 0xA5A5A5A5A5A5A5A5  // UE DL FDD record
#define UE_MAGICUL_FDD 0x5A5A5A5A5A5A5A5A  // UE UL FDD record
#define UE_MAGICDL_TDD 0xA6A6A6A6A6A6A6A6  // UE DL TDD record
#define UE_MAGICUL_TDD 0x6A6A6A6A6A6A6A6A  // UE UL TDD record

#define ENB_MAGICDL_FDD 0xB5B5B5B5B5B5B5B5  // eNB DL FDD record
#define ENB_MAGICUL_FDD 0x5B5B5B5B5B5B5B5B  // eNB UL FDD record
#define ENB_MAGICDL_TDD 0xB6B6B6B6B6B6B6B6  // eNB DL TDD record
#define ENB_MAGICUL_TDD 0x6B6B6B6B6B6B6B6B  // eNB UL TDD record

#define OPTION_LZ4  0x00000001          // LZ4 compression (option_value is set to compressed size)

#define sample_t uint32_t // 2*16 bits complex number

typedef struct {
  uint64_t magic;          // Magic value (see defines above)
  uint32_t size;           // Number of samples per antenna to follow this header
  uint32_t nbAnt;          // Total number of antennas following this header
  // Samples per antenna follow this header,
  // i.e. nbAnt = 2 => this header+samples_antenna_0+samples_antenna_1
  // data following this header in bytes is nbAnt*size*sizeof(sample_t)
  uint64_t timestamp;      // Timestamp value of first sample
  uint32_t option_value;   // Option value
  uint32_t option_flag;    // Option flag
} samplesBlockHeader_t;
Raymond Knopp's avatar
 
Raymond Knopp committed
421 422 423 424

#ifdef __cplusplus
extern "C"
{
425 426
#endif

427

428 429 430 431
/*! \brief Initialize openair RF target. It returns 0 if OK */
int openair0_device_load(openair0_device *device, openair0_config_t *openair0_cfg);
/*! \brief Initialize transport protocol . It returns 0 if OK */
int openair0_transport_load(openair0_device *device, openair0_config_t *openair0_cfg, eth_params_t *eth_params);
432

433

434 435 436 437 438 439 440 441 442 443 444
/*! \brief Get current timestamp of USRP
 * \param device the hardware to use
 */
openair0_timestamp get_usrp_time(openair0_device *device);

/*! \brief Set RX frequencies
 * \param device the hardware to use
 * \param openair0_cfg RF frontend parameters set by application
 * \returns 0 in success
 */
int openair0_set_rx_frequencies(openair0_device *device, openair0_config_t *openair0_cfg);
laurent's avatar
laurent committed
445
#define gettid() syscall(__NR_gettid)
446
/*@}*/
447

448
  void uhd_set_thread_prio(void);
449 450 451
  typedef void(*set_prio_func_t)(void);
  set_prio_func_t uhd_set_thread_priority_fun;

452
#ifdef __cplusplus
Raymond Knopp's avatar
 
Raymond Knopp committed
453 454 455
}
#endif

Raymond Knopp's avatar
 
Raymond Knopp committed
456
#endif // COMMON_LIB_H
457