device.c

   1 /*
   2  * This file is part of the sigrok project.
   3  *
   4  * Copyright (C) 2010 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 <sigrok.h>
  23 #include <sigrok-internal.h>
  24
  25 extern struct sr_global *global;
  26
  27 GSList *devices = NULL;
  28
  29 /**
  30  * Scan the system for attached logic analyzers / devices.
  31  *
  32  * This will try to autodetect all supported logic analyzer devices:
  33  *
  34  *  - Those attached via USB (can be reliably detected via USB VID/PID).
  35  *
  36  *  - Those using a (real or virtual) serial port (detected by sending
  37  *    device-specific commands to all OS-specific serial port devices such
  38  *    as /dev/ttyS*, /dev/ttyUSB*, /dev/ttyACM*, and others).
  39  *    The autodetection for this kind of devices can potentially be unreliable.
  40  *
  41  *    Also, sending various bytes/commands to (all!) devices which happen to
  42  *    be attached to the system via a (real or virtual) serial port can be
  43  *    problematic. There is no way for libsigrok to know how unknown devices
  44  *    react to the bytes libsigrok sends. Potentially they could lead to the
  45  *    device getting into invalid/error states, losing/overwriting data, or...
  46  *
  47  * In addition to the detection, the devices that are found are also
  48  * initialized automatically. On some devices, this involves a firmware upload,
  49  * or other such measures.
  50  *
  51  * The order in which the system is scanned for devices is not specified. The
  52  * caller should not assume or rely on any specific order.
  53  *
  54  * After the system has been scanned for devices, the list of detected (and
  55  * supported) devices can be acquired via sr_device_list().
  56  *
  57  * TODO: Should return int.
  58  * TODO: Error checks?
  59  * TODO: Option to only scan for specific devices or device classes.
  60  */
  61 void sr_device_scan(void)
  62 {
  63         GSList *plugins, *l;
  64         struct sr_device_plugin *plugin;
  65
  66         if (!(plugins = sr_list_hwplugins())) {
  67                 sr_err("dev: %s: no supported devices/hwplugins", __func__);
  68                 return; /* TODO? */
  69         }
  70
  71         /*
  72          * Initialize all plugins first. Since the init() call may involve
  73          * a firmware upload and associated delay, we may as well get all
  74          * of these out of the way first.
  75          */
  76         for (l = plugins; l; l = l->next) {
  77                 plugin = l->data;
  78                 /* TODO: Handle 'plugin' being NULL. */
  79                 sr_init_hwplugins(plugin);
  80         }
  81 }
  82
  83 /**
  84  * Return the list of logic analyzer devices libsigrok has detected.
  85  *
  86  * If the libsigrok-internal device list is empty, a scan for attached
  87  * devices -- via a call to sr_device_scan() -- is performed first.
  88  *
  89  * TODO: Error handling?
  90  *
  91  * @return The list (GSList) of detected devices, or NULL if none were found.
  92  */
  93 GSList *sr_device_list(void)
  94 {
  95         if (!devices)
  96                 sr_device_scan();
  97
  98         return devices;
  99 }
 100
 101 /**
 102  * Create a new device.
 103  *
 104  * TODO: 'plugin' can be const.
 105  * TODO: num_probes should be uint16_t.
 106  * TODO: Should return int, so that we can return SR_OK, SR_ERR_* etc.
 107  *
 108  * It is the caller's responsibility to g_free() the allocated memory when
 109  * no longer needed. TODO: Using which API function?
 110  *
 111  * @param plugin TODO.
 112  *               If 'plugin' is NULL, the created device is a "virtual" one.
 113  * @param plugin_index TODO
 114  * @param num_probes The number of probes (>= 1) this device has.
 115  *                   TODO: 0 allowed?
 116  *
 117  * @return Pointer to the newly allocated device, or NULL upon errors.
 118  */
 119 struct sr_device *sr_device_new(struct sr_device_plugin *plugin, int plugin_index,
 120                                 int num_probes)
 121 {
 122         struct sr_device *device;
 123         int i;
 124
 125         if (!plugin) {
 126                 sr_err("dev: %s: plugin was NULL", __func__);
 127                 return NULL; /* TODO: SR_ERR_ARG */
 128         }
 129
 130         /* TODO: Check if plugin_index valid? */
 131
 132         /* TODO: Check if num_probes valid? */
 133
 134         if (!(device = g_try_malloc0(sizeof(struct sr_device)))) {
 135                 sr_err("dev: %s: device malloc failed", __func__);
 136                 return NULL;
 137         }
 138
 139         device->plugin = plugin;
 140         device->plugin_index = plugin_index;
 141         devices = g_slist_append(devices, device);
 142
 143         for (i = 0; i < num_probes; i++)
 144                 sr_device_probe_add(device, NULL); /* TODO: Check return value. */
 145
 146         return device;
 147 }
 148
 149 /**
 150  * Clear all probes of the specified device.
 151  *
 152  * This removes/clears the 'name' and 'trigger' fields of all probes of
 153  * the device.
 154  *
 155  * The order in which the probes are cleared is not specified. The caller
 156  * should not assume or rely on a specific order.
 157  *
 158  * TODO: Should return int.
 159  * TODO: Rename to sr_device_clear_probes() or sr_device_probe_clear_all().
 160  *
 161  * @param device The device whose probes to clear. Must not be NULL.
 162  *               Note: device->probes is allowed to be NULL (in that case,
 163  *               there are no probes, thus none have to be cleared).
 164  */
 165 void sr_device_clear(struct sr_device *device)
 166 {
 167         unsigned int pnum;
 168
 169         if (!device) {
 170                 sr_err("dev: %s: device was NULL", __func__);
 171                 return; /* TODO: SR_ERR_ARG. */
 172         }
 173
 174         /* Note: device->probes can be NULL, this is handled correctly. */
 175
 176         for (pnum = 1; pnum <= g_slist_length(device->probes); pnum++)
 177                 sr_device_probe_clear(device, pnum);
 178
 179         /* TODO: return SR_OK; */
 180 }
 181
 182 /**
 183  * Clear the specified probe in the specified device.
 184  *
 185  * The probe itself still exists afterwards, but its 'name' and 'trigger'
 186  * fields are g_free()'d and set to NULL.
 187  *
 188  * TODO: Should return int.
 189  *
 190  * @param device The device in which the specified (to be cleared) probe
 191  *               resides. Must not be NULL.
 192  * @param probenum The number of the probe to clear.
 193  *                 Note that the probe numbers start at 1 (not 0!).
 194  */
 195 void sr_device_probe_clear(struct sr_device *device, int probenum)
 196 {
 197         struct sr_probe *p;
 198
 199         if (!device) {
 200                 sr_err("dev: %s: device was NULL", __func__);
 201                 return; /* TODO: SR_ERR_ARG. */
 202         }
 203
 204         /* TODO: Sanity check on 'probenum'. */
 205
 206         if (!(p = sr_device_probe_find(device, probenum))) {
 207                 sr_err("dev: %s: probe %d not found", __func__, probenum);
 208                 return; /* TODO: SR_ERR*. */
 209         }
 210
 211         /* If the probe has a name, remove it. */
 212         if (p->name) {
 213                 g_free(p->name);
 214                 p->name = NULL;
 215         }
 216
 217         /* If the probe has a trigger, remove it. */
 218         if (p->trigger) {
 219                 g_free(p->trigger);
 220                 p->trigger = NULL;
 221         }
 222
 223         /* TODO: return SR_OK; */
 224 }
 225
 226 /**
 227  * Add a probe with the specified name to the specified device.
 228  *
 229  * The added probe is automatically enabled (the 'enabled' field is TRUE).
 230  *
 231  * The 'trigger' field of the added probe is set to NULL. A trigger can be
 232  * added via sr_device_trigger_set().
 233  *
 234  * TODO: Should return int.
 235  * TODO: Are duplicate names allowed?
 236  * TODO: Do we enforce a maximum probe number for a device?
 237  * TODO: Error if the max. probe number for the specific LA is reached, e.g.
 238  *       if the caller tries to add more probes than the device actually has.
 239  *
 240  * @param device The device to which to add a probe with the specified name.
 241  *               Must not be NULL.
 242  * @param name The name of the probe to add to this device. Must not be NULL.
 243  *             TODO: Maximum length, allowed characters, etc.
 244  *
 245  * @return SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors,
 246  *         or SR_ERR_ARG upon invalid arguments.
 247  *         If something other than SR_OK is returned, 'device' is unchanged.
 248  */
 249 void sr_device_probe_add(struct sr_device *device, const char *name)
 250 {
 251         struct sr_probe *p;
 252         char probename[16]; /* FIXME: Don't hardcode 16? #define? */
 253         int probenum;
 254
 255         if (!device) {
 256                 sr_err("dev: %s: device was NULL", __func__);
 257                 return; /* SR_ERR_ARG; */
 258         }
 259
 260         if (!name) {
 261                 sr_err("dev: %s: name was NULL", __func__);
 262                 return; /* SR_ERR_ARG; */
 263         }
 264
 265         /* TODO: Further checks to ensure name is valid. */
 266
 267         probenum = g_slist_length(device->probes) + 1;
 268
 269         if (!(p = g_try_malloc0(sizeof(struct sr_probe)))) {
 270                 sr_err("dev: %s: p malloc failed", __func__);
 271                 return; /* SR_ERR_MALLOC; */
 272         }
 273
 274         p->index = probenum;
 275         p->enabled = TRUE;
 276         if (name) {
 277                 p->name = g_strdup(name);
 278         } else {
 279                 snprintf(probename, 16, "%d", probenum);
 280                 p->name = g_strdup(probename);
 281         }
 282         p->trigger = NULL;
 283         device->probes = g_slist_append(device->probes, p);
 284
 285         return SR_OK;
 286 }
 287
 288 /**
 289  * Find the probe with the specified number in the specified device.
 290  *
 291  * TODO
 292  *
 293  * @param device TODO. Must not be NULL.
 294  * @param probenum The number of the probe whose 'struct sr_probe' we want.
 295  *                 Note that the probe numbers start at 1 (not 0!).
 296  *
 297  * TODO: Should return int.
 298  * TODO: device can be const.
 299  * TODO: probenum should be unsigned.
 300  *
 301  * @return A pointer to the requested probe's 'struct sr_probe', or NULL
 302  *         if the probe could not be found.
 303  */
 304 struct sr_probe *sr_device_probe_find(struct sr_device *device, int probenum)
 305 {
 306         GSList *l;
 307         struct sr_probe *p, *found_probe;
 308
 309         if (!device) {
 310                 sr_err("dev: %s: device was NULL", __func__);
 311                 return NULL; /* TODO: SR_ERR_ARG */
 312         }
 313
 314         /* TODO: Sanity check on probenum. */
 315
 316         found_probe = NULL;
 317         for (l = device->probes; l; l = l->next) {
 318                 p = l->data;
 319                 /* TODO: Check for p != NULL. */
 320                 if (p->index == probenum) {
 321                         found_probe = p;
 322                         break;
 323                 }
 324         }
 325
 326         return found_probe;
 327 }
 328
 329 /**
 330  * Set the name of the specified probe in the specified device.
 331  *
 332  * If the probe already has a different name assigned to it, it will be
 333  * removed, and the new name will be saved instead.
 334  *
 335  * TODO: Should return int.
 336  * TODO: device can be const?
 337  * TODO: Rename to sr_device_set_probe_name().
 338  *
 339  * @param device TODO
 340  * @param probenum The number of the probe whose name to set.
 341  *                 Note that the probe numbers start at 1 (not 0!).
 342  * @param name The new name that the specified probe should get.
 343  */
 344 void sr_device_probe_name(struct sr_device *device, int probenum,
 345                           const char *name)
 346 {
 347         struct sr_probe *p;
 348
 349         if (!device) {
 350                 sr_err("dev: %s: device was NULL", __func__);
 351                 return; /* TODO: SR_ERR_ARG */
 352         }
 353
 354         p = sr_device_probe_find(device, probenum);
 355         if (!p) {
 356                 sr_err("dev: %s: probe %d not found", __func__, probenum);
 357                 return; /* TODO: SR_ERR*. */
 358         }
 359
 360         /* TODO: Sanity check on 'name'. */
 361
 362         /* If the probe already has a name, kill it first. */
 363         if (p->name)
 364                 g_free(p->name);
 365
 366         p->name = g_strdup(name);
 367 }
 368
 369 /**
 370  * Remove all triggers set up for the specified device.
 371  *
 372  * TODO: Better description.
 373  *
 374  * TODO: Should return int.
 375  * TODO: device can be const?
 376  *
 377  * @param device TODO
 378  */
 379 void sr_device_trigger_clear(struct sr_device *device)
 380 {
 381         struct sr_probe *p;
 382         unsigned int pnum; /* TODO: uint6_t? */
 383
 384         if (!device) {
 385                 sr_err("dev: %s: device was NULL", __func__);
 386                 return; /* TODO: SR_ERR_ARG */
 387         }
 388
 389         if (!device->probes) {
 390                 sr_err("dev: %s: device->probes was NULL", __func__);
 391                 return; /* TODO: SR_ERR*. */
 392         }
 393
 394         for (pnum = 1; pnum <= g_slist_length(device->probes); pnum++) {
 395                 p = sr_device_probe_find(device, pnum);
 396                 /* TODO: Silently ignore probes which cannot be found? */
 397                 if (p && p->trigger) {
 398                         g_free(p->trigger);
 399                         p->trigger = NULL;
 400                 }
 401         }
 402 }
 403
 404 /**
 405  * Add a trigger to the specified device.
 406  *
 407  * TODO: Better description.
 408  * TODO: Describe valid format of the 'trigger' string.
 409  *
 410  * TODO: Should return int.
 411  * TODO: device can be const?
 412  *
 413  * @param device TODO. Must not be NULL.
 414  * @param probenum The number of the probe. TODO.
 415  *                 Note that the probe numbers start at 1 (not 0!).
 416  * @param trigger TODO.
 417  *                TODO: Is NULL allowed?
 418  */
 419 void sr_device_trigger_set(struct sr_device *device, int probenum,
 420                            const char *trigger)
 421 {
 422         struct sr_probe *p;
 423
 424         if (!device) {
 425                 sr_err("dev: %s: device was NULL", __func__);
 426                 return; /* TODO: SR_ERR_ARG */
 427         }
 428
 429         /* TODO: Sanity check on 'probenum'. */
 430
 431         /* TODO: Sanity check on 'trigger'. */
 432
 433         p = sr_device_probe_find(device, probenum);
 434         if (!p) {
 435                 sr_err("dev: %s: probe %d not found", __func__, probenum);
 436                 return; /* TODO: SR_ERR*. */
 437         }
 438
 439         /* If the probe already has a trigger, kill it first. */
 440         if (p->trigger)
 441                 g_free(p->trigger);
 442
 443         p->trigger = g_strdup(trigger);
 444 }
 445
 446 /**
 447  * Determine whether the specified device has the specified capability.
 448  *
 449  * TODO: Should return int?
 450  * TODO: device can be const.
 451  *
 452  * @param device Pointer to the device to be checked. Must not be NULL.
 453  *               The device's 'plugin' field must not be NULL either.
 454  * @param hwcap The capability that should be checked (whether it's supported
 455  *              by the specified device).
 456  *
 457  * @return TRUE, if the device has the specified capability, FALSE otherwise.
 458  *         FALSE is also returned upon invalid input parameters or other
 459  *         error conditions.
 460  */
 461 gboolean sr_device_has_hwcap(struct sr_device *device, int hwcap)
 462 {
 463         int *capabilities, i;
 464
 465         if (!device) {
 466                 sr_err("dev: %s: device was NULL", __func__);
 467                 return FALSE; /* TODO: SR_ERR_ARG. */
 468         }
 469
 470         if (!device->plugin) {
 471                 sr_err("dev: %s: device->plugin was NULL", __func__);
 472                 return FALSE; /* TODO: SR_ERR_ARG. */
 473         }
 474
 475         /* TODO: Sanity check on 'hwcap'. */
 476
 477         if (!(capabilities = device->plugin->get_capabilities())) {
 478                 sr_err("dev: %s: device has no capabilities", __func__);
 479                 return FALSE; /* TODO: SR_ERR*. */
 480         }
 481
 482         for (i = 0; capabilities[i]; i++) {
 483                 if (capabilities[i] != hwcap)
 484                         continue;
 485                 sr_spew("dev: %s: found hwcap %d", __func__, hwcap);
 486                 return TRUE;
 487         }
 488
 489         sr_spew("dev: %s: hwcap %d not found", __func__, hwcap);
 490
 491         return FALSE;
 492 }