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