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