libsigrok
|
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 }