libsigrokdecode  0.2.0
sigrok protocol decoding library
 All Data Structures Files Functions Variables Typedefs Enumerator Macros Groups Pages
controller.c
Go to the documentation of this file.
1 /*
2  * This file is part of the libsigrokdecode project.
3  *
4  * Copyright (C) 2010 Uwe Hermann <uwe@hermann-uwe.de>
5  * Copyright (C) 2012 Bert Vermeulen <bert@biot.com>
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 "libsigrokdecode.h" /* First, so we avoid a _POSIX_C_SOURCE warning. */
22 #include "libsigrokdecode-internal.h"
23 #include "config.h"
24 #include <glib.h>
25 #include <inttypes.h>
26 #include <stdlib.h>
27 
28 /**
29  * @mainpage libsigrokdecode 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/Libsigrokdecode">libsigrokdecode</a> is a
39  * shared library written in C which provides the basic API for (streaming)
40  * protocol decoding functionality.
41  *
42  * The <a href="http://sigrok.org/wiki/Protocol_decoders">protocol decoders</a>
43  * are written in Python (>= 3.0).
44  *
45  * @section sec_api API reference
46  *
47  * See the "Modules" page for an introduction to various libsigrokdecode
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/libsigrokdecode: <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/Libsigrokdecode">sigrok.org/wiki/Libsigrokdecode</a>
67  */
68 
69 /**
70  * @file
71  *
72  * Initializing and shutting down libsigrokdecode.
73  */
74 
75 /**
76  * @defgroup grp_init Initialization
77  *
78  * Initializing and shutting down libsigrokdecode.
79  *
80  * Before using any of the libsigrokdecode functionality, srd_init() must
81  * be called to initialize the library.
82  *
83  * When libsigrokdecode functionality is no longer needed, srd_exit() should
84  * be called.
85  *
86  * @{
87  */
88 
89 /* List of decoder instances. */
90 static GSList *di_list = NULL;
91 
92 /* List of frontend callbacks to receive decoder output. */
93 static GSList *callbacks = NULL;
94 
95 /** @cond PRIVATE */
96 
97 /* decoder.c */
98 extern SRD_PRIV GSList *pd_list;
99 
100 /* module_sigrokdecode.c */
101 /* FIXME: SRD_PRIV causes issues on MinGW. Investigate. */
102 extern PyMODINIT_FUNC PyInit_sigrokdecode(void);
103 
104 /* type_logic.c */
105 extern SRD_PRIV PyTypeObject srd_logic_type;
106 
107 /** @endcond */
108 
109 /**
110  * Initialize libsigrokdecode.
111  *
112  * This initializes the Python interpreter, and creates and initializes
113  * a "sigrokdecode" Python module.
114  *
115  * Then, it searches for sigrok protocol decoders in the "decoders"
116  * subdirectory of the the libsigrokdecode installation directory.
117  * All decoders that are found are loaded into memory and added to an
118  * internal list of decoders, which can be queried via srd_decoder_list().
119  *
120  * The caller is responsible for calling the clean-up function srd_exit(),
121  * which will properly shut down libsigrokdecode and free its allocated memory.
122  *
123  * Multiple calls to srd_init(), without calling srd_exit() in between,
124  * are not allowed.
125  *
126  * @param path Path to an extra directory containing protocol decoders
127  * which will be added to the Python sys.path. May be NULL.
128  *
129  * @return SRD_OK upon success, a (negative) error code otherwise.
130  * Upon Python errors, SRD_ERR_PYTHON is returned. If the decoders
131  * directory cannot be accessed, SRD_ERR_DECODERS_DIR is returned.
132  * If not enough memory could be allocated, SRD_ERR_MALLOC is returned.
133  *
134  * @since 0.1.0
135  */
136 SRD_API int srd_init(const char *path)
137 {
138  int ret;
139  char *env_path;
140 
141  srd_dbg("Initializing libsigrokdecode.");
142 
143  /* Add our own module to the list of built-in modules. */
144  PyImport_AppendInittab("sigrokdecode", PyInit_sigrokdecode);
145 
146  /* Initialize the Python interpreter. */
147  Py_Initialize();
148 
149  /* Installed decoders. */
150  if ((ret = srd_decoder_searchpath_add(DECODERS_DIR)) != SRD_OK) {
151  Py_Finalize();
152  return ret;
153  }
154 
155  /* Path specified by the user. */
156  if (path) {
157  if ((ret = srd_decoder_searchpath_add(path)) != SRD_OK) {
158  Py_Finalize();
159  return ret;
160  }
161  }
162 
163  /* Environment variable overrides everything, for debugging. */
164  if ((env_path = getenv("SIGROKDECODE_DIR"))) {
165  if ((ret = srd_decoder_searchpath_add(env_path)) != SRD_OK) {
166  Py_Finalize();
167  return ret;
168  }
169  }
170 
171  return SRD_OK;
172 }
173 
174 /**
175  * Shutdown libsigrokdecode.
176  *
177  * This frees all the memory allocated for protocol decoders and shuts down
178  * the Python interpreter.
179  *
180  * This function should only be called if there was a (successful!) invocation
181  * of srd_init() before. Calling this function multiple times in a row, without
182  * any successful srd_init() calls in between, is not allowed.
183  *
184  * @return SRD_OK upon success, a (negative) error code otherwise.
185  *
186  * @since 0.1.0
187  */
188 SRD_API int srd_exit(void)
189 {
190  srd_dbg("Exiting libsigrokdecode.");
191 
193  g_slist_free(pd_list);
194  pd_list = NULL;
195 
196  /* Py_Finalize() returns void, any finalization errors are ignored. */
197  Py_Finalize();
198 
199  return SRD_OK;
200 }
201 
202 /**
203  * Add an additional search directory for the protocol decoders.
204  *
205  * The specified directory is prepended (not appended!) to Python's sys.path,
206  * in order to search for sigrok protocol decoders in the specified
207  * directories first, and in the generic Python module directories (and in
208  * the current working directory) last. This avoids conflicts if there are
209  * Python modules which have the same name as a sigrok protocol decoder in
210  * sys.path or in the current working directory.
211  *
212  * @param path Path to the directory containing protocol decoders which shall
213  * be added to the Python sys.path, or NULL.
214  *
215  * @return SRD_OK upon success, a (negative) error code otherwise.
216  *
217  * @private
218  *
219  * @since 0.1.0
220  */
221 SRD_PRIV int srd_decoder_searchpath_add(const char *path)
222 {
223  PyObject *py_cur_path, *py_item;
224  GString *new_path;
225  int wc_len, i;
226  wchar_t *wc_new_path;
227  char *item;
228 
229  srd_dbg("Adding '%s' to module path.", path);
230 
231  new_path = g_string_sized_new(256);
232  g_string_assign(new_path, g_strdup(path));
233  py_cur_path = PySys_GetObject("path");
234  for (i = 0; i < PyList_Size(py_cur_path); i++) {
235  g_string_append(new_path, g_strdup(G_SEARCHPATH_SEPARATOR_S));
236  py_item = PyList_GetItem(py_cur_path, i);
237  if (!PyUnicode_Check(py_item))
238  /* Shouldn't happen. */
239  continue;
240  if (py_str_as_str(py_item, &item) != SRD_OK)
241  continue;
242  g_string_append(new_path, item);
243  }
244 
245  /* Convert to wide chars. */
246  wc_len = sizeof(wchar_t) * (new_path->len + 1);
247  if (!(wc_new_path = g_try_malloc(wc_len))) {
248  srd_dbg("malloc failed");
249  return SRD_ERR_MALLOC;
250  }
251  mbstowcs(wc_new_path, new_path->str, wc_len);
252  PySys_SetPath(wc_new_path);
253  g_string_free(new_path, TRUE);
254  g_free(wc_new_path);
255 
256 //#ifdef _WIN32
257 // gchar **splitted;
258 //
259 // /*
260 // * On Windows/MinGW, Python's sys.path needs entries of the form
261 // * 'C:\\foo\\bar' instead of '/foo/bar'.
262 // */
263 //
264 // splitted = g_strsplit(DECODERS_DIR, "/", 0);
265 // path = g_build_pathv("\\\\", splitted);
266 // g_strfreev(splitted);
267 //#else
268 // path = g_strdup(DECODERS_DIR);
269 //#endif
270 
271  return SRD_OK;
272 }
273 
274 /** @} */
275 
276 /**
277  * @defgroup grp_instances Decoder instances
278  *
279  * Decoder instance handling.
280  *
281  * @{
282  */
283 
284 /**
285  * Set one or more options in a decoder instance.
286  *
287  * Handled options are removed from the hash.
288  *
289  * @param di Decoder instance.
290  * @param options A GHashTable of options to set.
291  *
292  * @return SRD_OK upon success, a (negative) error code otherwise.
293  *
294  * @since 0.1.0
295  */
297  GHashTable *options)
298 {
299  PyObject *py_dec_options, *py_dec_optkeys, *py_di_options, *py_optval;
300  PyObject *py_optlist, *py_classval;
301  Py_UNICODE *py_ustr;
302  GVariant *value;
303  unsigned long long int val_ull;
304  gint64 val_int;
305  int num_optkeys, ret, size, i;
306  const char *val_str;
307  char *dbg, *key;
308 
309  if (!PyObject_HasAttrString(di->decoder->py_dec, "options")) {
310  /* Decoder has no options. */
311  if (g_hash_table_size(options) == 0) {
312  /* No options provided. */
313  return SRD_OK;
314  } else {
315  srd_err("Protocol decoder has no options.");
316  return SRD_ERR_ARG;
317  }
318  return SRD_OK;
319  }
320 
321  ret = SRD_ERR_PYTHON;
322  key = NULL;
323  py_dec_options = py_dec_optkeys = py_di_options = py_optval = NULL;
324  py_optlist = py_classval = NULL;
325  py_dec_options = PyObject_GetAttrString(di->decoder->py_dec, "options");
326 
327  /* All of these are synthesized objects, so they're good. */
328  py_dec_optkeys = PyDict_Keys(py_dec_options);
329  num_optkeys = PyList_Size(py_dec_optkeys);
330  if (!(py_di_options = PyObject_GetAttrString(di->py_inst, "options")))
331  goto err_out;
332  for (i = 0; i < num_optkeys; i++) {
333  /* Get the default class value for this option. */
334  py_str_as_str(PyList_GetItem(py_dec_optkeys, i), &key);
335  if (!(py_optlist = PyDict_GetItemString(py_dec_options, key)))
336  goto err_out;
337  if (!(py_classval = PyList_GetItem(py_optlist, 1)))
338  goto err_out;
339  if (!PyUnicode_Check(py_classval) && !PyLong_Check(py_classval)) {
340  srd_err("Options of type %s are not yet supported.",
341  Py_TYPE(py_classval)->tp_name);
342  goto err_out;
343  }
344 
345  if ((value = g_hash_table_lookup(options, key))) {
346  dbg = g_variant_print(value, TRUE);
347  srd_dbg("got option '%s' = %s", key, dbg);
348  g_free(dbg);
349  /* An override for this option was provided. */
350  if (PyUnicode_Check(py_classval)) {
351  if (!g_variant_is_of_type(value, G_VARIANT_TYPE_STRING)) {
352  srd_err("Option '%s' requires a string value.", key);
353  goto err_out;
354  }
355  val_str = g_variant_get_string(value, NULL);
356  if (!(py_optval = PyUnicode_FromString(val_str))) {
357  /* Some UTF-8 encoding error. */
358  PyErr_Clear();
359  srd_err("Option '%s' requires a UTF-8 string value.", key);
360  goto err_out;
361  }
362  } else if (PyLong_Check(py_classval)) {
363  if (!g_variant_is_of_type(value, G_VARIANT_TYPE_INT64)) {
364  srd_err("Option '%s' requires an integer value.", key);
365  goto err_out;
366  }
367  val_int = g_variant_get_int64(value);
368  if (!(py_optval = PyLong_FromLong(val_int))) {
369  /* ValueError Exception */
370  PyErr_Clear();
371  srd_err("Option '%s' has invalid integer value.", key);
372  goto err_out;
373  }
374  }
375  g_hash_table_remove(options, key);
376  } else {
377  /* Use the class default for this option. */
378  if (PyUnicode_Check(py_classval)) {
379  /* Make a brand new copy of the string. */
380  py_ustr = PyUnicode_AS_UNICODE(py_classval);
381  size = PyUnicode_GET_SIZE(py_classval);
382  py_optval = PyUnicode_FromUnicode(py_ustr, size);
383  } else if (PyLong_Check(py_classval)) {
384  /* Make a brand new copy of the integer. */
385  val_ull = PyLong_AsUnsignedLongLong(py_classval);
386  if (val_ull == (unsigned long long)-1) {
387  /* OverFlowError exception */
388  PyErr_Clear();
389  srd_err("Invalid integer value for %s: "
390  "expected integer.", key);
391  goto err_out;
392  }
393  if (!(py_optval = PyLong_FromUnsignedLongLong(val_ull)))
394  goto err_out;
395  }
396  }
397 
398  /*
399  * If we got here, py_optval holds a known good new reference
400  * to the instance option to set.
401  */
402  if (PyDict_SetItemString(py_di_options, key, py_optval) == -1)
403  goto err_out;
404  }
405 
406  ret = SRD_OK;
407 
408 err_out:
409  Py_XDECREF(py_optlist);
410  Py_XDECREF(py_di_options);
411  Py_XDECREF(py_dec_optkeys);
412  Py_XDECREF(py_dec_options);
413  g_free(key);
414  if (PyErr_Occurred())
415  srd_exception_catch("Stray exception in srd_inst_option_set().");
416 
417  return ret;
418 }
419 
420 /* Helper GComparefunc for g_slist_find_custom() in srd_inst_probe_set_all() */
421 static gint compare_probe_id(const struct srd_probe *a, const char *probe_id)
422 {
423  return strcmp(a->id, probe_id);
424 }
425 
426 /**
427  * Set all probes in a decoder instance.
428  *
429  * This function sets _all_ probes for the specified decoder instance, i.e.,
430  * it overwrites any probes that were already defined (if any).
431  *
432  * @param di Decoder instance.
433  * @param new_probes A GHashTable of probes to set. Key is probe name, value is
434  * the probe number. Samples passed to this instance will be
435  * arranged in this order.
436  *
437  * @return SRD_OK upon success, a (negative) error code otherwise.
438  *
439  * @since 0.1.0
440  */
442  GHashTable *new_probes)
443 {
444  GVariant *probe_val;
445  GList *l;
446  GSList *sl;
447  struct srd_probe *p;
448  int *new_probemap, new_probenum;
449  char *probe_id;
450  int i, num_required_probes;
451 
452  srd_dbg("set probes called for instance %s with list of %d probes",
453  di->inst_id, g_hash_table_size(new_probes));
454 
455  if (g_hash_table_size(new_probes) == 0)
456  /* No probes provided. */
457  return SRD_OK;
458 
459  if (di->dec_num_probes == 0) {
460  /* Decoder has no probes. */
461  srd_err("Protocol decoder %s has no probes to define.",
462  di->decoder->name);
463  return SRD_ERR_ARG;
464  }
465 
466  new_probemap = NULL;
467 
468  if (!(new_probemap = g_try_malloc(sizeof(int) * di->dec_num_probes))) {
469  srd_err("Failed to g_malloc() new probe map.");
470  return SRD_ERR_MALLOC;
471  }
472 
473  /*
474  * For now, map all indexes to probe -1 (can be overridden later).
475  * This -1 is interpreted as an unspecified probe later.
476  */
477  for (i = 0; i < di->dec_num_probes; i++)
478  new_probemap[i] = -1;
479 
480  for (l = g_hash_table_get_keys(new_probes); l; l = l->next) {
481  probe_id = l->data;
482  probe_val= g_hash_table_lookup(new_probes, probe_id);
483  if (!g_variant_is_of_type(probe_val, G_VARIANT_TYPE_INT32)) {
484  /* Probe name was specified without a value. */
485  srd_err("No probe number was specified for %s.",
486  probe_id);
487  g_free(new_probemap);
488  return SRD_ERR_ARG;
489  }
490  new_probenum = g_variant_get_int32(probe_val);
491  if (!(sl = g_slist_find_custom(di->decoder->probes, probe_id,
492  (GCompareFunc)compare_probe_id))) {
493  /* Fall back on optional probes. */
494  if (!(sl = g_slist_find_custom(di->decoder->opt_probes,
495  probe_id, (GCompareFunc) compare_probe_id))) {
496  srd_err("Protocol decoder %s has no probe "
497  "'%s'.", di->decoder->name, probe_id);
498  g_free(new_probemap);
499  return SRD_ERR_ARG;
500  }
501  }
502  p = sl->data;
503  new_probemap[p->order] = new_probenum;
504  srd_dbg("Setting probe mapping: %s (index %d) = probe %d.",
505  p->id, p->order, new_probenum);
506  }
507 
508  srd_dbg("Final probe map:");
509  num_required_probes = g_slist_length(di->decoder->probes);
510  for (i = 0; i < di->dec_num_probes; i++) {
511  srd_dbg(" - index %d = probe %d (%s)", i, new_probemap[i],
512  (i < num_required_probes) ? "required" : "optional");
513  }
514 
515  g_free(di->dec_probemap);
516  di->dec_probemap = new_probemap;
517 
518  return SRD_OK;
519 }
520 
521 /**
522  * Create a new protocol decoder instance.
523  *
524  * @param decoder_id Decoder 'id' field.
525  * @param options GHashtable of options which override the defaults set in
526  * the decoder class. May be NULL.
527  *
528  * @return Pointer to a newly allocated struct srd_decoder_inst, or
529  * NULL in case of failure.
530  *
531  * @since 0.1.0
532  */
533 SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
534  GHashTable *options)
535 {
536  int i;
537  struct srd_decoder *dec;
538  struct srd_decoder_inst *di;
539  char *inst_id;
540 
541  srd_dbg("Creating new %s instance.", decoder_id);
542 
543  if (!(dec = srd_decoder_get_by_id(decoder_id))) {
544  srd_err("Protocol decoder %s not found.", decoder_id);
545  return NULL;
546  }
547 
548  if (!(di = g_try_malloc0(sizeof(struct srd_decoder_inst)))) {
549  srd_err("Failed to g_malloc() instance.");
550  return NULL;
551  }
552 
553  di->decoder = dec;
554  if (options) {
555  inst_id = g_hash_table_lookup(options, "id");
556  di->inst_id = g_strdup(inst_id ? inst_id : decoder_id);
557  g_hash_table_remove(options, "id");
558  } else
559  di->inst_id = g_strdup(decoder_id);
560 
561  /*
562  * Prepare a default probe map, where samples come in the
563  * order in which the decoder class defined them.
564  */
565  di->dec_num_probes = g_slist_length(di->decoder->probes) +
566  g_slist_length(di->decoder->opt_probes);
567  if (di->dec_num_probes) {
568  if (!(di->dec_probemap =
569  g_try_malloc(sizeof(int) * di->dec_num_probes))) {
570  srd_err("Failed to g_malloc() probe map.");
571  g_free(di);
572  return NULL;
573  }
574  for (i = 0; i < di->dec_num_probes; i++)
575  di->dec_probemap[i] = i;
576  }
577 
578  /* Create a new instance of this decoder class. */
579  if (!(di->py_inst = PyObject_CallObject(dec->py_dec, NULL))) {
580  if (PyErr_Occurred())
581  srd_exception_catch("failed to create %s instance: ",
582  decoder_id);
583  g_free(di->dec_probemap);
584  g_free(di);
585  return NULL;
586  }
587 
588  if (options && srd_inst_option_set(di, options) != SRD_OK) {
589  g_free(di->dec_probemap);
590  g_free(di);
591  return NULL;
592  }
593 
594  /* Instance takes input from a frontend by default. */
595  di_list = g_slist_append(di_list, di);
596 
597  return di;
598 }
599 
600 /**
601  * Stack a decoder instance on top of another.
602  *
603  * @param di_from The instance to move.
604  * @param di_to The instance on top of which di_from will be stacked.
605  *
606  * @return SRD_OK upon success, a (negative) error code otherwise.
607  *
608  * @since 0.1.0
609  */
611  struct srd_decoder_inst *di_to)
612 {
613  if (!di_from || !di_to) {
614  srd_err("Invalid from/to instance pair.");
615  return SRD_ERR_ARG;
616  }
617 
618  if (g_slist_find(di_list, di_to)) {
619  /* Remove from the unstacked list. */
620  di_list = g_slist_remove(di_list, di_to);
621  }
622 
623  /* Stack on top of source di. */
624  di_from->next_di = g_slist_append(di_from->next_di, di_to);
625 
626  return SRD_OK;
627 }
628 
629 /**
630  * Find a decoder instance by its instance ID.
631  *
632  * Only the bottom level of instances are searched -- instances already stacked
633  * on top of another one will not be found.
634  *
635  * @param inst_id The instance ID to be found.
636  *
637  * @return Pointer to struct srd_decoder_inst, or NULL if not found.
638  *
639  * @since 0.1.0
640  */
642 {
643  GSList *l;
644  struct srd_decoder_inst *tmp, *di;
645 
646  di = NULL;
647  for (l = di_list; l; l = l->next) {
648  tmp = l->data;
649  if (!strcmp(tmp->inst_id, inst_id)) {
650  di = tmp;
651  break;
652  }
653  }
654 
655  return di;
656 }
657 
658 /**
659  * Find a decoder instance by its Python object.
660  *
661  * I.e. find that instance's instantiation of the sigrokdecode.Decoder class.
662  * This will recurse to find the instance anywhere in the stack tree.
663  *
664  * @param stack Pointer to a GSList of struct srd_decoder_inst, indicating the
665  * stack to search. To start searching at the bottom level of
666  * decoder instances, pass NULL.
667  * @param obj The Python class instantiation.
668  *
669  * @return Pointer to struct srd_decoder_inst, or NULL if not found.
670  *
671  * @private
672  *
673  * @since 0.1.0
674  */
675 SRD_PRIV struct srd_decoder_inst *srd_inst_find_by_obj(const GSList *stack,
676  const PyObject *obj)
677 {
678  const GSList *l;
679  struct srd_decoder_inst *tmp, *di;
680 
681  di = NULL;
682  for (l = stack ? stack : di_list; di == NULL && l != NULL; l = l->next) {
683  tmp = l->data;
684  if (tmp->py_inst == obj)
685  di = tmp;
686  else if (tmp->next_di)
687  di = srd_inst_find_by_obj(tmp->next_di, obj);
688  }
689 
690  return di;
691 }
692 
693 /** @private */
694 SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di, PyObject *args)
695 {
696  PyObject *py_name, *py_res;
697  GSList *l;
698  struct srd_decoder_inst *next_di;
699 
700  srd_dbg("Calling start() method on protocol decoder instance %s.",
701  di->inst_id);
702 
703  if (!(py_name = PyUnicode_FromString("start"))) {
704  srd_err("Unable to build Python object for 'start'.");
705  srd_exception_catch("Protocol decoder instance %s: ",
706  di->inst_id);
707  return SRD_ERR_PYTHON;
708  }
709 
710  if (!(py_res = PyObject_CallMethodObjArgs(di->py_inst,
711  py_name, args, NULL))) {
712  srd_exception_catch("Protocol decoder instance %s: ",
713  di->inst_id);
714  return SRD_ERR_PYTHON;
715  }
716 
717  Py_DecRef(py_res);
718  Py_DecRef(py_name);
719 
720  /*
721  * Start all the PDs stacked on top of this one. Pass along the
722  * metadata all the way from the bottom PD, even though it's only
723  * applicable to logic data for now.
724  */
725  for (l = di->next_di; l; l = l->next) {
726  next_di = l->data;
727  srd_inst_start(next_di, args);
728  }
729 
730  return SRD_OK;
731 }
732 
733 /**
734  * Run the specified decoder function.
735  *
736  * @param start_samplenum The starting sample number for the buffer's sample
737  * set, relative to the start of capture.
738  * @param di The decoder instance to call. Must not be NULL.
739  * @param inbuf The buffer to decode. Must not be NULL.
740  * @param inbuflen Length of the buffer. Must be > 0.
741  *
742  * @return SRD_OK upon success, a (negative) error code otherwise.
743  *
744  * @private
745  *
746  * @since 0.1.0
747  */
748 SRD_PRIV int srd_inst_decode(uint64_t start_samplenum,
749  const struct srd_decoder_inst *di, const uint8_t *inbuf,
750  uint64_t inbuflen)
751 {
752  PyObject *py_res;
753  srd_logic *logic;
754  uint64_t end_samplenum;
755 
756  srd_dbg("Calling decode() on instance %s with %d bytes starting "
757  "at sample %d.", di->inst_id, inbuflen, start_samplenum);
758 
759  /* Return an error upon unusable input. */
760  if (!di) {
761  srd_dbg("empty decoder instance");
762  return SRD_ERR_ARG;
763  }
764  if (!inbuf) {
765  srd_dbg("NULL buffer pointer");
766  return SRD_ERR_ARG;
767  }
768  if (inbuflen == 0) {
769  srd_dbg("empty buffer");
770  return SRD_ERR_ARG;
771  }
772 
773  /*
774  * Create new srd_logic object. Each iteration around the PD's loop
775  * will fill one sample into this object.
776  */
777  logic = PyObject_New(srd_logic, &srd_logic_type);
778  Py_INCREF(logic);
779  logic->di = (struct srd_decoder_inst *)di;
780  logic->start_samplenum = start_samplenum;
781  logic->itercnt = 0;
782  logic->inbuf = (uint8_t *)inbuf;
783  logic->inbuflen = inbuflen;
784  logic->sample = PyList_New(2);
785  Py_INCREF(logic->sample);
786 
787  Py_IncRef(di->py_inst);
788  end_samplenum = start_samplenum + inbuflen / di->data_unitsize;
789  if (!(py_res = PyObject_CallMethod(di->py_inst, "decode",
790  "KKO", logic->start_samplenum,
791  end_samplenum, logic))) {
792  srd_exception_catch("Protocol decoder instance %s: ",
793  di->inst_id);
794  return SRD_ERR_PYTHON;
795  }
796  Py_DecRef(py_res);
797 
798  return SRD_OK;
799 }
800 
801 /** @private */
802 SRD_PRIV void srd_inst_free(struct srd_decoder_inst *di)
803 {
804  GSList *l;
805  struct srd_pd_output *pdo;
806 
807  srd_dbg("Freeing instance %s", di->inst_id);
808 
809  Py_DecRef(di->py_inst);
810  g_free(di->inst_id);
811  g_free(di->dec_probemap);
812  g_slist_free(di->next_di);
813  for (l = di->pd_output; l; l = l->next) {
814  pdo = l->data;
815  g_free(pdo->proto_id);
816  g_free(pdo);
817  }
818  g_slist_free(di->pd_output);
819 }
820 
821 /** @private */
822 SRD_PRIV void srd_inst_free_all(GSList *stack)
823 {
824  GSList *l;
825  struct srd_decoder_inst *di;
826 
827  di = NULL;
828  for (l = stack ? stack : di_list; di == NULL && l != NULL; l = l->next) {
829  di = l->data;
830  if (di->next_di)
831  srd_inst_free_all(di->next_di);
832  srd_inst_free(di);
833  }
834  if (!stack) {
835  g_slist_free(di_list);
836  di_list = NULL;
837  }
838 }
839 
840 /** @} */
841 
842 /**
843  * @defgroup grp_session Session handling
844  *
845  * Starting and handling decoding sessions.
846  *
847  * @{
848  */
849 
850 /**
851  * Start a decoding session.
852  *
853  * Decoders, instances and stack must have been prepared beforehand.
854  *
855  * @param num_probes The number of probes which the incoming feed will contain.
856  * @param unitsize The number of bytes per sample in the incoming feed.
857  * @param samplerate The samplerate of the incoming feed.
858  *
859  * @return SRD_OK upon success, a (negative) error code otherwise.
860  *
861  * @since 0.1.0
862  */
863 SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate)
864 {
865  PyObject *args;
866  GSList *d;
867  struct srd_decoder_inst *di;
868  int ret;
869 
870  ret = SRD_OK;
871 
872  srd_dbg("Calling start() on all instances with %d probes, "
873  "unitsize %d samplerate %d.", num_probes, unitsize, samplerate);
874 
875  /*
876  * Currently only one item of metadata is passed along to decoders,
877  * samplerate. This can be extended as needed.
878  */
879  if (!(args = Py_BuildValue("{s:l}", "samplerate", (long)samplerate))) {
880  srd_err("Unable to build Python object for metadata.");
881  return SRD_ERR_PYTHON;
882  }
883 
884  /* Run the start() method on all decoders receiving frontend data. */
885  for (d = di_list; d; d = d->next) {
886  di = d->data;
887  di->data_num_probes = num_probes;
888  di->data_unitsize = unitsize;
889  di->data_samplerate = samplerate;
890  if ((ret = srd_inst_start(di, args)) != SRD_OK)
891  break;
892  }
893 
894  Py_DecRef(args);
895 
896  return ret;
897 }
898 
899 /**
900  * Send a chunk of logic sample data to a running decoder session.
901  *
902  * @param start_samplenum The sample number of the first sample in this chunk.
903  * @param inbuf Pointer to sample data.
904  * @param inbuflen Length in bytes of the buffer.
905  *
906  * @return SRD_OK upon success, a (negative) error code otherwise.
907  *
908  * @since 0.1.0
909  */
910 SRD_API int srd_session_send(uint64_t start_samplenum, const uint8_t *inbuf,
911  uint64_t inbuflen)
912 {
913  GSList *d;
914  int ret;
915 
916  srd_dbg("Calling decode() on all instances with starting sample "
917  "number %" PRIu64 ", %" PRIu64 " bytes at 0x%p",
918  start_samplenum, inbuflen, inbuf);
919 
920  for (d = di_list; d; d = d->next) {
921  if ((ret = srd_inst_decode(start_samplenum, d->data, inbuf,
922  inbuflen)) != SRD_OK)
923  return ret;
924  }
925 
926  return SRD_OK;
927 }
928 
929 /**
930  * Register/add a decoder output callback function.
931  *
932  * The function will be called when a protocol decoder sends output back
933  * to the PD controller (except for Python objects, which only go up the
934  * stack).
935  *
936  * @param output_type The output type this callback will receive. Only one
937  * callback per output type can be registered.
938  * @param cb The function to call. Must not be NULL.
939  * @param cb_data Private data for the callback function. Can be NULL.
940  *
941  * @since 0.1.0
942  */
944  srd_pd_output_callback_t cb, void *cb_data)
945 {
946  struct srd_pd_callback *pd_cb;
947 
948  srd_dbg("Registering new callback for output type %d.", output_type);
949 
950  if (!(pd_cb = g_try_malloc(sizeof(struct srd_pd_callback)))) {
951  srd_err("Failed to g_malloc() struct srd_pd_callback.");
952  return SRD_ERR_MALLOC;
953  }
954 
955  pd_cb->output_type = output_type;
956  pd_cb->cb = cb;
957  pd_cb->cb_data = cb_data;
958  callbacks = g_slist_append(callbacks, pd_cb);
959 
960  return SRD_OK;
961 }
962 
963 /** @private */
964 SRD_PRIV void *srd_pd_output_callback_find(int output_type)
965 {
966  GSList *l;
967  struct srd_pd_callback *pd_cb;
968  void *(cb);
969 
970  cb = NULL;
971  for (l = callbacks; l; l = l->next) {
972  pd_cb = l->data;
973  if (pd_cb->output_type == output_type) {
974  cb = pd_cb->cb;
975  break;
976  }
977  }
978 
979  return cb;
980 }
981 
982 /* This is the backend function to Python sigrokdecode.add() call. */
983 /** @private */
984 SRD_PRIV int srd_inst_pd_output_add(struct srd_decoder_inst *di,
985  int output_type, const char *proto_id)
986 {
987  struct srd_pd_output *pdo;
988 
989  srd_dbg("Instance %s creating new output type %d for %s.",
990  di->inst_id, output_type, proto_id);
991 
992  if (!(pdo = g_try_malloc(sizeof(struct srd_pd_output)))) {
993  srd_err("Failed to g_malloc() struct srd_pd_output.");
994  return -1;
995  }
996 
997  /* pdo_id is just a simple index, nothing is deleted from this list anyway. */
998  pdo->pdo_id = g_slist_length(di->pd_output);
999  pdo->output_type = output_type;
1000  pdo->di = di;
1001  pdo->proto_id = g_strdup(proto_id);
1002  di->pd_output = g_slist_append(di->pd_output, pdo);
1003 
1004  return pdo->pdo_id;
1005 }
1006 
1007 /** @} */