libsigrokdecode  0.5.0
sigrok protocol decoding library
instance.c
Go to the documentation of this file.
1 /*
2  * This file is part of the libsigrokdecode project.
3  *
4  * Copyright (C) 2010 Uwe Hermann <uwe@hermann-uwe.de>
5  * Copyright (C) 2012 Bert Vermeulen <bert@biot.com>
6  *
7  * This program is free software: you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation, either version 3 of the License, or
10  * (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program. If not, see <http://www.gnu.org/licenses/>.
19  */
20 
21 #include <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  */
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  */
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);
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++) {
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 ").",
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 
1192  srd_dbg("Incorrect sample numbers: start=%" PRIu64 ", cur=%"
1193  PRIu64 ", end=%" PRIu64 ".", abs_start_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,
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;
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  }
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);
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 /** @} */
No error.
struct srd_decoder * decoder
Function argument error.
GThread * thread_handle
Handle for this PD stack&#39;s worker thread.
struct srd_decoder * srd_decoder_get_by_id(const char *id)
Get the decoder with the specified ID.
Definition: decoder.c:89
uint64_t abs_end_samplenum
Absolute end sample number.
struct srd_session * sess
int srd_inst_option_set(struct srd_decoder_inst *di, GHashTable *options)
Set one or more options in a decoder instance.
Definition: instance.c:68
gboolean want_wait_terminate
Requests termination of wait() and decode().
gboolean got_new_samples
Indicates whether new samples are available for processing.
uint64_t inbuflen
Length (in bytes) of the input sample buffer.
int order
The index of the channel, i.e.
Structure which contains information about one protocol decoder channel.
#define SRD_API
const uint8_t * inbuf
Pointer to the buffer/chunk of input samples.
GArray * match_array
Array of booleans denoting which conditions matched.
Generic/unspecified error.
GCond handled_all_samples_cond
GSList * opt_channels
List of optional channels for this decoder.
void * py_dec
sigrokdecode.Decoder class.
uint64_t abs_cur_samplenum
Absolute current samplenumber.
char * id
The ID of the channel.
GArray * old_pins_array
Array of "old" (previous sample) pin values.
The public libsigrokdecode header file to be used by frontends.
uint64_t abs_start_samplenum
Absolute start sample number.
GSList * condition_list
List of conditions a PD wants to wait for.
int srd_inst_stack(struct srd_session *sess, struct srd_decoder_inst *di_bottom, struct srd_decoder_inst *di_top)
Stack a decoder instance on top of another.
Definition: instance.c:479
char * name
The (short) decoder name.
GSList * options
List of decoder options.
struct srd_decoder_inst * srd_inst_find_by_id(struct srd_session *sess, const char *inst_id)
Find a decoder instance by its instance ID.
Definition: instance.c:552
gboolean handled_all_samples
Indicates whether the worker thread has handled all samples.
#define SRD_PRIV
GSList * channels
List of channels required by this decoder.
struct srd_decoder_inst * srd_inst_new(struct srd_session *sess, const char *decoder_id, GHashTable *options)
Create a new protocol decoder instance.
Definition: instance.c:296
int srd_inst_channel_set_all(struct srd_decoder_inst *di, GHashTable *new_channels)
Set all channels in a decoder instance.
Definition: instance.c:199
int srd_inst_initial_pins_set_all(struct srd_decoder_inst *di, GArray *initial_pins)
Set the list of initial (assumed) pin values.
Definition: instance.c:639
Python C API error.
uint8_t * channel_samples