libsigrok  0.2.2
sigrok hardware access and backend library
 All Data Structures Files Functions Variables Typedefs Enumerator Macros Groups Pages
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 <stdio.h>
21 #include <glib.h>
22 #include "config.h" /* Needed for HAVE_LIBUSB_1_0 and others. */
23 #include "libsigrok.h"
24 #include "libsigrok-internal.h"
25 
26 /* Message logging helpers with subsystem-specific prefix string. */
27 #define LOG_PREFIX "device: "
28 #define sr_log(l, s, args...) sr_log(l, LOG_PREFIX s, ## args)
29 #define sr_spew(s, args...) sr_spew(LOG_PREFIX s, ## args)
30 #define sr_dbg(s, args...) sr_dbg(LOG_PREFIX s, ## args)
31 #define sr_info(s, args...) sr_info(LOG_PREFIX s, ## args)
32 #define sr_warn(s, args...) sr_warn(LOG_PREFIX s, ## args)
33 #define sr_err(s, args...) sr_err(LOG_PREFIX s, ## args)
34 
35 /**
36  * @file
37  *
38  * Device handling in libsigrok.
39  */
40 
41 /**
42  * @defgroup grp_devices Devices
43  *
44  * Device handling in libsigrok.
45  *
46  * @{
47  */
48 
49 /** @private */
50 SR_PRIV struct sr_probe *sr_probe_new(int index, int type,
51  gboolean enabled, const char *name)
52 {
53  struct sr_probe *probe;
54 
55  if (!(probe = g_try_malloc0(sizeof(struct sr_probe)))) {
56  sr_err("Probe malloc failed.");
57  return NULL;
58  }
59 
60  probe->index = index;
61  probe->type = type;
62  probe->enabled = enabled;
63  if (name)
64  probe->name = g_strdup(name);
65 
66  return probe;
67 }
68 
69 /**
70  * Set the name of the specified probe in the specified device.
71  *
72  * If the probe already has a different name assigned to it, it will be
73  * removed, and the new name will be saved instead.
74  *
75  * @param sdi The device instance the probe is connected to.
76  * @param probenum The number of the probe whose name to set.
77  * Note that the probe numbers start at 0.
78  * @param name The new name that the specified probe should get. A copy
79  * of the string is made.
80  *
81  * @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
82  *
83  * @since 0.2.0
84  */
86  int probenum, const char *name)
87 {
88  GSList *l;
89  struct sr_probe *probe;
90  int ret;
91 
92  if (!sdi) {
93  sr_err("%s: sdi was NULL", __func__);
94  return SR_ERR_ARG;
95  }
96 
97  ret = SR_ERR_ARG;
98  for (l = sdi->probes; l; l = l->next) {
99  probe = l->data;
100  if (probe->index == probenum) {
101  g_free(probe->name);
102  probe->name = g_strdup(name);
103  ret = SR_OK;
104  break;
105  }
106  }
107 
108  return ret;
109 }
110 
111 /**
112  * Enable or disable a probe on the specified device.
113  *
114  * @param sdi The device instance the probe is connected to.
115  * @param probenum The probe number, starting from 0.
116  * @param state TRUE to enable the probe, FALSE to disable.
117  *
118  * @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
119  *
120  * @since 0.2.0
121  */
122 SR_API int sr_dev_probe_enable(const struct sr_dev_inst *sdi, int probenum,
123  gboolean state)
124 {
125  GSList *l;
126  struct sr_probe *probe;
127  int ret;
128 
129  if (!sdi)
130  return SR_ERR_ARG;
131 
132  ret = SR_ERR_ARG;
133  for (l = sdi->probes; l; l = l->next) {
134  probe = l->data;
135  if (probe->index == probenum) {
136  probe->enabled = state;
137  ret = SR_OK;
138  break;
139  }
140  }
141 
142  return ret;
143 }
144 
145 /**
146  * Add a trigger to the specified device (and the specified probe).
147  *
148  * If the specified probe of this device already has a trigger, it will
149  * be silently replaced.
150  *
151  * @param sdi Must not be NULL.
152  * @param probenum The probe number, starting from 0.
153  * @param trigger Trigger string, in the format used by sigrok-cli
154  *
155  * @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
156  *
157  * @since 0.2.0
158  */
159 SR_API int sr_dev_trigger_set(const struct sr_dev_inst *sdi, int probenum,
160  const char *trigger)
161 {
162  GSList *l;
163  struct sr_probe *probe;
164  int ret;
165 
166  if (!sdi)
167  return SR_ERR_ARG;
168 
169  ret = SR_ERR_ARG;
170  for (l = sdi->probes; l; l = l->next) {
171  probe = l->data;
172  if (probe->index == probenum) {
173  /* If the probe already has a trigger, kill it first. */
174  g_free(probe->trigger);
175  probe->trigger = g_strdup(trigger);
176  ret = SR_OK;
177  break;
178  }
179  }
180 
181  return ret;
182 }
183 
184 /**
185  * Determine whether the specified device instance has the specified
186  * capability.
187  *
188  * @param sdi Pointer to the device instance to be checked. Must not be NULL.
189  * If the device's 'driver' field is NULL (virtual device), this
190  * function will always return FALSE (virtual devices don't have
191  * a hardware capabilities list).
192  * @param key The option that should be checked for support on the
193  * specified device.
194  *
195  * @return TRUE if the device has the specified option, FALSE otherwise.
196  * FALSE is also returned on invalid input parameters or other
197  * error conditions.
198  *
199  * @since 0.2.0
200  */
201 SR_API gboolean sr_dev_has_option(const struct sr_dev_inst *sdi, int key)
202 {
203  GVariant *gvar;
204  const int *devopts;
205  gsize num_opts, i;
206  int ret;
207 
208  if (!sdi || !sdi->driver || !sdi->driver->config_list)
209  return FALSE;
210 
211  if (sdi->driver->config_list(SR_CONF_DEVICE_OPTIONS, &gvar, NULL) != SR_OK)
212  return FALSE;
213 
214  ret = FALSE;
215  devopts = g_variant_get_fixed_array(gvar, &num_opts, sizeof(int32_t));
216  for (i = 0; i < num_opts; i++) {
217  if (devopts[i] == key) {
218  ret = TRUE;
219  break;
220  }
221  }
222  g_variant_unref(gvar);
223 
224  return ret;
225 }
226 
227 /** @private */
228 SR_PRIV struct sr_dev_inst *sr_dev_inst_new(int index, int status,
229  const char *vendor, const char *model, const char *version)
230 {
231  struct sr_dev_inst *sdi;
232 
233  if (!(sdi = g_try_malloc(sizeof(struct sr_dev_inst)))) {
234  sr_err("Device instance malloc failed.");
235  return NULL;
236  }
237 
238  sdi->driver = NULL;
239  sdi->index = index;
240  sdi->status = status;
241  sdi->inst_type = -1;
242  sdi->vendor = vendor ? g_strdup(vendor) : NULL;
243  sdi->model = model ? g_strdup(model) : NULL;
244  sdi->version = version ? g_strdup(version) : NULL;
245  sdi->probes = NULL;
246  sdi->conn = NULL;
247  sdi->priv = NULL;
248 
249  return sdi;
250 }
251 
252 /** @private */
253 SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi)
254 {
255  struct sr_probe *probe;
256  GSList *l;
257 
258  for (l = sdi->probes; l; l = l->next) {
259  probe = l->data;
260  g_free(probe->name);
261  g_free(probe->trigger);
262  g_free(probe);
263  }
264  g_slist_free(sdi->probes);
265 
266  g_free(sdi->vendor);
267  g_free(sdi->model);
268  g_free(sdi->version);
269  g_free(sdi);
270 }
271 
272 #ifdef HAVE_LIBUSB_1_0
273 
274 /** @private */
275 SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus,
276  uint8_t address, struct libusb_device_handle *hdl)
277 {
278  struct sr_usb_dev_inst *udi;
279 
280  if (!(udi = g_try_malloc(sizeof(struct sr_usb_dev_inst)))) {
281  sr_err("USB device instance malloc failed.");
282  return NULL;
283  }
284 
285  udi->bus = bus;
286  udi->address = address;
287  udi->devhdl = hdl;
288 
289  return udi;
290 }
291 
292 /** @private */
293 SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
294 {
295  g_free(usb);
296 }
297 
298 #endif
299 
300 /**
301  * @private
302  *
303  * Both parameters are copied to newly allocated strings, and freed
304  * automatically by sr_serial_dev_inst_free().
305  *
306  * @param pathname OS-specific serial port specification. Examples:
307  * "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1".
308  * @param serialcomm A serial communication parameters string, in the form
309  * of <speed>/<data bits><parity><stopbits>, for example
310  * "9600/8n1" or "600/7o2". This is an optional parameter;
311  * it may be filled in later.
312  *
313  * @return A pointer to a newly initialized struct sr_serial_dev_inst,
314  * or NULL on error.
315  */
316 SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
317  const char *serialcomm)
318 {
319  struct sr_serial_dev_inst *serial;
320 
321  if (!port) {
322  sr_err("Serial port required.");
323  return NULL;
324  }
325 
326  if (!(serial = g_try_malloc0(sizeof(struct sr_serial_dev_inst)))) {
327  sr_err("Serial device instance malloc failed.");
328  return NULL;
329  }
330 
331  serial->port = g_strdup(port);
332  if (serialcomm)
333  serial->serialcomm = g_strdup(serialcomm);
334  serial->fd = -1;
335 
336  return serial;
337 }
338 
339 /** @private */
340 SR_PRIV void sr_serial_dev_inst_free(struct sr_serial_dev_inst *serial)
341 {
342  g_free(serial->port);
343  g_free(serial->serialcomm);
344  g_free(serial);
345 }
346 
347 /**
348  * Get the list of devices/instances of the specified driver.
349  *
350  * @param driver The driver to use. Must not be NULL.
351  *
352  * @return The list of devices/instances of this driver, or NULL upon errors
353  * or if the list is empty.
354  *
355  * @since 0.2.0
356  */
357 SR_API GSList *sr_dev_list(const struct sr_dev_driver *driver)
358 {
359  if (driver && driver->dev_list)
360  return driver->dev_list();
361  else
362  return NULL;
363 }
364 
365 /**
366  * Clear all devices/instances of the specified driver.
367  *
368  * @param driver The driver to use. Must not be NULL.
369  *
370  * @return SR_OK upon success, a negative error code upon errors.
371  *
372  * @since 0.2.0
373  */
374 SR_API int sr_dev_clear(const struct sr_dev_driver *driver)
375 {
376  if (driver && driver->dev_clear)
377  return driver->dev_clear();
378  else
379  return SR_OK;
380 }
381 
382 /**
383  * Open the specified device.
384  *
385  * @param sdi Device instance to use. Must not be NULL.
386  *
387  * @return SR_OK upon success, a negative error code upon errors.
388  *
389  * @since 0.2.0
390  */
392 {
393  int ret;
394 
395  if (!sdi || !sdi->driver || !sdi->driver->dev_open)
396  return SR_ERR;
397 
398  ret = sdi->driver->dev_open(sdi);
399 
400  return ret;
401 }
402 
403 /**
404  * Close the specified device.
405  *
406  * @param sdi Device instance to use. Must not be NULL.
407  *
408  * @return SR_OK upon success, a negative error code upon errors.
409  *
410  * @since 0.2.0
411  */
413 {
414  int ret;
415 
416  if (!sdi || !sdi->driver || !sdi->driver->dev_close)
417  return SR_ERR;
418 
419  ret = sdi->driver->dev_close(sdi);
420 
421  return ret;
422 }
423 
424 /** @} */
int sr_dev_probe_name_set(const struct sr_dev_inst *sdi, int probenum, const char *name)
Set the name of the specified probe in the specified device.
Definition: device.c:85
Device options for a particular device.
Definition: libsigrok.h:710
int inst_type
Definition: libsigrok.h:775
int(* config_list)(int info_id, GVariant **data, const struct sr_dev_inst *sdi)
Definition: libsigrok.h:820
int(* dev_open)(struct sr_dev_inst *sdi)
Definition: libsigrok.h:824
char * model
Definition: libsigrok.h:777
GSList * sr_dev_list(const struct sr_dev_driver *driver)
Get the list of devices/instances of the specified driver.
Definition: device.c:357
The public libsigrok header file to be used by frontends.
gboolean enabled
Definition: libsigrok.h:547
Generic/unspecified error.
Definition: libsigrok.h:68
int sr_dev_probe_enable(const struct sr_dev_inst *sdi, int probenum, gboolean state)
Enable or disable a probe on the specified device.
Definition: device.c:122
int type
Definition: libsigrok.h:546
void * priv
Definition: libsigrok.h:781
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:201
struct sr_dev_driver * driver
Definition: libsigrok.h:772
No error.
Definition: libsigrok.h:67
int(* dev_clear)(void)
Definition: libsigrok.h:815
char * trigger
Definition: libsigrok.h:549
char * vendor
Definition: libsigrok.h:776
int sr_dev_open(struct sr_dev_inst *sdi)
Open the specified device.
Definition: device.c:391
#define SR_PRIV
Definition: libsigrok.h:128
int sr_dev_close(struct sr_dev_inst *sdi)
Close the specified device.
Definition: device.c:412
int(* dev_close)(struct sr_dev_inst *sdi)
Definition: libsigrok.h:825
char * name
Definition: libsigrok.h:548
int index
Definition: libsigrok.h:545
GSList *(* dev_list)(void)
Definition: libsigrok.h:814
int sr_dev_clear(const struct sr_dev_driver *driver)
Clear all devices/instances of the specified driver.
Definition: device.c:374
char * version
Definition: libsigrok.h:778
int sr_dev_trigger_set(const struct sr_dev_inst *sdi, int probenum, const char *trigger)
Add a trigger to the specified device (and the specified probe).
Definition: device.c:159
#define sr_err(s, args...)
Definition: device.c:33
Function argument error.
Definition: libsigrok.h:70
GSList * probes
Definition: libsigrok.h:779
void * conn
Definition: libsigrok.h:780
#define SR_API
Definition: libsigrok.h:121