1 /** 2 * @file lime/LimeSuite.h 3 * 4 * @brief LMS API library 5 * 6 * Copyright (C) 2016 Lime Microsystems 7 * 8 * Licensed under the Apache License, Version 2.0 (the "License"); 9 * you may not use this file except in compliance with the License. 10 * You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 21 #ifndef LMS7_API_H 22 #define LMS7_API_H 23 24 #include <stdint.h> 25 #include <stdlib.h> 26 #include "LMS7002M_parameters.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #else 31 /* stdbool.h is not applicable for C++ programs, as the language inherently 32 * provides the bool type. 33 * 34 * Users of Visual Studio 2012 and earlier will need to supply a stdbool.h 35 * implementation, as it is not included with the toolchain. Visual Studio 2013 36 * onward supplies this header. 37 */ 38 #include <stdbool.h> 39 #endif 40 41 #if defined _WIN32 || defined __CYGWIN__ 42 # define CALL_CONV __cdecl 43 # ifdef __GNUC__ 44 # define API_EXPORT __attribute__ ((dllexport)) 45 # else 46 # define API_EXPORT __declspec(dllexport) 47 # endif 48 #elif defined _DOXYGEN_ONLY_ 49 /** Marks an API routine to be made visible to the dynamic loader. 50 * This is OS and/or compiler-specific. */ 51 # define API_EXPORT 52 /** Specifies calling convention, if necessary. 53 * This is OS and/or compiler-specific. */ 54 # define CALL_CONV 55 #else 56 # define API_EXPORT __attribute__ ((visibility ("default"))) 57 # define CALL_CONV 58 #endif 59 60 ///Floating point data type 61 typedef double float_type; 62 63 ///convenience constant for good return code 64 static const int LMS_SUCCESS = 0; 65 66 /** 67 * @defgroup FN_INIT Initialization/deinitialization 68 * 69 * The functions in this section provide the ability to query available devices, 70 * initialize them, and deinitialize them. 71 * @{ 72 */ 73 74 ///LMS Device handle 75 typedef void lms_device_t; 76 77 ///Convenience type for fixed length LMS Device information string 78 typedef char lms_info_str_t[256]; 79 80 /** 81 * Obtain a list of LMS devices attached to the system 82 * 83 * @param[out] dev_list List of available devices 84 * 85 * @return number of devices in the list on success, (-1) on failure 86 */ 87 API_EXPORT int CALL_CONV LMS_GetDeviceList(lms_info_str_t *dev_list); 88 89 /** 90 * Opens device specified by the provided ::lms_info_str_t string 91 * This function should be used to open a device based upon the results of 92 * LMS_GetDeviceList() 93 * 94 * @pre device should be initialized to NULL 95 * 96 * @param[out] device Updated with device handle on success 97 * @param[in] info Device information string. If NULL, the first 98 * available device will be opened. 99 * @param[in] args additional arguments. Can be NULL. 100 * 101 * @return 0 on success, (-1) on failure 102 */ 103 API_EXPORT int CALL_CONV LMS_Open(lms_device_t **device, const lms_info_str_t info, 104 void* args); 105 106 /** 107 * Close device 108 * 109 * @post device is deallocated and may no longer be used. 110 * 111 * @param device Device handle previously obtained by LMS_Open(). 112 * 113 * @return 0 on success, (-1) on failure 114 */ 115 API_EXPORT int CALL_CONV LMS_Close(lms_device_t *device); 116 117 /** @} (End FN_INIT) */ 118 119 /** 120 * @defgroup FN_HIGH_LVL High-level control functions 121 * 122 * The functions in this section provide the ability to easily configure the 123 * device for operation. They modify multiple internal device settings. 124 * 125 * @{ 126 */ 127 128 static const bool LMS_CH_TX = true; ///<Convenience constants for TX selection 129 static const bool LMS_CH_RX = false; ///<Convenience constants for RX selection 130 131 /** Convenience type for fixed length name string*/ 132 typedef char lms_name_t[16]; 133 134 /**Structure used to represent the allowed value range of various parameters*/ 135 typedef struct 136 { 137 float_type min; ///<Minimum allowed value 138 float_type max; ///<Maximum allowed value 139 float_type step; ///<Minimum value step 140 }lms_range_t; 141 142 /**Enumeration of LMS7 TEST signal types*/ 143 typedef enum 144 { 145 LMS_TESTSIG_NONE=0, ///<Disable test signals. Return to normal operation 146 LMS_TESTSIG_NCODIV8, ///<Test signal from NCO half scale 147 LMS_TESTSIG_NCODIV4, ///<Test signal from NCO half scale 148 LMS_TESTSIG_NCODIV8F, ///<Test signal from NCO full scale 149 LMS_TESTSIG_NCODIV4F, ///<Test signal from NCO full scale 150 LMS_TESTSIG_DC ///<DC test signal 151 }lms_testsig_t; 152 153 /** 154 * Configure LMS chip with settings that make it ready for operation. 155 * 156 * @note This configuration differs from default LMS chip configuration which is 157 * described in chip datasheet. In order to load default chip configuration use 158 * LMS_Reset(). 159 * 160 * @param[in] device Device handle previously obtained by LMS_Open(). 161 * 162 * @return 0 on success, (-1) on failure 163 */ 164 API_EXPORT int CALL_CONV LMS_Init(lms_device_t *device); 165 166 /** 167 * Obtain number of RX or TX channels. Use this to determine the maximum 168 * channel index (specifying channel index is required by most API functions). 169 * The maximum channel index is N-1, where N is number returned by this function 170 * 171 * @param device Device handle previously obtained by LMS_Open(). 172 * @param dir_tx Select RX or TX 173 * 174 * @return Number of channels on success, (-1) on failure 175 */ 176 API_EXPORT int CALL_CONV LMS_GetNumChannels(lms_device_t *device, bool dir_tx); 177 178 /** 179 * Enable or disable specified RX or TX channel. Some API functions will fail 180 * when performed on disabled channel. 181 * 182 * @param[in] device Device handle previously obtained by LMS_Open(). 183 * @param dir_tx Select RX or TX 184 * @param chan Channel index 185 * @param enabled true(1) to enable, false(0) to disable. 186 * 187 * @return 0 on success, (-1) on failure 188 */ 189 API_EXPORT int CALL_CONV LMS_EnableChannel(lms_device_t *device, bool dir_tx, 190 size_t chan, bool enabled); 191 192 /** 193 * Set sampling rate for all RX/TX channels. Sample rate is in complex samples 194 * (1 sample = I + Q). The function sets sampling rate that is used for data 195 * exchange with the host. It also allows to specify higher sampling rate to be 196 * used in RF by setting oversampling ratio. Valid oversampling values are 1, 2, 197 * 4, 8, 16, 32 or 0 (use device default oversampling value). 198 * 199 * @param[in] device Device handle previously obtained by LMS_Open(). 200 * @param rate sampling rate in Hz to set 201 * @param oversample RF oversampling ratio. 202 * 203 * @return 0 on success, (-1) on failure 204 */ 205 API_EXPORT int CALL_CONV LMS_SetSampleRate(lms_device_t *device, float_type rate, 206 size_t oversample); 207 208 /** 209 * Get the sampling rate of the specified RX or TX channel. 210 * The function obtains the sample rate used in data interface with the host and 211 * the RF sample rate used by DAC/ADC. 212 * 213 * @param[in] device Device handle previously obtained by LMS_Open(). 214 * @param dir_tx Select RX or TX 215 * @param chan Channel index 216 * @param[out] host_Hz sampling rate used for data exchange with the host 217 * @param[out] rf_Hz RF sampling rate in Hz 218 * 219 * @return 0 on success, (-1) on failure 220 */ 221 API_EXPORT int CALL_CONV LMS_GetSampleRate(lms_device_t *device, bool dir_tx, 222 size_t chan, float_type *host_Hz, float_type *rf_Hz); 223 /** 224 * Get the range of supported sampling rates. 225 * 226 * @param device Device handle previously obtained by LMS_Open(). 227 * @param dir_tx Select RX or TX 228 * @param[out] range Allowed sample rate range in Hz. 229 * 230 * @return 0 on success, (-1) on failure 231 */ 232 API_EXPORT int CALL_CONV LMS_GetSampleRateRange(lms_device_t *device, bool dir_tx, 233 lms_range_t *range); 234 235 /** 236 * Set RF center frequency in Hz. 237 * 238 * @note channels A and B in LMS7 chip share the same clock so ability to set 239 * different frequencies for channels A and B is very limited. This function 240 * will attempt to achieve different requested frequencies using NCO when 241 * possible, however often changing frequency for one (A or B) channel will 242 * result in frequency being changed for both (A and B) channels. 243 * 244 * @param device Device handle previously obtained by LMS_Open(). 245 * @param dir_tx Select RX or TX 246 * @param chan Channel index 247 * @param frequency Desired RF center frequency in Hz 248 * 249 * @return 0 on success, (-1) on failure 250 */ 251 API_EXPORT int CALL_CONV LMS_SetLOFrequency(lms_device_t *device, bool dir_tx, 252 size_t chan, float_type frequency); 253 254 /** 255 * Obtain the current RF center frequency in Hz. 256 * 257 * @param device Device handle previously obtained by LMS_Open(). 258 * @param dir_tx Select RX or TX 259 * @param chan Channel index 260 * @param[out] frequency Current RF center frequency in Hz 261 * 262 * @return 0 on success, (-1) on failure 263 */ 264 API_EXPORT int CALL_CONV LMS_GetLOFrequency(lms_device_t *device, bool dir_tx, 265 size_t chan, float_type *frequency); 266 267 /** 268 * Obtain the supported RF center frequency range in Hz. 269 * 270 * @param device Device handle previously obtained by LMS_Open(). 271 * @param dir_tx Select RX or TX 272 * @param[out] range Supported RF center frequency in Hz 273 * 274 * @return 0 on success, (-1) on failure 275 */ 276 API_EXPORT int CALL_CONV LMS_GetLOFrequencyRange(lms_device_t *device, bool dir_tx, 277 lms_range_t *range); 278 279 ///Enumeration of RF ports 280 enum 281 { 282 LMS_PATH_NONE = 0, ///<No active path (RX or TX) 283 LMS_PATH_LNAH = 1, ///<RX LNA_H port 284 LMS_PATH_LNAL = 2, ///<RX LNA_L port 285 LMS_PATH_LNAW = 3, ///<RX LNA_W port 286 LMS_PATH_TX1 = 1, ///<TX port 1 287 LMS_PATH_TX2 = 2, ///<TX port 2 288 LMS_PATH_AUTO = 255, ///<Automatically select port (if supported) 289 }; 290 291 /** 292 * Obtain antenna list with names. First item in the list is the name of antenna 293 * index 0. 294 * 295 * @param dev Device handle previously obtained by LMS_Open(). 296 * @param dir_tx Select RX or TX 297 * @param chan channel index 298 * @param[out] list List of antenna names (can be NULL) 299 * 300 * @return number of available antennae, (-1) on failure 301 */ 302 API_EXPORT int CALL_CONV LMS_GetAntennaList(lms_device_t *dev, bool dir_tx, 303 size_t chan, lms_name_t *list); 304 305 /** 306 * Select the antenna for the specified RX or TX channel. 307 * 308 * @param dev Device handle previously obtained by LMS_Open(). 309 * @param dir_tx Select RX or TX 310 * @param chan channel index 311 * @param index Index of antenna to select 312 * 313 * @return 0 on success, (-1) on failure 314 */ 315 API_EXPORT int CALL_CONV LMS_SetAntenna(lms_device_t *dev, bool dir_tx, 316 size_t chan, size_t index); 317 318 /** 319 * Obtain currently selected antenna of the the specified RX or TX channel. 320 * 321 * @param dev Device handle previously obtained by LMS_Open(). 322 * @param dir_tx Select RX or TX 323 * @param chan channel index 324 * 325 * @return Index of selected antenna on success, (-1) on failure 326 */ 327 API_EXPORT int CALL_CONV LMS_GetAntenna(lms_device_t *dev, bool dir_tx, 328 size_t chan); 329 330 /** 331 * Obtains recommended bandwidth (lower and upper frequency) for the specified 332 * antenna port. The ports can be used outside this range. 333 * 334 * @param dev Device handle previously obtained by LMS_Open(). 335 * @param dir_tx Select RX or TX 336 * @param chan channel index 337 * @param index Antenna index 338 * @param[out] range Antenna bandwidth 339 * 340 * @return 0 on success, (-1) on failure 341 */ 342 API_EXPORT int CALL_CONV LMS_GetAntennaBW(lms_device_t *dev, bool dir_tx, 343 size_t chan, size_t index, lms_range_t *range); 344 345 /** 346 * Set the combined gain value 347 * This function computes and sets the optimal gain values of various amplifiers 348 * that are present in the device based on desired normalized gain value. 349 * 350 * @note actual gain depends on LO frequency and analog LPF configuration and 351 * resulting output signal level may be different when those values are changed 352 * 353 * @attention Gain functionality will be changed in the future. IAMP 354 * and TIA gain elements won't configured via this function. To enable new 355 * behaviour, turn on ENABLE_NEW_GAIN_BEHAVIOUR CMake option. 356 * 357 * @param device Device handle previously obtained by LMS_Open(). 358 * @param dir_tx Select RX or TX 359 * @param chan Channel index 360 * @param gain Desired gain, range [0, 1.0], where 1.0 represents the 361 * maximum gain 362 * @return 0 on success, (-1) on failure 363 */ 364 API_EXPORT int CALL_CONV LMS_SetNormalizedGain(lms_device_t *device, bool dir_tx, 365 size_t chan,float_type gain); 366 367 /** 368 * Set the combined gain value in dB 369 * This function computes and sets the optimal gain values of various amplifiers 370 * that are present in the device based on desired gain value in dB. 371 * 372 * @note actual gain depends on LO frequency and analog LPF configuration and 373 * resulting output signal levle may be different when those values are changed 374 * 375 * @attention Gain functionality and range will be changed in the future. IAMP 376 * and TIA gain elements won't configured via this function. To enable new 377 * behaviour, turn on ENABLE_NEW_GAIN_BEHAVIOUR CMake option. 378 * 379 * @param device Device handle previously obtained by LMS_Open(). 380 * @param dir_tx Select RX or TX 381 * @param chan Channel index 382 * @param gain Desired gain, range [0, 73] 383 * @return 0 on success, (-1) on failure 384 */ 385 API_EXPORT int CALL_CONV LMS_SetGaindB(lms_device_t *device, bool dir_tx, 386 size_t chan, unsigned gain); 387 388 /** 389 * Obtain the current combined gain value 390 * 391 * @note actual gain depends on LO frequency and analog LPF configuration and 392 * resulting output signal level may be different when those values are changed 393 * 394 * @attention Gain functionality will be changed in the future. IAMP and TIA gain 395 * element values won't be obtained via this function. To enable new 396 * behaviour, turn on ENABLE_NEW_GAIN_BEHAVIOUR CMake option. 397 * 398 * @param device Device handle previously obtained by LMS_Open(). 399 * @param dir_tx Select RX or TX 400 * @param chan Channel index 401 * @param[out] gain Current gain, range [0, 1.0], where 1.0 represents 402 * the maximum gain 403 * @return 0 on success, (-1) on failure 404 */ 405 API_EXPORT int CALL_CONV LMS_GetNormalizedGain(lms_device_t *device, bool dir_tx, 406 size_t chan, float_type *gain); 407 /** 408 * Obtain the current combined gain value in dB 409 * 410 * @note actual gain depends on LO frequency and analog LPF configuration and 411 * resulting output signal level may be different when those values are changed 412 * 413 * @attention Gain functionality and range will be changed in the future. IAMP 414 * and TIA gain element values won't be obtained via this function. To enable new 415 * behaviour, turn on ENABLE_NEW_GAIN_BEHAVIOUR CMake option. 416 * 417 * @param device Device handle previously obtained by LMS_Open(). 418 * @param dir_tx Select RX or TX 419 * @param chan Channel index 420 * @param[out] gain Current gain 421 * @return 0 on success, (-1) on failure 422 */ 423 API_EXPORT int CALL_CONV LMS_GetGaindB(lms_device_t *device, bool dir_tx, 424 size_t chan, unsigned *gain); 425 426 /** 427 * Configure analog LPF of the LMS chip for the desired RF bandwidth. 428 * This function automatically enables LPF. 429 * 430 * @param device Device handle previously obtained by LMS_Open(). 431 * @param dir_tx Select RX or TX 432 * @param chan Channel index 433 * @param bandwidth LPF bandwidth in Hz 434 * 435 * @return 0 on success, (-1) on failure 436 */ 437 API_EXPORT int CALL_CONV LMS_SetLPFBW(lms_device_t *device, bool dir_tx, 438 size_t chan, float_type bandwidth); 439 440 /** 441 * Get the currently configured analog LPF RF bandwidth. 442 * @note readback from board is currently not supported, only returns last set 443 * value cached by software. 444 * 445 * @param device Device handle previously obtained by LMS_Open(). 446 * @param dir_tx Select RX or TX 447 * @param chan Channel index 448 * @param[out] bandwidth Current LPF bandwidth in Hz 449 * 450 * @return 0 on success, (-1) on failure 451 */ 452 API_EXPORT int CALL_CONV LMS_GetLPFBW(lms_device_t *device, bool dir_tx, 453 size_t chan, float_type *bandwidth); 454 455 /** 456 * Get the RF bandwidth setting range supported by the analog LPF of LMS chip. 457 * 458 * @param device Device handle previously obtained by LMS_Open(). 459 * @param dir_tx Select RX or TX 460 * @param[out] range Supported RF bandwidth range in Hz 461 * 462 * @return 0 on success, (-1) on failure 463 */ 464 API_EXPORT int CALL_CONV LMS_GetLPFBWRange(lms_device_t *device, bool dir_tx, 465 lms_range_t *range); 466 467 /** 468 * Disables or enables the analog LPF of LMS chip without reconfiguring it. 469 * 470 * @param device Device handle previously obtained by LMS_Open(). 471 * @param dir_tx Select RX or TX 472 * @param chan Channel index 473 * @param enable true(1) to enable, false(0) to disable 474 * 475 * @return 0 on success, (-1) on failure 476 */ 477 API_EXPORT int CALL_CONV LMS_SetLPF(lms_device_t *device, bool dir_tx, 478 size_t chan, bool enable); 479 480 /** 481 * Set up digital LPF using LMS chip GFIRS. This is a convenience function to 482 * quickly configure GFIRS as LPF with desired RF bandwidth. 483 * 484 * @pre sampling rate must be set 485 * 486 * @param device Device handle previously obtained by LMS_Open(). 487 * @param dir_tx Select RX or TX 488 * @param chan channel index 489 * @param enabled Disable (false) or enable (true) GFIRS. 490 * @param bandwidth LPF bandwidth in Hz. Has no effect if enabled is false. 491 * 492 * @return 0 on success, (-1) on failure 493 */ 494 API_EXPORT int CALL_CONV LMS_SetGFIRLPF(lms_device_t *device, bool dir_tx, 495 size_t chan, bool enabled, float_type bandwidth); 496 497 /** 498 * Perform the automatic calibration of specified RX/TX channel. The automatic 499 * calibration must be run after device configuration is finished because 500 * calibration values are dependant on various configuration settings. 501 * 502 * @pre Device should be configured 503 * 504 * @param device Device handle previously obtained by LMS_Open(). 505 * @param dir_tx Select RX or TX 506 * @param chan channel index 507 * @param bw bandwidth 508 * @param flags additional calibration flags (normally should be 0) 509 * 510 * @return 0 on success, (-1) on failure 511 */ 512 API_EXPORT int CALL_CONV LMS_Calibrate(lms_device_t *device, bool dir_tx, 513 size_t chan, double bw, unsigned flags); 514 515 /** 516 * Load LMS chip configuration from a file 517 * 518 * @note this only loads LMS chip configuration, in oder for streaming to work 519 * properly FPGA has also to be configured. Use LMS_SetSampleRate() to configure 520 * LMS and FPGA for streaming. 521 * 522 * @param device Device handle 523 * @param filename path to file 524 * 525 * @return 0 on success, (-1) on failure 526 */ 527 API_EXPORT int CALL_CONV LMS_LoadConfig(lms_device_t *device, const char *filename); 528 529 /** 530 * Save LMS chip configuration to a file 531 * 532 * @param device Device handle 533 * @param filename path to file with LMS chip configuration 534 * 535 * @return 0 on success, (-1) on failure 536 */ 537 API_EXPORT int CALL_CONV LMS_SaveConfig(lms_device_t *device, const char *filename); 538 539 /** 540 * Apply the specified test signal 541 * 542 * @param device Device handle previously obtained by LMS_Open(). 543 * @param dir_tx Select RX or TX. 544 * @param chan Channel index. 545 * @param sig Test signal. LMS_TESTSIG_NONE disables test signal. 546 * @param dc_i DC I value for LMS_TESTSIG_DC mode. Ignored in other modes. 547 * @param dc_q DC Q value for LMS_TESTSIG_DC mode. Ignored in other modes. 548 * 549 * @return 0 on success, (-1) on failure 550 */ 551 API_EXPORT int CALL_CONV LMS_SetTestSignal(lms_device_t *device, bool dir_tx, 552 size_t chan, lms_testsig_t sig, int16_t dc_i, int16_t dc_q); 553 /** 554 * Get the currently active test signal 555 * 556 * @param device Device handle previously obtained by LMS_Open(). 557 * @param dir_tx Select RX or TX 558 * @param chan Channel index 559 * @param sig Currently active test signal 560 * 561 * @return 0 on success, (-1) on failure 562 */ 563 API_EXPORT int CALL_CONV LMS_GetTestSignal(lms_device_t *device, bool dir_tx, 564 size_t chan, lms_testsig_t *sig); 565 566 /** 567 * Read LMS7 chip internal temperature sensor 568 * 569 * @param dev Device handle previously obtained by LMS_Open(). 570 * @param ind chip index 571 * @param temp temperature value 572 * 573 * @return 0 on success, (-1) on failure 574 */ 575 API_EXPORT int CALL_CONV LMS_GetChipTemperature(lms_device_t *dev, size_t ind, 576 float_type *temp); 577 578 /** 579 * @defgroup FN_ADVANCED Advanced control functions 580 * 581 * The functions in this section provides some additional control compared to 582 * High-Level functions. They are labeled advanced because they require better 583 * understanding of hardware and provide functionality that may conflict with 584 * other High-Level functions. 585 * @{ 586 */ 587 588 ///Enumeration of LMS7 GFIRS 589 typedef enum 590 { 591 LMS_GFIR1 = 0, 592 LMS_GFIR2, 593 LMS_GFIR3 594 }lms_gfir_t; 595 596 ///Number of NCO frequency/phase offset values 597 static const int LMS_NCO_VAL_COUNT = 16; 598 599 /** 600 * Set sampling rate for all RX or TX channels. Sample rate is in complex 601 * samples (1 sample = I + Q). The function sets sampling rate that is used for 602 * data exchange with the host. It also allows to specify higher sampling rate 603 * to be used in RF by setting oversampling ratio. Valid oversampling values are 604 * 1, 2, 4, 8, 16, 32 or 0 (use device default oversampling value). 605 * 606 * @note RX and TX rates sampling are closely tied in LMS7 chip. Changing RX or 607 * TX will often result in change of both (RX and TX). RX/TX ratio can only be 608 * power of 2 and is also limited by other factors. Use LMS_GetSampleRate() to 609 * obtain actual sample rate values. The function returns success if it is able 610 * to achieve desired sample rate and oversampling for the specified direction 611 * (RX or TX) ignoring possible value changes in other direction channels. 612 * 613 * @param[in] device Device handle previously obtained by LMS_Open(). 614 * @param dir_tx Select RX or TX 615 * @param rate Sampling rate in Hz to set 616 * @param oversample RF oversampling ratio. 617 * 618 * @return 0 on success, (-1) on failure 619 */ 620 API_EXPORT int CALL_CONV LMS_SetSampleRateDir(lms_device_t *device, bool dir_tx, 621 float_type rate, size_t oversample); 622 623 /** 624 * Configure NCO to operate in FCW mode. Configures NCO with up to 16 625 * frequencies that can be quickly switched between. 626 * Automatically starts NCO with frequency at index 0 627 * Use LMS_SetNCOindex() to switch between NCO frequencies. 628 * 629 * @param device Device handle previously obtained by LMS_Open(). 630 * @param dir_tx Select RX or TX 631 * @param chan Channel index 632 * @param[in] freq List of NCO frequencies. Values cannot be negative. 633 * Must be at least ::LMS_NCO_VAL_COUNT length; 634 * @param pho NCO phase offset in deg 635 * 636 * @return 0 on success, (-1) on failure 637 */ 638 API_EXPORT int CALL_CONV LMS_SetNCOFrequency(lms_device_t *device, bool dir_tx, 639 size_t chan, const float_type *freq, float_type pho); 640 641 /** 642 * Get the current NCO FCW mode configuration. 643 * 644 * @param device Device handle previously obtained by LMS_Open(). 645 * @param dir_tx Select RX or TX 646 * @param chan Channel index 647 * @param[out] freq List of NCO frequencies. Must be at least 648 * ::LMS_NCO_VAL_COUNT length; 649 * @param[out] pho Phase offset in deg 650 * 651 * @return 0 on success, (-1) on failure 652 */ 653 API_EXPORT int CALL_CONV LMS_GetNCOFrequency(lms_device_t *device, bool dir_tx, 654 size_t chan, float_type *freq, float_type *pho); 655 656 /** 657 * Configure NCO to operate in PHO mode. Configures NCO with up to 16 658 * phase offsets that can be quickly switched between. 659 * Automatically starts NCO with phase at index 0 660 * Use LMS_SetNCOindex() to switch between NCO phases. 661 * 662 * @param device Device handle previously obtained by LMS_Open(). 663 * @param dir_tx Select RX or TX 664 * @param chan Channel index 665 * @param[in] phases List of NCO phases. Values cannot be negative. 666 * Must be at least ::LMS_NCO_VAL_COUNT length; 667 * @param fcw NCO frequency in Hz 668 * 669 * @return 0 on success, (-1) on failure 670 */ 671 API_EXPORT int CALL_CONV LMS_SetNCOPhase(lms_device_t *device, bool dir_tx, 672 size_t chan, const float_type *phases, float_type fcw); 673 674 /** 675 * Get the current NCO PHO mode configuration. 676 * 677 * @param device Device handle previously obtained by LMS_Open(). 678 * @param dir_tx Select RX or TX 679 * @param chan channel index 680 * @param[out] phases List of configured NCO phases 681 * Must be at least ::LMS_NCO_VAL_COUNT length; 682 * @param[out] fcw Current NCO frequency 683 * 684 * @return 0 on success, (-1) on failure 685 */ 686 API_EXPORT int CALL_CONV LMS_GetNCOPhase(lms_device_t *device, bool dir_tx, 687 size_t chan, float_type *phases, float_type *fcw); 688 689 /** 690 * Switches between configured list of NCO frequencies/phase offsets. Also 691 * Allows to switch CMIX mode to either downconvert or upconvert. 692 * 693 * @param device Device handle previously obtained by LMS_Open(). 694 * @param dir_tx Select RX or TX 695 * @param chan channel index 696 * @param index NCO frequency/phase index to activate or (-1) to disable NCO 697 * @param downconv true(1) CMIX downconvert, false(0) CMIX upconvert 698 * 699 * @return 0 on success, (-1) on failure 700 */ 701 API_EXPORT int CALL_CONV LMS_SetNCOIndex(lms_device_t *device, bool dir_tx, 702 size_t chan, int index, bool downconv); 703 704 /** 705 * Get the currently active NCO frequency/phase offset index 706 * 707 * @param device Device handle previously obtained by LMS_Open(). 708 * @param dir_tx Select RX or TX 709 * @param chan Channel index 710 * 711 * @return Current NCO frequency/phase index on success, (-1) on failure 712 */ 713 API_EXPORT int CALL_CONV LMS_GetNCOIndex(lms_device_t *device, bool dir_tx, 714 size_t chan); 715 716 /** 717 * Configure LMS GFIR using specified filter coefficients. Maximum number of 718 * coefficients is 40 for GFIR1 and GFIR2, and 120 for GFIR3. 719 * 720 * @param device Device handle previously obtained by LMS_Open(). 721 * @param dir_tx Select RX or TX 722 * @param chan Channel index 723 * @param filt GFIR to configure 724 * @param[in] coef Array of filter coefficients. Coeff range [-1.0, 1.0]. 725 * @param count number of filter coefficients. 726 * 727 * @return 0 on success, (-1) on failure 728 */ 729 API_EXPORT int CALL_CONV LMS_SetGFIRCoeff(lms_device_t * device, bool dir_tx, 730 size_t chan, lms_gfir_t filt, const float_type* coef,size_t count); 731 732 /** 733 * Get currently set GFIR coefficients. 734 * 735 * @param device Device handle previously obtained by LMS_Open(). 736 * @param dir_tx Select RX or TX 737 * @param chan Channel index 738 * @param filt GFIR to configure 739 * @param[out] coef Current GFIR coefficients. Array must be big enough to 740 * hold 40 (GFIR1, GFIR2) or 120 (GFIR3) values. 741 * 742 * @return 0 on success, (-1) on failure 743 */ 744 API_EXPORT int CALL_CONV LMS_GetGFIRCoeff(lms_device_t * device, bool dir_tx, 745 size_t chan, lms_gfir_t filt, float_type* coef); 746 747 /** 748 * Enables or disables specified GFIR. 749 * 750 * @param device Device handle previously obtained by LMS_Open(). 751 * @param dir_tx Select RX or TX 752 * @param chan Channel index 753 * @param filt GFIR to configure 754 * @param enabled true(1) enable, false(0) disable. 755 * 756 * @return 0 on success, (-1) on failure 757 */ 758 API_EXPORT int CALL_CONV LMS_SetGFIR(lms_device_t * device, bool dir_tx, 759 size_t chan, lms_gfir_t filt, bool enabled); 760 761 /** 762 * Enables or disable caching of LMS7 and FPGA register values. 763 * 764 * @param dev Device handle previously obtained by LMS_Open(). 765 * @param enable true to enable cache 766 * 767 * @return 0 on success, (-1) on failure 768 */ 769 770 API_EXPORT int CALL_CONV LMS_EnableCache(lms_device_t *dev, bool enable); 771 772 /** @} (End FN_ADVANCED) */ 773 774 /** @} (End FN_HIGH_LVL) */ 775 776 /** 777 * @defgroup FN_LOW_LVL Low-Level control functions 778 * The functions in this section provide a low access to device such as modifying 779 * device internal register or clock frequency. Low-Level functions can be used 780 * to configure device entirely, however a more practical use is to fine-tune 781 * device settings after configuring it with /ref FN_HIGH_LVL. 782 * @{ 783 */ 784 785 /** 786 * Send Reset signal to LMS chip. This initializes LMS chip with default 787 * configuration as described in LMS chip datasheet. 788 * 789 * @param device Device handle previously obtained by LMS_Open(). 790 * 791 * @return 0 on success, (-1) on failure 792 */ 793 API_EXPORT int CALL_CONV LMS_Reset(lms_device_t *device); 794 795 /** 796 * Read device LMS chip register 797 * 798 * @param device Device handle previously obtained by LMS_Open(). 799 * @param address Register address 800 * @param val Current register value 801 * 802 * @return 0 on success, (-1) on failure 803 */ 804 API_EXPORT int CALL_CONV LMS_ReadLMSReg(lms_device_t *device, uint32_t address, 805 uint16_t *val); 806 807 /** 808 * Write device LMS chip register 809 * 810 * @param device Device handle previously obtained by LMS_Open(). 811 * @param address Register address 812 * @param val Value to write 813 * 814 * @return 0 on success, (-1) on failure 815 */ 816 API_EXPORT int CALL_CONV LMS_WriteLMSReg(lms_device_t *device, uint32_t address, 817 uint16_t val); 818 819 /** 820 * Read device parameter. Parameter defines specific bits in device register. 821 * 822 * @param device Device handle previously obtained by LMS_Open(). 823 * @param param Parameter. 824 * @param val Current parameter value. 825 * 826 * @return 0 on success, (-1) on failure 827 */ 828 API_EXPORT int CALL_CONV LMS_ReadParam(lms_device_t *device, 829 struct LMS7Parameter param, uint16_t *val); 830 831 /** 832 * Write device parameter. Parameter defines specific bits in device register. 833 * 834 * @param device Device handle previously obtained by LMS_Open(). 835 * @param param Parameter. 836 * @param val Parameter value to write 837 * 838 * @return 0 on success, (-1) on failure 839 */ 840 API_EXPORT int CALL_CONV LMS_WriteParam(lms_device_t *device, 841 struct LMS7Parameter param, uint16_t val); 842 843 /** 844 * Read device FPGA register 845 * 846 * @param device Device handle previously obtained by LMS_Open(). 847 * @param address Register address 848 * @param val Current register value 849 * 850 * @return 0 on success, (-1) on failure 851 */ 852 API_EXPORT int CALL_CONV LMS_ReadFPGAReg(lms_device_t *device, uint32_t address, 853 uint16_t *val); 854 855 /** 856 * Write device FPGA register 857 * 858 * @param device Device handle previously obtained by LMS_Open(). 859 * @param address Register address 860 * @param val Value to write 861 * 862 * @return 0 on success, (-1) on failure 863 */ 864 API_EXPORT int CALL_CONV LMS_WriteFPGAReg(lms_device_t *device, uint32_t address, 865 uint16_t val); 866 867 /** 868 * @defgroup BOARD_PARAM Board parameter 869 * 870 * @{ 871 */ 872 ///Runtime VCTCXO DAC trim value. Does not persist over power-cycle 873 #define BOARD_PARAM_DAC 0 874 ///The value of board temperature sensor (if present), read-only. 875 #define BOARD_PARAM_TEMP 1 876 /** @} (End BOARD_PARAM) */ 877 878 /** 879 * Read custom parameter from board 880 * 881 * @param device Device handle previously obtained by LMS_Open(). 882 * @param id Parameter identifier (\ref BOARD_PARAM) 883 * @param val Current register value 884 * @param units [optional] measurement units of parameter if available 885 * 886 * @return 0 on success, (-1) on failure 887 */ 888 API_EXPORT int CALL_CONV LMS_ReadCustomBoardParam(lms_device_t *device, 889 uint8_t id, float_type *val, lms_name_t units); 890 891 /** 892 * Write custom parameter from board 893 * 894 * @param device Device handle previously obtained by LMS_Open(). 895 * @param id Parameter identifier (\ref BOARD_PARAM) 896 * @param[out] val Value to write 897 * @param[out] units [optional] measurement units of parameter if available 898 * 899 * @return 0 on success, (-1) on failure 900 */ 901 API_EXPORT int CALL_CONV LMS_WriteCustomBoardParam(lms_device_t *device, 902 uint8_t id, float_type val, const lms_name_t units); 903 904 /** 905 * @defgroup LMS_CLOCK_ID Clock definitions 906 * 907 * Clock definitions for accessing specific internal clocks 908 * @{ 909 */ 910 ///Chip reference clock 911 #define LMS_CLOCK_REF 0x0000 912 ///RX LO clock 913 #define LMS_CLOCK_SXR 0x0001 914 ///TX LO clock 915 #define LMS_CLOCK_SXT 0x0002 916 ///CGEN clock 917 #define LMS_CLOCK_CGEN 0x0003 918 ///RXTSP reference clock (read-only) 919 #define LMS_CLOCK_RXTSP 0x0004 920 ///TXTSP reference clock (read-only) 921 #define LMS_CLOCK_TXTSP 0x0005 922 /** 923 * @brief External reference clock (write-only) 924 * 925 * Set to positive value to enable usage of external reference clock of the 926 * specified frequency. Set to 0 or negative value to disable usage of external 927 * reference clock (if switching reference clock source is supported by HW) 928 */ 929 #define LMS_CLOCK_EXTREF 0x0006 930 931 /** @} (End LMS_CLOCK_ID) */ 932 933 /** 934 * Get frequency of the specified clock. 935 * 936 * @param dev Device handle previously obtained by LMS_Open(). 937 * @param clk_id Clock identifier (\ref LMS_CLOCK_ID) 938 * @param freq Clock frequency in Hz 939 * 940 * @return 0 on success, (-1) on failure 941 */ 942 API_EXPORT int CALL_CONV LMS_GetClockFreq(lms_device_t *dev, size_t clk_id, 943 float_type *freq); 944 945 /** 946 * Set frequency of the specified clock 947 * 948 * @param dev Device handle previously obtained by LMS_Open(). 949 * @param clk_id Clock identifier (\ref LMS_CLOCK_ID) 950 * @param freq Clock frequency in Hz. Pass zero or negative value to only 951 * perform tune (if supported) without recalculating values 952 * 953 * @return 0 on success, (-1) on failure 954 */ 955 API_EXPORT int CALL_CONV LMS_SetClockFreq(lms_device_t *dev, size_t clk_id, 956 float_type freq); 957 958 /** 959 * Write value to VCTCXO trim DAC. Used to adjust/calibrate reference clock 960 * generated by voltage controlled oscillator. Value is written to non-volatile 961 * storage. 962 * @note calling this functions switches clock source to VCTCXO 963 * 964 * @param dev Device handle previously obtained by LMS_Open(). 965 * @param val Value to write to VCTCXO trim DAC 966 * 967 * @return 0 on success, (-1) on failure 968 */ 969 API_EXPORT int CALL_CONV LMS_VCTCXOWrite(lms_device_t * dev, uint16_t val); 970 971 /** 972 * Read VCTCXO trim DAC value from non-volatile storage. Returned value is value 973 * that is loaded on power-on and may different from current runtime value. 974 * 975 * @param[in] dev Device handle previously obtained by LMS_Open(). 976 * @param[out] val VCTCXO trim DAC value 977 * 978 * @return 0 on success, (-1) on failure 979 */ 980 API_EXPORT int CALL_CONV LMS_VCTCXORead(lms_device_t * dev, uint16_t *val); 981 982 /** 983 * Synchronizes register values between API cache and chip 984 * 985 * @param dev Device handle previously obtained by LMS_Open(). 986 * @param toChip if true copies values from API cache to chip. 987 * 988 * @return 0 on success, (-1) on failure 989 */ 990 API_EXPORT int CALL_CONV LMS_Synchronize(lms_device_t *dev, bool toChip); 991 992 /** 993 * @param dev Device handle previously obtained by LMS_Open(). 994 * @param[in] buffer read values (8 GPIO values per byte, LSB first) 995 * @param len number of bytes to read 996 * 997 * @return 0 on success, (-1) on failure 998 */ 999 API_EXPORT int CALL_CONV LMS_GPIORead(lms_device_t *dev, uint8_t* buffer, size_t len); 1000 1001 /** 1002 * @param dev Device handle previously obtained by LMS_Open(). 1003 * @param[out] buffer values to write (8 GPIO values per byte, LSB first) 1004 * @param len number of bytes to write 1005 * 1006 * @return 0 on success, (-1) on failure 1007 */ 1008 API_EXPORT int CALL_CONV LMS_GPIOWrite(lms_device_t *dev, const uint8_t* buffer, size_t len); 1009 1010 /** 1011 * @param dev Device handle previously obtained by LMS_Open(). 1012 * @param[out] buffer GPIO direction configuration(8 GPIO per byte, LSB first; 0 input, 1 output) 1013 * @param len number of bytes to read 1014 * 1015 * @return 0 on success, (-1) on failure 1016 */ 1017 API_EXPORT int CALL_CONV LMS_GPIODirRead(lms_device_t *dev, uint8_t* buffer, size_t len); 1018 1019 /** 1020 * @param dev Device handle previously obtained by LMS_Open(). 1021 * @param[in] buffer GPIO direction configuration(8 GPIO per byte, LSB first; 0 input, 1 output) 1022 * @param len number of bytes to write 1023 * 1024 * @return 0 on success, (-1) on failure 1025 */ 1026 API_EXPORT int CALL_CONV LMS_GPIODirWrite(lms_device_t *dev, const uint8_t* buffer, size_t len); 1027 1028 /** @} (End FN_LOW_LVL) */ 1029 1030 /** 1031 * @defgroup FN_STREAM Sample Streaming functions 1032 * The functions in this section provides support for sending and receiving 1033 * IQ data samples. 1034 * @{ 1035 */ 1036 1037 /**Metadata structure used in sample transfers*/ 1038 typedef struct 1039 { 1040 /** 1041 * Timestamp is a value of HW counter with a tick based on sample rate. 1042 * In RX: time when the first sample in the returned buffer was received 1043 * In TX: time when the first sample in the submitted buffer should be send 1044 */ 1045 uint64_t timestamp; 1046 1047 /**In TX: wait for the specified HW timestamp before broadcasting data over 1048 * the air 1049 * In RX: not used/ignored 1050 */ 1051 bool waitForTimestamp; 1052 1053 /**In TX: send samples to HW even if packet is not completely filled (end TX burst). 1054 * in RX: not used/ignored 1055 */ 1056 bool flushPartialPacket; 1057 1058 }lms_stream_meta_t; 1059 1060 /** 1061 * @defgroup STREAM_CH_FLAGS Additional streaming options 1062 * 1063 * @brief These can be combined with lms_stream_t::channel to 1064 * enable additional streaming options. 1065 * @{ 1066 */ 1067 ///Attempt to align channel phases in MIMO mode (supported only for Rx channels) 1068 #define LMS_ALIGN_CH_PHASE (1<<16) 1069 /** @} (End STREAM_CH_FLAGS) */ 1070 1071 /**Stream structure*/ 1072 typedef struct 1073 { 1074 /** @brief 1075 * Stream handle. Should not be modified manually. 1076 * Assigned by LMS_SetupStream().*/ 1077 size_t handle; 1078 1079 //! Indicates whether stream is TX (true) or RX (false) 1080 bool isTx; 1081 1082 /** @brief 1083 * Channel number, starts at 0. 1084 * Can be combined with additional flags (\ref STREAM_CH_FLAGS)*/ 1085 uint32_t channel; 1086 1087 //! FIFO size (in samples) used by stream. 1088 uint32_t fifoSize; 1089 1090 /** @brief 1091 * Parameter for controlling configuration bias toward low latency or high 1092 * data throughput range [0,1.0]. 1093 * 0 - lowest latency, usually results in lower throughput 1094 * 1 - higher throughput, usually results in higher latency 1095 */ 1096 float throughputVsLatency; 1097 1098 //! Data output format 1099 enum 1100 { 1101 LMS_FMT_F32=0, ///<32-bit floating point 1102 LMS_FMT_I16, ///<16-bit integers 1103 LMS_FMT_I12 ///<12-bit integers stored in 16-bit variables 1104 }dataFmt; 1105 1106 //! Data link format 1107 enum 1108 { 1109 LMS_LINK_FMT_DEFAULT=0, ///<12-bit integers stored in 16-bit variables 1110 /// when dataFmt=LMS_FMT_I12, 16-bit otherwise 1111 LMS_LINK_FMT_I16, ///<16-bit integers 1112 LMS_LINK_FMT_I12 ///<12-bit integers 1113 }linkFmt; 1114 }lms_stream_t; 1115 1116 /**Streaming status structure*/ 1117 typedef struct 1118 { 1119 ///Indicates whether the stream is currently active 1120 bool active; 1121 ///Number of samples in FIFO buffer 1122 uint32_t fifoFilledCount; 1123 ///Size (in samples) of FIFO buffer 1124 uint32_t fifoSize; 1125 ///FIFO underrun count since the last call to LMS_GetStreamStatus() 1126 uint32_t underrun; 1127 ///FIFO overrun count since the last call to LMS_GetStreamStatus() 1128 uint32_t overrun; 1129 ///Number of dropped packets by HW since the last call to LMS_GetStreamStatus() 1130 uint32_t droppedPackets; 1131 ///Currently not used 1132 float_type sampleRate; 1133 ///Data transfer rate (B/s) over the last 1 s per direction per LMS chip. 1134 float_type linkRate; 1135 ///The most recently received Rx timestamp, or the last timestamp submitted to Tx. 1136 uint64_t timestamp; 1137 1138 } lms_stream_status_t; 1139 1140 /** 1141 * Create new stream based on parameters passed in configuration structure. 1142 * The structure is initialized with stream handle. 1143 * 1144 * @param device Device handle previously obtained by LMS_Open(). 1145 * @param stream Stream configuration .See the ::lms_stream_t description. 1146 * 1147 * @return 0 on success, (-1) on failure 1148 */ 1149 API_EXPORT int CALL_CONV LMS_SetupStream(lms_device_t *device, lms_stream_t *stream); 1150 1151 /** 1152 * Deallocate memory used by stream. 1153 * 1154 * @param dev Device handle previously obtained by LMS_Open(). 1155 * @param stream Stream structure previously initialized with LMS_SetupStream(). 1156 * 1157 * @return 0 on success, (-1) on failure 1158 */ 1159 API_EXPORT int CALL_CONV LMS_DestroyStream(lms_device_t *dev, lms_stream_t *stream); 1160 1161 /** 1162 * Start stream 1163 * 1164 * @param stream Stream structure previously initialized with LMS_SetupStream(). 1165 * 1166 * @return 0 on success, (-1) on failure 1167 */ 1168 API_EXPORT int CALL_CONV LMS_StartStream(lms_stream_t *stream); 1169 1170 /** 1171 * Stop stream 1172 * 1173 * @param stream Stream structure previously initialized with LMS_SetupStream(). 1174 * 1175 * @return 0 on success, (-1) on failure 1176 */ 1177 API_EXPORT int CALL_CONV LMS_StopStream(lms_stream_t *stream); 1178 1179 /** 1180 * Read samples from the FIFO of the specified stream. 1181 * Sample buffer must be big enough to hold requested number of samples. 1182 * 1183 * @param stream structure previously initialized with LMS_SetupStream(). 1184 * @param samples sample buffer. 1185 * @param sample_count Number of samples to read 1186 * @param meta Metadata. See the ::lms_stream_meta_t description. 1187 * @param timeout_ms how long to wait for data before timing out. 1188 * 1189 * @return number of samples received on success, (-1) on failure 1190 */ 1191 API_EXPORT int CALL_CONV LMS_RecvStream(lms_stream_t *stream, void *samples, 1192 size_t sample_count, lms_stream_meta_t *meta, unsigned timeout_ms); 1193 1194 /** 1195 * Get stream operation status 1196 * 1197 * @param stream structure previously initialized with LMS_SetupStream(). 1198 * @param status Stream status. See the ::lms_stream_status_t for description 1199 * 1200 * @return 0 on success, (-1) on failure 1201 */ 1202 API_EXPORT int CALL_CONV LMS_GetStreamStatus(lms_stream_t *stream, lms_stream_status_t* status); 1203 1204 /** 1205 * Write samples to the FIFO of the specified stream. 1206 * 1207 * @param stream structure previously initialized with LMS_SetupStream(). 1208 * @param samples sample buffer. 1209 * @param sample_count Number of samples to write 1210 * @param meta Metadata. See the ::lms_stream_meta_t description. 1211 * @param timeout_ms how long to wait for data before timing out. 1212 * 1213 * @return number of samples send on success, (-1) on failure 1214 */ 1215 API_EXPORT int CALL_CONV LMS_SendStream(lms_stream_t *stream, 1216 const void *samples,size_t sample_count, 1217 const lms_stream_meta_t *meta, unsigned timeout_ms); 1218 1219 /** 1220 * Uploads waveform to on board memory for later use 1221 * @param device Device handle previously obtained by LMS_Open(). 1222 * @param samples multiple channel samples data 1223 * @param chCount number of waveform channels (1 or 2). 1224 * @param sample_count number of samples in each channel. Must be multiple of 4 1225 * @param format waveform data format: 0 - int16 [-2048, 2047], 1226 * 1 - int16 [-32768, 32767] 1227 * 2 - float [-1.0, 1.0] 1228 * @return 0 on success, (-1) on failure 1229 */ 1230 API_EXPORT int CALL_CONV LMS_UploadWFM(lms_device_t *device, const void **samples, 1231 uint8_t chCount, size_t sample_count, int format); 1232 1233 /** 1234 * Enables/Disables transmitting of uploaded waveform 1235 * @param device Device handle previously obtained by LMS_Open(). 1236 * @param chan Channel index 1237 * @param active Enable/Disable waveform playback 1238 * @return 0 on success, (-1) on failure 1239 */ 1240 API_EXPORT int CALL_CONV LMS_EnableTxWFM(lms_device_t *device, unsigned chan, bool active); 1241 1242 /** @} (End FN_STREAM) */ 1243 1244 /** 1245 * @defgroup FN_VERSION Version and update functions 1246 * 1247 * The functions in this section provides ability to check device version 1248 * and perform updates 1249 * @{ 1250 */ 1251 1252 /** 1253 * Get the list of supported programming modes. 1254 * 1255 * @param device Device handle previously obtained by LMS_Open(). 1256 * @param[out] list list of programming modes (can be NULL). 1257 * 1258 * @return number of modes in the list, (-1) on failure 1259 */ 1260 API_EXPORT int CALL_CONV LMS_GetProgramModes(lms_device_t *device, lms_name_t *list); 1261 1262 /** 1263 * Callback from programming processes 1264 * @param bsent number of bytes transferred 1265 * @param btotal total number of bytes to send 1266 * @param progressMsg string describing current progress state 1267 * @return 0-continue programming, 1-abort operation 1268 */ 1269 typedef bool (*lms_prog_callback_t)(int bsent, int btotal, const char* progressMsg); 1270 1271 /** 1272 * Write binary firmware/bitsteam image to specified device component. 1273 * 1274 * @param device Device handle previously obtained by LMS_Open(). 1275 * @param data Pointer to memory containing firmware/bitsteam image 1276 * @param size Size of firmware/bitsteam image in bytes. 1277 * @param mode programming mode, use LMS_GetProgramModes to get list of modes 1278 * @param callback callback function for monitoring progress 1279 * 1280 * @return 0 on success, (-1) on failure 1281 */ 1282 API_EXPORT int CALL_CONV LMS_Program(lms_device_t *device, const char *data, 1283 size_t size, const lms_name_t mode, lms_prog_callback_t callback); 1284 1285 /**Device information structure*/ 1286 typedef struct 1287 { 1288 char deviceName[32]; ///<The display name of the device 1289 char expansionName[32]; ///<The display name of the expansion card 1290 char firmwareVersion[16]; ///<The firmware version as a string 1291 char hardwareVersion[16]; ///<The hardware version as a string 1292 char protocolVersion[16]; ///<The protocol version as a string 1293 uint64_t boardSerialNumber; ///<A unique board serial number 1294 char gatewareVersion[16]; ///<Gateware version as a string 1295 char gatewareTargetBoard[32]; ///<Which board should use this gateware 1296 }lms_dev_info_t; 1297 1298 /** 1299 * Get device serial number and version information 1300 * 1301 * @note This function returns pointer to internal data structure that gets 1302 * deallocated when device is closed. Do not attempt to read from it after 1303 * closing the device. If you need to keep using device info returned by this 1304 * function after closing the device, make a copy before closing the device. 1305 * 1306 * @param device Device handle previously obtained by LMS_Open(). 1307 * @return pointer to device info structure ::lms_dev_info_t 1308 */ 1309 API_EXPORT const lms_dev_info_t* CALL_CONV LMS_GetDeviceInfo(lms_device_t *device); 1310 1311 /** 1312 * @brief Returns API library version 1313 */ 1314 API_EXPORT const char* LMS_GetLibraryVersion(void); 1315 1316 /** 1317 * Get the error message detailing why the last error occurred. 1318 * 1319 * @deprecated use LMS_RegisterLogHandler() to obtain error messages 1320 * 1321 * @return last error message. 1322 */ 1323 API_EXPORT const char * CALL_CONV LMS_GetLastErrorMessage(void); 1324 1325 /** 1326 * @defgroup LMS_LOG_LEVEL Message logging level 1327 * 1328 * @{ 1329 */ 1330 ///A critical error. The application might not be able to continue running successfully. 1331 #define LMS_LOG_CRITICAL 0 1332 ///An error message . An operation did not complete successfully. 1333 #define LMS_LOG_ERROR 1 1334 ///A warning message. An operation completed with an unexpected result. 1335 #define LMS_LOG_WARNING 2 1336 ///An informational message, usually denoting the successful completion of an operation 1337 #define LMS_LOG_INFO 3 1338 ///A debugging message. 1339 #define LMS_LOG_DEBUG 4 1340 /** @} (End LMS_LOG_LEVEL) */ 1341 1342 /** 1343 * Callback function for redirecting API messages 1344 * 1345 * @param lvl \ref LMS_LOG_LEVEL. 1346 * @param msg string containing log message text. 1347 */ 1348 typedef void (*LMS_LogHandler)(int lvl, const char *msg); 1349 1350 /*! 1351 * Register a new system log handler. Should be called to replace the default 1352 * stdio handler. 1353 * 1354 * @param handler function for handling API messages 1355 */ 1356 API_EXPORT void LMS_RegisterLogHandler(LMS_LogHandler handler); 1357 1358 /** @} (End FN_VERSION) */ 1359 1360 #ifdef __cplusplus 1361 } //extern "C" 1362 #endif 1363 1364 #endif //LMS_SDR_INTERFACE_H 1365