libsigrok  0.3.0
sigrok hardware access and backend library
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 <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 /** @cond PRIVATE */
27 #define LOG_PREFIX "backend"
28 /** @endcond */
29 
30 extern struct sr_session *session;
31 
32 /**
33  * @mainpage libsigrok API
34  *
35  * @section sec_intro Introduction
36  *
37  * The <a href="http://sigrok.org">sigrok</a> project aims at creating a
38  * portable, cross-platform, Free/Libre/Open-Source signal analysis software
39  * suite that supports various device types (such as logic analyzers,
40  * oscilloscopes, multimeters, and more).
41  *
42  * <a href="http://sigrok.org/wiki/Libsigrok">libsigrok</a> is a shared
43  * library written in C which provides the basic API for talking to
44  * <a href="http://sigrok.org/wiki/Supported_hardware">supported hardware</a>
45  * and reading/writing the acquired data into various
46  * <a href="http://sigrok.org/wiki/Input_output_formats">input/output
47  * file formats</a>.
48  *
49  * @section sec_api API reference
50  *
51  * See the "Modules" page for an introduction to various libsigrok
52  * related topics and the detailed API documentation of the respective
53  * functions.
54  *
55  * You can also browse the API documentation by file, or review all
56  * data structures.
57  *
58  * @section sec_mailinglists Mailing lists
59  *
60  * There are two mailing lists for sigrok/libsigrok: <a href="https://lists.sourceforge.net/lists/listinfo/sigrok-devel">sigrok-devel</a> and <a href="https://lists.sourceforge.net/lists/listinfo/sigrok-commits">sigrok-commits</a>.
61  *
62  * @section sec_irc IRC
63  *
64  * You can find the sigrok developers in the
65  * <a href="irc://chat.freenode.net/sigrok">\#sigrok</a>
66  * IRC channel on Freenode.
67  *
68  * @section sec_website Website
69  *
70  * <a href="http://sigrok.org/wiki/Libsigrok">sigrok.org/wiki/Libsigrok</a>
71  */
72 
73 /**
74  * @file
75  *
76  * Initializing and shutting down libsigrok.
77  */
78 
79 /**
80  * @defgroup grp_init Initialization
81  *
82  * Initializing and shutting down libsigrok.
83  *
84  * Before using any of the libsigrok functionality, sr_init() must
85  * be called to initialize the library, which will return a struct sr_context
86  * when the initialization was successful.
87  *
88  * When libsigrok functionality is no longer needed, sr_exit() should be
89  * called, which will (among other things) free the struct sr_context.
90  *
91  * Example for a minimal program using libsigrok:
92  *
93  * @code{.c}
94  * #include <stdio.h>
95  * #include <libsigrok/libsigrok.h>
96  *
97  * int main(int argc, char **argv)
98  * {
99  * int ret;
100  * struct sr_context *sr_ctx;
101  *
102  * if ((ret = sr_init(&sr_ctx)) != SR_OK) {
103  * printf("Error initializing libsigrok (%s): %s.\n",
104  * sr_strerror_name(ret), sr_strerror(ret));
105  * return 1;
106  * }
107  *
108  * // Use libsigrok functions here...
109  *
110  * if ((ret = sr_exit(sr_ctx)) != SR_OK) {
111  * printf("Error shutting down libsigrok (%s): %s.\n",
112  * sr_strerror_name(ret), sr_strerror(ret));
113  * return 1;
114  * }
115  *
116  * return 0;
117  * }
118  * @endcode
119  *
120  * @{
121  */
122 
123 /**
124  * Sanity-check all libsigrok drivers.
125  *
126  * @retval SR_OK All drivers are OK
127  * @retval SR_ERR One or more drivers have issues.
128  */
129 static int sanity_check_all_drivers(void)
130 {
131  int i, errors, ret = SR_OK;
132  struct sr_dev_driver **drivers;
133  const char *d;
134 
135  sr_spew("Sanity-checking all drivers.");
136 
137  drivers = sr_driver_list();
138  for (i = 0; drivers[i]; i++) {
139  errors = 0;
140 
141  d = (drivers[i]->name) ? drivers[i]->name : "NULL";
142 
143  if (!drivers[i]->name) {
144  sr_err("No name in driver %d ('%s').", i, d);
145  errors++;
146  }
147  if (!drivers[i]->longname) {
148  sr_err("No longname in driver %d ('%s').", i, d);
149  errors++;
150  }
151  if (drivers[i]->api_version < 1) {
152  sr_err("API version in driver %d ('%s') < 1.", i, d);
153  errors++;
154  }
155  if (!drivers[i]->init) {
156  sr_err("No init in driver %d ('%s').", i, d);
157  errors++;
158  }
159  if (!drivers[i]->cleanup) {
160  sr_err("No cleanup in driver %d ('%s').", i, d);
161  errors++;
162  }
163  if (!drivers[i]->scan) {
164  sr_err("No scan in driver %d ('%s').", i, d);
165  errors++;
166  }
167  if (!drivers[i]->dev_list) {
168  sr_err("No dev_list in driver %d ('%s').", i, d);
169  errors++;
170  }
171  /* Note: config_get() is optional. */
172  if (!drivers[i]->config_set) {
173  sr_err("No config_set in driver %d ('%s').", i, d);
174  errors++;
175  }
176  if (!drivers[i]->config_list) {
177  sr_err("No config_list in driver %d ('%s').", i, d);
178  errors++;
179  }
180  if (!drivers[i]->dev_open) {
181  sr_err("No dev_open in driver %d ('%s').", i, d);
182  errors++;
183  }
184  if (!drivers[i]->dev_close) {
185  sr_err("No dev_close in driver %d ('%s').", i, d);
186  errors++;
187  }
188  if (!drivers[i]->dev_acquisition_start) {
189  sr_err("No dev_acquisition_start in driver %d ('%s').",
190  i, d);
191  errors++;
192  }
193  if (!drivers[i]->dev_acquisition_stop) {
194  sr_err("No dev_acquisition_stop in driver %d ('%s').",
195  i, d);
196  errors++;
197  }
198 
199  /* Note: 'priv' is allowed to be NULL. */
200 
201  if (errors == 0)
202  continue;
203 
204  ret = SR_ERR;
205  }
206 
207  return ret;
208 }
209 
210 /**
211  * Sanity-check all libsigrok input modules.
212  *
213  * @retval SR_OK All modules are OK
214  * @retval SR_ERR One or more modules have issues.
215  */
216 static int sanity_check_all_input_modules(void)
217 {
218  int i, errors, ret = SR_OK;
219  struct sr_input_format **inputs;
220  const char *d;
221 
222  sr_spew("Sanity-checking all input modules.");
223 
224  inputs = sr_input_list();
225  for (i = 0; inputs[i]; i++) {
226  errors = 0;
227 
228  d = (inputs[i]->id) ? inputs[i]->id : "NULL";
229 
230  if (!inputs[i]->id) {
231  sr_err("No ID in module %d ('%s').", i, d);
232  errors++;
233  }
234  if (!inputs[i]->description) {
235  sr_err("No description in module %d ('%s').", i, d);
236  errors++;
237  }
238  if (!inputs[i]->format_match) {
239  sr_err("No format_match in module %d ('%s').", i, d);
240  errors++;
241  }
242  if (!inputs[i]->init) {
243  sr_err("No init in module %d ('%s').", i, d);
244  errors++;
245  }
246  if (!inputs[i]->loadfile) {
247  sr_err("No loadfile in module %d ('%s').", i, d);
248  errors++;
249  }
250 
251  if (errors == 0)
252  continue;
253 
254  ret = SR_ERR;
255  }
256 
257  return ret;
258 }
259 
260 /**
261  * Sanity-check all libsigrok output modules.
262  *
263  * @retval SR_OK All modules are OK
264  * @retval SR_ERR One or more modules have issues.
265  */
266 static int sanity_check_all_output_modules(void)
267 {
268  int i, errors, ret = SR_OK;
269  struct sr_output_format **outputs;
270  const char *d;
271 
272  sr_spew("Sanity-checking all output modules.");
273 
274  outputs = sr_output_list();
275  for (i = 0; outputs[i]; i++) {
276  errors = 0;
277 
278  d = (outputs[i]->id) ? outputs[i]->id : "NULL";
279 
280  if (!outputs[i]->id) {
281  sr_err("No ID in module %d ('%s').", i, d);
282  errors++;
283  }
284  if (!outputs[i]->description) {
285  sr_err("No description in module '%s'.", d);
286  errors++;
287  }
288  if (!outputs[i]->receive) {
289  sr_err("No receive in module '%s'.", d);
290  errors++;
291  }
292 
293  if (errors == 0)
294  continue;
295 
296  ret = SR_ERR;
297  }
298 
299  return ret;
300 }
301 
302 /**
303  * Initialize libsigrok.
304  *
305  * This function must be called before any other libsigrok function.
306  *
307  * @param ctx Pointer to a libsigrok context struct pointer. Must not be NULL.
308  * This will be a pointer to a newly allocated libsigrok context
309  * object upon success, and is undefined upon errors.
310  *
311  * @return SR_OK upon success, a (negative) error code otherwise. Upon errors
312  * the 'ctx' pointer is undefined and should not be used. Upon success,
313  * the context will be free'd by sr_exit() as part of the libsigrok
314  * shutdown.
315  *
316  * @since 0.2.0
317  */
318 SR_API int sr_init(struct sr_context **ctx)
319 {
320  int ret = SR_ERR;
321  struct sr_context *context;
322 
323  if (!ctx) {
324  sr_err("%s(): libsigrok context was NULL.", __func__);
325  return SR_ERR;
326  }
327 
328  if (sanity_check_all_drivers() < 0) {
329  sr_err("Internal driver error(s), aborting.");
330  return ret;
331  }
332 
333  if (sanity_check_all_input_modules() < 0) {
334  sr_err("Internal input module error(s), aborting.");
335  return ret;
336  }
337 
338  if (sanity_check_all_output_modules() < 0) {
339  sr_err("Internal output module error(s), aborting.");
340  return ret;
341  }
342 
343  /* + 1 to handle when struct sr_context has no members. */
344  context = g_try_malloc0(sizeof(struct sr_context) + 1);
345 
346  if (!context) {
347  ret = SR_ERR_MALLOC;
348  goto done;
349  }
350 
351 #ifdef HAVE_LIBUSB_1_0
352  ret = libusb_init(&context->libusb_ctx);
353  if (LIBUSB_SUCCESS != ret) {
354  sr_err("libusb_init() returned %s.", libusb_error_name(ret));
355  ret = SR_ERR;
356  goto done;
357  }
358 #endif
359 
360  *ctx = context;
361  context = NULL;
362  session = NULL;
363  ret = SR_OK;
364 
365 done:
366  if (context)
367  g_free(context);
368  return ret;
369 }
370 
371 /**
372  * Shutdown libsigrok.
373  *
374  * @param ctx Pointer to a libsigrok context struct. Must not be NULL.
375  *
376  * @retval SR_OK Success
377  * @retval other Error code SR_ERR, ...
378  *
379  * @since 0.2.0
380  */
381 SR_API int sr_exit(struct sr_context *ctx)
382 {
383  if (!ctx) {
384  sr_err("%s(): libsigrok context was NULL.", __func__);
385  return SR_ERR;
386  }
387 
388  sr_hw_cleanup_all();
389 
390 #ifdef HAVE_LIBUSB_1_0
391  libusb_exit(ctx->libusb_ctx);
392 #endif
393 
394  g_free(ctx);
395 
396  return SR_OK;
397 }
398 
399 /** @} */
Generic/unspecified error.
Definition: libsigrok.h:68
char * description
A short description of the input format, which can (for example) be displayed to the user by frontend...
Definition: libsigrok.h:383
struct sr_session * session
Definition: session.c:64
int(* format_match)(const char *filename)
Check if this input module can load and parse the specified file.
Definition: libsigrok.h:393
int(* cleanup)(void)
Called before driver is unloaded.
Definition: libsigrok.h:903
struct sr_input_format ** sr_input_list(void)
Definition: input.c:71
int(* dev_acquisition_stop)(struct sr_dev_inst *sdi, void *cb_data)
End data acquisition on the specified device.
Definition: libsigrok.h:952
No error.
Definition: libsigrok.h:67
char * longname
Long name.
Definition: libsigrok.h:896
int sr_exit(struct sr_context *ctx)
Shutdown libsigrok.
Definition: backend.c:381
int(* loadfile)(struct sr_input *in, const char *filename)
Load a file, parsing the input according to the file's format.
Definition: libsigrok.h:428
The public libsigrok header file to be used by frontends.
int(* dev_acquisition_start)(const struct sr_dev_inst *sdi, void *cb_data)
Begin data acquisition on the specified device.
Definition: libsigrok.h:949
char * description
A short description of the output format.
Definition: libsigrok.h:477
GSList *(* scan)(GSList *options)
Scan for devices.
Definition: libsigrok.h:910
int api_version
API version (currently 1).
Definition: libsigrok.h:898
struct sr_dev_driver ** sr_driver_list(void)
Return the list of supported hardware drivers.
Definition: hwdriver.c:446
int(* receive)(struct sr_output *o, const struct sr_datafeed_packet *packet, GString **out)
This function is passed a copy of every packed in the data feed.
Definition: libsigrok.h:514
int(* config_set)(int id, 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:926
Input (file) format driver.
Definition: libsigrok.h:375
int(* dev_close)(struct sr_dev_inst *sdi)
Close device.
Definition: libsigrok.h:947
Opaque data structure representing a libsigrok session.
Opaque structure representing a libsigrok context.
Malloc/calloc/realloc error.
Definition: libsigrok.h:69
GSList *(* dev_list)(void)
Get list of device instances the driver knows about.
Definition: libsigrok.h:915
int(* dev_open)(struct sr_dev_inst *sdi)
Open device.
Definition: libsigrok.h:945
int(* config_list)(int info_id, 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:939
char * id
The unique ID for this input format.
Definition: libsigrok.h:377
struct sr_output_format ** sr_output_list(void)
Definition: output.c:77
Device driver data.
Definition: libsigrok.h:891
char * name
Driver name.
Definition: libsigrok.h:894
int(* init)(struct sr_context *sr_ctx)
Called when driver is loaded, e.g.
Definition: libsigrok.h:900
int sr_init(struct sr_context **ctx)
Initialize libsigrok.
Definition: backend.c:318
int(* init)(struct sr_input *in, const char *filename)
Initialize the input module.
Definition: libsigrok.h:406
Output (file) format driver.
Definition: libsigrok.h:460
char * id
A unique ID for this output format.
Definition: libsigrok.h:469
#define SR_API
Definition: libsigrok.h:122