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 /* 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  */
  85 SR_API int sr_dev_probe_name_set(const struct sr_dev_inst *sdi,
  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,
 212                                 &gvar, NULL, NULL) != SR_OK)
 213                 return FALSE;
 214
 215         ret = FALSE;
 216         devopts = g_variant_get_fixed_array(gvar, &num_opts, sizeof(int32_t));
 217         for (i = 0; i < num_opts; i++) {
 218                 if (devopts[i] == key) {
 219                         ret = TRUE;
 220                         break;
 221                 }
 222         }
 223         g_variant_unref(gvar);
 224
 225         return ret;
 226 }
 227
 228 /** @private */
 229 SR_PRIV struct sr_dev_inst *sr_dev_inst_new(int index, int status,
 230                 const char *vendor, const char *model, const char *version)
 231 {
 232         struct sr_dev_inst *sdi;
 233
 234         if (!(sdi = g_try_malloc(sizeof(struct sr_dev_inst)))) {
 235                 sr_err("Device instance malloc failed.");
 236                 return NULL;
 237         }
 238
 239         sdi->driver = NULL;
 240         sdi->index = index;
 241         sdi->status = status;
 242         sdi->inst_type = -1;
 243         sdi->vendor = vendor ? g_strdup(vendor) : NULL;
 244         sdi->model = model ? g_strdup(model) : NULL;
 245         sdi->version = version ? g_strdup(version) : NULL;
 246         sdi->probes = NULL;
 247         sdi->probe_groups = NULL;
 248         sdi->conn = NULL;
 249         sdi->priv = NULL;
 250
 251         return sdi;
 252 }
 253
 254 /** @private */
 255 SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi)
 256 {
 257         struct sr_probe *probe;
 258         GSList *l;
 259
 260         for (l = sdi->probes; l; l = l->next) {
 261                 probe = l->data;
 262                 g_free(probe->name);
 263                 g_free(probe->trigger);
 264                 g_free(probe);
 265         }
 266         g_slist_free(sdi->probes);
 267
 268         if (sdi->probe_groups)
 269                 g_slist_free(sdi->probe_groups);
 270
 271         g_free(sdi->vendor);
 272         g_free(sdi->model);
 273         g_free(sdi->version);
 274         g_free(sdi);
 275 }
 276
 277 #ifdef HAVE_LIBUSB_1_0
 278
 279 /** @private */
 280 SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus,
 281                         uint8_t address, struct libusb_device_handle *hdl)
 282 {
 283         struct sr_usb_dev_inst *udi;
 284
 285         if (!(udi = g_try_malloc(sizeof(struct sr_usb_dev_inst)))) {
 286                 sr_err("USB device instance malloc failed.");
 287                 return NULL;
 288         }
 289
 290         udi->bus = bus;
 291         udi->address = address;
 292         udi->devhdl = hdl;
 293
 294         return udi;
 295 }
 296
 297 /** @private */
 298 SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
 299 {
 300         g_free(usb);
 301 }
 302
 303 #endif
 304
 305 #ifdef HAVE_LIBSERIALPORT
 306
 307 /**
 308  * @private
 309  *
 310  * Both parameters are copied to newly allocated strings, and freed
 311  * automatically by sr_serial_dev_inst_free().
 312  *
 313  * @param pathname OS-specific serial port specification. Examples:
 314  *                 "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1".
 315  * @param serialcomm A serial communication parameters string, in the form
 316  *                   of <speed>/<data bits><parity><stopbits>, for example
 317  *                   "9600/8n1" or "600/7o2". This is an optional parameter;
 318  *                   it may be filled in later.
 319  *
 320  * @return A pointer to a newly initialized struct sr_serial_dev_inst,
 321  *         or NULL on error.
 322  */
 323 SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
 324                 const char *serialcomm)
 325 {
 326         struct sr_serial_dev_inst *serial;
 327
 328         if (!port) {
 329                 sr_err("Serial port required.");
 330                 return NULL;
 331         }
 332
 333         if (!(serial = g_try_malloc0(sizeof(struct sr_serial_dev_inst)))) {
 334                 sr_err("Serial device instance malloc failed.");
 335                 return NULL;
 336         }
 337
 338         serial->port = g_strdup(port);
 339         if (serialcomm)
 340                 serial->serialcomm = g_strdup(serialcomm);
 341         serial->fd = -1;
 342
 343         return serial;
 344 }
 345
 346 /** @private */
 347 SR_PRIV void sr_serial_dev_inst_free(struct sr_serial_dev_inst *serial)
 348 {
 349         g_free(serial->port);
 350         g_free(serial->serialcomm);
 351         g_free(serial);
 352 }
 353 #endif
 354
 355 SR_PRIV struct sr_usbtmc_dev_inst *sr_usbtmc_dev_inst_new(const char *device)
 356 {
 357         struct sr_usbtmc_dev_inst *usbtmc;
 358
 359         if (!device) {
 360                 sr_err("Device name required.");
 361                 return NULL;
 362         }
 363
 364         if (!(usbtmc = g_try_malloc0(sizeof(struct sr_usbtmc_dev_inst)))) {
 365                 sr_err("USBTMC device instance malloc failed.");
 366                 return NULL;
 367         }
 368
 369         usbtmc->device = g_strdup(device);
 370         usbtmc->fd = -1;
 371
 372         return usbtmc;
 373 }
 374
 375 SR_PRIV void sr_usbtmc_dev_inst_free(struct sr_usbtmc_dev_inst *usbtmc)
 376 {
 377         g_free(usbtmc->device);
 378         g_free(usbtmc);
 379 }
 380
 381 /**
 382  * Get the list of devices/instances of the specified driver.
 383  *
 384  * @param driver The driver to use. Must not be NULL.
 385  *
 386  * @return The list of devices/instances of this driver, or NULL upon errors
 387  *         or if the list is empty.
 388  *
 389  * @since 0.2.0
 390  */
 391 SR_API GSList *sr_dev_list(const struct sr_dev_driver *driver)
 392 {
 393         if (driver && driver->dev_list)
 394                 return driver->dev_list();
 395         else
 396                 return NULL;
 397 }
 398
 399 /**
 400  * Clear all devices/instances of the specified driver.
 401  *
 402  * @param driver The driver to use. Must not be NULL.
 403  *
 404  * @return SR_OK upon success, a negative error code upon errors.
 405  *
 406  * @since 0.2.0
 407  */
 408 SR_API int sr_dev_clear(const struct sr_dev_driver *driver)
 409 {
 410         if (driver && driver->dev_clear)
 411                 return driver->dev_clear();
 412         else
 413                 return SR_OK;
 414 }
 415
 416 /**
 417  * Open the specified device.
 418  *
 419  * @param sdi Device instance to use. Must not be NULL.
 420  *
 421  * @return SR_OK upon success, a negative error code upon errors.
 422  *
 423  * @since 0.2.0
 424  */
 425 SR_API int sr_dev_open(struct sr_dev_inst *sdi)
 426 {
 427         int ret;
 428
 429         if (!sdi || !sdi->driver || !sdi->driver->dev_open)
 430                 return SR_ERR;
 431
 432         ret = sdi->driver->dev_open(sdi);
 433
 434         return ret;
 435 }
 436
 437 /**
 438  * Close the specified device.
 439  *
 440  * @param sdi Device instance to use. Must not be NULL.
 441  *
 442  * @return SR_OK upon success, a negative error code upon errors.
 443  *
 444  * @since 0.2.0
 445  */
 446 SR_API int sr_dev_close(struct sr_dev_inst *sdi)
 447 {
 448         int ret;
 449
 450         if (!sdi || !sdi->driver || !sdi->driver->dev_close)
 451                 return SR_ERR;
 452
 453         ret = sdi->driver->dev_close(sdi);
 454
 455         return ret;
 456 }
 457
 458 /** @} */