common_lib.h 12.5 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/*
 * 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
 * the OAI Public License, Version 1.0  (the "License"); you may not use this file
 * 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
24
25
26
27
28
29
30
31
/*! \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
 */
32

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

38
39
40
41
42
/* 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"

43
44
45
/* 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
46

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

knopp's avatar
 
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*/
knopp's avatar
 
knopp committed
56
typedef struct openair0_device_t openair0_device;
57

knopp's avatar
   
knopp committed
58

59
60
61



62

63
//#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
64

knopp's avatar
   
knopp committed
65
66
67
68
typedef enum {
  max_gain=0,med_gain,byp_gain
} rx_gain_t;

laurent's avatar
laurent committed
69
70
71
#if OCP_FRAMEWORK
#include <enums.h>
#else
72
73
74
typedef enum {
  duplex_mode_TDD=1,duplex_mode_FDD=0
} duplex_mode_t;
laurent's avatar
laurent committed
75
#endif
76

77

78
/** @addtogroup _GENERIC_PHY_RF_INTERFACE_
79
80
 * @{
 */
81
82
/*!\brief RF device types
 */
laurent's avatar
laurent committed
83
84
85
#ifdef OCP_FRAMEWORK
#include <enums.h>
#else
86
87
88
89
90
91
92
93
94
95
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
  /*!\brief device is NONE*/
  NONE_DEV,
  MAX_RF_DEV_TYPE

} dev_type_t;
laurent's avatar
laurent committed
103
#endif
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

/*!\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
129
130

/*! \brief RF Gain clibration */ 
131
132
133
134
135
136
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
137

138
139
140
141
142
/*! \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
143
144
145
  external=1,
  //! This tells the underlying hardware to use the gpsdo reference
  gpsdo=2
146
147
} clock_source_t;

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

186
  //! mode for rxgain (ExpressMIMO2) 
knopp's avatar
   
knopp committed
187
  rx_gain_t rxg_mode[4];
gauthier's avatar
gauthier committed
188
  //! \brief Gain for RX in dB.
189
  //! index: [0..rx_num_channels]
knopp's avatar
   
knopp committed
190
  double rx_gain[4];
191
192
193
  //! \brief Gain offset (for calibration) in dB
  //! index: [0..rx_num_channels]
  double rx_gain_offset[4];
gauthier's avatar
gauthier committed
194
  //! gain for TX in dB
knopp's avatar
   
knopp committed
195
  double tx_gain[4];
gauthier's avatar
gauthier committed
196
  //! RX bandwidth in Hz
knopp's avatar
 
knopp committed
197
  double rx_bw;
gauthier's avatar
gauthier committed
198
  //! TX bandwidth in Hz
knopp's avatar
 
knopp committed
199
  double tx_bw;
200
201
  //! clock source 
  clock_source_t clock_source;
202
203
  //! Auto calibration flag
  int autocal[4];
204
205
206
207
208
209
210
211
212
213
214
215
  //! 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;
216
217
  //! Configuration file for LMS7002M
  char *configFilename;
knopp's avatar
 
knopp committed
218
219
} openair0_config_t;

Rohit Gupta's avatar
Rohit Gupta committed
220
/*! \brief RF mapping */ 
221
typedef struct {
Rohit Gupta's avatar
Rohit Gupta committed
222
  //! card id
223
  int card;
Rohit Gupta's avatar
Rohit Gupta committed
224
  //! rf chain id
225
226
227
228
  int chain;
} openair0_rf_map;


229
230
231
typedef struct {
  char *remote_addr;
  //! remote port number for Ethernet interface
232
  uint16_t remote_port;
233
234
235
  //! local IP/MAC addr for Ethernet interface (eNB/BBU, UE)
  char *my_addr;
  //! local port number for Ethernet interface (eNB/BBU, UE)
236
237
  uint16_t  my_port;
  //! local Ethernet interface (eNB/BBU, UE)
238
  char *local_if_name;
239
240
241
242
243
244
245
  //! 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)
246
  uint8_t transp_preference;
247
248
  //! compression enable (0: No comp/ 1: A-LAW)
  uint8_t if_compress;
249
250
  //! radio front end preference (EXMIMO,USRP, BALDERF,LMSSDR)
  uint8_t rf_preference;
251
} eth_params_t;
252
253


Sandeep Kumar's avatar
Sandeep Kumar committed
254
typedef struct {
255
256
  //! Tx buffer for if device, keep one per subframe now to allow multithreading
  void *tx[10];
257
258
  //! Tx buffer (PRACH) for if device
  void *tx_prach;
Sandeep Kumar's avatar
Sandeep Kumar committed
259
260
261
262
263
  //! Rx buffer for if device
  void *rx;
} if_buffer_t;


264
/*!\brief structure holds the parameters to configure USRP devices */
knopp's avatar
 
