libsigrok
device.c
Go to the documentation of this file.
00001 /*
00002  * This file is part of the sigrok project.
00003  *
00004  * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
00005  *
00006  * This program is free software: you can redistribute it and/or modify
00007  * it under the terms of the GNU General Public License as published by
00008  * the Free Software Foundation, either version 3 of the License, or
00009  * (at your option) any later version.
00010  *
00011  * This program is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014  * GNU General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU General Public License
00017  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
00018  */
00019 
00020 #include <stdio.h>
00021 #include <glib.h>
00022 #include "sigrok.h"
00023 #include "sigrok-internal.h"
00024 
00025 static GSList *devs = NULL;
00026 
00027 /**
00028  * Scan the system for attached logic analyzers / devices.
00029  *
00030  * This will try to autodetect all supported logic analyzer devices:
00031  *
00032  *  - Those attached via USB (can be reliably detected via USB VID/PID).
00033  *
00034  *  - Those using a (real or virtual) serial port (detected by sending
00035  *    device-specific commands to all OS-specific serial port devices such
00036  *    as /dev/ttyS*, /dev/ttyUSB*, /dev/ttyACM*, and others).
00037  *    The autodetection for this kind of devices can potentially be unreliable.
00038  *
00039  *    Also, sending various bytes/commands to (all!) devices which happen to
00040  *    be attached to the system via a (real or virtual) serial port can be
00041  *    problematic. There is no way for libsigrok to know how unknown devices
00042  *    react to the bytes libsigrok sends. Potentially they could lead to the
00043  *    device getting into invalid/error states, losing/overwriting data, or...
00044  *
00045  * In addition to the detection, the devices that are found are also
00046  * initialized automatically. On some devices, this involves a firmware upload,
00047  * or other such measures.
00048  *
00049  * The order in which the system is scanned for devices is not specified. The
00050  * caller should not assume or rely on any specific order.
00051  *
00052  * After the system has been scanned for devices, the list of detected (and
00053  * supported) devices can be acquired via sr_dev_list().
00054  *
00055  * TODO: Error checks?
00056  * TODO: Option to only scan for specific devices or device classes.
00057  *
00058  * @return SR_OK upon success, SR_ERR_BUG upon internal errors.
00059  */
00060 SR_API int sr_dev_scan(void)
00061 {
00062         int i;
00063         struct sr_dev_driver **drivers;
00064 
00065         drivers = sr_driver_list();
00066         if (!drivers[0]) {
00067                 sr_err("dev: %s: no supported hardware drivers", __func__);
00068                 return SR_ERR_BUG;
00069         }
00070 
00071         /*
00072          * Initialize all drivers first. Since the init() call may involve
00073          * a firmware upload and associated delay, we may as well get all
00074          * of these out of the way first.
00075          */
00076         for (i = 0; drivers[i]; i++)
00077                 sr_driver_init(drivers[i]);
00078 
00079         return SR_OK;
00080 }
00081 
00082 /**
00083  * Return the list of logic analyzer devices libsigrok has detected.
00084  *
00085  * If the libsigrok-internal device list is empty, a scan for attached
00086  * devices -- via a call to sr_dev_scan() -- is performed first.
00087  *
00088  * TODO: Error handling?
00089  *
00090  * @return The list (GSList) of detected devices, or NULL if none were found.
00091  */
00092 SR_API GSList *sr_dev_list(void)
00093 {
00094         if (!devs)
00095                 sr_dev_scan();
00096 
00097         return devs;
00098 }
00099 
00100 /**
00101  * Create a new device.
00102  *
00103  * The device is added to the (libsigrok-internal) list of devices, but
00104  * additionally a pointer to the newly created device is also returned.
00105  *
00106  * The device has no probes attached to it yet after this call. You can
00107  * use sr_dev_probe_add() to add one or more probes.
00108  *
00109  * TODO: Should return int, so that we can return SR_OK, SR_ERR_* etc.
00110  *
00111  * It is the caller's responsibility to g_free() the allocated memory when
00112  * no longer needed. TODO: Using which API function?
00113  *
00114  * @param driver TODO.
00115  *               If 'driver' is NULL, the created device is a "virtual" one.
00116  * @param driver_index TODO
00117  *
00118  * @return Pointer to the newly allocated device, or NULL upon errors.
00119  */
00120 SR_API struct sr_dev *sr_dev_new(const struct sr_dev_driver *driver,
00121                                  int driver_index)
00122 {
00123         struct sr_dev *dev;
00124 
00125         /* TODO: Check if driver_index valid? */
00126 
00127         if (!(dev = g_try_malloc0(sizeof(struct sr_dev)))) {
00128                 sr_err("dev: %s: dev malloc failed", __func__);
00129                 return NULL;
00130         }
00131 
00132         dev->driver = (struct sr_dev_driver *)driver;
00133         dev->driver_index = driver_index;
00134         devs = g_slist_append(devs, dev);
00135 
00136         return dev;
00137 }
00138 
00139 /**
00140  * Add a probe with the specified name to the specified device.
00141  *
00142  * The added probe is automatically enabled (the 'enabled' field is TRUE).
00143  *
00144  * The 'trigger' field of the added probe is set to NULL. A trigger can be
00145  * added via sr_dev_trigger_set().
00146  *
00147  * TODO: Are duplicate names allowed?
00148  * TODO: Do we enforce a maximum probe number for a device?
00149  * TODO: Error if the max. probe number for the specific LA is reached, e.g.
00150  *       if the caller tries to add more probes than the device actually has.
00151  *
00152  * @param dev The device to which to add a probe with the specified name.
00153  *            Must not be NULL.
00154  * @param name The name of the probe to add to this device. Must not be NULL.
00155  *             TODO: Maximum length, allowed characters, etc.
00156  *
00157  * @return SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors,
00158  *         or SR_ERR_ARG upon invalid arguments.
00159  *         If something other than SR_OK is returned, 'dev' is unchanged.
00160  */
00161 SR_API int sr_dev_probe_add(struct sr_dev *dev, const char *name)
00162 {
00163         struct sr_probe *p;
00164         int probenum;
00165 
00166         if (!dev) {
00167                 sr_err("dev: %s: dev was NULL", __func__);
00168                 return SR_ERR_ARG;
00169         }
00170 
00171         if (!name) {
00172                 sr_err("dev: %s: name was NULL", __func__);
00173                 return SR_ERR_ARG;
00174         }
00175 
00176         /* TODO: Further checks to ensure name is valid. */
00177 
00178         probenum = g_slist_length(dev->probes) + 1;
00179 
00180         if (!(p = g_try_malloc0(sizeof(struct sr_probe)))) {
00181                 sr_err("dev: %s: p malloc failed", __func__);
00182                 return SR_ERR_MALLOC;
00183         }
00184 
00185         p->index = probenum;
00186         p->enabled = TRUE;
00187         p->name = g_strdup(name);
00188         p->trigger = NULL;
00189         dev->probes = g_slist_append(dev->probes, p);
00190 
00191         return SR_OK;
00192 }
00193 
00194 /**
00195  * Find the probe with the specified number in the specified device.
00196  *
00197  * TODO
00198  *
00199  * @param dev TODO. Must not be NULL.
00200  * @param probenum The number of the probe whose 'struct sr_probe' we want.
00201  *                 Note that the probe numbers start at 1 (not 0!).
00202  *
00203  * TODO: Should return int.
00204  * TODO: probenum should be unsigned.
00205  *
00206  * @return A pointer to the requested probe's 'struct sr_probe', or NULL
00207  *         if the probe could not be found.
00208  */
00209 SR_API struct sr_probe *sr_dev_probe_find(const struct sr_dev *dev,
00210                                           int probenum)
00211 {
00212         GSList *l;
00213         struct sr_probe *p, *found_probe;
00214 
00215         if (!dev) {
00216                 sr_err("dev: %s: dev was NULL", __func__);
00217                 return NULL; /* TODO: SR_ERR_ARG */
00218         }
00219 
00220         /* TODO: Sanity check on probenum. */
00221 
00222         found_probe = NULL;
00223         for (l = dev->probes; l; l = l->next) {
00224                 p = l->data;
00225                 /* TODO: Check for p != NULL. */
00226                 if (p->index == probenum) {
00227                         found_probe = p;
00228                         break;
00229                 }
00230         }
00231 
00232         return found_probe;
00233 }
00234 
00235 /**
00236  * Set the name of the specified probe in the specified device.
00237  *
00238  * If the probe already has a different name assigned to it, it will be
00239  * removed, and the new name will be saved instead.
00240  *
00241  * @param dev TODO
00242  * @param probenum The number of the probe whose name to set.
00243  *                 Note that the probe numbers start at 1 (not 0!).
00244  * @param name The new name that the specified probe should get.
00245  *
00246  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR
00247  *         upon other errors.
00248  *         If something other than SR_OK is returned, 'dev' is unchanged.
00249  */
00250 SR_API int sr_dev_probe_name_set(struct sr_dev *dev, int probenum,
00251                                  const char *name)
00252 {
00253         struct sr_probe *p;
00254 
00255         if (!dev) {
00256                 sr_err("dev: %s: dev was NULL", __func__);
00257                 return SR_ERR_ARG;
00258         }
00259 
00260         p = sr_dev_probe_find(dev, probenum);
00261         if (!p) {
00262                 sr_err("dev: %s: probe %d not found", __func__, probenum);
00263                 return SR_ERR; /* TODO: More specific error? */
00264         }
00265 
00266         /* TODO: Sanity check on 'name'. */
00267 
00268         /* If the probe already has a name, kill it first. */
00269         g_free(p->name);
00270 
00271         p->name = g_strdup(name);
00272 
00273         return SR_OK;
00274 }
00275 
00276 /**
00277  * Remove all triggers set up for the specified device.
00278  *
00279  * TODO: Better description.
00280  *
00281  * @param dev TODO
00282  *
00283  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
00284  *         If something other than SR_OK is returned, 'dev' is unchanged.
00285  */
00286 SR_API int sr_dev_trigger_remove_all(struct sr_dev *dev)
00287 {
00288         struct sr_probe *p;
00289         unsigned int pnum; /* TODO: uint16_t? */
00290 
00291         if (!dev) {
00292                 sr_err("dev: %s: dev was NULL", __func__);
00293                 return SR_ERR_ARG;
00294         }
00295 
00296         if (!dev->probes) {
00297                 sr_err("dev: %s: dev->probes was NULL", __func__);
00298                 return SR_ERR_ARG;
00299         }
00300 
00301         for (pnum = 1; pnum <= g_slist_length(dev->probes); pnum++) {
00302                 p = sr_dev_probe_find(dev, pnum);
00303                 /* TODO: Silently ignore probes which cannot be found? */
00304                 if (p) {
00305                         g_free(p->trigger);
00306                         p->trigger = NULL;
00307                 }
00308         }
00309 
00310         return SR_OK;
00311 }
00312 
00313 /**
00314  * Add a trigger to the specified device (and the specified probe).
00315  *
00316  * If the specified probe of this device already has a trigger, it will
00317  * be silently replaced.
00318  *
00319  * TODO: Better description.
00320  * TODO: Describe valid format of the 'trigger' string.
00321  *
00322  * @param dev TODO. Must not be NULL.
00323  * @param probenum The number of the probe. TODO.
00324  *                 Note that the probe numbers start at 1 (not 0!).
00325  * @param trigger TODO.
00326  *                TODO: Is NULL allowed?
00327  *
00328  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR
00329  *         upon other errors.
00330  *         If something other than SR_OK is returned, 'dev' is unchanged.
00331  */
00332 SR_API int sr_dev_trigger_set(struct sr_dev *dev, int probenum,
00333                               const char *trigger)
00334 {
00335         struct sr_probe *p;
00336 
00337         if (!dev) {
00338                 sr_err("dev: %s: dev was NULL", __func__);
00339                 return SR_ERR_ARG;
00340         }
00341 
00342         /* TODO: Sanity check on 'probenum'. */
00343 
00344         /* TODO: Sanity check on 'trigger'. */
00345 
00346         p = sr_dev_probe_find(dev, probenum);
00347         if (!p) {
00348                 sr_err("dev: %s: probe %d not found", __func__, probenum);
00349                 return SR_ERR; /* TODO: More specific error? */
00350         }
00351 
00352         /* If the probe already has a trigger, kill it first. */
00353         g_free(p->trigger);
00354 
00355         p->trigger = g_strdup(trigger);
00356         sr_dbg("dev: %s: Setting '%s' trigger for probe %d.", __func__,
00357                p->trigger, probenum);
00358 
00359         return SR_OK;
00360 }
00361 
00362 /**
00363  * Determine whether the specified device has the specified capability.
00364  *
00365  * @param dev Pointer to the device to be checked. Must not be NULL.
00366  *            If the device's 'driver' field is NULL (virtual device), this
00367  *            function will always return FALSE (virtual devices don't have
00368  *            a hardware capabilities list).
00369  * @param hwcap The capability that should be checked (whether it's supported
00370  *              by the specified device).
00371  *
00372  * @return TRUE, if the device has the specified capability, FALSE otherwise.
00373  *         FALSE is also returned upon invalid input parameters or other
00374  *         error conditions.
00375  */
00376 SR_API gboolean sr_dev_has_hwcap(const struct sr_dev *dev, int hwcap)
00377 {
00378         int *hwcaps, i;
00379 
00380         sr_spew("dev: %s: requesting hwcap %d", __func__, hwcap);
00381 
00382         if (!dev) {
00383                 sr_err("dev: %s: dev was NULL", __func__);
00384                 return FALSE;
00385         }
00386 
00387         /*
00388          * Virtual devices (which have dev->driver set to NULL) always say that
00389          * they don't have the capability (they can't call hwcap_get_all()).
00390          */
00391         if (!dev->driver) {
00392                 sr_dbg("dev: %s: dev->driver was NULL, this seems to be "
00393                        "a virtual device without capabilities", __func__);
00394                 return FALSE;
00395         }
00396 
00397         /* TODO: Sanity check on 'hwcap'. */
00398 
00399         if (!(hwcaps = dev->driver->hwcap_get_all())) {
00400                 sr_err("dev: %s: dev has no capabilities", __func__);
00401                 return FALSE;
00402         }
00403 
00404         for (i = 0; hwcaps[i]; i++) {
00405                 if (hwcaps[i] != hwcap)
00406                         continue;
00407                 sr_spew("dev: %s: found hwcap %d", __func__, hwcap);
00408                 return TRUE;
00409         }
00410 
00411         sr_spew("dev: %s: hwcap %d not found", __func__, hwcap);
00412 
00413         return FALSE;
00414 }
00415 
00416 /**
00417  * Returns information about the given device.
00418  *
00419  * @param dev Pointer to the device to be checked. Must not be NULL.
00420  *            The device's 'driver' field must not be NULL either.
00421  * @param id The type of information.
00422  * @param data The return value. Must not be NULL.
00423  *
00424  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR
00425  *         upon other errors.
00426  */
00427 SR_API int sr_dev_info_get(const struct sr_dev *dev, int id, const void **data)
00428 {
00429         if ((dev == NULL) || (dev->driver == NULL))
00430                 return SR_ERR_ARG;
00431 
00432         if (data == NULL)
00433                 return SR_ERR_ARG;
00434 
00435         *data = dev->driver->dev_info_get(dev->driver_index, id);
00436 
00437         if (*data == NULL)
00438                 return SR_ERR;
00439 
00440         return SR_OK;
00441 }
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines