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

Raymond Knopp's avatar
 
Raymond Knopp committed
54
typedef int64_t openair0_timestamp;
55
typedef volatile int64_t openair0_vtimestamp;
56

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

Raymond Knopp's avatar
 
Raymond Knopp committed
61

62
#ifndef EXMIMO
63 64 65
#define MAX_CARDS 1
#endif

66
//#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
67

Raymond Knopp's avatar
 
Raymond Knopp committed
68 69 70 71
typedef enum {
  max_gain=0,med_gain,byp_gain
} rx_gain_t;

72 73 74 75 76
typedef enum {
  duplex_mode_TDD=1,duplex_mode_FDD=0
} duplex_mode_t;


77

78
/** @addtogroup _GENERIC_PHY_RF_INTERFACE_
79 80
 * @{
 */
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 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
/*!\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,
  /*!\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
123 124

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

Rohit Gupta's avatar
Rohit Gupta committed
132
/*! \brief RF frontend parameters set by application */
Raymond Knopp's avatar
 
Raymond Knopp committed
133
typedef struct {
134
  //! Module ID for this configuration
135
  int Mod_id;
Rohit Gupta's avatar
Rohit Gupta committed
136
  //! device log level
137
  int log_level;
138 139
  //! duplexing mode
  duplex_mode_t duplex_mode;
140 141 142 143
  //! number of downlink resource blocks
  int num_rb_dl;
  //! number of samples per frame 
  unsigned int  samples_per_frame;
144
  //! the sample rate for both transmit and receive.
Raymond Knopp's avatar
 
Raymond Knopp committed
145
  double sample_rate;
146
  //! number of samples per RX/TX packet (USRP + Ethernet)
Aikaterini's avatar
Aikaterini committed
147
  unsigned int samples_per_packet; 
148 149 150 151
  //! delay in sending samples (write)  due to hardware access, softmodem processing and fronthaul delay if exist
  int tx_scheduling_advance;
  //! offset in samples between TX and RX paths
  int tx_sample_advance;
152 153
  //! configurable tx thread lauch delay 
  int txlaunch_wait;               /* 1 or 0 */
Aikaterini's avatar
Aikaterini committed
154
  //! configurable tx thread lauch delay 
155
  int txlaunch_wait_slotcount;
156
  //! number of RX channels (=RX antennas)
Raymond Knopp's avatar
 
Raymond Knopp committed
157
  int rx_num_channels;
158
  //! number of TX channels (=TX antennas)
Raymond Knopp's avatar
 
Raymond Knopp committed
159
  int tx_num_channels;
160 161
  //! \brief Center frequency in Hz for RX.
  //! index: [0..rx_num_channels[
Raymond Knopp's avatar
 
Raymond Knopp committed
162
  double rx_freq[4];
163 164
  //! \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
165
  double tx_freq[4];
166 167 168 169

  //! \brief Pointer to Calibration table for RX gains
  rx_gain_calib_table_t *rx_gain_calib_table;

170
  //! mode for rxgain (ExpressMIMO2) 
Raymond Knopp's avatar
 
Raymond Knopp committed
171
  rx_gain_t rxg_mode[4];
172
  //! \brief Gain for RX in dB.
173
  //! index: [0..rx_num_channels]
Raymond Knopp's avatar
 
Raymond Knopp committed
174
  double rx_gain[4];
175 176 177
  //! \brief Gain offset (for calibration) in dB
  //! index: [0..rx_num_channels]
  double rx_gain_offset[4];
178
  //! gain for TX in dB
Raymond Knopp's avatar
 
Raymond Knopp committed
179
  double tx_gain[4];
180
  //! RX bandwidth in Hz
Raymond Knopp's avatar
 
Raymond Knopp committed
181
  double rx_bw;
182
  //! TX bandwidth in Hz
Raymond Knopp's avatar
 
Raymond Knopp committed
183
  double tx_bw;
184 185
  //! Auto calibration flag
  int autocal[4];
186 187 188 189 190 191 192 193 194 195 196 197
  //! 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;
198

Raymond Knopp's avatar
 
Raymond Knopp committed
199 200
} openair0_config_t;

Rohit Gupta's avatar
Rohit Gupta committed
201
/*! \brief RF mapping */ 
202
typedef struct {
Rohit Gupta's avatar
Rohit Gupta committed
203
  //! card id
204
  int card;
Rohit Gupta's avatar
Rohit Gupta committed
205
  //! rf chain id
206 207 208
  int chain;
} openair0_rf_map;

209 210 211 212 213 214 215 216 217 218 219 220 221
typedef struct {
  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;
  //! local port number for Ethernet interface (eNB/BBU, UE)
  char *local_if_name;
 //! local port number for Ethernet interface (eNB/BBU, UE)
  uint8_t transp_preference;
} eth_params_t;
222 223


