Various Doxygen fixes.
[libsigrokdecode.git] / instance.c
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 <config.h>
22 #include "libsigrokdecode-internal.h" /* First, so we avoid a _POSIX_C_SOURCE warning. */
23 #include "libsigrokdecode.h"
24 #include <glib.h>
25 #include <inttypes.h>
26 #include <stdlib.h>
27 #include <stdint.h>
28
29 /** @cond PRIVATE */
30
31 extern SRD_PRIV GSList *sessions;
32
33 /* module_sigrokdecode.c */
34 extern SRD_PRIV PyObject *srd_logic_type;
35
36 static void srd_inst_join_decode_thread(struct srd_decoder_inst *di);
37 static void srd_inst_reset_state(struct srd_decoder_inst *di);
38 SRD_PRIV void oldpins_array_free(struct srd_decoder_inst *di);
39
40 /** @endcond */
41
42 /**
43  * @file
44  *
45  * Decoder instance handling.
46  */
47
48 /**
49  * @defgroup grp_instances Decoder instances
50  *
51  * Decoder instance handling.
52  *
53  * @{
54  */
55
56 /**
57  * Set one or more options in a decoder instance.
58  *
59  * Handled options are removed from the hash.
60  *
61  * @param di Decoder instance.
62  * @param options A GHashTable of options to set.
63  *
64  * @return SRD_OK upon success, a (negative) error code otherwise.
65  *
66  * @since 0.1.0
67  */
68 SRD_API int srd_inst_option_set(struct srd_decoder_inst *di,
69                 GHashTable *options)
70 {
71         struct srd_decoder_option *sdo;
72         PyObject *py_di_options, *py_optval;
73         GVariant *value;
74         GSList *l;
75         double val_double;
76         gint64 val_int;
77         int ret;
78         const char *val_str;
79
80         if (!di) {
81                 srd_err("Invalid decoder instance.");
82                 return SRD_ERR_ARG;
83         }
84
85         if (!options) {
86                 srd_err("Invalid options GHashTable.");
87                 return SRD_ERR_ARG;
88         }
89
90         if (!PyObject_HasAttrString(di->decoder->py_dec, "options")) {
91                 /* Decoder has no options. */
92                 if (g_hash_table_size(options) == 0) {
93                         /* No options provided. */
94                         return SRD_OK;
95                 } else {
96                         srd_err("Protocol decoder has no options.");
97                         return SRD_ERR_ARG;
98                 }
99                 return SRD_OK;
100         }
101
102         ret = SRD_ERR_PYTHON;
103         py_optval = NULL;
104
105         /*
106          * The 'options' tuple is a class variable, but we need to
107          * change it. Changing it directly will affect the entire class,
108          * so we need to create a new object for it, and populate that
109          * instead.
110          */
111         if (!(py_di_options = PyObject_GetAttrString(di->py_inst, "options")))
112                 goto err_out;
113         Py_DECREF(py_di_options);
114         py_di_options = PyDict_New();
115         PyObject_SetAttrString(di->py_inst, "options", py_di_options);
116
117         for (l = di->decoder->options; l; l = l->next) {
118                 sdo = l->data;
119                 if ((value = g_hash_table_lookup(options, sdo->id))) {
120                         /* A value was supplied for this option. */
121                         if (!g_variant_type_equal(g_variant_get_type(value),
122                                   g_variant_get_type(sdo->def))) {
123                                 srd_err("Option '%s' should have the same type "
124                                         "as the default value.", sdo->id);
125                                 goto err_out;
126                         }
127                 } else {
128                         /* Use default for this option. */
129                         value = sdo->def;
130                 }
131                 if (g_variant_is_of_type(value, G_VARIANT_TYPE_STRING)) {
132                         val_str = g_variant_get_string(value, NULL);
133                         if (!(py_optval = PyUnicode_FromString(val_str))) {
134                                 /* Some UTF-8 encoding error. */
135                                 PyErr_Clear();
136                                 srd_err("Option '%s' requires a UTF-8 string value.", sdo->id);
137                                 goto err_out;
138                         }
139                 } else if (g_variant_is_of_type(value, G_VARIANT_TYPE_INT64)) {
140                         val_int = g_variant_get_int64(value);
141                         if (!(py_optval = PyLong_FromLong(val_int))) {
142                                 /* ValueError Exception */
143                                 PyErr_Clear();
144                                 srd_err("Option '%s' has invalid integer value.", sdo->id);
145                                 goto err_out;
146                         }
147                 } else if (g_variant_is_of_type(value, G_VARIANT_TYPE_DOUBLE)) {
148                         val_double = g_variant_get_double(value);
149                         if (!(py_optval = PyFloat_FromDouble(val_double))) {
150                                 /* ValueError Exception */
151                                 PyErr_Clear();
152                                 srd_err("Option '%s' has invalid float value.",
153                                         sdo->id);
154                                 goto err_out;
155                         }
156                 }
157                 if (PyDict_SetItemString(py_di_options, sdo->id, py_optval) == -1)
158                         goto err_out;
159                 /* Not harmful even if we used the default. */
160                 g_hash_table_remove(options, sdo->id);
161         }
162         if (g_hash_table_size(options) != 0)
163                 srd_warn("Unknown options specified for '%s'", di->inst_id);
164
165         ret = SRD_OK;
166
167 err_out:
168         Py_XDECREF(py_optval);
169         if (PyErr_Occurred()) {
170                 srd_exception_catch("Stray exception in srd_inst_option_set()");
171                 ret = SRD_ERR_PYTHON;
172         }
173
174         return ret;
175 }
176
177 /* Helper GComparefunc for g_slist_find_custom() in srd_inst_channel_set_all() */
178 static gint compare_channel_id(const struct srd_channel *pdch,
179                         const char *channel_id)
180 {
181         return strcmp(pdch->id, channel_id);
182 }
183
184 /**
185  * Set all channels in a decoder instance.
186  *
187  * This function sets _all_ channels for the specified decoder instance, i.e.,
188  * it overwrites any channels that were already defined (if any).
189  *
190  * @param di Decoder instance.
191  * @param new_channels A GHashTable of channels to set. Key is channel name,
192  *                     value is the channel number. Samples passed to this
193  *                     instance will be arranged in this order.
194  *
195  * @return SRD_OK upon success, a (negative) error code otherwise.
196  *
197  * @since 0.4.0
198  */
199 SRD_API int srd_inst_channel_set_all(struct srd_decoder_inst *di,
200                 GHashTable *new_channels)
201 {
202         GVariant *channel_val;
203         GList *l;
204         GSList *sl;
205         struct srd_channel *pdch;
206         int *new_channelmap, new_channelnum, num_required_channels, i;
207         char *channel_id;
208
209         srd_dbg("Setting channels for instance %s with list of %d channels.",
210                 di->inst_id, g_hash_table_size(new_channels));
211
212         if (g_hash_table_size(new_channels) == 0)
213                 /* No channels provided. */
214                 return SRD_OK;
215
216         if (di->dec_num_channels == 0) {
217                 /* Decoder has no channels. */
218                 srd_err("Protocol decoder %s has no channels to define.",
219                         di->decoder->name);
220                 return SRD_ERR_ARG;
221         }
222
223         new_channelmap = g_malloc(sizeof(int) * di->dec_num_channels);
224
225         /*
226          * For now, map all indexes to channel -1 (can be overridden later).
227          * This -1 is interpreted as an unspecified channel later.
228          */
229         for (i = 0; i < di->dec_num_channels; i++)
230                 new_channelmap[i] = -1;
231
232         for (l = g_hash_table_get_keys(new_channels); l; l = l->next) {
233                 channel_id = l->data;
234                 channel_val = g_hash_table_lookup(new_channels, channel_id);
235                 if (!g_variant_is_of_type(channel_val, G_VARIANT_TYPE_INT32)) {
236                         /* Channel name was specified without a value. */
237                         srd_err("No channel number was specified for %s.",
238                                         channel_id);
239                         g_free(new_channelmap);
240                         return SRD_ERR_ARG;
241                 }
242                 new_channelnum = g_variant_get_int32(channel_val);
243                 if (!(sl = g_slist_find_custom(di->decoder->channels, channel_id,
244                                 (GCompareFunc)compare_channel_id))) {
245                         /* Fall back on optional channels. */
246                         if (!(sl = g_slist_find_custom(di->decoder->opt_channels,
247                              channel_id, (GCompareFunc)compare_channel_id))) {
248                                 srd_err("Protocol decoder %s has no channel "
249                                         "'%s'.", di->decoder->name, channel_id);
250                                 g_free(new_channelmap);
251                                 return SRD_ERR_ARG;
252                         }
253                 }
254                 pdch = sl->data;
255                 new_channelmap[pdch->order] = new_channelnum;
256                 srd_dbg("Setting channel mapping: %s (index %d) = channel %d.",
257                         pdch->id, pdch->order, new_channelnum);
258         }
259
260         srd_dbg("Final channel map:");
261         num_required_channels = g_slist_length(di->decoder->channels);
262         for (i = 0; i < di->dec_num_channels; i++) {
263                 srd_dbg(" - index %d = channel %d (%s)", i, new_channelmap[i],
264                         (i < num_required_channels) ? "required" : "optional");
265         }
266
267         /* Report an error if not all required channels were specified. */
268         for (i = 0; i < num_required_channels; i++) {
269                 if (new_channelmap[i] != -1)
270                         continue;
271                 pdch = g_slist_nth(di->decoder->channels, i)->data;
272                 srd_err("Required channel '%s' (index %d) was not specified.",
273                         pdch->id, i);
274                 return SRD_ERR;
275         }
276
277         g_free(di->dec_channelmap);
278         di->dec_channelmap = new_channelmap;
279
280         return SRD_OK;
281 }
282
283 /**
284  * Create a new protocol decoder instance.
285  *
286  * @param sess The session holding the protocol decoder instance.
287  * @param decoder_id Decoder 'id' field.
288  * @param options GHashtable of options which override the defaults set in
289  *                the decoder class. May be NULL.
290  *
291  * @return Pointer to a newly allocated struct srd_decoder_inst, or
292  *         NULL in case of failure.
293  *
294  * @since 0.3.0
295  */
296 SRD_API struct srd_decoder_inst *srd_inst_new(struct srd_session *sess,
297                 const char *decoder_id, GHashTable *options)
298 {
299         int i;
300         struct srd_decoder *dec;
301         struct srd_decoder_inst *di;
302         char *inst_id;
303
304         i = 1;
305         srd_dbg("Creating new %s instance.", decoder_id);
306
307         if (session_is_valid(sess) != SRD_OK) {
308                 srd_err("Invalid session.");
309                 return NULL;
310         }
311
312         if (!(dec = srd_decoder_get_by_id(decoder_id))) {
313                 srd_err("Protocol decoder %s not found.", decoder_id);
314                 return NULL;
315         }
316
317         di = g_malloc0(sizeof(struct srd_decoder_inst));
318
319         di->decoder = dec;
320         di->sess = sess;
321
322         if (options) {
323                 inst_id = g_hash_table_lookup(options, "id");
324                 if (inst_id)
325                         di->inst_id = g_strdup(inst_id);
326                 g_hash_table_remove(options, "id");
327         }
328
329         /* Create a unique instance ID (as none was provided). */
330         if (!di->inst_id) {
331                 di->inst_id = g_strdup_printf("%s-%d", decoder_id, i++);
332                 while (srd_inst_find_by_id(sess, di->inst_id)) {
333                         g_free(di->inst_id);
334                         di->inst_id = g_strdup_printf("%s-%d", decoder_id, i++);
335                 }
336         }
337
338         /*
339          * Prepare a default channel map, where samples come in the
340          * order in which the decoder class defined them.
341          */
342         di->dec_num_channels = g_slist_length(di->decoder->channels) +
343                         g_slist_length(di->decoder->opt_channels);
344         if (di->dec_num_channels) {
345                 di->dec_channelmap =
346                                 g_malloc(sizeof(int) * di->dec_num_channels);
347                 for (i = 0; i < di->dec_num_channels; i++)
348                         di->dec_channelmap[i] = i;
349                 /*
350                  * Will be used to prepare a sample at every iteration
351                  * of the instance's decode() method.
352                  */
353                 di->channel_samples = g_malloc(di->dec_num_channels);
354         }
355
356         /* Default to the initial pins being the same as in sample 0. */
357         di->old_pins_array = g_array_sized_new(FALSE, TRUE, sizeof(uint8_t),
358                                                 di->dec_num_channels);
359         g_array_set_size(di->old_pins_array, di->dec_num_channels);
360         memset(di->old_pins_array->data, SRD_INITIAL_PIN_SAME_AS_SAMPLE0,
361                 di->dec_num_channels);
362
363         /* Create a new instance of this decoder class. */
364         if (!(di->py_inst = PyObject_CallObject(dec->py_dec, NULL))) {
365                 if (PyErr_Occurred())
366                         srd_exception_catch("Failed to create %s instance",
367                                         decoder_id);
368                 g_free(di->dec_channelmap);
369                 g_free(di);
370                 return NULL;
371         }
372
373         if (options && srd_inst_option_set(di, options) != SRD_OK) {
374                 g_free(di->dec_channelmap);
375                 g_free(di);
376                 return NULL;
377         }
378
379         di->condition_list = NULL;
380         di->match_array = NULL;
381         di->abs_start_samplenum = 0;
382         di->abs_end_samplenum = 0;
383         di->inbuf = NULL;
384         di->inbuflen = 0;
385         di->abs_cur_samplenum = 0;
386         di->thread_handle = NULL;
387         di->got_new_samples = FALSE;
388         di->handled_all_samples = FALSE;
389         di->want_wait_terminate = FALSE;
390
391         /*
392          * Strictly speaking initialization of statically allocated
393          * condition and mutex variables (or variables allocated on the
394          * stack) is not required, but won't harm either. Explicitly
395          * running init() will better match subsequent clear() calls.
396          */
397         g_cond_init(&di->got_new_samples_cond);
398         g_cond_init(&di->handled_all_samples_cond);
399         g_mutex_init(&di->data_mutex);
400
401         /* Instance takes input from a frontend by default. */
402         sess->di_list = g_slist_append(sess->di_list, di);
403         srd_dbg("Created new %s instance with ID %s.", decoder_id, di->inst_id);
404
405         return di;
406 }
407
408 static void srd_inst_join_decode_thread(struct srd_decoder_inst *di)
409 {
410         if (!di)
411                 return;
412         if (!di->thread_handle)
413                 return;
414
415         srd_dbg("%s: Joining decoder thread.", di->inst_id);
416
417         /*
418          * Terminate potentially running threads which still
419          * execute the decoder instance's decode() method.
420          */
421         srd_dbg("%s: Raising want_term, sending got_new.", di->inst_id);
422         g_mutex_lock(&di->data_mutex);
423         di->want_wait_terminate = TRUE;
424         g_cond_signal(&di->got_new_samples_cond);
425         g_mutex_unlock(&di->data_mutex);
426
427         srd_dbg("%s: Running join().", di->inst_id);
428         (void)g_thread_join(di->thread_handle);
429         srd_dbg("%s: Call to join() done.", di->inst_id);
430         di->thread_handle = NULL;
431
432         /*
433          * Reset condition and mutex variables, such that next
434          * operations on them will find them in a clean state.
435          */
436         g_cond_clear(&di->got_new_samples_cond);
437         g_cond_init(&di->got_new_samples_cond);
438         g_cond_clear(&di->handled_all_samples_cond);
439         g_cond_init(&di->handled_all_samples_cond);
440         g_mutex_clear(&di->data_mutex);
441         g_mutex_init(&di->data_mutex);
442 }
443
444 static void srd_inst_reset_state(struct srd_decoder_inst *di)
445 {
446         if (!di)
447                 return;
448
449         srd_dbg("%s: Resetting decoder state.", di->inst_id);
450
451         /*
452          * Reset internal state of the decoder.
453          */
454         condition_list_free(di);
455         match_array_free(di);
456         di->abs_start_samplenum = 0;
457         di->abs_end_samplenum = 0;
458         di->inbuf = NULL;
459         di->inbuflen = 0;
460         di->abs_cur_samplenum = 0;
461         oldpins_array_free(di);
462         di->got_new_samples = FALSE;
463         di->handled_all_samples = FALSE;
464         di->want_wait_terminate = FALSE;
465         /* Conditions and mutex got reset after joining the thread. */
466 }
467
468 /**
469  * Stack a decoder instance on top of another.
470  *
471  * @param sess The session holding the protocol decoder instances.
472  * @param di_bottom The instance on top of which di_top will be stacked.
473  * @param di_top The instance to go on top.
474  *
475  * @return SRD_OK upon success, a (negative) error code otherwise.
476  *
477  * @since 0.3.0
478  */
479 SRD_API int srd_inst_stack(struct srd_session *sess,
480                 struct srd_decoder_inst *di_bottom,
481                 struct srd_decoder_inst *di_top)
482 {
483
484         if (session_is_valid(sess) != SRD_OK) {
485                 srd_err("Invalid session.");
486                 return SRD_ERR_ARG;
487         }
488
489         if (!di_bottom || !di_top) {
490                 srd_err("Invalid from/to instance pair.");
491                 return SRD_ERR_ARG;
492         }
493
494         if (g_slist_find(sess->di_list, di_top)) {
495                 /* Remove from the unstacked list. */
496                 sess->di_list = g_slist_remove(sess->di_list, di_top);
497         }
498
499         /* Stack on top of source di. */
500         di_bottom->next_di = g_slist_append(di_bottom->next_di, di_top);
501
502         srd_dbg("Stacked %s onto %s.", di_top->inst_id, di_bottom->inst_id);
503
504         return SRD_OK;
505 }
506
507 /**
508  * Search a decoder instance and its stack for instance ID.
509  *
510  * @param[in] inst_id ID to search for.
511  * @param[in] stack A decoder instance, potentially with stacked instances.
512  *
513  * @return The matching instance, or NULL.
514  */
515 static struct srd_decoder_inst *srd_inst_find_by_id_stack(const char *inst_id,
516                 struct srd_decoder_inst *stack)
517 {
518         const GSList *l;
519         struct srd_decoder_inst *tmp, *di;
520
521         if (!strcmp(stack->inst_id, inst_id))
522                 return stack;
523
524         /* Otherwise, look recursively in our stack. */
525         di = NULL;
526         if (stack->next_di) {
527                 for (l = stack->next_di; l; l = l->next) {
528                         tmp = l->data;
529                         if (!strcmp(tmp->inst_id, inst_id)) {
530                                 di = tmp;
531                                 break;
532                         }
533                 }
534         }
535
536         return di;
537 }
538
539 /**
540  * Find a decoder instance by its instance ID.
541  *
542  * This will recurse to find the instance anywhere in the stack tree of the
543  * given session.
544  *
545  * @param sess The session holding the protocol decoder instance.
546  * @param inst_id The instance ID to be found.
547  *
548  * @return Pointer to struct srd_decoder_inst, or NULL if not found.
549  *
550  * @since 0.3.0
551  */
552 SRD_API struct srd_decoder_inst *srd_inst_find_by_id(struct srd_session *sess,
553                 const char *inst_id)
554 {
555         GSList *l;
556         struct srd_decoder_inst *tmp, *di;
557
558         if (session_is_valid(sess) != SRD_OK) {
559                 srd_err("Invalid session.");
560                 return NULL;
561         }
562
563         di = NULL;
564         for (l = sess->di_list; l; l = l->next) {
565                 tmp = l->data;
566                 if ((di = srd_inst_find_by_id_stack(inst_id, tmp)) != NULL)
567                         break;
568         }
569
570         return di;
571 }
572
573 static struct srd_decoder_inst *srd_sess_inst_find_by_obj(
574                 struct srd_session *sess, const GSList *stack,
575                 const PyObject *obj)
576 {
577         const GSList *l;
578         struct srd_decoder_inst *tmp, *di;
579
580         if (session_is_valid(sess) != SRD_OK) {
581                 srd_err("Invalid session.");
582                 return NULL;
583         }
584
585         di = NULL;
586         for (l = stack ? stack : sess->di_list; di == NULL && l != NULL; l = l->next) {
587                 tmp = l->data;
588                 if (tmp->py_inst == obj)
589                         di = tmp;
590                 else if (tmp->next_di)
591                         di = srd_sess_inst_find_by_obj(sess, tmp->next_di, obj);
592         }
593
594         return di;
595 }
596
597 /**
598  * Find a decoder instance by its Python object.
599  *
600  * I.e. find that instance's instantiation of the sigrokdecode.Decoder class.
601  * This will recurse to find the instance anywhere in the stack tree of all
602  * sessions.
603  *
604  * @param stack Pointer to a GSList of struct srd_decoder_inst, indicating the
605  *              stack to search. To start searching at the bottom level of
606  *              decoder instances, pass NULL.
607  * @param obj The Python class instantiation.
608  *
609  * @return Pointer to struct srd_decoder_inst, or NULL if not found.
610  *
611  * @private
612  *
613  * @since 0.1.0
614  */
615 SRD_PRIV struct srd_decoder_inst *srd_inst_find_by_obj(const GSList *stack,
616                 const PyObject *obj)
617 {
618         struct srd_decoder_inst *di;
619         struct srd_session *sess;
620         GSList *l;
621
622         di = NULL;
623         for (l = sessions; di == NULL && l != NULL; l = l->next) {
624                 sess = l->data;
625                 di = srd_sess_inst_find_by_obj(sess, stack, obj);
626         }
627
628         return di;
629 }
630
631 /**
632  * Set the list of initial (assumed) pin values.
633  *
634  * @param di Decoder instance to use. Must not be NULL.
635  * @param initial_pins A GArray of uint8_t values. Must not be NULL.
636  *
637  * @since 0.5.0
638  */
639 SRD_API int srd_inst_initial_pins_set_all(struct srd_decoder_inst *di, GArray *initial_pins)
640 {
641         int i;
642         GString *s;
643
644         if (!di) {
645                 srd_err("Invalid decoder instance.");
646                 return SRD_ERR_ARG;
647         }
648
649         if (!initial_pins)
650                 return SRD_ERR_ARG;
651
652         if (initial_pins->len != (guint)di->dec_num_channels) {
653                 srd_err("Incorrect number of channels (need %d, got %d).",
654                         di->dec_num_channels, initial_pins->len);
655                 return SRD_ERR_ARG;
656         }
657
658         /* Sanity-check initial pin state values. */
659         for (i = 0; i < di->dec_num_channels; i++) {
660                 if (initial_pins->data[i] <= 2)
661                         continue;
662                 srd_err("Invalid initial channel %d pin state: %d.",
663                         i, initial_pins->data[i]);
664                 return SRD_ERR_ARG;
665         }
666
667         s = g_string_sized_new(100);
668         for (i = 0; i < di->dec_num_channels; i++) {
669                 di->old_pins_array->data[i] = initial_pins->data[i];
670                 g_string_append_printf(s, "%d, ", di->old_pins_array->data[i]);
671         }
672         s = g_string_truncate(s, s->len - 2);
673         srd_dbg("Initial pins: %s.", s->str);
674         g_string_free(s, TRUE);
675
676         return SRD_OK;
677 }
678
679 /** @private */
680 SRD_PRIV void oldpins_array_free(struct srd_decoder_inst *di)
681 {
682         if (!di)
683                 return;
684         if (!di->old_pins_array)
685                 return;
686
687         srd_dbg("%s: Releasing initial pin state.", di->inst_id);
688
689         g_array_free(di->old_pins_array, TRUE);
690         di->old_pins_array = NULL;
691 }
692
693 /** @private */
694 SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di)
695 {
696         PyObject *py_res;
697         GSList *l;
698         struct srd_decoder_inst *next_di;
699         int ret;
700
701         srd_dbg("Calling start() method on protocol decoder instance %s.",
702                         di->inst_id);
703
704         /* Run self.start(). */
705         if (!(py_res = PyObject_CallMethod(di->py_inst, "start", NULL))) {
706                 srd_exception_catch("Protocol decoder instance %s",
707                                 di->inst_id);
708                 return SRD_ERR_PYTHON;
709         }
710         Py_DecRef(py_res);
711
712         /* Set self.samplenum to 0. */
713         PyObject_SetAttrString(di->py_inst, "samplenum", PyLong_FromLong(0));
714
715         /* Set self.matched to None. */
716         PyObject_SetAttrString(di->py_inst, "matched", Py_None);
717
718         /* Start all the PDs stacked on top of this one. */
719         for (l = di->next_di; l; l = l->next) {
720                 next_di = l->data;
721                 if ((ret = srd_inst_start(next_di)) != SRD_OK)
722                         return ret;
723         }
724
725         return SRD_OK;
726 }
727
728 /**
729  * Check whether the specified sample matches the specified term.
730  *
731  * In the case of SRD_TERM_SKIP, this function can modify
732  * term->num_samples_already_skipped.
733  *
734  * @param old_sample The value of the previous sample (0/1).
735  * @param sample The value of the current sample (0/1).
736  * @param term The term that should be checked for a match. Must not be NULL.
737  *
738  * @retval TRUE The current sample matches the specified term.
739  * @retval FALSE The current sample doesn't match the specified term, or an
740  *               invalid term was provided.
741  *
742  * @private
743  */
744 static gboolean sample_matches(uint8_t old_sample, uint8_t sample, struct srd_term *term)
745 {
746         if (!term)
747                 return FALSE;
748
749         switch (term->type) {
750         case SRD_TERM_HIGH:
751                 if (sample == 1)
752                         return TRUE;
753                 break;
754         case SRD_TERM_LOW:
755                 if (sample == 0)
756                         return TRUE;
757                 break;
758         case SRD_TERM_RISING_EDGE:
759                 if (old_sample == 0 && sample == 1)
760                         return TRUE;
761                 break;
762         case SRD_TERM_FALLING_EDGE:
763                 if (old_sample == 1 && sample == 0)
764                         return TRUE;
765                 break;
766         case SRD_TERM_EITHER_EDGE:
767                 if ((old_sample == 1 && sample == 0) || (old_sample == 0 && sample == 1))
768                         return TRUE;
769                 break;
770         case SRD_TERM_NO_EDGE:
771                 if ((old_sample == 0 && sample == 0) || (old_sample == 1 && sample == 1))
772                         return TRUE;
773                 break;
774         case SRD_TERM_SKIP:
775                 if (term->num_samples_already_skipped == term->num_samples_to_skip)
776                         return TRUE;
777                 term->num_samples_already_skipped++;
778                 break;
779         default:
780                 srd_err("Unknown term type %d.", term->type);
781                 break;
782         }
783
784         return FALSE;
785 }
786
787 /** @private */
788 SRD_PRIV void match_array_free(struct srd_decoder_inst *di)
789 {
790         if (!di || !di->match_array)
791                 return;
792
793         g_array_free(di->match_array, TRUE);
794         di->match_array = NULL;
795 }
796
797 /** @private */
798 SRD_PRIV void condition_list_free(struct srd_decoder_inst *di)
799 {
800         GSList *l, *ll;
801
802         if (!di)
803                 return;
804
805         for (l = di->condition_list; l; l = l->next) {
806                 ll = l->data;
807                 if (ll)
808                         g_slist_free_full(ll, g_free);
809         }
810
811         di->condition_list = NULL;
812 }
813
814 static gboolean have_non_null_conds(const struct srd_decoder_inst *di)
815 {
816         GSList *l, *cond;
817
818         if (!di)
819                 return FALSE;
820
821         for (l = di->condition_list; l; l = l->next) {
822                 cond = l->data;
823                 if (cond)
824                         return TRUE;
825         }
826
827         return FALSE;
828 }
829
830 static void update_old_pins_array(struct srd_decoder_inst *di,
831                 const uint8_t *sample_pos)
832 {
833         uint8_t sample;
834         int i, byte_offset, bit_offset;
835
836         if (!di || !di->dec_channelmap || !sample_pos)
837                 return;
838
839         for (i = 0; i < di->dec_num_channels; i++) {
840                 byte_offset = di->dec_channelmap[i] / 8;
841                 bit_offset = di->dec_channelmap[i] % 8;
842                 sample = *(sample_pos + byte_offset) & (1 << bit_offset) ? 1 : 0;
843                 di->old_pins_array->data[i] = sample;
844         }
845 }
846
847 static void update_old_pins_array_initial_pins(struct srd_decoder_inst *di)
848 {
849         uint8_t sample;
850         int i, byte_offset, bit_offset;
851         const uint8_t *sample_pos;
852
853         if (!di || !di->dec_channelmap)
854                 return;
855
856         sample_pos = di->inbuf + ((di->abs_cur_samplenum - di->abs_start_samplenum) * di->data_unitsize);
857
858         for (i = 0; i < di->dec_num_channels; i++) {
859                 if (di->old_pins_array->data[i] != SRD_INITIAL_PIN_SAME_AS_SAMPLE0)
860                         continue;
861                 byte_offset = di->dec_channelmap[i] / 8;
862                 bit_offset = di->dec_channelmap[i] % 8;
863                 sample = *(sample_pos + byte_offset) & (1 << bit_offset) ? 1 : 0;
864                 di->old_pins_array->data[i] = sample;
865         }
866 }
867
868 static gboolean term_matches(const struct srd_decoder_inst *di,
869                 struct srd_term *term, const uint8_t *sample_pos)
870 {
871         uint8_t old_sample, sample;
872         int byte_offset, bit_offset, ch;
873
874         if (!di || !di->dec_channelmap || !term || !sample_pos)
875                 return FALSE;
876
877         /* Overwritten below (or ignored for SRD_TERM_SKIP). */
878         old_sample = sample = 0;
879
880         if (term->type != SRD_TERM_SKIP) {
881                 ch = term->channel;
882                 byte_offset = di->dec_channelmap[ch] / 8;
883                 bit_offset = di->dec_channelmap[ch] % 8;
884                 sample = *(sample_pos + byte_offset) & (1 << bit_offset) ? 1 : 0;
885                 old_sample = di->old_pins_array->data[ch];
886         }
887
888         return sample_matches(old_sample, sample, term);
889 }
890
891 static gboolean all_terms_match(const struct srd_decoder_inst *di,
892                 const GSList *cond, const uint8_t *sample_pos)
893 {
894         const GSList *l;
895         struct srd_term *term;
896
897         if (!di || !cond || !sample_pos)
898                 return FALSE;
899
900         for (l = cond; l; l = l->next) {
901                 term = l->data;
902                 if (!term_matches(di, term, sample_pos))
903                         return FALSE;
904         }
905
906         return TRUE;
907 }
908
909 static gboolean at_least_one_condition_matched(
910                 const struct srd_decoder_inst *di, unsigned int num_conditions)
911 {
912         unsigned int i;
913
914         if (!di)
915                 return FALSE;
916
917         for (i = 0; i < num_conditions; i++) {
918                 if (di->match_array->data[i])
919                         return TRUE;
920         }
921
922         return FALSE;
923 }
924
925 static gboolean find_match(struct srd_decoder_inst *di)
926 {
927         static uint64_t s = 0;
928         uint64_t i, j, num_samples_to_process;
929         GSList *l, *cond;
930         const uint8_t *sample_pos;
931         unsigned int num_conditions;
932
933         /* Check whether the condition list is NULL/empty. */
934         if (!di->condition_list) {
935                 srd_dbg("NULL/empty condition list, automatic match.");
936                 return TRUE;
937         }
938
939         /* Check whether we have any non-NULL conditions. */
940         if (!have_non_null_conds(di)) {
941                 srd_dbg("Only NULL conditions in list, automatic match.");
942                 return TRUE;
943         }
944
945         num_samples_to_process = di->abs_end_samplenum - di->abs_cur_samplenum;
946         num_conditions = g_slist_length(di->condition_list);
947
948         /* di->match_array is NULL here. Create a new GArray. */
949         di->match_array = g_array_sized_new(FALSE, TRUE, sizeof(gboolean), num_conditions);
950         g_array_set_size(di->match_array, num_conditions);
951
952         /* Sample 0: Set di->old_pins_array for SRD_INITIAL_PIN_SAME_AS_SAMPLE0 pins. */
953         if (di->abs_cur_samplenum == 0)
954                 update_old_pins_array_initial_pins(di);
955
956         for (i = 0, s = 0; i < num_samples_to_process; i++, s++, (di->abs_cur_samplenum)++) {
957
958                 sample_pos = di->inbuf + ((di->abs_cur_samplenum - di->abs_start_samplenum) * di->data_unitsize);
959
960                 /* Check whether the current sample matches at least one of the conditions (logical OR). */
961                 /* IMPORTANT: We need to check all conditions, even if there was a match already! */
962                 for (l = di->condition_list, j = 0; l; l = l->next, j++) {
963                         cond = l->data;
964                         if (!cond)
965                                 continue;
966                         /* All terms in 'cond' must match (logical AND). */
967                         di->match_array->data[j] = all_terms_match(di, cond, sample_pos);
968                 }
969
970                 update_old_pins_array(di, sample_pos);
971
972                 /* If at least one condition matched we're done. */
973                 if (at_least_one_condition_matched(di, num_conditions))
974                         return TRUE;
975         }
976
977         return FALSE;
978 }
979
980 /**
981  * Process available samples and check if they match the defined conditions.
982  *
983  * This function returns if there is an error, or when a match is found, or
984  * when all samples have been processed (whether a match was found or not).
985  * This function immediately terminates when the decoder's wait() method
986  * invocation shall get terminated.
987  *
988  * @param di The decoder instance to use. Must not be NULL.
989  * @param found_match Will be set to TRUE if at least one condition matched,
990  *                    FALSE otherwise. Must not be NULL.
991  *
992  * @retval SRD_OK No errors occured, see found_match for the result.
993  * @retval SRD_ERR_ARG Invalid arguments.
994  *
995  * @private
996  */
997 SRD_PRIV int process_samples_until_condition_match(struct srd_decoder_inst *di, gboolean *found_match)
998 {
999         if (!di || !found_match)
1000                 return SRD_ERR_ARG;
1001
1002         *found_match = FALSE;
1003         if (di->want_wait_terminate)
1004                 return SRD_OK;
1005
1006         /* Check if any of the current condition(s) match. */
1007         while (TRUE) {
1008                 /* Feed the (next chunk of the) buffer to find_match(). */
1009                 *found_match = find_match(di);
1010
1011                 /* Did we handle all samples yet? */
1012                 if (di->abs_cur_samplenum >= di->abs_end_samplenum) {
1013                         srd_dbg("Done, handled all samples (abs cur %" PRIu64
1014                                 " / abs end %" PRIu64 ").",
1015                                 di->abs_cur_samplenum, di->abs_end_samplenum);
1016                         return SRD_OK;
1017                 }
1018
1019                 /* If we didn't find a match, continue looking. */
1020                 if (!(*found_match))
1021                         continue;
1022
1023                 /* At least one condition matched, return. */
1024                 return SRD_OK;
1025         }
1026
1027         return SRD_OK;
1028 }
1029
1030 /**
1031  * Worker thread (per PD-stack).
1032  *
1033  * @param data Pointer to the lowest-level PD's device instance.
1034  *             Must not be NULL.
1035  *
1036  * @return NULL if there was an error.
1037  */
1038 static gpointer di_thread(gpointer data)
1039 {
1040         PyObject *py_res;
1041         struct srd_decoder_inst *di;
1042         int wanted_term;
1043
1044         if (!data)
1045                 return NULL;
1046
1047         di = data;
1048
1049         srd_dbg("%s: Starting thread routine for decoder.", di->inst_id);
1050
1051         /*
1052          * Call self.decode(). Only returns if the PD throws an exception.
1053          * "Regular" termination of the decode() method is not expected.
1054          */
1055         Py_IncRef(di->py_inst);
1056         srd_dbg("%s: Calling decode() method.", di->inst_id);
1057         py_res = PyObject_CallMethod(di->py_inst, "decode", NULL);
1058         srd_dbg("%s: decode() method terminated.", di->inst_id);
1059
1060         /*
1061          * Make sure to unblock potentially pending srd_inst_decode()
1062          * calls in application threads after the decode() method might
1063          * have terminated, while it neither has processed sample data
1064          * nor has terminated upon request. This happens e.g. when "need
1065          * a samplerate to decode" exception is thrown.
1066          */
1067         g_mutex_lock(&di->data_mutex);
1068         wanted_term = di->want_wait_terminate;
1069         di->want_wait_terminate = TRUE;
1070         di->handled_all_samples = TRUE;
1071         g_cond_signal(&di->handled_all_samples_cond);
1072         g_mutex_unlock(&di->data_mutex);
1073
1074         /*
1075          * Check for the termination cause of the decode() method.
1076          * Though this is mostly for information.
1077          */
1078         if (!py_res && wanted_term) {
1079                 /*
1080                  * Silently ignore errors upon return from decode() calls
1081                  * when termination was requested. Terminate the thread
1082                  * which executed this instance's decode() logic.
1083                  */
1084                 srd_dbg("%s: Thread done (!res, want_term).", di->inst_id);
1085                 PyErr_Clear();
1086                 return NULL;
1087         }
1088         if (!py_res) {
1089                 /*
1090                  * The decode() invocation terminated unexpectedly. Have
1091                  * the back trace printed, and terminate the thread which
1092                  * executed the decode() method.
1093                  */
1094                 srd_dbg("%s: decode() terminated unrequested.", di->inst_id);
1095                 srd_exception_catch("Protocol decoder instance %s: ", di->inst_id);
1096                 srd_dbg("%s: Thread done (!res, !want_term).", di->inst_id);
1097                 return NULL;
1098         }
1099
1100         /*
1101          * TODO: By design the decode() method is not supposed to terminate.
1102          * Nevertheless we have the thread joined, and srd backend calls to
1103          * decode() will re-start another thread transparently.
1104          */
1105         srd_dbg("%s: decode() terminated (req %d).", di->inst_id, wanted_term);
1106         Py_DecRef(py_res);
1107         PyErr_Clear();
1108
1109         srd_dbg("%s: Thread done (with res).", di->inst_id);
1110
1111         return NULL;
1112 }
1113
1114 /**
1115  * Decode a chunk of samples.
1116  *
1117  * The calls to this function must provide the samples that shall be
1118  * used by the protocol decoder
1119  *  - in the correct order ([...]5, 6, 4, 7, 8[...] is a bug),
1120  *  - starting from sample zero (2, 3, 4, 5, 6[...] is a bug),
1121  *  - consecutively, with no gaps (0, 1, 2, 4, 5[...] is a bug).
1122  *
1123  * The start- and end-sample numbers are absolute sample numbers (relative
1124  * to the start of the whole capture/file/stream), i.e. they are not relative
1125  * sample numbers within the chunk specified by 'inbuf' and 'inbuflen'.
1126  *
1127  * Correct example (4096 samples total, 4 chunks @ 1024 samples each):
1128  *   srd_inst_decode(di, 0,    1024, inbuf, 1024, 1);
1129  *   srd_inst_decode(di, 1024, 2048, inbuf, 1024, 1);
1130  *   srd_inst_decode(di, 2048, 3072, inbuf, 1024, 1);
1131  *   srd_inst_decode(di, 3072, 4096, inbuf, 1024, 1);
1132  *
1133  * The chunk size ('inbuflen') can be arbitrary and can differ between calls.
1134  *
1135  * Correct example (4096 samples total, 7 chunks @ various samples each):
1136  *   srd_inst_decode(di, 0,    1024, inbuf, 1024, 1);
1137  *   srd_inst_decode(di, 1024, 1124, inbuf,  100, 1);
1138  *   srd_inst_decode(di, 1124, 1424, inbuf,  300, 1);
1139  *   srd_inst_decode(di, 1424, 1643, inbuf,  219, 1);
1140  *   srd_inst_decode(di, 1643, 2048, inbuf,  405, 1);
1141  *   srd_inst_decode(di, 2048, 3072, inbuf, 1024, 1);
1142  *   srd_inst_decode(di, 3072, 4096, inbuf, 1024, 1);
1143  *
1144  * INCORRECT example (4096 samples total, 4 chunks @ 1024 samples each, but
1145  * the start- and end-samplenumbers are not absolute):
1146  *   srd_inst_decode(di, 0,    1024, inbuf, 1024, 1);
1147  *   srd_inst_decode(di, 0,    1024, inbuf, 1024, 1);
1148  *   srd_inst_decode(di, 0,    1024, inbuf, 1024, 1);
1149  *   srd_inst_decode(di, 0,    1024, inbuf, 1024, 1);
1150  *
1151  * @param di The decoder instance to call. Must not be NULL.
1152  * @param abs_start_samplenum The absolute starting sample number for the
1153  *              buffer's sample set, relative to the start of capture.
1154  * @param abs_end_samplenum The absolute ending sample number for the
1155  *              buffer's sample set, relative to the start of capture.
1156  * @param inbuf The buffer to decode. Must not be NULL.
1157  * @param inbuflen Length of the buffer. Must be > 0.
1158  * @param unitsize The number of bytes per sample. Must be > 0.
1159  *
1160  * @return SRD_OK upon success, a (negative) error code otherwise.
1161  *
1162  * @private
1163  */
1164 SRD_PRIV int srd_inst_decode(struct srd_decoder_inst *di,
1165                 uint64_t abs_start_samplenum, uint64_t abs_end_samplenum,
1166                 const uint8_t *inbuf, uint64_t inbuflen, uint64_t unitsize)
1167 {
1168         PyObject *py_res;
1169         srd_logic *logic;
1170         long apiver;
1171
1172         /* Return an error upon unusable input. */
1173         if (!di) {
1174                 srd_dbg("empty decoder instance");
1175                 return SRD_ERR_ARG;
1176         }
1177         if (!inbuf) {
1178                 srd_dbg("NULL buffer pointer");
1179                 return SRD_ERR_ARG;
1180         }
1181         if (inbuflen == 0) {
1182                 srd_dbg("empty buffer");
1183                 return SRD_ERR_ARG;
1184         }
1185         if (unitsize == 0) {
1186                 srd_dbg("unitsize 0");
1187                 return SRD_ERR_ARG;
1188         }
1189
1190         if (abs_start_samplenum != di->abs_cur_samplenum ||
1191             abs_end_samplenum < abs_start_samplenum) {
1192                 srd_dbg("Incorrect sample numbers: start=%" PRIu64 ", cur=%"
1193                         PRIu64 ", end=%" PRIu64 ".", abs_start_samplenum,
1194                         di->abs_cur_samplenum, abs_end_samplenum);
1195                 return SRD_ERR_ARG;
1196         }
1197
1198         di->data_unitsize = unitsize;
1199
1200         srd_dbg("Decoding: abs start sample %" PRIu64 ", abs end sample %"
1201                 PRIu64 " (%" PRIu64 " samples, %" PRIu64 " bytes, unitsize = "
1202                 "%d), instance %s.", abs_start_samplenum, abs_end_samplenum,
1203                 abs_end_samplenum - abs_start_samplenum, inbuflen, di->data_unitsize,
1204                 di->inst_id);
1205
1206         apiver = srd_decoder_apiver(di->decoder);
1207
1208         if (apiver == 2) {
1209                 /*
1210                  * Create new srd_logic object. Each iteration around the PD's
1211                  * loop will fill one sample into this object.
1212                  */
1213                 logic = PyObject_New(srd_logic, (PyTypeObject *)srd_logic_type);
1214                 Py_INCREF(logic);
1215                 logic->di = (struct srd_decoder_inst *)di;
1216                 logic->abs_start_samplenum = abs_start_samplenum;
1217                 logic->itercnt = 0;
1218                 logic->inbuf = (uint8_t *)inbuf;
1219                 logic->inbuflen = inbuflen;
1220                 logic->sample = PyList_New(2);
1221                 Py_INCREF(logic->sample);
1222
1223                 Py_IncRef(di->py_inst);
1224                 if (!(py_res = PyObject_CallMethod(di->py_inst, "decode",
1225                         "KKO", abs_start_samplenum, abs_end_samplenum, logic))) {
1226                         srd_exception_catch("Protocol decoder instance %s",
1227                                         di->inst_id);
1228                         return SRD_ERR_PYTHON;
1229                 }
1230                 di->abs_cur_samplenum = abs_end_samplenum;
1231                 Py_DecRef(py_res);
1232         } else {
1233                 /* If this is the first call, start the worker thread. */
1234                 if (!di->thread_handle) {
1235                         srd_dbg("No worker thread for this decoder stack "
1236                                 "exists yet, creating one: %s.", di->inst_id);
1237                         di->thread_handle = g_thread_new(di->inst_id,
1238                                                          di_thread, di);
1239                 }
1240
1241                 /* Push the new sample chunk to the worker thread. */
1242                 g_mutex_lock(&di->data_mutex);
1243                 di->abs_start_samplenum = abs_start_samplenum;
1244                 di->abs_end_samplenum = abs_end_samplenum;
1245                 di->inbuf = inbuf;
1246                 di->inbuflen = inbuflen;
1247                 di->got_new_samples = TRUE;
1248                 di->handled_all_samples = FALSE;
1249                 di->want_wait_terminate = FALSE;
1250
1251                 /* Signal the thread that we have new data. */
1252                 g_cond_signal(&di->got_new_samples_cond);
1253                 g_mutex_unlock(&di->data_mutex);
1254
1255                 /* When all samples in this chunk were handled, return. */
1256                 g_mutex_lock(&di->data_mutex);
1257                 while (!di->handled_all_samples && !di->want_wait_terminate)
1258                         g_cond_wait(&di->handled_all_samples_cond, &di->data_mutex);
1259                 g_mutex_unlock(&di->data_mutex);
1260         }
1261
1262         return SRD_OK;
1263 }
1264
1265 /** @private */
1266 SRD_PRIV void srd_inst_free(struct srd_decoder_inst *di)
1267 {
1268         GSList *l;
1269         struct srd_pd_output *pdo;
1270
1271         srd_dbg("Freeing instance %s", di->inst_id);
1272
1273         srd_inst_join_decode_thread(di);
1274         srd_inst_reset_state(di);
1275
1276         Py_DecRef(di->py_inst);
1277         g_free(di->inst_id);
1278         g_free(di->dec_channelmap);
1279         g_free(di->channel_samples);
1280         g_slist_free(di->next_di);
1281         for (l = di->pd_output; l; l = l->next) {
1282                 pdo = l->data;
1283                 g_free(pdo->proto_id);
1284                 g_free(pdo);
1285         }
1286         g_slist_free(di->pd_output);
1287         g_free(di);
1288 }
1289
1290 /** @private */
1291 SRD_PRIV void srd_inst_free_all(struct srd_session *sess)
1292 {
1293         if (session_is_valid(sess) != SRD_OK) {
1294                 srd_err("Invalid session.");
1295                 return;
1296         }
1297
1298         g_slist_free_full(sess->di_list, (GDestroyNotify)srd_inst_free);
1299 }
1300
1301 /** @} */