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