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