224
/*!\brief structure holds the parameters to configure USRP devices */
Raymond Knopp's avatar
 
Raymond Knopp committed
225
struct openair0_device_t {
226
  /*!brief Module ID of this device */
227
  int Mod_id;
228
  
229
  /*!brief Type of this device */
230 231
  dev_type_t type;

232 233 234 235 236
  /*!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;
237

Aikaterini's avatar
Aikaterini committed
238
  /* !brief RF frontend parameters set by application */
239
  openair0_config_t *openair0_cfg;
240

241
  /*!brief Can be used by driver to hold internal structure*/
Raymond Knopp's avatar
 
Raymond Knopp committed
242 243 244 245
  void *priv;

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

246 247 248
  /*! \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
249 250
  int (*trx_start_func)(openair0_device *device);

251 252 253 254 255
  /*! \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  
  */  
256
  int (*trx_request_func)(openair0_device *device, void *msg, ssize_t msg_len);
257

258 259 260 261 262
  /*! \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
263
  int (*trx_reply_func)(openair0_device *device, void *msg, ssize_t msg_len);
264

265 266 267 268 269 270 271 272
  /*! \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
  */   
273
  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
274

275 276
  /*! \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
277 278
   * the first channel. *ptimestamp is the time at which the first sample
   * was received.
279 280
   * \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
281
   * \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.
282
   * \param nsamps Number of samples. One sample is 2 byte I + 2 byte Q => 4 byte.
Rohit Gupta's avatar
Rohit Gupta committed
283
   * \param antenna_id Index of antenna for which to receive samples
284 285
   * \returns the number of sample read
   */
286 287 288 289 290 291 292 293 294 295 296 297 298
  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
299

Rohit Gupta's avatar
Rohit Gupta committed
300 301 302
  /*! \brief Terminate operation of the transceiver -- free all associated resources 
   * \param device the hardware to use
   */
Raymond Knopp's avatar
 
Raymond Knopp committed
303
  void (*trx_end_func)(openair0_device *device);
304

Rohit Gupta's avatar
Rohit Gupta committed
305 306 307
  /*! \brief Stop operation of the transceiver 
   * \param card RF Card to use
   */
308 309 310 311 312
  int (*trx_stop_func)(int card);

  /* Functions API related to UE*/

  /*! \brief Set RX feaquencies 
Rohit Gupta's avatar
Rohit Gupta committed
313 314 315
   * \param device the hardware to use
   * \param openair0_cfg RF frontend parameters set by application
   * \param exmimo_dump_config  dump EXMIMO configuration 
316 317 318
   * \returns 0 in success 
   */
  int (*trx_set_freq_func)(openair0_device* device, openair0_config_t *openair0_cfg,int exmimo_dump_config);
319
  
320
  /*! \brief Set gains
Rohit Gupta's avatar
Rohit Gupta committed
321 322
   * \param device the hardware to use
   * \param openair0_cfg RF frontend parameters set by application
323 324 325 326
   * \returns 0 in success 
   */
  int (*trx_set_gains_func)(openair0_device* device, openair0_config_t *openair0_cfg);

Raymond Knopp's avatar
 
Raymond Knopp committed
327 328
};

329
/* type of device init function, implemented in shared lib */
330 331 332
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
333 334 335 336

#ifdef __cplusplus
extern "C"
{
337 338
#endif

339 340

  /*! \brief Initialize openair RF target. It returns 0 if OK */
341 342
  int openair0_device_load(openair0_device *device, openair0_config_t *openair0_cfg);  
  /*! \brief Initialize transport protocol . It returns 0 if OK */
343
  int openair0_transport_load(openair0_device *device, openair0_config_t *openair0_cfg, eth_params_t * eth_params);
344

345
  
346
 /*! \brief Get current timestamp of USRP
Rohit Gupta's avatar
Rohit Gupta committed
347 348
  * \param device the hardware to use
  */
349
  openair0_timestamp get_usrp_time(openair0_device *device);
Rohit Gupta's avatar
Rohit Gupta committed
350
  
351
 /*! \brief Set RX frequencies 
Rohit Gupta's avatar
Rohit Gupta committed
352 353
  * \param device the hardware to use
  * \param openair0_cfg RF frontend parameters set by application
354
  * \returns 0 in success 
Rohit Gupta's avatar
Rohit Gupta committed
355
  */
356
  int openair0_set_rx_frequencies(openair0_device* device, openair0_config_t *openair0_cfg);
Rohit Gupta's avatar
Rohit Gupta committed
357

358
/*@}*/
359

360
#ifdef __cplusplus
Raymond Knopp's avatar
 
Raymond Knopp committed
361 362 363
}
#endif

Raymond Knopp's avatar
 
Raymond Knopp committed
364
#endif // COMMON_LIB_H
365