libsigrok  0.5.0
sigrok hardware access and backend library
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
backend.c
Go to the documentation of this file.
1 /*
2  * This file is part of the libsigrok project.
3  *
4  * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
5  * Copyright (C) 2012 Peter Stuge <peter@stuge.se>
6  *
7  * This program is free software: you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation, either version 3 of the License, or
10  * (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program. If not, see <http://www.gnu.org/licenses/>.
19  */
20 
21 #include <config.h>
22 #include <glib.h>
23 #ifdef _WIN32
24 #include <winsock2.h>
25 #endif
26 #include <libsigrok/libsigrok.h>
27 #include "libsigrok-internal.h"
28 
29 /** @cond PRIVATE */
30 #define LOG_PREFIX "backend"
31 /** @endcond */
32 
33 /**
34  * @mainpage libsigrok API
35  *
36  * @section sec_intro Introduction
37  *
38  * The <a href="http://sigrok.org">sigrok</a> project aims at creating a
39  * portable, cross-platform, Free/Libre/Open-Source signal analysis software
40  * suite that supports various device types (such as logic analyzers,
41  * oscilloscopes, multimeters, and more).
42  *
43  * <a href="http://sigrok.org/wiki/Libsigrok">libsigrok</a> is a shared
44  * library written in C which provides the basic API for talking to
45  * <a href="http://sigrok.org/wiki/Supported_hardware">supported hardware</a>
46  * and reading/writing the acquired data into various
47  * <a href="http://sigrok.org/wiki/Input_output_formats">input/output
48  * file formats</a>.
49  *
50  * @section sec_api API reference
51  *
52  * See the "Modules" page for an introduction to various libsigrok
53  * related topics and the detailed API documentation of the respective
54  * functions.
55  *
56  * You can also browse the API documentation by file, or review all
57  * data structures.
58  *
59  * @section sec_mailinglists Mailing lists
60  *
61  * There is one mailing list for sigrok/libsigrok: <a href="https://lists.sourceforge.net/lists/listinfo/sigrok-devel">sigrok-devel</a>.
62  *
63  * @section sec_irc IRC
64  *
65  * You can find the sigrok developers in the
66  * <a href="irc://chat.freenode.net/sigrok">\#sigrok</a>
67  * IRC channel on Freenode.
68  *
69  * @section sec_website Website
70  *
71  * <a href="http://sigrok.org/wiki/Libsigrok">sigrok.org/wiki/Libsigrok</a>
72  */
73 
74 /**
75  * @file
76  *
77  * Initializing and shutting down libsigrok.
78  */
79 
80 /**
81  * @defgroup grp_init Initialization
82  *
83  * Initializing and shutting down libsigrok.
84  *
85  * Before using any of the libsigrok functionality (except for
86  * sr_log_loglevel_set()), sr_init() must be called to initialize the
87  * library, which will return a struct sr_context when the initialization
88  * was successful.
89  *
90  * When libsigrok functionality is no longer needed, sr_exit() should be
91  * called, which will (among other things) free the struct sr_context.
92  *
93  * Example for a minimal program using libsigrok:
94  *
95  * @code{.c}
96  * #include <stdio.h>
97  * #include <libsigrok/libsigrok.h>
98  *
99  * int main(int argc, char **argv)
100  * {
101  * int ret;
102  * struct sr_context *sr_ctx;
103  *
104  * if ((ret = sr_init(&sr_ctx)) != SR_OK) {
105  * printf("Error initializing libsigrok (%s): %s.\n",
106  * sr_strerror_name(ret), sr_strerror(ret));
107  * return 1;
108  * }
109  *
110  * // Use libsigrok functions here...
111  *
112  * if ((ret = sr_exit(sr_ctx)) != SR_OK) {
113  * printf("Error shutting down libsigrok (%s): %s.\n",
114  * sr_strerror_name(ret), sr_strerror(ret));
115  * return 1;
116  * }
117  *
118  * return 0;
119  * }
120  * @endcode
121  *
122  * @{
123  */
124 
126 {
127  GSList *l = NULL, *m = NULL;
128 #if defined(HAVE_LIBUSB_1_0) && !defined(__FreeBSD__)
129  const struct libusb_version *lv;
130 #endif
131 
132  m = g_slist_append(NULL, g_strdup("glib"));
133  m = g_slist_append(m, g_strdup_printf("%d.%d.%d (rt: %d.%d.%d/%d:%d)",
134  GLIB_MAJOR_VERSION, GLIB_MINOR_VERSION, GLIB_MICRO_VERSION,
135  glib_major_version, glib_minor_version, glib_micro_version,
136  glib_binary_age, glib_interface_age));
137  l = g_slist_append(l, m);
138 
139  m = g_slist_append(NULL, g_strdup("libzip"));
140  m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBZIP_VERSION));
141  l = g_slist_append(l, m);
142 
143 #ifdef HAVE_LIBSERIALPORT
144  m = g_slist_append(NULL, g_strdup("libserialport"));
145  m = g_slist_append(m, g_strdup_printf("%s/%s (rt: %s/%s)",
146  SP_PACKAGE_VERSION_STRING, SP_LIB_VERSION_STRING,
147  sp_get_package_version_string(), sp_get_lib_version_string()));
148  l = g_slist_append(l, m);
149 #endif
150 #ifdef HAVE_LIBUSB_1_0
151  m = g_slist_append(NULL, g_strdup("libusb-1.0"));
152 #ifdef __FreeBSD__
153  m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBUSB_1_0_VERSION));
154 #else
155  lv = libusb_get_version();
156  m = g_slist_append(m, g_strdup_printf("%d.%d.%d.%d%s",
157  lv->major, lv->minor, lv->micro, lv->nano, lv->rc));
158 #endif
159  l = g_slist_append(l, m);
160 #endif
161 #ifdef HAVE_LIBFTDI
162  m = g_slist_append(NULL, g_strdup("libftdi"));
163  m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBFTDI_VERSION));
164  l = g_slist_append(l, m);
165 #endif
166 #ifdef HAVE_LIBGPIB
167  m = g_slist_append(NULL, g_strdup("libgpib"));
168  m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBGPIB_VERSION));
169  l = g_slist_append(l, m);
170 #endif
171 #ifdef HAVE_LIBREVISA
172  m = g_slist_append(NULL, g_strdup("librevisa"));
173  m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBREVISA_VERSION));
174  l = g_slist_append(l, m);
175 #endif
176 
177  return l;
178 }
179 
181 {
182  return g_strdup_printf("%s, %s-endian", CONF_HOST,
183 #ifdef WORDS_BIGENDIAN
184  "big"
185 #else
186  "little"
187 #endif
188  );
189 }
190 
192 {
193  GString *s;
194  char *str;
195 
196  s = g_string_sized_new(200);
197 
198  g_string_append_printf(s, "TCP, ");
199 #if HAVE_RPC
200  g_string_append_printf(s, "RPC, ");
201 #endif
202 #ifdef HAVE_LIBSERIALPORT
203  g_string_append_printf(s, "serial, ");
204 #endif
205 #ifdef HAVE_LIBREVISA
206  g_string_append_printf(s, "VISA, ");
207 #endif
208 #ifdef HAVE_LIBGPIB
209  g_string_append_printf(s, "GPIB, ");
210 #endif
211 #ifdef HAVE_LIBUSB_1_0
212  g_string_append_printf(s, "USBTMC, ");
213 #endif
214  s->str[s->len - 2] = '\0';
215 
216  str = g_strdup(s->str);
217  g_string_free(s, TRUE);
218 
219  return str;
220 }
221 
222 static void print_versions(void)
223 {
224  GString *s;
225  GSList *l, *l_orig, *m;
226  char *str;
227  const char *lib, *version;
228 
229  sr_dbg("libsigrok %s/%s (rt: %s/%s).",
232 
233  s = g_string_sized_new(200);
234  g_string_append(s, "Libs: ");
235  l_orig = sr_buildinfo_libs_get();
236  for (l = l_orig; l; l = l->next) {
237  m = l->data;
238  lib = m->data;
239  version = m->next->data;
240  g_string_append_printf(s, "%s %s, ", lib, version);
241  g_slist_free_full(m, g_free);
242  }
243  g_slist_free(l_orig);
244  s->str[s->len - 2] = '.';
245  s->str[s->len - 1] = '\0';
246  sr_dbg("%s", s->str);
247  g_string_free(s, TRUE);
248 
249  str = sr_buildinfo_host_get();
250  sr_dbg("Host: %s.", str);
251  g_free(str);
252 
254  sr_dbg("SCPI backends: %s.", str);
255  g_free(str);
256 }
257 
258 /**
259  * Sanity-check all libsigrok drivers.
260  *
261  * @param[in] ctx Pointer to a libsigrok context struct. Must not be NULL.
262  *
263  * @retval SR_OK All drivers are OK
264  * @retval SR_ERR One or more drivers have issues.
265  * @retval SR_ERR_ARG Invalid argument.
266  */
267 static int sanity_check_all_drivers(const struct sr_context *ctx)
268 {
269  int i, errors, ret = SR_OK;
270  struct sr_dev_driver **drivers;
271  const char *d;
272 
273  if (!ctx)
274  return SR_ERR_ARG;
275 
276  sr_spew("Sanity-checking all drivers.");
277 
278  drivers = sr_driver_list(ctx);
279  for (i = 0; drivers[i]; i++) {
280  errors = 0;
281 
282  d = (drivers[i]->name) ? drivers[i]->name : "NULL";
283 
284  if (!drivers[i]->name) {
285  sr_err("No name in driver %d ('%s').", i, d);
286  errors++;
287  }
288  if (!drivers[i]->longname) {
289  sr_err("No longname in driver %d ('%s').", i, d);
290  errors++;
291  }
292  if (drivers[i]->api_version < 1) {
293  sr_err("API version in driver %d ('%s') < 1.", i, d);
294  errors++;
295  }
296  if (!drivers[i]->init) {
297  sr_err("No init in driver %d ('%s').", i, d);
298  errors++;
299  }
300  if (!drivers[i]->cleanup) {
301  sr_err("No cleanup in driver %d ('%s').", i, d);
302  errors++;
303  }
304  if (!drivers[i]->scan) {
305  sr_err("No scan in driver %d ('%s').", i, d);
306  errors++;
307  }
308  if (!drivers[i]->dev_list) {
309  sr_err("No dev_list in driver %d ('%s').", i, d);
310  errors++;
311  }
312  /* Note: dev_clear() is optional. */
313  /* Note: config_get() is optional. */
314  if (!drivers[i]->config_set) {
315  sr_err("No config_set in driver %d ('%s').", i, d);
316  errors++;
317  }
318  /* Note: config_channel_set() is optional. */
319  /* Note: config_commit() is optional. */
320  if (!drivers[i]->config_list) {
321  sr_err("No config_list in driver %d ('%s').", i, d);
322  errors++;
323  }
324  if (!drivers[i]->dev_open) {
325  sr_err("No dev_open in driver %d ('%s').", i, d);
326  errors++;
327  }
328  if (!drivers[i]->dev_close) {
329  sr_err("No dev_close in driver %d ('%s').", i, d);
330  errors++;
331  }
332  if (!drivers[i]->dev_acquisition_start) {
333  sr_err("No dev_acquisition_start in driver %d ('%s').",
334  i, d);
335  errors++;
336  }
337  if (!drivers[i]->dev_acquisition_stop) {
338  sr_err("No dev_acquisition_stop in driver %d ('%s').",
339  i, d);
340  errors++;
341  }
342 
343  /* Note: 'priv' is allowed to be NULL. */
344 
345  if (errors == 0)
346  continue;
347 
348  ret = SR_ERR;
349  }
350 
351  return ret;
352 }
353 
354 /**
355  * Sanity-check all libsigrok input modules.
356  *
357  * @retval SR_OK All modules are OK
358  * @retval SR_ERR One or more modules have issues.
359  */
360 static int sanity_check_all_input_modules(void)
361 {
362  int i, errors, ret = SR_OK;
363  const struct sr_input_module **inputs;
364  const char *d;
365 
366  sr_spew("Sanity-checking all input modules.");
367 
368  inputs = sr_input_list();
369  for (i = 0; inputs[i]; i++) {
370  errors = 0;
371 
372  d = (inputs[i]->id) ? inputs[i]->id : "NULL";
373 
374  if (!inputs[i]->id) {
375  sr_err("No ID in module %d ('%s').", i, d);
376  errors++;
377  }
378  if (!inputs[i]->name) {
379  sr_err("No name in module %d ('%s').", i, d);
380  errors++;
381  }
382  if (!inputs[i]->desc) {
383  sr_err("No description in module %d ('%s').", i, d);
384  errors++;
385  }
386  if (!inputs[i]->init) {
387  sr_err("No init in module %d ('%s').", i, d);
388  errors++;
389  }
390  if (!inputs[i]->receive) {
391  sr_err("No receive in module %d ('%s').", i, d);
392  errors++;
393  }
394  if (!inputs[i]->end) {
395  sr_err("No end in module %d ('%s').", i, d);
396  errors++;
397  }
398 
399  if (errors == 0)
400  continue;
401 
402  ret = SR_ERR;
403  }
404 
405  return ret;
406 }
407 
408 /**
409  * Sanity-check all libsigrok output modules.
410  *
411  * @retval SR_OK All modules are OK
412  * @retval SR_ERR One or more modules have issues.
413  */
414 static int sanity_check_all_output_modules(void)
415 {
416  int i, errors, ret = SR_OK;
417  const struct sr_output_module **outputs;
418  const char *d;
419 
420  sr_spew("Sanity-checking all output modules.");
421 
422  outputs = sr_output_list();
423  for (i = 0; outputs[i]; i++) {
424  errors = 0;
425 
426  d = (outputs[i]->id) ? outputs[i]->id : "NULL";
427 
428  if (!outputs[i]->id) {
429  sr_err("No ID in module %d ('%s').", i, d);
430  errors++;
431  }
432  if (!outputs[i]->name) {
433  sr_err("No name in module %d ('%s').", i, d);
434  errors++;
435  }
436  if (!outputs[i]->desc) {
437  sr_err("No description in module '%s'.", d);
438  errors++;
439  }
440  if (!outputs[i]->receive) {
441  sr_err("No receive in module '%s'.", d);
442  errors++;
443  }
444 
445  if (errors == 0)
446  continue;
447 
448  ret = SR_ERR;
449  }
450 
451  return ret;
452 }
453 
454 /**
455  * Sanity-check all libsigrok transform modules.
456  *
457  * @retval SR_OK All modules are OK
458  * @retval SR_ERR One or more modules have issues.
459  */
460 static int sanity_check_all_transform_modules(void)
461 {
462  int i, errors, ret = SR_OK;
463  const struct sr_transform_module **transforms;
464  const char *d;
465 
466  sr_spew("Sanity-checking all transform modules.");
467 
468  transforms = sr_transform_list();
469  for (i = 0; transforms[i]; i++) {
470  errors = 0;
471 
472  d = (transforms[i]->id) ? transforms[i]->id : "NULL";
473 
474  if (!transforms[i]->id) {
475  sr_err("No ID in module %d ('%s').", i, d);
476  errors++;
477  }
478  if (!transforms[i]->name) {
479  sr_err("No name in module %d ('%s').", i, d);
480  errors++;
481  }
482  if (!transforms[i]->desc) {
483  sr_err("No description in module '%s'.", d);
484  errors++;
485  }
486  /* Note: options() is optional. */
487  /* Note: init() is optional. */
488  if (!transforms[i]->receive) {
489  sr_err("No receive in module '%s'.", d);
490  errors++;
491  }
492  /* Note: cleanup() is optional. */
493 
494  if (errors == 0)
495  continue;
496 
497  ret = SR_ERR;
498  }
499 
500  return ret;
501 }
502 
503 /**
504  * Initialize libsigrok.
505  *
506  * This function must be called before any other libsigrok function.
507  *
508  * @param ctx Pointer to a libsigrok context struct pointer. Must not be NULL.
509  * This will be a pointer to a newly allocated libsigrok context
510  * object upon success, and is undefined upon errors.
511  *
512  * @return SR_OK upon success, a (negative) error code otherwise. Upon errors
513  * the 'ctx' pointer is undefined and should not be used. Upon success,
514  * the context will be free'd by sr_exit() as part of the libsigrok
515  * shutdown.
516  *
517  * @since 0.2.0
518  */
519 SR_API int sr_init(struct sr_context **ctx)
520 {
521  int ret = SR_ERR;
522  struct sr_context *context;
523 #ifdef _WIN32
524  WSADATA wsadata;
525 #endif
526 
527  print_versions();
528 
529  if (!ctx) {
530  sr_err("%s(): libsigrok context was NULL.", __func__);
531  return SR_ERR;
532  }
533 
534  context = g_malloc0(sizeof(struct sr_context));
535 
536  sr_drivers_init(context);
537 
538  if (sanity_check_all_drivers(context) < 0) {
539  sr_err("Internal driver error(s), aborting.");
540  return ret;
541  }
542 
543  if (sanity_check_all_input_modules() < 0) {
544  sr_err("Internal input module error(s), aborting.");
545  return ret;
546  }
547 
548  if (sanity_check_all_output_modules() < 0) {
549  sr_err("Internal output module error(s), aborting.");
550  return ret;
551  }
552 
553  if (sanity_check_all_transform_modules() < 0) {
554  sr_err("Internal transform module error(s), aborting.");
555  return ret;
556  }
557 
558 #ifdef _WIN32
559  if ((ret = WSAStartup(MAKEWORD(2, 2), &wsadata)) != 0) {
560  sr_err("WSAStartup failed with error code %d.", ret);
561  ret = SR_ERR;
562  goto done;
563  }
564 #endif
565 
566 #ifdef HAVE_LIBUSB_1_0
567  ret = libusb_init(&context->libusb_ctx);
568  if (LIBUSB_SUCCESS != ret) {
569  sr_err("libusb_init() returned %s.", libusb_error_name(ret));
570  ret = SR_ERR;
571  goto done;
572  }
573 #endif
574  sr_resource_set_hooks(context, NULL, NULL, NULL, NULL);
575 
576  *ctx = context;
577  context = NULL;
578  ret = SR_OK;
579 
580 #if defined(HAVE_LIBUSB_1_0) || defined(_WIN32)
581 done:
582 #endif
583  g_free(context);
584  return ret;
585 }
586 
587 /**
588  * Shutdown libsigrok.
589  *
590  * @param ctx Pointer to a libsigrok context struct. Must not be NULL.
591  *
592  * @retval SR_OK Success
593  * @retval other Error code SR_ERR, ...
594  *
595  * @since 0.2.0
596  */
597 SR_API int sr_exit(struct sr_context *ctx)
598 {
599  if (!ctx) {
600  sr_err("%s(): libsigrok context was NULL.", __func__);
601  return SR_ERR;
602  }
603 
604  sr_hw_cleanup_all(ctx);
605 
606 #ifdef _WIN32
607  WSACleanup();
608 #endif
609 
610 #ifdef HAVE_LIBUSB_1_0
611  libusb_exit(ctx->libusb_ctx);
612 #endif
613 
614  g_free(sr_driver_list(ctx));
615  g_free(ctx);
616 
617  return SR_OK;
618 }
619 
620 /** @} */
Generic/unspecified error.
Definition: libsigrok.h:68
const char * sr_lib_version_string_get(void)
Get the libsigrok library version number as a string.
Definition: version.c:142
int api_version
API version (currently 1).
Definition: libsigrok.h:1107
#define SR_PACKAGE_VERSION_STRING
The libsigrok package version ("major.minor.micro") as string.
Definition: version.h:50
No error.
Definition: libsigrok.h:67
#define SR_LIB_VERSION_STRING
The libsigrok libtool version ("current:revision:age") as string.
Definition: version.h:66
int(* cleanup)(const struct sr_dev_driver *driver)
Called before driver is unloaded.
Definition: libsigrok.h:1112
The public libsigrok header file to be used by frontends.
GSList * sr_buildinfo_libs_get(void)
Definition: backend.c:125
const char * name
Driver name.
Definition: libsigrok.h:1103
int(* dev_open)(struct sr_dev_inst *sdi)
Open device.
Definition: libsigrok.h:1154
struct sr_dev_driver ** sr_driver_list(const struct sr_context *ctx)
Return the list of supported hardware drivers.
Definition: hwdriver.c:356
GSList *(* dev_list)(const struct sr_dev_driver *driver)
Get list of device instances the driver knows about.
Definition: libsigrok.h:1124
const char * longname
Long name.
Definition: libsigrok.h:1105
char * sr_buildinfo_host_get(void)
Definition: backend.c:180
int sr_resource_set_hooks(struct sr_context *ctx, sr_resource_open_callback open_cb, sr_resource_close_callback close_cb, sr_resource_read_callback read_cb, void *cb_data)
Install resource access hooks.
Definition: resource.c:217
int(* dev_acquisition_start)(const struct sr_dev_inst *sdi)
Begin data acquisition on the specified device.
Definition: libsigrok.h:1158
int(* config_list)(uint32_t key, GVariant **data, const struct sr_dev_inst *sdi, const struct sr_channel_group *cg)
List all possible values for a configuration key in a device instance.
Definition: libsigrok.h:1148
int sr_exit(struct sr_context *ctx)
Shutdown libsigrok.
Definition: backend.c:597
const struct sr_transform_module ** sr_transform_list(void)
Returns a NULL-terminated list of all available transform modules.
Definition: transform.c:62
const char * sr_package_version_string_get(void)
Get the libsigrok package version number as a string.
Definition: version.c:93
int(* dev_acquisition_stop)(struct sr_dev_inst *sdi)
End data acquisition on the specified device.
Definition: libsigrok.h:1160
int sr_init(struct sr_context **ctx)
Initialize libsigrok.
Definition: backend.c:519
const struct sr_output_module ** sr_output_list(void)
Returns a NULL-terminated list of all available output modules.
Definition: output.c:89
Device driver data.
Definition: libsigrok.h:1100
int(* dev_close)(struct sr_dev_inst *sdi)
Close device.
Definition: libsigrok.h:1156
GSList *(* scan)(struct sr_dev_driver *driver, GSList *options)
Scan for devices.
Definition: libsigrok.h:1119
const struct sr_input_module ** sr_input_list(void)
Returns a NULL-terminated list of all available input modules.
Definition: input.c:87
Function argument error.
Definition: libsigrok.h:70
int(* config_set)(uint32_t key, GVariant *data, const struct sr_dev_inst *sdi, const struct sr_channel_group *cg)
Set value of a configuration key in driver or a given device instance.
Definition: libsigrok.h:1135
char * sr_buildinfo_scpi_backends_get(void)
Definition: backend.c:191
int(* init)(struct sr_dev_driver *driver, struct sr_context *sr_ctx)
Called when driver is loaded, e.g.
Definition: libsigrok.h:1109
Opaque structure representing a libsigrok context.
#define SR_API
Definition: libsigrok.h:121