2 * This file is part of the libsigrokdecode project.
4 * Copyright (C) 2010 Uwe Hermann <uwe@hermann-uwe.de>
5 * Copyright (C) 2012 Bert Vermeulen <bert@biot.com>
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.
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.
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/>.
22 #include "libsigrokdecode.h" /* First, so we avoid a _POSIX_C_SOURCE warning. */
23 #include "libsigrokdecode-internal.h"
29 * Listing, loading, unloading, and handling protocol decoders.
33 * @defgroup grp_decoder Protocol decoders
35 * Handling protocol decoders.
42 /* The list of protocol decoders. */
43 static GSList
*pd_list
= NULL
;
46 extern SRD_PRIV GSList
*searchpaths
;
49 extern SRD_PRIV GSList
*sessions
;
50 extern SRD_PRIV
int max_session_id
;
52 /* module_sigrokdecode.c */
53 extern SRD_PRIV PyObject
*mod_sigrokdecode
;
57 static gboolean
srd_check_init(void)
59 if (max_session_id
< 0) {
60 srd_err("Library is not initialized.");
67 * Returns the list of supported/loaded protocol decoders.
69 * This is a GSList of pointers to struct srd_decoder items.
71 * @return List of decoders, NULL if none are supported or loaded.
75 SRD_API
const GSList
*srd_decoder_list(void)
81 * Get the decoder with the specified ID.
83 * @param id The ID string of the decoder to return.
85 * @return The decoder with the specified ID, or NULL if not found.
89 SRD_API
struct srd_decoder
*srd_decoder_get_by_id(const char *id
)
92 struct srd_decoder
*dec
;
94 for (l
= pd_list
; l
; l
= l
->next
) {
96 if (!strcmp(dec
->id
, id
))
103 static int get_channels(const struct srd_decoder
*d
, const char *attr
,
106 PyObject
*py_channellist
, *py_entry
;
107 struct srd_channel
*pdch
;
108 int ret
, num_channels
, i
;
110 if (!PyObject_HasAttrString(d
->py_dec
, attr
))
111 /* No channels of this type specified. */
114 py_channellist
= PyObject_GetAttrString(d
->py_dec
, attr
);
115 if (!PyTuple_Check(py_channellist
)) {
116 srd_err("Protocol decoder %s %s attribute is not a tuple.",
118 return SRD_ERR_PYTHON
;
121 if ((num_channels
= PyTuple_Size(py_channellist
)) == 0)
122 /* Empty channellist. */
126 for (i
= 0; i
< num_channels
; i
++) {
127 py_entry
= PyTuple_GetItem(py_channellist
, i
);
128 if (!PyDict_Check(py_entry
)) {
129 srd_err("Protocol decoder %s %s attribute is not "
130 "a list with dict elements.", d
->name
, attr
);
131 ret
= SRD_ERR_PYTHON
;
135 if (!(pdch
= g_try_malloc(sizeof(struct srd_channel
)))) {
136 srd_err("Failed to g_malloc() struct srd_channel.");
137 ret
= SRD_ERR_MALLOC
;
141 if ((py_dictitem_as_str(py_entry
, "id", &pdch
->id
)) != SRD_OK
) {
142 ret
= SRD_ERR_PYTHON
;
145 if ((py_dictitem_as_str(py_entry
, "name", &pdch
->name
)) != SRD_OK
) {
146 ret
= SRD_ERR_PYTHON
;
149 if ((py_dictitem_as_str(py_entry
, "desc", &pdch
->desc
)) != SRD_OK
) {
150 ret
= SRD_ERR_PYTHON
;
155 *pdchl
= g_slist_append(*pdchl
, pdch
);
158 Py_DecRef(py_channellist
);
163 static int get_options(struct srd_decoder
*d
)
165 PyObject
*py_opts
, *py_opt
, *py_val
, *py_default
, *py_item
;
167 struct srd_decoder_option
*o
;
174 if (!PyObject_HasAttrString(d
->py_dec
, "options"))
175 /* No options, that's fine. */
178 /* If present, options must be a tuple. */
179 py_opts
= PyObject_GetAttrString(d
->py_dec
, "options");
180 if (!PyTuple_Check(py_opts
)) {
181 srd_err("Protocol decoder %s: options attribute is not "
183 return SRD_ERR_PYTHON
;
186 for (opt
= 0; opt
< PyTuple_Size(py_opts
); opt
++) {
187 py_opt
= PyTuple_GetItem(py_opts
, opt
);
188 if (!PyDict_Check(py_opt
)) {
189 srd_err("Protocol decoder %s options: each option "
190 "must consist of a dictionary.", d
->name
);
191 return SRD_ERR_PYTHON
;
193 if (!(py_val
= PyDict_GetItemString(py_opt
, "id"))) {
194 srd_err("Protocol decoder %s option %d has no "
196 return SRD_ERR_PYTHON
;
198 o
= g_malloc0(sizeof(struct srd_decoder_option
));
199 py_str_as_str(py_val
, &o
->id
);
201 if ((py_val
= PyDict_GetItemString(py_opt
, "desc")))
202 py_str_as_str(py_val
, &o
->desc
);
204 if ((py_default
= PyDict_GetItemString(py_opt
, "default"))) {
205 if (PyUnicode_Check(py_default
)) {
207 py_str_as_str(py_default
, &sval
);
208 o
->def
= g_variant_new_string(sval
);
210 } else if (PyLong_Check(py_default
)) {
212 lval
= PyLong_AsLongAndOverflow(py_default
, &overflow
);
214 /* Value is < LONG_MIN or > LONG_MAX */
216 srd_err("Protocol decoder %s option 'default' has "
217 "invalid default value.", d
->name
);
218 return SRD_ERR_PYTHON
;
220 o
->def
= g_variant_new_int64(lval
);
221 } else if (PyFloat_Check(py_default
)) {
223 if ((dval
= PyFloat_AsDouble(py_default
)) == -1.0) {
225 srd_err("Protocol decoder %s option 'default' has "
226 "invalid default value.", d
->name
);
227 return SRD_ERR_PYTHON
;
229 o
->def
= g_variant_new_double(dval
);
231 srd_err("Protocol decoder %s option 'default' has "
232 "value of unsupported type '%s'.", d
->name
,
233 Py_TYPE(py_default
)->tp_name
);
234 return SRD_ERR_PYTHON
;
236 g_variant_ref_sink(o
->def
);
239 if ((py_val
= PyDict_GetItemString(py_opt
, "values"))) {
240 /* A default is required if a list of values is
241 * given, since it's used to verify their type. */
243 srd_err("No default for option '%s'", o
->id
);
244 return SRD_ERR_PYTHON
;
246 if (!PyTuple_Check(py_val
)) {
247 srd_err("Option '%s' values should be a tuple.", o
->id
);
248 return SRD_ERR_PYTHON
;
250 for (i
= 0; i
< PyTuple_Size(py_val
); i
++) {
251 py_item
= PyTuple_GetItem(py_val
, i
);
252 if (Py_TYPE(py_default
) != Py_TYPE(py_item
)) {
253 srd_err("All values for option '%s' must be "
254 "of the same type as the default.",
256 return SRD_ERR_PYTHON
;
258 if (PyUnicode_Check(py_item
)) {
260 py_str_as_str(py_item
, &sval
);
261 gvar
= g_variant_new_string(sval
);
262 g_variant_ref_sink(gvar
);
264 o
->values
= g_slist_append(o
->values
, gvar
);
265 } else if (PyLong_Check(py_item
)) {
267 lval
= PyLong_AsLongAndOverflow(py_item
, &overflow
);
269 /* Value is < LONG_MIN or > LONG_MAX */
271 srd_err("Protocol decoder %s option 'values' "
272 "has invalid value.", d
->name
);
273 return SRD_ERR_PYTHON
;
275 gvar
= g_variant_new_int64(lval
);
276 g_variant_ref_sink(gvar
);
277 o
->values
= g_slist_append(o
->values
, gvar
);
278 } else if (PyFloat_Check(py_item
)) {
280 if ((dval
= PyFloat_AsDouble(py_item
)) == -1.0) {
282 srd_err("Protocol decoder %s option 'default' has "
283 "invalid default value.", d
->name
);
284 return SRD_ERR_PYTHON
;
286 gvar
= g_variant_new_double(dval
);
287 g_variant_ref_sink(gvar
);
288 o
->values
= g_slist_append(o
->values
, gvar
);
292 d
->options
= g_slist_append(d
->options
, o
);
299 * Load a protocol decoder module into the embedded Python interpreter.
301 * @param module_name The module name to be loaded.
303 * @return SRD_OK upon success, a (negative) error code otherwise.
307 SRD_API
int srd_decoder_load(const char *module_name
)
309 PyObject
*py_basedec
, *py_method
, *py_attr
, *py_annlist
, *py_ann
;
310 PyObject
*py_bin_classes
, *py_bin_class
, *py_ann_rows
, *py_ann_row
;
311 PyObject
*py_ann_classes
, *py_long
;
312 struct srd_decoder
*d
;
314 char **ann
, **bin
, *ann_row_id
, *ann_row_desc
;
315 struct srd_channel
*pdch
;
316 GSList
*l
, *ann_classes
;
317 struct srd_decoder_annotation_row
*ann_row
;
319 if (!srd_check_init())
325 if (PyDict_GetItemString(PyImport_GetModuleDict(), module_name
)) {
326 /* Module was already imported. */
330 srd_dbg("Loading protocol decoder '%s'.", module_name
);
332 py_basedec
= py_method
= py_attr
= NULL
;
334 if (!(d
= g_try_malloc0(sizeof(struct srd_decoder
)))) {
335 srd_dbg("Failed to g_malloc() struct srd_decoder.");
336 ret
= SRD_ERR_MALLOC
;
340 ret
= SRD_ERR_PYTHON
;
342 /* Import the Python module. */
343 if (!(d
->py_mod
= PyImport_ImportModule(module_name
))) {
344 srd_exception_catch("Import of '%s' failed.", module_name
);
348 /* Get the 'Decoder' class as Python object. */
349 if (!(d
->py_dec
= PyObject_GetAttrString(d
->py_mod
, "Decoder"))) {
350 /* This generated an AttributeError exception. */
352 srd_err("Decoder class not found in protocol decoder %s.",
357 if (!(py_basedec
= PyObject_GetAttrString(mod_sigrokdecode
, "Decoder"))) {
358 srd_dbg("sigrokdecode module not loaded.");
362 if (!PyObject_IsSubclass(d
->py_dec
, py_basedec
)) {
363 srd_err("Decoder class in protocol decoder module %s is not "
364 "a subclass of sigrokdecode.Decoder.", module_name
);
367 Py_CLEAR(py_basedec
);
370 * Check that thÑ–s decoder has the correct PD API version.
371 * PDs of different API versions are incompatible and cannot work.
373 py_long
= PyObject_GetAttrString(d
->py_dec
, "api_version");
374 if (PyLong_AsLong(py_long
) != 2) {
375 srd_err("Only PDs of API version 2 are supported.");
380 /* Check for a proper start() method. */
381 if (!PyObject_HasAttrString(d
->py_dec
, "start")) {
382 srd_err("Protocol decoder %s has no start() method Decoder "
383 "class.", module_name
);
386 py_method
= PyObject_GetAttrString(d
->py_dec
, "start");
387 if (!PyFunction_Check(py_method
)) {
388 srd_err("Protocol decoder %s Decoder class attribute 'start' "
389 "is not a method.", module_name
);
394 /* Check for a proper decode() method. */
395 if (!PyObject_HasAttrString(d
->py_dec
, "decode")) {
396 srd_err("Protocol decoder %s has no decode() method Decoder "
397 "class.", module_name
);
400 py_method
= PyObject_GetAttrString(d
->py_dec
, "decode");
401 if (!PyFunction_Check(py_method
)) {
402 srd_err("Protocol decoder %s Decoder class attribute 'decode' "
403 "is not a method.", module_name
);
408 /* Store required fields in newly allocated strings. */
409 if (py_attr_as_str(d
->py_dec
, "id", &(d
->id
)) != SRD_OK
)
412 if (py_attr_as_str(d
->py_dec
, "name", &(d
->name
)) != SRD_OK
)
415 if (py_attr_as_str(d
->py_dec
, "longname", &(d
->longname
)) != SRD_OK
)
418 if (py_attr_as_str(d
->py_dec
, "desc", &(d
->desc
)) != SRD_OK
)
421 if (py_attr_as_str(d
->py_dec
, "license", &(d
->license
)) != SRD_OK
)
424 /* All options and their default values. */
425 if (get_options(d
) != SRD_OK
)
428 /* Check and import required channels. */
429 if (get_channels(d
, "channels", &d
->channels
) != SRD_OK
)
432 /* Check and import optional channels. */
433 if (get_channels(d
, "optional_channels", &d
->opt_channels
) != SRD_OK
)
437 * Fix order numbers for the optional channels.
440 * Required channels: r1, r2, r3. Optional: o1, o2, o3, o4.
441 * 'order' fields in the d->channels list = 0, 1, 2.
442 * 'order' fields in the d->opt_channels list = 3, 4, 5, 6.
444 for (l
= d
->opt_channels
; l
; l
= l
->next
) {
446 pdch
->order
+= g_slist_length(d
->channels
);
449 /* Convert annotation class attribute to GSList of char **. */
450 d
->annotations
= NULL
;
451 if (PyObject_HasAttrString(d
->py_dec
, "annotations")) {
452 py_annlist
= PyObject_GetAttrString(d
->py_dec
, "annotations");
453 if (!PyTuple_Check(py_annlist
)) {
454 srd_err("Protocol decoder %s annotations should "
455 "be a tuple.", module_name
);
458 for (i
= 0; i
< PyTuple_Size(py_annlist
); i
++) {
459 py_ann
= PyTuple_GetItem(py_annlist
, i
);
460 if (!PyTuple_Check(py_ann
) || PyTuple_Size(py_ann
) != 2) {
461 srd_err("Protocol decoder %s annotation %d should "
462 "be a tuple with two elements.", module_name
, i
+ 1);
466 if (py_strseq_to_char(py_ann
, &ann
) != SRD_OK
) {
469 d
->annotations
= g_slist_append(d
->annotations
, ann
);
473 /* Convert annotation_rows to GSList of 'struct srd_decoder_annotation_row'. */
474 d
->annotation_rows
= NULL
;
475 if (PyObject_HasAttrString(d
->py_dec
, "annotation_rows")) {
476 py_ann_rows
= PyObject_GetAttrString(d
->py_dec
, "annotation_rows");
477 if (!PyTuple_Check(py_ann_rows
)) {
478 srd_err("Protocol decoder %s annotation row list "
479 "must be a tuple.", module_name
);
482 for (i
= 0; i
< PyTuple_Size(py_ann_rows
); i
++) {
483 py_ann_row
= PyTuple_GetItem(py_ann_rows
, i
);
484 if (!PyTuple_Check(py_ann_row
)) {
485 srd_err("Protocol decoder %s annotation rows "
486 "must be tuples.", module_name
);
489 if (PyTuple_Size(py_ann_row
) != 3
490 || !PyUnicode_Check(PyTuple_GetItem(py_ann_row
, 0))
491 || !PyUnicode_Check(PyTuple_GetItem(py_ann_row
, 1))
492 || !PyTuple_Check(PyTuple_GetItem(py_ann_row
, 2))) {
493 srd_err("Protocol decoder %s annotation rows "
494 "must contain tuples containing two "
495 "strings and a tuple.", module_name
);
499 if (py_str_as_str(PyTuple_GetItem(py_ann_row
, 0), &ann_row_id
) != SRD_OK
)
502 if (py_str_as_str(PyTuple_GetItem(py_ann_row
, 1), &ann_row_desc
) != SRD_OK
)
505 py_ann_classes
= PyTuple_GetItem(py_ann_row
, 2);
507 for (j
= 0; j
< PyTuple_Size(py_ann_classes
); j
++) {
508 py_long
= PyTuple_GetItem(py_ann_classes
, j
);
509 if (!PyLong_Check(py_long
)) {
510 srd_err("Protocol decoder %s annotation row class "
511 "list must only contain numbers.", module_name
);
514 ann_classes
= g_slist_append(ann_classes
,
515 GINT_TO_POINTER(PyLong_AsLong(py_long
)));
518 ann_row
= g_malloc0(sizeof(struct srd_decoder_annotation_row
));
519 ann_row
->id
= ann_row_id
;
520 ann_row
->desc
= ann_row_desc
;
521 ann_row
->ann_classes
= ann_classes
;
522 d
->annotation_rows
= g_slist_append(d
->annotation_rows
, ann_row
);
526 /* Convert binary class to GSList of char *. */
528 if (PyObject_HasAttrString(d
->py_dec
, "binary")) {
529 py_bin_classes
= PyObject_GetAttrString(d
->py_dec
, "binary");
530 if (!PyTuple_Check(py_bin_classes
)) {
531 srd_err("Protocol decoder %s binary classes should "
532 "be a tuple.", module_name
);
535 for (i
= 0; i
< PyTuple_Size(py_bin_classes
); i
++) {
536 py_bin_class
= PyTuple_GetItem(py_bin_classes
, i
);
537 if (!PyTuple_Check(py_bin_class
)) {
538 srd_err("Protocol decoder %s binary classes "
539 "should consist of tuples.", module_name
);
542 if (PyTuple_Size(py_bin_class
) != 2
543 || !PyUnicode_Check(PyTuple_GetItem(py_bin_class
, 0))
544 || !PyUnicode_Check(PyTuple_GetItem(py_bin_class
, 1))) {
545 srd_err("Protocol decoder %s binary classes should "
546 "contain tuples with two strings.", module_name
);
550 if (py_strseq_to_char(py_bin_class
, &bin
) != SRD_OK
) {
553 d
->binary
= g_slist_append(d
->binary
, bin
);
557 /* Append it to the list of supported/loaded decoders. */
558 pd_list
= g_slist_append(pd_list
, d
);
564 Py_XDECREF(py_method
);
565 Py_XDECREF(py_basedec
);
566 Py_XDECREF(d
->py_dec
);
567 Py_XDECREF(d
->py_mod
);
575 * Return a protocol decoder's docstring.
577 * @param dec The loaded protocol decoder.
579 * @return A newly allocated buffer containing the protocol decoder's
580 * documentation. The caller is responsible for free'ing the buffer.
584 SRD_API
char *srd_decoder_doc_get(const struct srd_decoder
*dec
)
589 if (!srd_check_init())
595 if (!PyObject_HasAttrString(dec
->py_mod
, "__doc__"))
598 if (!(py_str
= PyObject_GetAttrString(dec
->py_mod
, "__doc__"))) {
599 srd_exception_catch("");
604 if (py_str
!= Py_None
)
605 py_str_as_str(py_str
, &doc
);
611 static void free_channels(GSList
*channellist
)
614 struct srd_channel
*pdch
;
616 if (channellist
== NULL
)
619 for (l
= channellist
; l
; l
= l
->next
) {
626 g_slist_free(channellist
);
630 * Unload the specified protocol decoder.
632 * @param dec The struct srd_decoder to be unloaded.
634 * @return SRD_OK upon success, a (negative) error code otherwise.
638 SRD_API
int srd_decoder_unload(struct srd_decoder
*dec
)
640 struct srd_decoder_option
*o
;
641 struct srd_session
*sess
;
644 if (!srd_check_init())
650 srd_dbg("Unloading protocol decoder '%s'.", dec
->name
);
653 * Since any instances of this decoder need to be released as well,
654 * but they could be anywhere in the stack, just free the entire
655 * stack. A frontend reloading a decoder thus has to restart all
656 * instances, and rebuild the stack.
658 for (l
= sessions
; l
; l
= l
->next
) {
660 srd_inst_free_all(sess
, NULL
);
663 for (l
= dec
->options
; l
; l
= l
->next
) {
667 g_variant_unref(o
->def
);
670 g_slist_free(dec
->options
);
672 free_channels(dec
->channels
);
673 free_channels(dec
->opt_channels
);
676 g_free(dec
->longname
);
678 g_free(dec
->license
);
680 /* The module's Decoder class. */
681 Py_XDECREF(dec
->py_dec
);
682 /* The module itself. */
683 Py_XDECREF(dec
->py_mod
);
690 static void srd_decoder_load_all_zip_path(char *path
)
692 PyObject
*zipimport_mod
, *zipimporter_class
, *zipimporter
;
693 PyObject
*prefix_obj
, *files
, *key
, *value
, *set
, *modname
;
698 set
= files
= prefix_obj
= zipimporter
= zipimporter_class
= NULL
;
700 zipimport_mod
= PyImport_ImportModule("zipimport");
701 if (zipimport_mod
== NULL
)
704 zipimporter_class
= PyObject_GetAttrString(zipimport_mod
, "zipimporter");
705 if (zipimporter_class
== NULL
)
708 zipimporter
= PyObject_CallFunction(zipimporter_class
, "s", path
);
709 if (zipimporter
== NULL
)
712 prefix_obj
= PyObject_GetAttrString(zipimporter
, "prefix");
713 if (prefix_obj
== NULL
)
716 files
= PyObject_GetAttrString(zipimporter
, "_files");
720 set
= PySet_New(NULL
);
724 if (py_str_as_str(prefix_obj
, &prefix
) != SRD_OK
)
727 prefix_len
= strlen(prefix
);
729 while (PyDict_Next(files
, &pos
, &key
, &value
)) {
731 if (py_str_as_str(key
, &path
) == SRD_OK
) {
732 if (strlen(path
) > prefix_len
&&
733 !memcmp(path
, prefix
, prefix_len
) &&
734 (slash
= strchr(path
+prefix_len
, '/'))) {
736 PyUnicode_FromStringAndSize(path
+prefix_len
,
737 slash
-(path
+prefix_len
));
738 if (modname
== NULL
) {
741 PySet_Add(set
, modname
);
751 while ((modname
= PySet_Pop(set
))) {
753 if (py_str_as_str(modname
, &modname_str
) == SRD_OK
) {
754 /* The directory name is the module name (e.g. "i2c"). */
755 srd_decoder_load(modname_str
);
764 Py_XDECREF(prefix_obj
);
765 Py_XDECREF(zipimporter
);
766 Py_XDECREF(zipimporter_class
);
767 Py_XDECREF(zipimport_mod
);
771 static void srd_decoder_load_all_path(char *path
)
774 const gchar
*direntry
;
776 if (!(dir
= g_dir_open(path
, 0, NULL
))) {
777 /* Not really fatal */
778 /* Try zipimport method too */
779 srd_decoder_load_all_zip_path(path
);
783 /* This ignores errors returned by srd_decoder_load(). That
784 * function will have logged the cause, but in any case we
785 * want to continue anyway. */
786 while ((direntry
= g_dir_read_name(dir
)) != NULL
) {
787 /* The directory name is the module name (e.g. "i2c"). */
788 srd_decoder_load(direntry
);
795 * Load all installed protocol decoders.
797 * @return SRD_OK upon success, a (negative) error code otherwise.
801 SRD_API
int srd_decoder_load_all(void)
805 if (!srd_check_init())
808 for (l
= searchpaths
; l
; l
= l
->next
)
809 srd_decoder_load_all_path(l
->data
);
815 * Unload all loaded protocol decoders.
817 * @return SRD_OK upon success, a (negative) error code otherwise.
821 SRD_API
int srd_decoder_unload_all(void)
824 struct srd_decoder
*dec
;
826 for (l
= pd_list
; l
; l
= l
->next
) {
828 srd_decoder_unload(dec
);
830 g_slist_free(pd_list
);