Minor whitespace/typo fixes.
[libsigrokdecode.git] / type_decoder.c
1 /*
2  * This file is part of the libsigrokdecode project.
3  *
4  * Copyright (C) 2012 Bert Vermeulen <bert@biot.com>
5  *
6  * This program is free software: you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
18  */
19
20 #include <config.h>
21 #include "libsigrokdecode-internal.h" /* First, so we avoid a _POSIX_C_SOURCE warning. */
22 #include "libsigrokdecode.h"
23 #include <inttypes.h>
24
25 typedef struct {
26         PyObject_HEAD
27 } srd_Decoder;
28
29 /* This is only used for nicer srd_dbg() output.
30  */
31 static const char *output_type_name(unsigned int idx)
32 {
33         static const char names[][16] = {
34                 "OUTPUT_ANN",
35                 "OUTPUT_PYTHON",
36                 "OUTPUT_BINARY",
37                 "OUTPUT_META",
38                 "(invalid)"
39         };
40         return names[MIN(idx, G_N_ELEMENTS(names) - 1)];
41 }
42
43 static int convert_annotation(struct srd_decoder_inst *di, PyObject *obj,
44                 struct srd_proto_data *pdata)
45 {
46         PyObject *py_tmp;
47         struct srd_pd_output *pdo;
48         struct srd_proto_data_annotation *pda;
49         int ann_class;
50         char **ann_text;
51         PyGILState_STATE gstate;
52
53         gstate = PyGILState_Ensure();
54
55         /* Should be a list of [annotation class, [string, ...]]. */
56         if (!PyList_Check(obj)) {
57                 srd_err("Protocol decoder %s submitted an annotation that"
58                         " is not a list", di->decoder->name);
59                 goto err;
60         }
61
62         /* Should have 2 elements. */
63         if (PyList_Size(obj) != 2) {
64                 srd_err("Protocol decoder %s submitted annotation list with "
65                         "%zd elements instead of 2", di->decoder->name,
66                         PyList_Size(obj));
67                 goto err;
68         }
69
70         /*
71          * The first element should be an integer matching a previously
72          * registered annotation class.
73          */
74         py_tmp = PyList_GetItem(obj, 0);
75         if (!PyLong_Check(py_tmp)) {
76                 srd_err("Protocol decoder %s submitted annotation list, but "
77                         "first element was not an integer.", di->decoder->name);
78                 goto err;
79         }
80         ann_class = PyLong_AsLong(py_tmp);
81         if (!(pdo = g_slist_nth_data(di->decoder->annotations, ann_class))) {
82                 srd_err("Protocol decoder %s submitted data to unregistered "
83                         "annotation class %d.", di->decoder->name, ann_class);
84                 goto err;
85         }
86
87         /* Second element must be a list. */
88         py_tmp = PyList_GetItem(obj, 1);
89         if (!PyList_Check(py_tmp)) {
90                 srd_err("Protocol decoder %s submitted annotation list, but "
91                         "second element was not a list.", di->decoder->name);
92                 goto err;
93         }
94         if (py_strseq_to_char(py_tmp, &ann_text) != SRD_OK) {
95                 srd_err("Protocol decoder %s submitted annotation list, but "
96                         "second element was malformed.", di->decoder->name);
97                 goto err;
98         }
99
100         pda = g_malloc(sizeof(struct srd_proto_data_annotation));
101         pda->ann_class = ann_class;
102         pda->ann_text = ann_text;
103         pdata->data = pda;
104
105         PyGILState_Release(gstate);
106
107         return SRD_OK;
108
109 err:
110         PyGILState_Release(gstate);
111
112         return SRD_ERR_PYTHON;
113 }
114
115 static int convert_binary(struct srd_decoder_inst *di, PyObject *obj,
116                 struct srd_proto_data *pdata)
117 {
118         struct srd_proto_data_binary *pdb;
119         PyObject *py_tmp;
120         Py_ssize_t size;
121         int bin_class;
122         char *class_name, *buf;
123         PyGILState_STATE gstate;
124
125         gstate = PyGILState_Ensure();
126
127         /* Should be a list of [binary class, bytes]. */
128         if (!PyList_Check(obj)) {
129                 srd_err("Protocol decoder %s submitted non-list for SRD_OUTPUT_BINARY.",
130                         di->decoder->name);
131                 goto err;
132         }
133
134         /* Should have 2 elements. */
135         if (PyList_Size(obj) != 2) {
136                 srd_err("Protocol decoder %s submitted SRD_OUTPUT_BINARY list "
137                                 "with %zd elements instead of 2", di->decoder->name,
138                                 PyList_Size(obj));
139                 goto err;
140         }
141
142         /* The first element should be an integer. */
143         py_tmp = PyList_GetItem(obj, 0);
144         if (!PyLong_Check(py_tmp)) {
145                 srd_err("Protocol decoder %s submitted SRD_OUTPUT_BINARY list, "
146                         "but first element was not an integer.", di->decoder->name);
147                 goto err;
148         }
149         bin_class = PyLong_AsLong(py_tmp);
150         if (!(class_name = g_slist_nth_data(di->decoder->binary, bin_class))) {
151                 srd_err("Protocol decoder %s submitted SRD_OUTPUT_BINARY with "
152                         "unregistered binary class %d.", di->decoder->name, bin_class);
153                 goto err;
154         }
155
156         /* Second element should be bytes. */
157         py_tmp = PyList_GetItem(obj, 1);
158         if (!PyBytes_Check(py_tmp)) {
159                 srd_err("Protocol decoder %s submitted SRD_OUTPUT_BINARY list, "
160                         "but second element was not bytes.", di->decoder->name);
161                 goto err;
162         }
163
164         /* Consider an empty set of bytes a bug. */
165         if (PyBytes_Size(py_tmp) == 0) {
166                 srd_err("Protocol decoder %s submitted SRD_OUTPUT_BINARY "
167                                 "with empty data set.", di->decoder->name);
168                 goto err;
169         }
170
171         pdb = g_malloc(sizeof(struct srd_proto_data_binary));
172         if (PyBytes_AsStringAndSize(py_tmp, &buf, &size) == -1)
173                 goto err;
174
175         PyGILState_Release(gstate);
176
177         pdb->bin_class = bin_class;
178         pdb->size = size;
179         if (!(pdb->data = g_try_malloc(pdb->size)))
180                 return SRD_ERR_MALLOC;
181         memcpy((void *)pdb->data, (const void *)buf, pdb->size);
182         pdata->data = pdb;
183
184         return SRD_OK;
185
186 err:
187         PyGILState_Release(gstate);
188
189         return SRD_ERR_PYTHON;
190 }
191
192 static int convert_meta(struct srd_proto_data *pdata, PyObject *obj)
193 {
194         long long intvalue;
195         double dvalue;
196         PyGILState_STATE gstate;
197
198         gstate = PyGILState_Ensure();
199
200         if (pdata->pdo->meta_type == G_VARIANT_TYPE_INT64) {
201                 if (!PyLong_Check(obj)) {
202                         PyErr_Format(PyExc_TypeError, "This output was registered "
203                                         "as 'int', but something else was passed.");
204                         goto err;
205                 }
206                 intvalue = PyLong_AsLongLong(obj);
207                 if (PyErr_Occurred())
208                         goto err;
209                 pdata->data = g_variant_new_int64(intvalue);
210         } else if (pdata->pdo->meta_type == G_VARIANT_TYPE_DOUBLE) {
211                 if (!PyFloat_Check(obj)) {
212                         PyErr_Format(PyExc_TypeError, "This output was registered "
213                                         "as 'float', but something else was passed.");
214                         goto err;
215                 }
216                 dvalue = PyFloat_AsDouble(obj);
217                 if (PyErr_Occurred())
218                         goto err;
219                 pdata->data = g_variant_new_double(dvalue);
220         }
221
222         PyGILState_Release(gstate);
223
224         return SRD_OK;
225
226 err:
227         PyGILState_Release(gstate);
228
229         return SRD_ERR_PYTHON;
230 }
231
232 static PyObject *Decoder_put(PyObject *self, PyObject *args)
233 {
234         GSList *l;
235         PyObject *py_data, *py_res;
236         struct srd_decoder_inst *di, *next_di;
237         struct srd_pd_output *pdo;
238         struct srd_proto_data pdata;
239         uint64_t start_sample, end_sample;
240         int output_id;
241         struct srd_pd_callback *cb;
242         PyGILState_STATE gstate;
243
244         gstate = PyGILState_Ensure();
245
246         if (!(di = srd_inst_find_by_obj(NULL, self))) {
247                 /* Shouldn't happen. */
248                 srd_dbg("put(): self instance not found.");
249                 goto err;
250         }
251
252         if (!PyArg_ParseTuple(args, "KKiO", &start_sample, &end_sample,
253                 &output_id, &py_data)) {
254                 /*
255                  * This throws an exception, but by returning NULL here we let
256                  * Python raise it. This results in a much better trace in
257                  * controller.c on the decode() method call.
258                  */
259                 goto err;
260         }
261
262         if (!(l = g_slist_nth(di->pd_output, output_id))) {
263                 srd_err("Protocol decoder %s submitted invalid output ID %d.",
264                         di->decoder->name, output_id);
265                 goto err;
266         }
267         pdo = l->data;
268
269         srd_spew("Instance %s put %" PRIu64 "-%" PRIu64 " %s on oid %d.",
270                  di->inst_id, start_sample, end_sample,
271                  output_type_name(pdo->output_type), output_id);
272
273         pdata.start_sample = start_sample;
274         pdata.end_sample = end_sample;
275         pdata.pdo = pdo;
276         pdata.data = NULL;
277
278         switch (pdo->output_type) {
279         case SRD_OUTPUT_ANN:
280                 /* Annotations are only fed to callbacks. */
281                 if ((cb = srd_pd_output_callback_find(di->sess, pdo->output_type))) {
282                         /* Convert from PyDict to srd_proto_data_annotation. */
283                         if (convert_annotation(di, py_data, &pdata) != SRD_OK) {
284                                 /* An error was already logged. */
285                                 break;
286                         }
287                         Py_BEGIN_ALLOW_THREADS
288                         cb->cb(&pdata, cb->cb_data);
289                         Py_END_ALLOW_THREADS
290                 }
291                 break;
292         case SRD_OUTPUT_PYTHON:
293                 for (l = di->next_di; l; l = l->next) {
294                         next_di = l->data;
295                         srd_spew("Sending %" PRIu64 "-%" PRIu64 " to instance %s",
296                                  start_sample, end_sample, next_di->inst_id);
297                         if (!(py_res = PyObject_CallMethod(
298                                 next_di->py_inst, "decode", "KKO", start_sample,
299                                 end_sample, py_data))) {
300                                 srd_exception_catch("Calling %s decode() failed",
301                                                         next_di->inst_id);
302                         }
303                         Py_XDECREF(py_res);
304                 }
305                 if ((cb = srd_pd_output_callback_find(di->sess, pdo->output_type))) {
306                         /* Frontends aren't really supposed to get Python
307                          * callbacks, but it's useful for testing. */
308                         pdata.data = py_data;
309                         cb->cb(&pdata, cb->cb_data);
310                 }
311                 break;
312         case SRD_OUTPUT_BINARY:
313                 if ((cb = srd_pd_output_callback_find(di->sess, pdo->output_type))) {
314                         /* Convert from PyDict to srd_proto_data_binary. */
315                         if (convert_binary(di, py_data, &pdata) != SRD_OK) {
316                                 /* An error was already logged. */
317                                 break;
318                         }
319                         Py_BEGIN_ALLOW_THREADS
320                         cb->cb(&pdata, cb->cb_data);
321                         Py_END_ALLOW_THREADS
322                 }
323                 break;
324         case SRD_OUTPUT_META:
325                 if ((cb = srd_pd_output_callback_find(di->sess, pdo->output_type))) {
326                         /* Annotations need converting from PyObject. */
327                         if (convert_meta(&pdata, py_data) != SRD_OK) {
328                                 /* An exception was already set up. */
329                                 break;
330                         }
331                         Py_BEGIN_ALLOW_THREADS
332                         cb->cb(&pdata, cb->cb_data);
333                         Py_END_ALLOW_THREADS
334                 }
335                 break;
336         default:
337                 srd_err("Protocol decoder %s submitted invalid output type %d.",
338                         di->decoder->name, pdo->output_type);
339                 break;
340         }
341
342         PyGILState_Release(gstate);
343
344         Py_RETURN_NONE;
345
346 err:
347         PyGILState_Release(gstate);
348
349         return NULL;
350 }
351
352 static PyObject *Decoder_register(PyObject *self, PyObject *args,
353                 PyObject *kwargs)
354 {
355         struct srd_decoder_inst *di;
356         struct srd_pd_output *pdo;
357         PyObject *py_new_output_id;
358         PyTypeObject *meta_type_py;
359         const GVariantType *meta_type_gv;
360         int output_type;
361         char *proto_id, *meta_name, *meta_descr;
362         char *keywords[] = {"output_type", "proto_id", "meta", NULL};
363         PyGILState_STATE gstate;
364
365         gstate = PyGILState_Ensure();
366
367         meta_type_py = NULL;
368         meta_type_gv = NULL;
369         meta_name = meta_descr = NULL;
370
371         if (!(di = srd_inst_find_by_obj(NULL, self))) {
372                 PyErr_SetString(PyExc_Exception, "decoder instance not found");
373                 goto err;
374         }
375
376         /* Default to instance id, which defaults to class id. */
377         proto_id = di->inst_id;
378         if (!PyArg_ParseTupleAndKeywords(args, kwargs, "i|s(Oss)", keywords,
379                         &output_type, &proto_id,
380                         &meta_type_py, &meta_name, &meta_descr)) {
381                 /* Let Python raise this exception. */
382                 goto err;
383         }
384
385         /* Check if the meta value's type is supported. */
386         if (output_type == SRD_OUTPUT_META) {
387                 if (meta_type_py == &PyLong_Type)
388                         meta_type_gv = G_VARIANT_TYPE_INT64;
389                 else if (meta_type_py == &PyFloat_Type)
390                         meta_type_gv = G_VARIANT_TYPE_DOUBLE;
391                 else {
392                         PyErr_Format(PyExc_TypeError, "Unsupported type.");
393                         goto err;
394                 }
395         }
396
397         srd_dbg("Instance %s creating new output type %d for %s.",
398                 di->inst_id, output_type, proto_id);
399
400         pdo = g_malloc(sizeof(struct srd_pd_output));
401
402         /* pdo_id is just a simple index, nothing is deleted from this list anyway. */
403         pdo->pdo_id = g_slist_length(di->pd_output);
404         pdo->output_type = output_type;
405         pdo->di = di;
406         pdo->proto_id = g_strdup(proto_id);
407
408         if (output_type == SRD_OUTPUT_META) {
409                 pdo->meta_type = meta_type_gv;
410                 pdo->meta_name = g_strdup(meta_name);
411                 pdo->meta_descr = g_strdup(meta_descr);
412         }
413
414         di->pd_output = g_slist_append(di->pd_output, pdo);
415         py_new_output_id = Py_BuildValue("i", pdo->pdo_id);
416
417         PyGILState_Release(gstate);
418
419         return py_new_output_id;
420
421 err:
422         PyGILState_Release(gstate);
423
424         return NULL;
425 }
426
427 static int get_term_type(const char *v)
428 {
429         switch (v[0]) {
430         case 'h':
431                 return SRD_TERM_HIGH;
432         case 'l':
433                 return SRD_TERM_LOW;
434         case 'r':
435                 return SRD_TERM_RISING_EDGE;
436         case 'f':
437                 return SRD_TERM_FALLING_EDGE;
438         case 'e':
439                 return SRD_TERM_EITHER_EDGE;
440         case 'n':
441                 return SRD_TERM_NO_EDGE;
442         }
443
444         return -1;
445 }
446
447 /**
448  * Get the pin values at the current sample number.
449  *
450  * @param di The decoder instance to use. Must not be NULL.
451  *           The number of channels must be >= 1.
452  *
453  * @return A newly allocated PyTuple containing the pin values at the
454  *         current sample number.
455  */
456 static PyObject *get_current_pinvalues(const struct srd_decoder_inst *di)
457 {
458         int i;
459         uint8_t sample;
460         const uint8_t *sample_pos;
461         int byte_offset, bit_offset;
462         PyObject *py_pinvalues;
463         PyGILState_STATE gstate;
464
465         gstate = PyGILState_Ensure();
466
467         if (!di) {
468                 srd_err("Invalid decoder instance.");
469                 PyGILState_Release(gstate);
470                 return NULL;
471         }
472
473         py_pinvalues = PyTuple_New(di->dec_num_channels);
474
475         for (i = 0; i < di->dec_num_channels; i++) {
476                 /* A channelmap value of -1 means "unused optional channel". */
477                 if (di->dec_channelmap[i] == -1) {
478                         /* Value of unused channel is 0xff, instead of 0 or 1. */
479                         PyTuple_SetItem(py_pinvalues, i, PyLong_FromLong(0xff));
480                 } else {
481                         sample_pos = di->inbuf + ((di->abs_cur_samplenum - di->abs_start_samplenum) * di->data_unitsize);
482                         byte_offset = di->dec_channelmap[i] / 8;
483                         bit_offset = di->dec_channelmap[i] % 8;
484                         sample = *(sample_pos + byte_offset) & (1 << bit_offset) ? 1 : 0;
485                         PyTuple_SetItem(py_pinvalues, i, PyLong_FromLong(sample));
486                 }
487         }
488
489         PyGILState_Release(gstate);
490
491         return py_pinvalues;
492 }
493
494 /**
495  * Create a list of terms in the specified condition.
496  *
497  * If there are no terms in the condition, 'term_list' will be NULL.
498  *
499  * @param py_dict A Python dict containing terms. Must not be NULL.
500  * @param term_list Pointer to a GSList which will be set to the newly
501  *                  created list of terms. Must not be NULL.
502  *
503  * @return SRD_OK upon success, a negative error code otherwise.
504  */
505 static int create_term_list(PyObject *py_dict, GSList **term_list)
506 {
507         Py_ssize_t pos = 0;
508         PyObject *py_key, *py_value;
509         struct srd_term *term;
510         uint64_t num_samples_to_skip;
511         char *term_str;
512         PyGILState_STATE gstate;
513
514         if (!py_dict || !term_list)
515                 return SRD_ERR_ARG;
516
517         /* "Create" an empty GSList of terms. */
518         *term_list = NULL;
519
520         gstate = PyGILState_Ensure();
521
522         /* Iterate over all items in the current dict. */
523         while (PyDict_Next(py_dict, &pos, &py_key, &py_value)) {
524                 /* Check whether the current key is a string or a number. */
525                 if (PyLong_Check(py_key)) {
526                         /* The key is a number. */
527                         /* TODO: Check if the number is a valid channel. */
528                         /* Get the value string. */
529                         if ((py_pydictitem_as_str(py_dict, py_key, &term_str)) != SRD_OK) {
530                                 srd_err("Failed to get the value.");
531                                 goto err;
532                         }
533                         term = g_malloc0(sizeof(struct srd_term));
534                         term->type = get_term_type(term_str);
535                         term->channel = PyLong_AsLong(py_key);
536                         g_free(term_str);
537                 } else if (PyUnicode_Check(py_key)) {
538                         /* The key is a string. */
539                         /* TODO: Check if it's "skip". */
540                         if ((py_pydictitem_as_long(py_dict, py_key, &num_samples_to_skip)) != SRD_OK) {
541                                 srd_err("Failed to get number of samples to skip.");
542                                 goto err;
543                         }
544                         term = g_malloc0(sizeof(struct srd_term));
545                         term->type = SRD_TERM_SKIP;
546                         term->num_samples_to_skip = num_samples_to_skip;
547                         term->num_samples_already_skipped = 0;
548                 } else {
549                         srd_err("Term key is neither a string nor a number.");
550                         goto err;
551                 }
552
553                 /* Add the term to the list of terms. */
554                 *term_list = g_slist_append(*term_list, term);
555         }
556
557         PyGILState_Release(gstate);
558
559         return SRD_OK;
560
561 err:
562         PyGILState_Release(gstate);
563
564         return SRD_ERR;
565 }
566
567 /**
568  * Replace the current condition list with the new one.
569  *
570  * @param self TODO. Must not be NULL.
571  * @param args TODO. Must not be NULL.
572  *
573  * @retval SRD_OK The new condition list was set successfully.
574  * @retval SRD_ERR There was an error setting the new condition list.
575  *                 The contents of di->condition_list are undefined.
576  * @retval 9999 TODO.
577  */
578 static int set_new_condition_list(PyObject *self, PyObject *args)
579 {
580         struct srd_decoder_inst *di;
581         GSList *term_list;
582         PyObject *py_conditionlist, *py_conds, *py_dict;
583         int i, num_conditions, ret;
584         PyGILState_STATE gstate;
585
586         if (!self || !args)
587                 return SRD_ERR_ARG;
588
589         gstate = PyGILState_Ensure();
590
591         /* Get the decoder instance. */
592         if (!(di = srd_inst_find_by_obj(NULL, self))) {
593                 PyErr_SetString(PyExc_Exception, "decoder instance not found");
594                 goto err;
595         }
596
597         /*
598          * Return an error condition from .wait() when termination is
599          * requested, such that decode() will terminate.
600          */
601         if (di->want_wait_terminate) {
602                 srd_dbg("%s: %s: Skip (want_term).", di->inst_id, __func__);
603                 goto err;
604         }
605
606         /*
607          * Parse the argument of self.wait() into 'py_conds', and check
608          * the data type. The argument is optional, None is assumed in
609          * its absence. None or an empty dict or an empty list mean that
610          * there is no condition, and the next available sample shall
611          * get returned to the caller.
612          */
613         py_conds = Py_None;
614         if (!PyArg_ParseTuple(args, "|O", &py_conds)) {
615                 /* Let Python raise this exception. */
616                 goto err;
617         }
618         if (py_conds == Py_None) {
619                 /* 'py_conds' is None. */
620                 goto ret_9999;
621         } else if (PyList_Check(py_conds)) {
622                 /* 'py_conds' is a list. */
623                 py_conditionlist = py_conds;
624                 num_conditions = PyList_Size(py_conditionlist);
625                 if (num_conditions == 0)
626                         goto ret_9999; /* The PD invoked self.wait([]). */
627                 Py_IncRef(py_conditionlist);
628         } else if (PyDict_Check(py_conds)) {
629                 /* 'py_conds' is a dict. */
630                 if (PyDict_Size(py_conds) == 0)
631                         goto ret_9999; /* The PD invoked self.wait({}). */
632                 /* Make a list and put the dict in there for convenience. */
633                 py_conditionlist = PyList_New(1);
634                 Py_IncRef(py_conds);
635                 PyList_SetItem(py_conditionlist, 0, py_conds);
636                 num_conditions = 1;
637         } else {
638                 srd_err("Condition list is neither a list nor a dict.");
639                 goto err;
640         }
641
642         /* Free the old condition list. */
643         condition_list_free(di);
644
645         ret = SRD_OK;
646
647         /* Iterate over the conditions, set di->condition_list accordingly. */
648         for (i = 0; i < num_conditions; i++) {
649                 /* Get a condition (dict) from the condition list. */
650                 py_dict = PyList_GetItem(py_conditionlist, i);
651                 if (!PyDict_Check(py_dict)) {
652                         srd_err("Condition is not a dict.");
653                         ret = SRD_ERR;
654                         break;
655                 }
656
657                 /* Create the list of terms in this condition. */
658                 if ((ret = create_term_list(py_dict, &term_list)) < 0)
659                         break;
660
661                 /* Add the new condition to the PD instance's condition list. */
662                 di->condition_list = g_slist_append(di->condition_list, term_list);
663         }
664
665         Py_DecRef(py_conditionlist);
666
667         PyGILState_Release(gstate);
668
669         return ret;
670
671 err:
672         PyGILState_Release(gstate);
673
674         return SRD_ERR;
675
676 ret_9999:
677         PyGILState_Release(gstate);
678
679         return 9999;
680 }
681
682 /**
683  * Create a SKIP condition list for condition-less .wait() calls.
684  *
685  * @param di Decoder instance.
686  * @param count Number of samples to skip.
687  *
688  * @retval SRD_OK The new condition list was set successfully.
689  * @retval SRD_ERR There was an error setting the new condition list.
690  *                 The contents of di->condition_list are undefined.
691  *
692  * This routine is a reduced and specialized version of the @ref
693  * set_new_condition_list() and @ref create_term_list() routines which
694  * gets invoked when .wait() was called without specifications for
695  * conditions. This minor duplication of the SKIP term list creation
696  * simplifies the logic and avoids the creation of expensive Python
697  * objects with "constant" values which the caller did not pass in the
698  * first place. It results in maximum sharing of match handling code
699  * paths.
700  */
701 static int set_skip_condition(struct srd_decoder_inst *di, uint64_t count)
702 {
703         struct srd_term *term;
704         GSList *term_list;
705
706         condition_list_free(di);
707         term = g_malloc0(sizeof(*term));
708         term->type = SRD_TERM_SKIP;
709         term->num_samples_to_skip = count;
710         term->num_samples_already_skipped = 0;
711         term_list = g_slist_append(NULL, term);
712         di->condition_list = g_slist_append(di->condition_list, term_list);
713
714         return SRD_OK;
715 }
716
717 static PyObject *Decoder_wait(PyObject *self, PyObject *args)
718 {
719         int ret;
720         uint64_t skip_count;
721         unsigned int i;
722         gboolean found_match;
723         struct srd_decoder_inst *di;
724         PyObject *py_pinvalues, *py_matched;
725         PyGILState_STATE gstate;
726
727         if (!self || !args)
728                 return NULL;
729
730         gstate = PyGILState_Ensure();
731
732         if (!(di = srd_inst_find_by_obj(NULL, self))) {
733                 PyErr_SetString(PyExc_Exception, "decoder instance not found");
734                 PyGILState_Release(gstate);
735                 Py_RETURN_NONE;
736         }
737
738         ret = set_new_condition_list(self, args);
739         if (ret < 0) {
740                 srd_dbg("%s: %s: Aborting wait().", di->inst_id, __func__);
741                 goto err;
742         }
743         if (ret == 9999) {
744                 /*
745                  * Empty condition list, automatic match. Arrange for the
746                  * execution of regular match handling code paths such that
747                  * the next available sample is returned to the caller.
748                  * Make sure to skip one sample when "anywhere within the
749                  * stream", yet make sure to not skip sample number 0.
750                  */
751                 if (di->abs_cur_samplenum)
752                         skip_count = 1;
753                 else if (!di->condition_list)
754                         skip_count = 0;
755                 else
756                         skip_count = 1;
757                 ret = set_skip_condition(di, skip_count);
758                 if (ret < 0) {
759                         srd_dbg("%s: %s: Cannot setup condition-less wait().",
760                                 di->inst_id, __func__);
761                         goto err;
762                 }
763         }
764
765         while (1) {
766
767                 Py_BEGIN_ALLOW_THREADS
768
769                 /* Wait for new samples to process, or termination request. */
770                 g_mutex_lock(&di->data_mutex);
771                 while (!di->got_new_samples && !di->want_wait_terminate)
772                         g_cond_wait(&di->got_new_samples_cond, &di->data_mutex);
773
774                 /*
775                  * Check whether any of the current condition(s) match.
776                  * Arrange for termination requests to take a code path which
777                  * won't find new samples to process, pretends to have processed
778                  * previously stored samples, and returns to the main thread,
779                  * while the termination request still gets signalled.
780                  */
781                 found_match = FALSE;
782                 ret = process_samples_until_condition_match(di, &found_match);
783
784                 Py_END_ALLOW_THREADS
785
786                 /* If there's a match, set self.samplenum etc. and return. */
787                 if (found_match) {
788                         /* Set self.samplenum to the (absolute) sample number that matched. */
789                         PyObject_SetAttrString(di->py_inst, "samplenum",
790                                 PyLong_FromLong(di->abs_cur_samplenum));
791
792                         if (di->match_array && di->match_array->len > 0) {
793                                 py_matched = PyTuple_New(di->match_array->len);
794                                 for (i = 0; i < di->match_array->len; i++)
795                                         PyTuple_SetItem(py_matched, i, PyBool_FromLong(di->match_array->data[i]));
796                                 PyObject_SetAttrString(di->py_inst, "matched", py_matched);
797                                 match_array_free(di);
798                         } else {
799                                 PyObject_SetAttrString(di->py_inst, "matched", Py_None);
800                         }
801
802                         py_pinvalues = get_current_pinvalues(di);
803
804                         g_mutex_unlock(&di->data_mutex);
805
806                         PyGILState_Release(gstate);
807
808                         return py_pinvalues;
809                 }
810
811                 /* No match, reset state for the next chunk. */
812                 di->got_new_samples = FALSE;
813                 di->handled_all_samples = TRUE;
814                 di->abs_start_samplenum = 0;
815                 di->abs_end_samplenum = 0;
816                 di->inbuf = NULL;
817                 di->inbuflen = 0;
818
819                 /* Signal the main thread that we handled all samples. */
820                 g_cond_signal(&di->handled_all_samples_cond);
821
822                 /*
823                  * When termination of wait() and decode() was requested,
824                  * then exit the loop after releasing the mutex.
825                  */
826                 if (di->want_wait_terminate) {
827                         srd_dbg("%s: %s: Will return from wait().",
828                                 di->inst_id, __func__);
829                         g_mutex_unlock(&di->data_mutex);
830                         goto err;
831                 }
832
833                 g_mutex_unlock(&di->data_mutex);
834         }
835
836         PyGILState_Release(gstate);
837
838         Py_RETURN_NONE;
839
840 err:
841         PyGILState_Release(gstate);
842
843         return NULL;
844 }
845
846 /**
847  * Return whether the specified channel was supplied to the decoder.
848  *
849  * @param self TODO. Must not be NULL.
850  * @param args TODO. Must not be NULL.
851  *
852  * @retval Py_True The channel has been supplied by the frontend.
853  * @retval Py_False The channel has been supplied by the frontend.
854  * @retval NULL An error occurred.
855  */
856 static PyObject *Decoder_has_channel(PyObject *self, PyObject *args)
857 {
858         int idx, max_idx;
859         struct srd_decoder_inst *di;
860         PyObject *py_channel;
861         PyGILState_STATE gstate;
862
863         if (!self || !args)
864                 return NULL;
865
866         gstate = PyGILState_Ensure();
867
868         if (!(di = srd_inst_find_by_obj(NULL, self))) {
869                 PyErr_SetString(PyExc_Exception, "decoder instance not found");
870                 goto err;
871         }
872
873         /* Parse the argument of self.has_channel() into 'py_channel'. */
874         if (!PyArg_ParseTuple(args, "O", &py_channel)) {
875                 /* Let Python raise this exception. */
876                 goto err;
877         }
878
879         if (!PyLong_Check(py_channel)) {
880                 PyErr_SetString(PyExc_Exception, "channel index not a number");
881                 goto err;
882         }
883
884         idx = PyLong_AsLong(py_channel);
885         max_idx = g_slist_length(di->decoder->channels)
886                 + g_slist_length(di->decoder->opt_channels) - 1;
887
888         if (idx < 0 || idx > max_idx) {
889                 srd_err("Invalid channel index %d/%d.", idx, max_idx);
890                 PyErr_SetString(PyExc_Exception, "invalid channel");
891                 goto err;
892         }
893
894         PyGILState_Release(gstate);
895
896         return (di->dec_channelmap[idx] == -1) ? Py_False : Py_True;
897
898 err:
899         PyGILState_Release(gstate);
900
901         return NULL;
902 }
903
904 static PyMethodDef Decoder_methods[] = {
905         {"put", Decoder_put, METH_VARARGS,
906          "Accepts a dictionary with the following keys: startsample, endsample, data"},
907         {"register", (PyCFunction)Decoder_register, METH_VARARGS|METH_KEYWORDS,
908                         "Register a new output stream"},
909         {"wait", Decoder_wait, METH_VARARGS,
910                         "Wait for one or more conditions to occur"},
911         {"has_channel", Decoder_has_channel, METH_VARARGS,
912                         "Report whether a channel was supplied"},
913         {NULL, NULL, 0, NULL}
914 };
915
916 /**
917  * Create the sigrokdecode.Decoder type.
918  *
919  * @return The new type object.
920  *
921  * @private
922  */
923 SRD_PRIV PyObject *srd_Decoder_type_new(void)
924 {
925         PyType_Spec spec;
926         PyType_Slot slots[] = {
927                 { Py_tp_doc, "sigrok Decoder base class" },
928                 { Py_tp_methods, Decoder_methods },
929                 { Py_tp_new, (void *)&PyType_GenericNew },
930                 { 0, NULL }
931         };
932         PyObject *py_obj;
933         PyGILState_STATE gstate;
934
935         gstate = PyGILState_Ensure();
936
937         spec.name = "sigrokdecode.Decoder";
938         spec.basicsize = sizeof(srd_Decoder);
939         spec.itemsize = 0;
940         spec.flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE;
941         spec.slots = slots;
942
943         py_obj = PyType_FromSpec(&spec);
944
945         PyGILState_Release(gstate);
946
947         return py_obj;
948 }