knopp committed
265
struct openair0_device_t {
266
  /*!brief Module ID of this device */
knopp's avatar
knopp committed
267
  int Mod_id;
268
269
270

  /*!brief Component Carrier ID of this device */
  int CC_id;
271
  
272
  /*!brief Type of this device */
273
274
  dev_type_t type;

275
276
277
278
279
  /*!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;
280

281
  /* !brief RF frontend parameters set by application */
282
  openair0_config_t *openair0_cfg;
283

284
  /*!brief Can be used by driver to hold internal structure*/
knopp's avatar
 
knopp committed
285
286
287
288
  void *priv;

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

289
290
291
  /*! \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
292
293
  int (*trx_start_func)(openair0_device *device);

294
295
296
297
298
  /*! \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  
  */  
299
  int (*trx_request_func)(openair0_device *device, void *msg, ssize_t msg_len);
300

301
302
303
304
305
  /*! \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
306
  int (*trx_reply_func)(openair0_device *device, void *msg, ssize_t msg_len);
307

308
309
310
311
312
313
314
315
  /*! \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
  */   
316
  int (*trx_write_func)(openair0_device *device, openair0_timestamp timestamp, void **buff, int nsamps,int antenna_id, int flags);
knopp's avatar
 
knopp committed
317

gauthier's avatar
gauthier committed
318
319
  /*! \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
320
321
   * the first channel. *ptimestamp is the time at which the first sample
   * was received.
gauthier's avatar
gauthier committed
322
323
   * \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
324
   * \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
325
   * \param nsamps Number of samples. One sample is 2 byte I + 2 byte Q => 4 byte.
Rohit Gupta's avatar
Rohit Gupta committed
326
   * \param antenna_id Index of antenna for which to receive samples
gauthier's avatar
gauthier committed
327
328
   * \returns the number of sample read
   */
329
330
331
332
333
334
335
336
337
338
339
340
341
  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
342

Rohit Gupta's avatar
Rohit Gupta committed
343
344
345
  /*! \brief Terminate operation of the transceiver -- free all associated resources 
   * \param device the hardware to use
   */
knopp's avatar
 
knopp committed
346
  void (*trx_end_func)(openair0_device *device);
347

Rohit Gupta's avatar
Rohit Gupta committed
348
349
  /*! \brief Stop operation of the transceiver 
   */
350
  int (*trx_stop_func)(openair0_device *device);
351
352
353
354

  /* Functions API related to UE*/

  /*! \brief Set RX feaquencies 
Rohit Gupta's avatar
Rohit Gupta committed
355
356
357
   * \param device the hardware to use
   * \param openair0_cfg RF frontend parameters set by application
   * \param exmimo_dump_config  dump EXMIMO configuration 
358
359
360
   * \returns 0 in success 
   */
  int (*trx_set_freq_func)(openair0_device* device, openair0_config_t *openair0_cfg,int exmimo_dump_config);
361
  
362
  /*! \brief Set gains
Rohit Gupta's avatar
Rohit Gupta committed
363
364
   * \param device the hardware to use
   * \param openair0_cfg RF frontend parameters set by application
365
366
367
368
   * \returns 0 in success 
   */
  int (*trx_set_gains_func)(openair0_device* device, openair0_config_t *openair0_cfg);

knopp's avatar
 
knopp committed
369
370
};

371
/* type of device init function, implemented in shared lib */
372
373
374
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
375
376
377
378

#ifdef __cplusplus
extern "C"
{
gauthier's avatar
gauthier committed
379
380
#endif

381
382

  /*! \brief Initialize openair RF target. It returns 0 if OK */
383
384
  int openair0_device_load(openair0_device *device, openair0_config_t *openair0_cfg);  
  /*! \brief Initialize transport protocol . It returns 0 if OK */
385
  int openair0_transport_load(openair0_device *device, openair0_config_t *openair0_cfg, eth_params_t * eth_params);
386

navid's avatar
navid committed
387
  
388
 /*! \brief Get current timestamp of USRP
Rohit Gupta's avatar
Rohit Gupta committed
389
390
  * \param device the hardware to use
  */
navid's avatar
navid committed
391
  openair0_timestamp get_usrp_time(openair0_device *device);
392

393
 /*! \brief Set RX frequencies 
Rohit Gupta's avatar
Rohit Gupta committed
394
395
  * \param device the hardware to use
  * \param openair0_cfg RF frontend parameters set by application
396
  * \returns 0 in success 
Rohit Gupta's avatar
Rohit Gupta committed
397
  */
navid's avatar
navid committed
398
  int openair0_set_rx_frequencies(openair0_device* device, openair0_config_t *openair0_cfg);
Rohit Gupta's avatar
Rohit Gupta committed
399

400
/*@}*/
401

gauthier's avatar
gauthier committed
402
#ifdef __cplusplus
knopp's avatar
 
knopp committed
403
404
405
}
#endif

knopp's avatar
   
knopp committed
406
#endif // COMMON_LIB_H
407