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