src/device.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2013 Bert Vermeulen <bert@biot.com>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #include <config.h>
  21 #include <glib.h>
  22 #include <stdio.h>
  23 #include <string.h>
  24 #include <libsigrok/libsigrok.h>
  25 #include "libsigrok-internal.h"
  26
  27 /** @cond PRIVATE */
  28 #define LOG_PREFIX "device"
  29 /** @endcond */
  30
  31 /**
  32  * @file
  33  *
  34  * Device handling in libsigrok.
  35  */
  36
  37 /**
  38  * @defgroup grp_devices Devices
  39  *
  40  * Device handling in libsigrok.
  41  *
  42  * @{
  43  */
  44
  45 /**
  46  * Allocate and initialize a new struct sr_channel and add it to sdi.
  47  *
  48  * @param[in] sdi The device instance the channel is connected to.
  49  *                Must not be NULL.
  50  * @param[in] index @copydoc sr_channel::index
  51  * @param[in] type @copydoc sr_channel::type
  52  * @param[in] enabled @copydoc sr_channel::enabled
  53  * @param[in] name @copydoc sr_channel::name
  54  *
  55  * @return A new struct sr_channel*.
  56  *
  57  * @private
  58  */
  59 SR_PRIV struct sr_channel *sr_channel_new(struct sr_dev_inst *sdi,
  60                 int index, int type, gboolean enabled, const char *name)
  61 {
  62         struct sr_channel *ch;
  63
  64         ch = g_malloc0(sizeof(struct sr_channel));
  65         ch->sdi = sdi;
  66         ch->index = index;
  67         ch->type = type;
  68         ch->enabled = enabled;
  69         if (name)
  70                 ch->name = g_strdup(name);
  71
  72         sdi->channels = g_slist_append(sdi->channels, ch);
  73
  74         return ch;
  75 }
  76
  77 /**
  78  * Release a previously allocated struct sr_channel.
  79  *
  80  * @param[in] ch Pointer to struct sr_channel.
  81  *
  82  * @private
  83  */
  84 SR_PRIV void sr_channel_free(struct sr_channel *ch)
  85 {
  86         if (!ch)
  87                 return;
  88         g_free(ch->name);
  89         g_free(ch->priv);
  90         g_free(ch);
  91 }
  92
  93 /**
  94  * Wrapper around @ref sr_channel_free(), suitable for glib iterators.
  95  */
  96 SR_PRIV void sr_channel_free_cb(void *p)
  97 {
  98         sr_channel_free(p);
  99 }
 100
 101 /**
 102  * Set the name of the specified channel.
 103  *
 104  * If the channel already has a different name assigned to it, it will be
 105  * removed, and the new name will be saved instead.
 106  *
 107  * @param[in] channel The channel whose name to set. Must not be NULL.
 108  * @param[in] name The new name that the specified channel should get.
 109  *                 A copy of the string is made.
 110  *
 111  * @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
 112  *
 113  * @since 0.3.0
 114  */
 115 SR_API int sr_dev_channel_name_set(struct sr_channel *channel,
 116                 const char *name)
 117 {
 118         if (!channel)
 119                 return SR_ERR_ARG;
 120
 121         g_free(channel->name);
 122         channel->name = g_strdup(name);
 123
 124         return SR_OK;
 125 }
 126
 127 /**
 128  * Enable or disable a channel.
 129  *
 130  * @param[in] channel The channel to enable or disable. Must not be NULL.
 131  * @param[in] state TRUE to enable the channel, FALSE to disable.
 132  *
 133  * @return SR_OK on success or SR_ERR on failure. In case of invalid
 134  *         arguments, SR_ERR_ARG is returned and the channel enabled state
 135  *         remains unchanged.
 136  *
 137  * @since 0.3.0
 138  */
 139 SR_API int sr_dev_channel_enable(struct sr_channel *channel, gboolean state)
 140 {
 141         int ret;
 142         gboolean was_enabled;
 143         struct sr_dev_inst *sdi;
 144
 145         if (!channel)
 146                 return SR_ERR_ARG;
 147
 148         sdi = channel->sdi;
 149         was_enabled = channel->enabled;
 150         channel->enabled = state;
 151         if (!state != !was_enabled && sdi->driver
 152                         && sdi->driver->config_channel_set) {
 153                 ret = sdi->driver->config_channel_set(
 154                         sdi, channel, SR_CHANNEL_SET_ENABLED);
 155                 /* Roll back change if it wasn't applicable. */
 156                 if (ret != SR_OK)
 157                         return ret;
 158         }
 159
 160         return SR_OK;
 161 }
 162
 163 /**
 164  * Returns the next enabled channel, wrapping around if necessary.
 165  *
 166  * @param[in] sdi The device instance the channel is connected to.
 167  *                Must not be NULL.
 168  * @param[in] cur_channel The current channel.
 169  *
 170  * @return A pointer to the next enabled channel of this device.
 171  *
 172  * @private
 173  */
 174 SR_PRIV struct sr_channel *sr_next_enabled_channel(const struct sr_dev_inst *sdi,
 175                 struct sr_channel *cur_channel)
 176 {
 177         struct sr_channel *next_channel;
 178         GSList *l;
 179
 180         next_channel = cur_channel;
 181         do {
 182                 l = g_slist_find(sdi->channels, next_channel);
 183                 if (l && l->next)
 184                         next_channel = l->next->data;
 185                 else
 186                         next_channel = sdi->channels->data;
 187         } while (!next_channel->enabled);
 188
 189         return next_channel;
 190 }
 191
 192 /**
 193  * Compare two channels, return whether they differ.
 194  *
 195  * The channels' names and types are checked. The enabled state is not
 196  * considered a condition for difference. The test is motivated by the
 197  * desire to detect changes in the configuration of acquisition setups
 198  * between re-reads of an input file.
 199  *
 200  * @param[in] ch1 First channel.
 201  * @param[in] ch2 Second channel.
 202  *
 203  * @return #TRUE upon differences or unexpected input, #FALSE otherwise.
 204  *
 205  * @internal
 206  */
 207 SR_PRIV gboolean sr_channels_differ(struct sr_channel *ch1, struct sr_channel *ch2)
 208 {
 209         if (!ch1 || !ch2)
 210                 return TRUE;
 211
 212         if (ch1->type != ch2->type)
 213                 return TRUE;
 214         if (strcmp(ch1->name, ch2->name))
 215                 return TRUE;
 216
 217         return FALSE;
 218 }
 219
 220 /**
 221  * Compare two channel lists, return whether they differ.
 222  *
 223  * Listing the same set of channels but in a different order is considered
 224  * a difference in the lists.
 225  *
 226  * @param[in] l1 First channel list.
 227  * @param[in] l2 Second channel list.
 228  *
 229  * @return #TRUE upon differences or unexpected input, #FALSE otherwise.
 230  *
 231  * @internal
 232  */
 233 SR_PRIV gboolean sr_channel_lists_differ(GSList *l1, GSList *l2)
 234 {
 235         struct sr_channel *ch1, *ch2;
 236
 237         while (l1 && l2) {
 238                 ch1 = l1->data;
 239                 ch2 = l2->data;
 240                 l1 = l1->next;
 241                 l2 = l2->next;
 242                 if (!ch1 || !ch2)
 243                         return TRUE;
 244                 if (sr_channels_differ(ch1, ch2))
 245                         return TRUE;
 246                 if (ch1->index != ch2->index)
 247                         return TRUE;
 248         }
 249         if (l1 || l2)
 250                 return TRUE;
 251
 252         return FALSE;
 253 }
 254
 255 /**
 256  * Determine whether the specified device instance has the specified
 257  * capability.
 258  *
 259  * @param sdi Pointer to the device instance to be checked. Must not be NULL.
 260  *            If the device's 'driver' field is NULL (virtual device), this
 261  *            function will always return FALSE (virtual devices don't have
 262  *            a hardware capabilities list).
 263  * @param[in] key The option that should be checked for is supported by the
 264  *            specified device.
 265  *
 266  * @retval TRUE Device has the specified option.
 267  * @retval FALSE Device does not have the specified option, invalid input
 268  *         parameters or other error conditions.
 269  *
 270  * @since 0.2.0
 271  */
 272 SR_API gboolean sr_dev_has_option(const struct sr_dev_inst *sdi, int key)
 273 {
 274         GVariant *gvar;
 275         const int *devopts;
 276         gsize num_opts, i;
 277         int ret;
 278
 279         if (!sdi || !sdi->driver || !sdi->driver->config_list)
 280                 return FALSE;
 281
 282         if (sdi->driver->config_list(SR_CONF_DEVICE_OPTIONS,
 283                                 &gvar, sdi, NULL) != SR_OK)
 284                 return FALSE;
 285
 286         ret = FALSE;
 287         devopts = g_variant_get_fixed_array(gvar, &num_opts, sizeof(int32_t));
 288         for (i = 0; i < num_opts; i++) {
 289                 if ((devopts[i] & SR_CONF_MASK) == key) {
 290                         ret = TRUE;
 291                         break;
 292                 }
 293         }
 294         g_variant_unref(gvar);
 295
 296         return ret;
 297 }
 298
 299 /**
 300  * Enumerate the configuration options of the specified item.
 301  *
 302  * @param driver Pointer to the driver to be checked. Must not be NULL.
 303  * @param sdi Pointer to the device instance to be checked. May be NULL to
 304  *            check driver options.
 305  * @param cg Pointer to a channel group, if a specific channel group is to
 306  *           be checked. Must be NULL to check device-wide options.
 307  *
 308  * @return A GArray * of enum sr_configkey values, or NULL on invalid
 309  *         arguments. The array must be freed by the caller using
 310  *         g_array_free().
 311  *
 312  * @since 0.4.0
 313  */
 314 SR_API GArray *sr_dev_options(const struct sr_dev_driver *driver,
 315         const struct sr_dev_inst *sdi, const struct sr_channel_group *cg)
 316 {
 317         GVariant *gvar;
 318         const uint32_t *opts;
 319         uint32_t opt;
 320         gsize num_opts, i;
 321         GArray *result;
 322
 323         if (!driver || !driver->config_list)
 324                 return NULL;
 325
 326         if (sdi && sdi->driver != driver)
 327                 return NULL;
 328
 329         if (driver->config_list(SR_CONF_DEVICE_OPTIONS, &gvar, sdi, cg) != SR_OK)
 330                 return NULL;
 331
 332         opts = g_variant_get_fixed_array(gvar, &num_opts, sizeof(uint32_t));
 333
 334         result = g_array_sized_new(FALSE, FALSE, sizeof(uint32_t), num_opts);
 335
 336         for (i = 0; i < num_opts; i++) {
 337                 opt = opts[i] & SR_CONF_MASK;
 338                 g_array_insert_val(result, i, opt);
 339         }
 340
 341         g_variant_unref(gvar);
 342
 343         return result;
 344 }
 345
 346 /**
 347  * Enumerate the configuration capabilities supported by a device instance
 348  * for a given configuration key.
 349  *
 350  * @param sdi Pointer to the device instance to be checked. Must not be NULL.
 351  *            If the device's 'driver' field is NULL (virtual device), this
 352  *            function will always return FALSE (virtual devices don't have
 353  *            a hardware capabilities list).
 354  * @param cg Pointer to a channel group, if a specific channel group is to
 355  *           be checked. Must be NULL to check device-wide options.
 356  * @param[in] key The option that should be checked for is supported by the
 357  *            specified device.
 358  *
 359  * @retval A bitmask of enum sr_configcap values, which will be zero for
 360  *         invalid inputs or if the key is unsupported.
 361  *
 362  * @since 0.4.0
 363  */
 364 SR_API int sr_dev_config_capabilities_list(const struct sr_dev_inst *sdi,
 365                 const struct sr_channel_group *cg, const int key)
 366 {
 367         GVariant *gvar;
 368         const int *devopts;
 369         gsize num_opts, i;
 370         int ret;
 371
 372         if (!sdi || !sdi->driver || !sdi->driver->config_list)
 373                 return 0;
 374
 375         if (sdi->driver->config_list(SR_CONF_DEVICE_OPTIONS,
 376                                 &gvar, sdi, cg) != SR_OK)
 377                 return 0;
 378
 379         ret = 0;
 380         devopts = g_variant_get_fixed_array(gvar, &num_opts, sizeof(int32_t));
 381         for (i = 0; i < num_opts; i++) {
 382                 if ((devopts[i] & SR_CONF_MASK) == key) {
 383                         ret = devopts[i] & ~SR_CONF_MASK;
 384                         break;
 385                 }
 386         }
 387         g_variant_unref(gvar);
 388
 389         return ret;
 390 }
 391
 392 /**
 393  * Allocate and init a new user-generated device instance.
 394  *
 395  * @param vendor Device vendor.
 396  * @param model Device model.
 397  * @param version Device version.
 398  *
 399  * @retval struct sr_dev_inst *. Dynamically allocated, free using
 400  *         sr_dev_inst_free().
 401  */
 402 SR_API struct sr_dev_inst *sr_dev_inst_user_new(const char *vendor,
 403                 const char *model, const char *version)
 404 {
 405         struct sr_dev_inst *sdi;
 406
 407         sdi = g_malloc0(sizeof(struct sr_dev_inst));
 408
 409         sdi->vendor = g_strdup(vendor);
 410         sdi->model = g_strdup(model);
 411         sdi->version = g_strdup(version);
 412         sdi->inst_type = SR_INST_USER;
 413
 414         return sdi;
 415 }
 416
 417 /**
 418  * Add a new channel to the specified device instance.
 419  *
 420  * @param[in] index @copydoc sr_channel::index
 421  * @param[in] type @copydoc sr_channel::type
 422  * @param[in] name @copydoc sr_channel::name
 423  *
 424  * @return SR_OK Success.
 425  * @return SR_OK Invalid argument.
 426  */
 427 SR_API int sr_dev_inst_channel_add(struct sr_dev_inst *sdi, int index, int type, const char *name)
 428 {
 429         if (!sdi || sdi->inst_type != SR_INST_USER || index < 0)
 430                 return SR_ERR_ARG;
 431
 432         sr_channel_new(sdi, index, type, TRUE, name);
 433
 434         return SR_OK;
 435 }
 436
 437 /**
 438  * Free device instance struct created by sr_dev_inst().
 439  *
 440  * @param sdi Device instance to free. If NULL, the function will do nothing.
 441  *
 442  * @private
 443  */
 444 SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi)
 445 {
 446         struct sr_channel *ch;
 447         struct sr_channel_group *cg;
 448         GSList *l;
 449
 450         if (!sdi)
 451                 return;
 452
 453         for (l = sdi->channels; l; l = l->next) {
 454                 ch = l->data;
 455                 sr_channel_free(ch);
 456         }
 457         g_slist_free(sdi->channels);
 458
 459         for (l = sdi->channel_groups; l; l = l->next) {
 460                 cg = l->data;
 461                 g_free(cg->name);
 462                 g_slist_free(cg->channels);
 463                 g_free(cg->priv);
 464                 g_free(cg);
 465         }
 466         g_slist_free(sdi->channel_groups);
 467
 468         if (sdi->session)
 469                 sr_session_dev_remove(sdi->session, sdi);
 470
 471         g_free(sdi->vendor);
 472         g_free(sdi->model);
 473         g_free(sdi->version);
 474         g_free(sdi->serial_num);
 475         g_free(sdi->connection_id);
 476         g_free(sdi);
 477 }
 478
 479 #ifdef HAVE_LIBUSB_1_0
 480
 481 /**
 482  * Allocate and init a struct for a USB device instance.
 483  *
 484  * @param[in] bus @copydoc sr_usb_dev_inst::bus
 485  * @param[in] address @copydoc sr_usb_dev_inst::address
 486  * @param[in] hdl @copydoc sr_usb_dev_inst::devhdl
 487  *
 488  * @return The struct sr_usb_dev_inst * for USB device instance.
 489  *
 490  * @private
 491  */
 492 SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus,
 493                         uint8_t address, struct libusb_device_handle *hdl)
 494 {
 495         struct sr_usb_dev_inst *udi;
 496
 497         udi = g_malloc0(sizeof(struct sr_usb_dev_inst));
 498         udi->bus = bus;
 499         udi->address = address;
 500         udi->devhdl = hdl;
 501
 502         return udi;
 503 }
 504
 505 /**
 506  * Free struct sr_usb_dev_inst * allocated by sr_usb_dev_inst().
 507  *
 508  * @param usb The struct sr_usb_dev_inst * to free. If NULL, this
 509  *            function does nothing.
 510  *
 511  * @private
 512  */
 513 SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
 514 {
 515         g_free(usb);
 516 }
 517
 518 #endif
 519
 520 #ifdef HAVE_LIBSERIALPORT
 521
 522 /**
 523  * Allocate and init a struct for a serial device instance.
 524  *
 525  * Both parameters are copied to newly allocated strings, and freed
 526  * automatically by sr_serial_dev_inst_free().
 527  *
 528  * @param[in] port OS-specific serial port specification. Examples:
 529  *                 "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1".
 530  *                 Must not be NULL.
 531  * @param[in] serialcomm A serial communication parameters string, in the form
 532  *              of \<speed\>/\<data bits\>\<parity\>\<stopbits\>, for example
 533  *              "9600/8n1" or "600/7o2". This is an optional parameter;
 534  *              it may be filled in later. Can be NULL.
 535  *
 536  * @return A pointer to a newly initialized struct sr_serial_dev_inst,
 537  *         or NULL on error.
 538  *
 539  * @private
 540  */
 541 SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
 542                 const char *serialcomm)
 543 {
 544         struct sr_serial_dev_inst *serial;
 545
 546         serial = g_malloc0(sizeof(struct sr_serial_dev_inst));
 547         serial->port = g_strdup(port);
 548         if (serialcomm)
 549                 serial->serialcomm = g_strdup(serialcomm);
 550
 551         return serial;
 552 }
 553
 554 /**
 555  * Free struct sr_serial_dev_inst * allocated by sr_serial_dev_inst().
 556  *
 557  * @param serial The struct sr_serial_dev_inst * to free. If NULL, this
 558  *               function will do nothing.
 559  *
 560  * @private
 561  */
 562 SR_PRIV void sr_serial_dev_inst_free(struct sr_serial_dev_inst *serial)
 563 {
 564         if (!serial)
 565                 return;
 566
 567         g_free(serial->port);
 568         g_free(serial->serialcomm);
 569         g_free(serial);
 570 }
 571 #endif
 572
 573 /** @private */
 574 SR_PRIV struct sr_usbtmc_dev_inst *sr_usbtmc_dev_inst_new(const char *device)
 575 {
 576         struct sr_usbtmc_dev_inst *usbtmc;
 577
 578         usbtmc = g_malloc0(sizeof(struct sr_usbtmc_dev_inst));
 579         usbtmc->device = g_strdup(device);
 580         usbtmc->fd = -1;
 581
 582         return usbtmc;
 583 }
 584
 585 /** @private */
 586 SR_PRIV void sr_usbtmc_dev_inst_free(struct sr_usbtmc_dev_inst *usbtmc)
 587 {
 588         if (!usbtmc)
 589                 return;
 590
 591         g_free(usbtmc->device);
 592         g_free(usbtmc);
 593 }
 594
 595 /**
 596  * Get the list of devices/instances of the specified driver.
 597  *
 598  * @param driver The driver to use. Must not be NULL.
 599  *
 600  * @return The list of devices/instances of this driver, or NULL upon errors
 601  *         or if the list is empty.
 602  *
 603  * @since 0.2.0
 604  */
 605 SR_API GSList *sr_dev_list(const struct sr_dev_driver *driver)
 606 {
 607         if (driver && driver->dev_list)
 608                 return driver->dev_list(driver);
 609         else
 610                 return NULL;
 611 }
 612
 613 /**
 614  * Clear the list of device instances a driver knows about.
 615  *
 616  * @param driver The driver to use. This must be a pointer to one of
 617  *               the entries returned by sr_driver_list(). Must not be NULL.
 618  *
 619  * @retval SR_OK Success.
 620  * @retval SR_ERR_ARG Invalid driver.
 621  *
 622  * @since 0.2.0
 623  */
 624 SR_API int sr_dev_clear(const struct sr_dev_driver *driver)
 625 {
 626         if (!driver) {
 627                 sr_err("Invalid driver.");
 628                 return SR_ERR_ARG;
 629         }
 630
 631         if (!driver->context) {
 632                 /*
 633                  * Driver was never initialized, nothing to do.
 634                  *
 635                  * No log message since this usually gets called for all
 636                  * drivers, whether they were initialized or not.
 637                  */
 638                 return SR_OK;
 639         }
 640
 641         /* No log message here, too verbose and not very useful. */
 642
 643         return driver->dev_clear(driver);
 644 }
 645
 646 /**
 647  * Open the specified device instance.
 648  *
 649  * If the device instance is already open (sdi->status == SR_ST_ACTIVE),
 650  * SR_ERR will be returned and no re-opening of the device will be attempted.
 651  *
 652  * If opening was successful, sdi->status is set to SR_ST_ACTIVE, otherwise
 653  * it will be left unchanged.
 654  *
 655  * @param sdi Device instance to use. Must not be NULL.
 656  *
 657  * @retval SR_OK Success.
 658  * @retval SR_ERR_ARG Invalid arguments.
 659  * @retval SR_ERR Device instance was already active, or other error.
 660  *
 661  * @since 0.2.0
 662  */
 663 SR_API int sr_dev_open(struct sr_dev_inst *sdi)
 664 {
 665         int ret;
 666
 667         if (!sdi || !sdi->driver || !sdi->driver->dev_open)
 668                 return SR_ERR_ARG;
 669
 670         if (sdi->status == SR_ST_ACTIVE) {
 671                 sr_err("%s: Device instance already active, can't re-open.",
 672                         sdi->driver->name);
 673                 return SR_ERR;
 674         }
 675
 676         sr_dbg("%s: Opening device instance.", sdi->driver->name);
 677
 678         ret = sdi->driver->dev_open(sdi);
 679
 680         if (ret == SR_OK)
 681                 sdi->status = SR_ST_ACTIVE;
 682
 683         return ret;
 684 }
 685
 686 /**
 687  * Close the specified device instance.
 688  *
 689  * If the device instance is not open (sdi->status != SR_ST_ACTIVE),
 690  * SR_ERR_DEV_CLOSED will be returned and no closing will be attempted.
 691  *
 692  * Note: sdi->status will be set to SR_ST_INACTIVE, regardless of whether
 693  * there are any errors during closing of the device instance (any errors
 694  * will be reported via error code and log message, though).
 695  *
 696  * @param sdi Device instance to use. Must not be NULL.
 697  *
 698  * @retval SR_OK Success.
 699  * @retval SR_ERR_ARG Invalid arguments.
 700  * @retval SR_ERR_DEV_CLOSED Device instance was not active.
 701  * @retval SR_ERR Other error.
 702  *
 703  * @since 0.2.0
 704  */
 705 SR_API int sr_dev_close(struct sr_dev_inst *sdi)
 706 {
 707         if (!sdi || !sdi->driver || !sdi->driver->dev_close)
 708                 return SR_ERR_ARG;
 709
 710         if (sdi->status != SR_ST_ACTIVE) {
 711                 sr_err("%s: Device instance not active, can't close.",
 712                         sdi->driver->name);
 713                 return SR_ERR_DEV_CLOSED;
 714         }
 715
 716         sdi->status = SR_ST_INACTIVE;
 717
 718         sr_dbg("%s: Closing device instance.", sdi->driver->name);
 719
 720         return sdi->driver->dev_close(sdi);
 721 }
 722
 723 /**
 724  * Queries a device instances' driver.
 725  *
 726  * @param sdi Device instance to use. Must not be NULL.
 727  *
 728  * @return The driver instance or NULL on error.
 729  */
 730 SR_API struct sr_dev_driver *sr_dev_inst_driver_get(const struct sr_dev_inst *sdi)
 731 {
 732         if (!sdi || !sdi->driver)
 733                 return NULL;
 734
 735         return sdi->driver;
 736 }
 737
 738 /**
 739  * Queries a device instances' vendor.
 740  *
 741  * @param sdi Device instance to use. Must not be NULL.
 742  *
 743  * @return The vendor string or NULL.
 744  */
 745 SR_API const char *sr_dev_inst_vendor_get(const struct sr_dev_inst *sdi)
 746 {
 747         if (!sdi)
 748                 return NULL;
 749
 750         return sdi->vendor;
 751 }
 752
 753 /**
 754  * Queries a device instances' model.
 755  *
 756  * @param sdi Device instance to use. Must not be NULL.
 757  *
 758  * @return The model string or NULL.
 759  */
 760 SR_API const char *sr_dev_inst_model_get(const struct sr_dev_inst *sdi)
 761 {
 762         if (!sdi)
 763                 return NULL;
 764
 765         return sdi->model;
 766 }
 767
 768 /**
 769  * Queries a device instances' version.
 770  *
 771  * @param sdi Device instance to use. Must not be NULL.
 772  *
 773  * @return The version string or NULL.
 774  */
 775 SR_API const char *sr_dev_inst_version_get(const struct sr_dev_inst *sdi)
 776 {
 777         if (!sdi)
 778                 return NULL;
 779
 780         return sdi->version;
 781 }
 782
 783 /**
 784  * Queries a device instances' serial number.
 785  *
 786  * @param sdi Device instance to use. Must not be NULL.
 787  *
 788  * @return The serial number string or NULL.
 789  */
 790 SR_API const char *sr_dev_inst_sernum_get(const struct sr_dev_inst *sdi)
 791 {
 792         if (!sdi)
 793                 return NULL;
 794
 795         return sdi->serial_num;
 796 }
 797
 798 /**
 799  * Queries a device instances' connection identifier.
 800  *
 801  * @param sdi Device instance to use. Must not be NULL.
 802  *
 803  * @return A copy of the connection ID string or NULL. The caller is responsible
 804  *         for g_free()ing the string when it is no longer needed.
 805  */
 806 SR_API const char *sr_dev_inst_connid_get(const struct sr_dev_inst *sdi)
 807 {
 808 #ifdef HAVE_LIBUSB_1_0
 809         struct drv_context *drvc;
 810         int cnt, i, a, b;
 811         char connection_id[64];
 812         struct sr_usb_dev_inst *usb;
 813         struct libusb_device **devlist;
 814 #endif
 815
 816         if (!sdi)
 817                 return NULL;
 818
 819 #ifdef HAVE_LIBSERIALPORT
 820         struct sr_serial_dev_inst *serial;
 821
 822         if ((!sdi->connection_id) && (sdi->inst_type == SR_INST_SERIAL)) {
 823                 /* connection_id isn't populated, let's do that here. */
 824
 825                 serial = sdi->conn;
 826                 ((struct sr_dev_inst *)sdi)->connection_id = g_strdup(serial->port);
 827         }
 828 #endif
 829
 830 #ifdef HAVE_LIBUSB_1_0
 831         if ((!sdi->connection_id) && (sdi->inst_type == SR_INST_USB)) {
 832                 /* connection_id isn't populated, let's do that here. */
 833
 834                 drvc = sdi->driver->context;
 835                 usb = sdi->conn;
 836
 837                 if ((cnt = libusb_get_device_list(drvc->sr_ctx->libusb_ctx, &devlist)) < 0) {
 838                         sr_err("Failed to retrieve device list: %s.",
 839                                libusb_error_name(cnt));
 840                         return NULL;
 841                 }
 842
 843                 for (i = 0; i < cnt; i++) {
 844                         /* Find the USB device by the logical address we know. */
 845                         b = libusb_get_bus_number(devlist[i]);
 846                         a = libusb_get_device_address(devlist[i]);
 847                         if (b != usb->bus || a != usb->address)
 848                                 continue;
 849
 850                         if (usb_get_port_path(devlist[i], connection_id, sizeof(connection_id)) < 0)
 851                                 continue;
 852
 853                         ((struct sr_dev_inst *)sdi)->connection_id = g_strdup(connection_id);
 854                         break;
 855                 }
 856
 857                 libusb_free_device_list(devlist, 1);
 858         }
 859 #endif
 860
 861         return sdi->connection_id;
 862 }
 863
 864 /**
 865  * Queries a device instances' channel list.
 866  *
 867  * @param sdi Device instance to use. Must not be NULL.
 868  *
 869  * @return The GSList of channels or NULL.
 870  */
 871 SR_API GSList *sr_dev_inst_channels_get(const struct sr_dev_inst *sdi)
 872 {
 873         if (!sdi)
 874                 return NULL;
 875
 876         return sdi->channels;
 877 }
 878
 879 /**
 880  * Queries a device instances' channel groups list.
 881  *
 882  * @param sdi Device instance to use. Must not be NULL.
 883  *
 884  * @return The GSList of channel groups or NULL.
 885  */
 886 SR_API GSList *sr_dev_inst_channel_groups_get(const struct sr_dev_inst *sdi)
 887 {
 888         if (!sdi)
 889                 return NULL;
 890
 891         return sdi->channel_groups;
 892 }
 893
 894 /** @} */