libsigrok  0.2.0
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.1.0 (but the API changed in 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.1.0 (but the API changed in 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.1.0 (but the API changed in 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);
262  }
263 
264  g_free(sdi->priv);
265  g_free(sdi->vendor);
266  g_free(sdi->model);
267  g_free(sdi->version);
268  g_free(sdi);
269 }
270 
271 #ifdef HAVE_LIBUSB_1_0
272 
273 /** @private */
274 SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus,
275  uint8_t address, struct libusb_device_handle *hdl)
276 {
277  struct sr_usb_dev_inst *udi;
278 
279  if (!(udi = g_try_malloc(sizeof(struct sr_usb_dev_inst)))) {
280  sr_err("USB device instance malloc failed.");
281  return NULL;
282  }
283 
284  udi->bus = bus;
285  udi->address = address;
286  udi->devhdl = hdl;
287 
288  return udi;
289 }
290 
291 /** @private */
292 SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
293 {
294  (void)usb;
295 
296  /* Nothing to do for this device instance type. */
297 }
298 
299 #endif
300 
301 /**
302  * @private
303  *
304  * Both parameters are copied to newly allocated strings, and freed
305  * automatically by sr_serial_dev_inst_free().
306  *
307  * @param pathname OS-specific serial port specification. Examples:
308  * "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1".
309  * @param serialcomm A serial communication parameters string, in the form
310  * of <speed>/<data bits><parity><stopbits>, for example
311  * "9600/8n1" or "600/7o2". This is an optional parameter;
312  * it may be filled in later.
313  *
314  * @return A pointer to a newly initialized struct sr_serial_dev_inst,
315  * or NULL on error.
316  */
317 SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
318  const char *serialcomm)
319 {
320  struct sr_serial_dev_inst *serial;
321 
322  if (!port) {
323  sr_err("Serial port required.");
324  return NULL;
325  }
326 
327  if (!(serial = g_try_malloc0(sizeof(struct sr_serial_dev_inst)))) {
328  sr_err("Serial device instance malloc failed.");
329  return NULL;
330  }
331 
332  serial->port = g_strdup(port);
333  if (serialcomm)
334  serial->serialcomm = g_strdup(serialcomm);
335  serial->fd = -1;
336 
337  return serial;
338 }
339 
340 /** @private */
341 SR_PRIV void sr_serial_dev_inst_free(struct sr_serial_dev_inst *serial)
342 {
343  g_free(serial->port);
344  g_free(serial->serialcomm);
345  g_free(serial);
346 }
347 
348 SR_API GSList *sr_dev_list(const struct sr_dev_driver *driver)
349 {
350  if (driver && driver->dev_list)
351  return driver->dev_list();
352  else
353  return NULL;
354 }
355 
356 SR_API int sr_dev_clear(const struct sr_dev_driver *driver)
357 {
358  if (driver && driver->dev_clear)
359  return driver->dev_clear();
360  else
361  return SR_OK;
362 }
363 
365 {
366  int ret;
367 
368  if (!sdi || !sdi->driver || !sdi->driver->dev_open)
369  return SR_ERR;
370 
371  ret = sdi->driver->dev_open(sdi);
372 
373  return ret;
374 }
375 
377 {
378  int ret;
379 
380  if (!sdi || !sdi->driver || !sdi->driver->dev_close)
381  return SR_ERR;
382 
383  ret = sdi->driver->dev_close(sdi);
384 
385  return ret;
386 }
387 
388 /** @} */