2 * This file is part of the libsigrok project.
4 * Copyright (C) 2012 Petteri Aimonen <jpa@sr.mail.kapsi.fi>
5 * Copyright (C) 2014 Bert Vermeulen <bert@biot.com>
6 * Copyright (C) 2017-2020 Gerhard Sittig <gerhard.sittig@gmx.net>
8 * This program is free software: you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation, either version 3 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with this program. If not, see <http://www.gnu.org/licenses/>.
23 * The VCD input module has the following options. See the options[]
24 * declaration near the bottom of the input module's source file.
26 * numchannels: Maximum number of sigrok channels to create. VCD signals
27 * are detected in their order of declaration in the VCD file header,
28 * and mapped to sigrok channels.
30 * skip: Allows to skip data at the start of the input file. This can
31 * speed up operation on long captures.
32 * Value < 0: Skip until first timestamp that is listed in the file.
33 * (This is the default behaviour.)
34 * Value = 0: Do not skip, instead generate samples beginning from
36 * Value > 0: Start at the given timestamp.
38 * downsample: Divide the samplerate by the given factor. This can
39 * speed up operation on long captures.
41 * compress: Trim idle periods which are longer than this value to span
42 * only this many timescale ticks. This can speed up operation on long
43 * captures (default 0, don't compress).
45 * Based on Verilog standard IEEE Std 1364-2001 Version C
48 * - $var with 'wire' and 'reg' types of scalar variables
49 * - $timescale definition for samplerate
50 * - multiple character variable identifiers
51 * - same identifer used for multiple signals (identical values)
52 * - vector variables (bit vectors)
53 * - integer variables (analog signals with 0 digits, passed as single
54 * precision float number)
55 * - real variables (analog signals, passed on with single precision,
56 * arbitrary digits value, not user adjustable)
57 * - nested $scope, results in prefixed sigrok channel names
59 * Most important unsupported features:
60 * - $dumpvars initial value declaration (is not an issue if generators
61 * provide sample data for the #0 timestamp, otherwise session data
62 * starts from zero values, and catches up when the signal changes its
63 * state to a supported value)
65 * Implementor's note: This input module specifically does _not_ use
66 * glib routines where they would hurt performance. Lots of memory
67 * allocations increase execution time not by percents but by huge
68 * factors. This motivated this module's custom code for splitting
69 * words on text lines, and pooling previously allocated buffers.
71 * TODO (in arbitrary order)
72 * - Map VCD scopes to sigrok channel groups?
73 * - Does libsigrok support nested channel groups? Or is this feature
74 * exclusive to Pulseview?
75 * - Check VCD input to VCD output behaviour. Verify that export and
76 * re-import results in identical data (well, VCD's constraints on
77 * timescale values is known to result in differences).
78 * - Check the minimum timestamp delta in the input data set, suggest
79 * the downsample=N option to users for reduced resource consumption.
80 * Popular VCD file creation utilities love to specify insanely tiny
81 * timescale values in the pico or even femto seconds range. Which
82 * results in huge sample counts after import, and potentially even
83 * terminates the application due to resource exhaustion. This issue
84 * only will vanish when common libsigrok infrastructure no longer
85 * depends on constant rate streams of samples at discrete points
86 * in time. The current input module implementation has code in place
87 * to gather timestamp statistics, but the most appropriate condition
88 * when to notify users is yet to be found.
89 * - Cleanup the implementation.
90 * - Consistent use of the glib API (where appropriate).
91 * - More appropriate variable/function identifiers.
92 * - More robust handling of multi-word input phrases and chunked
93 * input buffers? This implementation assumes that e.g. b[01]+
94 * patterns are complete when they start, and the signal identifier
95 * is available as well. Which may be true assuming that input data
96 * comes in complete text lines.
97 * - See if other input modules have learned lessons that we could
98 * benefit from here as well? Pointless BOM (done), line oriented
99 * processing with EOL variants and with optional last EOL, module
100 * state reset and file re-read (stable channels list), buffered
101 * session feed, synchronized feed for mixed signal sources, digits
102 * or formats support for analog input, single vs double precision,
104 * - Re-consider logging. Verbosity levels should be acceptable,
105 * but volume is an issue. Drop duplicates, and drop messages from
106 * known good code paths.
112 #include <libsigrok/libsigrok.h>
113 #include "libsigrok-internal.h"
118 #define LOG_PREFIX "input/vcd"
120 #define CHUNK_SIZE (4 * 1024 * 1024)
121 #define SCOPE_SEP '.'
124 struct vcd_user_opt {
125 size_t maxchannels; /* sigrok channels (output) */
128 uint64_t skip_starttime;
129 gboolean skip_specified;
134 uint64_t prev_timestamp;
136 size_t vcdsignals; /* VCD signals (input) */
137 GSList *ignored_signals;
138 gboolean data_after_timestamp;
139 gboolean ignore_end_keyword;
140 gboolean skip_until_end;
145 uint8_t *current_logic;
146 float *current_floats;
153 GString *scope_prefix;
154 struct feed_queue_logic *feed_logic;
161 size_t total_ts_seen;
162 uint64_t last_ts_value;
163 uint64_t last_ts_delta;
169 uint32_t early_check_shift;
170 size_t early_last_emitted;
182 enum sr_channeltype type;
187 size_t range_lower, range_upper;
189 struct feed_queue_analog *feed_analog;
192 static void free_channel(void *data)
194 struct vcd_channel *vcd_ch;
200 g_free(vcd_ch->name);
201 g_free(vcd_ch->identifier);
202 g_free(vcd_ch->base_name);
203 feed_queue_analog_free(vcd_ch->feed_analog);
208 /* TODO Drop the local decl when this has become a common helper. */
209 void sr_channel_group_free(struct sr_channel_group *cg);
211 /* Wrapper for GDestroyNotify compatibility. */
212 static void cg_free(void *p)
214 sr_channel_group_free(p);
218 * Another timestamp delta was observed, update statistics: Update the
219 * sorted list of minimum values, and increment the occurance counter.
220 * Returns the position of the item's statistics slot, or returns a huge
221 * invalid index when the current delta is larger than previously found
224 static size_t ts_stats_update_min(struct ts_stats *stats, uint64_t delta)
226 size_t idx, copy_idx;
228 /* Advance over previously recorded values which are smaller. */
230 while (idx < stats->min_count && stats->min_items[idx].delta < delta)
232 if (idx == ARRAY_SIZE(stats->min_items))
235 /* Found the exact value that previously was registered? */
236 if (stats->min_items[idx].delta == delta) {
237 stats->min_items[idx].count++;
241 /* Allocate another slot, bubble up larger values as needed. */
242 if (stats->min_count < ARRAY_SIZE(stats->min_items))
244 for (copy_idx = stats->min_count - 1; copy_idx > idx; copy_idx--)
245 stats->min_items[copy_idx] = stats->min_items[copy_idx - 1];
247 /* Start tracking this value in the found or freed slot. */
248 memset(&stats->min_items[idx], 0, sizeof(stats->min_items[idx]));
249 stats->min_items[idx].delta = delta;
250 stats->min_items[idx].count++;
256 * Intermediate check for extreme oversampling in the input data. Rate
257 * limited emission of warnings to avoid noise, "late" emission of the
258 * first potential message to avoid false positives, yet need to emit
259 * the messages early (*way* before EOF) to raise awareness.
262 * Tune the limits, improve perception and usefulness of these checks.
263 * Need to start emitting messages soon enough to be seen by users. Yet
264 * avoid unnecessary messages for valid input's idle/quiet phases. Slow
265 * input transitions are perfectly legal before bursty phases are seen
266 * in the input data. Needs the check become an option, on by default,
267 * but suppressable by users?
269 static void ts_stats_check_early(struct ts_stats *stats)
271 static const struct {
274 } *cp, check_points[] = {
275 { 100, 1000000, }, /* Still x100 after 1mio transitions. */
276 { 1000, 100000, }, /* Still x1k after 100k transitions. */
277 { 10000, 10000, }, /* Still x10k after 10k transitions. */
278 { 1000000, 2500, }, /* Still x1m after 2.5k transitions. */
282 uint64_t seen_delta, check_delta;
285 /* Get the current minimum's value and count. */
286 if (!stats->min_count)
288 seen_delta = stats->min_items[0].delta;
289 seen_count = stats->min_items[0].count;
291 /* Emit at most one weak message per import. */
292 if (stats->early_last_emitted)
295 /* Check arbitrary marks, emit rate limited warnings. */
297 check_delta = seen_delta >> stats->early_check_shift;
298 for (cp_idx = 0; cp_idx < ARRAY_SIZE(check_points); cp_idx++) {
299 cp = &check_points[cp_idx];
300 /* No other match can happen below. Done iterating. */
301 if (stats->total_ts_seen > cp->count)
303 /* Advance to the next checkpoint description. */
304 if (stats->total_ts_seen != cp->count)
306 /* First occurance of that timestamp count. Check the value. */
307 sr_dbg("TS early chk: total %zu, min delta %" PRIu64 " / %" PRIu64 ".",
308 cp->count, seen_delta, check_delta);
309 if (check_delta < cp->delta)
311 sr_warn("Low change rate? (weak estimate, min TS delta %" PRIu64 " after %zu timestamps)",
312 seen_delta, stats->total_ts_seen);
313 sr_warn("Consider using the downsample=N option, or increasing its value.");
314 stats->early_last_emitted = stats->total_ts_seen;
319 /* Reset the internal state of the timestamp tracker. */
320 static int ts_stats_prep(struct context *inc)
322 struct ts_stats *stats;
323 uint64_t down_sample_value;
324 uint32_t down_sample_shift;
326 stats = &inc->ts_stats;
327 memset(stats, 0, sizeof(*stats));
329 down_sample_value = inc->options.downsample;
330 down_sample_shift = 0;
331 while (down_sample_value >= 2) {
333 down_sample_value /= 2;
335 stats->early_check_shift = down_sample_shift;
340 /* Inspect another timestamp that was received. */
341 static int ts_stats_check(struct ts_stats *stats, uint64_t curr_ts)
343 uint64_t last_ts, delta;
345 last_ts = stats->last_ts_value;
346 stats->last_ts_value = curr_ts;
347 stats->total_ts_seen++;
348 if (stats->total_ts_seen < 2)
351 delta = curr_ts - last_ts;
352 stats->last_ts_delta = delta;
353 (void)ts_stats_update_min(stats, delta);
355 ts_stats_check_early(stats);
360 /* Postprocess internal timestamp tracker state. */
361 static int ts_stats_post(struct context *inc, gboolean ignore_terminal)
363 struct ts_stats *stats;
365 uint64_t delta, over_sample, over_sample_scaled, suggest_factor;
366 enum sr_loglevel log_level;
367 gboolean is_suspicious, has_downsample;
369 stats = &inc->ts_stats;
372 * Lookup the smallest timestamp delta which was found during
373 * data import. Ignore the last delta if its timestamp was never
374 * followed by data, and this was the only occurance. Absence of
375 * result data is non-fatal here -- this code exclusively serves
376 * to raise users' awareness of potential pitfalls, but does not
377 * change behaviour of data processing.
379 * TODO Also filter by occurance count? To not emit warnings when
380 * captured signals only change slowly by design. Only warn when
381 * the sample rate and samples count product exceeds a threshold?
382 * See below for the necessity (and potential) to adjust the log
383 * message's severity and content.
386 if (ignore_terminal) do {
387 if (min_idx >= stats->min_count)
389 delta = stats->last_ts_delta;
390 if (stats->min_items[min_idx].delta != delta)
392 if (stats->min_items[min_idx].count != 1)
396 if (min_idx >= stats->min_count)
400 * TODO Refine the condition whether to notify the user, and
401 * which severity to use after having inspected all input data.
402 * Any detail could get involved which previously was gathered
403 * during data processing: total sample count, channel count
404 * including their data type and bits width, the oversampling
405 * factor (minimum observed "change rate"), or any combination
406 * thereof. The current check is rather simple (unconditional
407 * warning for ratios starting at 100, regardless of sample or
410 over_sample = stats->min_items[min_idx].delta;
411 over_sample_scaled = over_sample / inc->options.downsample;
412 sr_dbg("TS post stats: oversample unscaled %" PRIu64 ", scaled %" PRIu64,
413 over_sample, over_sample_scaled);
414 if (over_sample_scaled < 10) {
415 sr_dbg("TS post stats: Low oversampling ratio, good.");
420 * Avoid constructing the message from several tiny pieces by
421 * design, because this would be hard on translators. Stick with
422 * complete sentences instead, and accept the redundancy in the
425 log_level = (over_sample_scaled > 20) ? SR_LOG_WARN : SR_LOG_INFO;
426 is_suspicious = over_sample_scaled > 20;
428 sr_log(log_level, LOG_PREFIX ": "
429 "Suspiciously low overall change rate (total min TS delta %" PRIu64 ").",
432 sr_log(log_level, LOG_PREFIX ": "
433 "Low overall change rate (total min TS delta %" PRIu64 ").",
436 has_downsample = inc->options.downsample > 1;
437 suggest_factor = inc->options.downsample;
438 while (over_sample_scaled >= 10) {
439 suggest_factor *= 10;
440 over_sample_scaled /= 10;
442 if (has_downsample) {
443 sr_log(log_level, LOG_PREFIX ": "
444 "Suggest higher downsample value, like %" PRIu64 ".",
447 sr_log(log_level, LOG_PREFIX ": "
448 "Suggest to downsample, value like %" PRIu64 ".",
455 static void check_remove_bom(GString *buf)
457 static const char *bom_text = "\xef\xbb\xbf";
459 if (buf->len < strlen(bom_text))
461 if (strncmp(buf->str, bom_text, strlen(bom_text)) != 0)
463 g_string_erase(buf, 0, strlen(bom_text));
467 * Reads a single VCD section from input file and parses it to name/contents.
468 * e.g. $timescale 1ps $end => "timescale" "1ps"
470 static gboolean parse_section(GString *buf, char **name, char **contents)
472 static const char *end_text = "$end";
476 const char *grab_start, *grab_end;
477 GString *sname, *scontent;
479 /* Preset falsy return values. Gets updated below. */
480 *name = *contents = NULL;
483 /* Skip any initial white-space. */
485 while (pos < buf->len && g_ascii_isspace(buf->str[pos]))
488 /* Section tag should start with $. */
489 if (buf->str[pos++] != '$')
492 /* Read the section tag. */
493 grab_start = &buf->str[pos];
494 while (pos < buf->len && !g_ascii_isspace(buf->str[pos]))
496 grab_end = &buf->str[pos];
497 sname = g_string_new_len(grab_start, grab_end - grab_start);
499 /* Skip whitespace before content. */
500 while (pos < buf->len && g_ascii_isspace(buf->str[pos]))
503 /* Read the content up to the '$end' marker. */
504 scontent = g_string_sized_new(128);
505 grab_start = &buf->str[pos];
506 grab_end = g_strstr_len(grab_start, buf->len - pos, end_text);
508 /* Advance 'pos' to after '$end' and more whitespace. */
509 pos = grab_end - buf->str;
510 pos += strlen(end_text);
511 while (pos < buf->len && g_ascii_isspace(buf->str[pos]))
514 /* Grab the (trimmed) content text. */
515 while (grab_end > grab_start && g_ascii_isspace(grab_end[-1]))
517 len = grab_end - grab_start;
518 g_string_append_len(scontent, grab_start, len);
522 /* Consume the input text which just was taken. */
523 g_string_erase(buf, 0, pos);
526 /* Return section name and content if a section was seen. */
527 *name = g_string_free(sname, !status);
528 *contents = g_string_free(scontent, !status);
534 * The glib routine which splits an input text into a list of words also
535 * "provides empty strings" which application code then needs to remove.
536 * And copies of the input text get allocated for all words.
538 * The repeated memory allocation is acceptable for small workloads like
539 * parsing the header sections. But the heavy lifting for sample data is
540 * done by DIY code to speedup execution. The use of glib routines would
541 * severely hurt throughput. Allocated memory gets re-used while a strict
542 * ping-pong pattern is assumed (each text line of input data enters and
543 * leaves in a strict symmetrical manner, due to the organization of the
544 * receive() routine and parse calls).
547 /* Remove empty parts from an array returned by g_strsplit(). */
548 static void remove_empty_parts(gchar **parts)
566 static char **split_text_line(struct context *inc, char *text, size_t *count)
568 struct split_state *state;
569 size_t counted, alloced, wanted;
570 char **words, *p, **new_words;
578 sr_dbg("coding error, split() called while \"in use\".");
583 * Seed allocation when invoked for the first time. Assume
584 * simple logic data, start with a few words per line. Will
585 * automatically adjust with subsequent use.
587 if (!state->alloced) {
589 words = g_malloc(sizeof(words[0]) * alloced);
592 state->alloced = alloced;
593 state->words = words;
596 /* Start with most recently allocated word list space. */
597 alloced = state->alloced;
598 words = state->words;
601 /* As long as more input text remains ... */
604 /* Resize word list if needed. Just double the size. */
605 if (counted + 1 >= alloced) {
606 wanted = 2 * alloced;
607 new_words = g_realloc(words, sizeof(words[0]) * wanted);
613 state->words = words;
614 state->alloced = alloced;
617 /* Skip leading spaces. */
618 while (g_ascii_isspace(*p))
623 /* Add found word to word list. */
624 words[counted++] = p;
626 /* Find end of the word. Terminate loop upon EOS. */
627 while (*p && !g_ascii_isspace(*p))
632 /* More text follows. Terminate the word. */
637 * NULL terminate the word list. Provide its length so that
638 * calling code need not re-iterate the list to get the count.
640 words[counted] = NULL;
643 state->in_use = TRUE;
648 static void free_text_split(struct context *inc, char **words)
650 struct split_state *state;
654 if (words && words != state->words) {
655 sr_dbg("coding error, free() arg differs from split() result.");
658 /* "Double free" finally releases the memory. */
659 if (!state->in_use) {
660 g_free(state->words);
665 /* Mark as no longer in use. */
666 state->in_use = FALSE;
669 static gboolean have_header(GString *buf)
671 static const char *enddef_txt = "$enddefinitions";
672 static const char *end_txt = "$end";
676 /* Search for "end of definitions" section keyword. */
677 p = g_strstr_len(buf->str, buf->len, enddef_txt);
680 p += strlen(enddef_txt);
682 /* Search for end of section (content expected to be empty). */
683 p_stop = &buf->str[buf->len];
684 p_stop -= strlen(end_txt);
685 while (p < p_stop && g_ascii_isspace(*p))
687 if (strncmp(p, end_txt, strlen(end_txt)) != 0)
689 p += strlen(end_txt);
694 static int parse_timescale(struct context *inc, char *contents)
699 * The standard allows for values 1, 10 or 100
700 * and units s, ms, us, ns, ps and fs.
702 if (sr_parse_period(contents, &p, &q) != SR_OK) {
703 sr_err("Parsing $timescale failed.");
707 inc->samplerate = q / p;
708 sr_dbg("Samplerate: %" PRIu64, inc->samplerate);
710 /* Does not happen unless time value is non-standard */
711 sr_warn("Inexact rounding of samplerate, %" PRIu64 " / %" PRIu64 " to %" PRIu64 " Hz.",
712 q, p, inc->samplerate);
719 * Handle '$scope' and '$upscope' sections in the input file. Assume that
720 * input signals have a "base name", which may be ambiguous within the
721 * file. These names get declared within potentially nested scopes, which
722 * this implementation uses to create longer but hopefully unique and
723 * thus more usable sigrok channel names.
725 * Track the currently effective scopes in a string variable to simplify
726 * the channel name creation. Start from an empty string, then append the
727 * scope name and a separator when a new scope opens, and remove the last
728 * scope name when a scope closes. This allows to simply prefix basenames
729 * with the current scope to get a full name.
731 * It's an implementation detail to keep the trailing NUL here in the
732 * GString member, to simplify the g_strconcat() call in the channel name
736 * - Check whether scope types must get supported, this implementation
737 * does not distinguish between 'module' and 'begin' and what else
738 * may be seen. The first word simply gets ignored.
739 * - Check the allowed alphabet for scope names. This implementation
740 * assumes "programming language identifier" style (alphanumeric with
741 * underscores, plus brackets since we've seen them in example files).
743 static int parse_scope(struct context *inc, char *contents, gboolean is_up)
745 char *sep_pos, *name_pos;
750 * The 'upscope' case, drop one scope level (if available). Accept
751 * excess 'upscope' calls, assume that a previous 'scope' section
752 * was ignored because it referenced our software package's name.
756 * Check for a second right-most separator (and position
757 * right behind that, which is the start of the last
758 * scope component), or fallback to the start of string.
759 * g_string_erase() from that positon to the end to drop
760 * the last component.
762 name_pos = inc->scope_prefix->str;
764 sep_pos = strrchr(name_pos, SCOPE_SEP);
768 sep_pos = strrchr(name_pos, SCOPE_SEP);
771 name_pos = ++sep_pos;
773 length = name_pos - inc->scope_prefix->str;
774 g_string_truncate(inc->scope_prefix, length);
775 g_string_append_c(inc->scope_prefix, '\0');
776 sr_dbg("$upscope, prefix now: \"%s\"", inc->scope_prefix->str);
781 * The 'scope' case, add another scope level. But skip our own
782 * package name, assuming that this is an artificial node which
783 * was emitted by libsigrok's VCD output module.
785 sr_spew("$scope, got: \"%s\"", contents);
786 parts = g_strsplit_set(contents, " \r\n\t", 0);
787 remove_empty_parts(parts);
788 length = g_strv_length(parts);
790 sr_err("Unsupported 'scope' syntax: %s", contents);
795 if (strcmp(name_pos, PACKAGE_NAME) == 0) {
796 sr_info("Skipping scope with application's package name: %s",
801 /* Drop NUL, append scope name and separator, and re-add NUL. */
802 g_string_truncate(inc->scope_prefix, inc->scope_prefix->len - 1);
803 g_string_append_printf(inc->scope_prefix,
804 "%s%c%c", name_pos, SCOPE_SEP, '\0');
807 sr_dbg("$scope, prefix now: \"%s\"", inc->scope_prefix->str);
813 * Parse a $var section which describes a VCD signal ("variable").
815 * @param[in] inc Input module context.
816 * @param[in] contents Input text, content of $var section.
818 static int parse_header_var(struct context *inc, char *contents)
822 char *type, *size_txt, *id, *ref, *idx;
823 gboolean is_reg, is_wire, is_real, is_int;
825 enum sr_channeltype ch_type;
826 size_t size, next_size;
827 struct vcd_channel *vcd_ch;
830 * Format of $var or $reg header specs:
831 * $var type size identifier reference [opt-index] $end
833 parts = g_strsplit_set(contents, " \r\n\t", 0);
834 remove_empty_parts(parts);
835 length = g_strv_length(parts);
836 if (length != 4 && length != 5) {
837 sr_warn("$var section should have 4 or 5 items");
849 is_reg = g_strcmp0(type, "reg") == 0;
850 is_wire = g_strcmp0(type, "wire") == 0;
851 is_real = g_strcmp0(type, "real") == 0;
852 is_int = g_strcmp0(type, "integer") == 0;
853 is_str = g_strcmp0(type, "string") == 0;
855 if (is_reg || is_wire) {
856 ch_type = SR_CHANNEL_LOGIC;
857 } else if (is_real || is_int) {
858 ch_type = SR_CHANNEL_ANALOG;
860 sr_warn("Skipping id %s, name '%s%s', unsupported type '%s'.",
861 id, ref, idx ? idx : "", type);
862 inc->ignored_signals = g_slist_append(inc->ignored_signals,
867 sr_err("Unsupported signal type: '%s'", type);
872 size = strtol(size_txt, NULL, 10);
873 if (ch_type == SR_CHANNEL_ANALOG) {
874 if (is_real && size != 32 && size != 64) {
876 * The VCD input module does not depend on the
877 * specific width of the floating point value.
878 * This is just for information. Upon value
879 * changes, a mere string gets converted to
880 * float, so we may not care at all.
882 * Strictly speaking we might warn for 64bit
883 * (double precision) declarations, because
884 * sigrok internally uses single precision
887 sr_info("Unexpected real width: '%s'", size_txt);
889 /* Simplify code paths below, by assuming size 1. */
893 sr_warn("Unsupported signal size: '%s'", size_txt);
897 if (inc->conv_bits.max_bits < size)
898 inc->conv_bits.max_bits = size;
899 next_size = inc->logic_count + inc->analog_count + size;
900 if (inc->options.maxchannels && next_size > inc->options.maxchannels) {
901 sr_warn("Skipping '%s%s', exceeds requested channel count %zu.",
902 ref, idx ? idx : "", inc->options.maxchannels);
903 inc->ignored_signals = g_slist_append(inc->ignored_signals,
909 vcd_ch = g_malloc0(sizeof(*vcd_ch));
910 vcd_ch->identifier = g_strdup(id);
911 vcd_ch->name = g_strconcat(inc->scope_prefix->str, ref, idx, NULL);
913 vcd_ch->type = ch_type;
915 case SR_CHANNEL_LOGIC:
916 vcd_ch->array_index = inc->logic_count;
917 vcd_ch->byte_idx = vcd_ch->array_index / 8;
918 vcd_ch->bit_mask = 1 << (vcd_ch->array_index % 8);
919 inc->logic_count += size;
921 case SR_CHANNEL_ANALOG:
922 vcd_ch->array_index = inc->analog_count++;
923 /* TODO: Use proper 'digits' value for this input module. */
924 vcd_ch->submit_digits = is_real ? 2 : 0;
928 sr_spew("VCD signal %zu '%s' ID '%s' (size %zu), sr type %s, idx %zu.",
929 inc->vcdsignals, vcd_ch->name,
930 vcd_ch->identifier, vcd_ch->size,
931 vcd_ch->type == SR_CHANNEL_ANALOG ? "A" : "L",
932 vcd_ch->array_index);
933 inc->channels = g_slist_append(inc->channels, vcd_ch);
940 * Construct the name of the nth sigrok channel for a VCD signal.
942 * Uses the VCD signal name for scalar types and single-bit signals.
943 * Uses "signal.idx" for multi-bit VCD signals without a range spec in
944 * their declaration. Uses "signal[idx]" when a range is known and was
947 * @param[in] vcd_ch The VCD signal's description.
948 * @param[in] idx The sigrok channel's index within the VCD signal's group.
950 * @return An allocated text buffer which callers need to release, #NULL
951 * upon failure to create a sigrok channel name.
953 static char *get_channel_name(struct vcd_channel *vcd_ch, size_t idx)
955 char *open_pos, *close_pos, *check_pos, *endptr;
956 gboolean has_brackets, has_range;
957 size_t upper, lower, tmp;
960 /* Handle simple scalar types, and single-bit logic first. */
961 if (vcd_ch->size <= 1)
962 return g_strdup(vcd_ch->name);
965 * If not done before: Search for a matching pair of brackets in
966 * the right-most position at the very end of the string. Get the
967 * two colon separated numbers between the brackets, which are
968 * the range limits for array indices into the multi-bit signal.
969 * Grab the "base name" of the VCD signal.
971 * Notice that arrays can get nested. Earlier path components can
972 * be indexed as well, that's why we need the right-most range.
973 * This implementation does not handle bit vectors of size 1 here
974 * by explicit logic. The check for a [0:0] range would even fail.
975 * But the case of size 1 is handled above, and "happens to" give
976 * the expected result (just the VCD signal name).
978 * This implementation also deals with range limits in the reverse
979 * order, as well as ranges which are not 0-based (like "[4:7]").
981 if (!vcd_ch->base_name) {
983 open_pos = strrchr(vcd_ch->name, '[');
984 close_pos = strrchr(vcd_ch->name, ']');
985 if (close_pos && close_pos[1])
987 has_brackets = open_pos && close_pos && close_pos > open_pos;
991 check_pos = &open_pos[1];
993 upper = strtoul(check_pos, &endptr, 10);
994 if (!endptr || *endptr != ':')
998 check_pos = &endptr[1];
1000 lower = strtoul(check_pos, &endptr, 10);
1001 if (!endptr || endptr != close_pos)
1004 if (has_range && lower > upper) {
1012 if (upper + 1 - lower != vcd_ch->size)
1016 /* Temporarily patch the VCD channel's name. */
1018 vcd_ch->base_name = g_strdup(vcd_ch->name);
1020 vcd_ch->range_lower = lower;
1021 vcd_ch->range_upper = upper;
1024 has_range = vcd_ch->range_lower + vcd_ch->range_upper;
1025 if (has_range && idx >= vcd_ch->size)
1028 return g_strdup_printf("%s.%zu", vcd_ch->name, idx);
1031 * Create a sigrok channel name with just the bit's index in
1032 * brackets. This avoids "name[7:0].3" results, instead results
1035 ch_name = g_strdup_printf("%s[%zu]",
1036 vcd_ch->base_name, vcd_ch->range_lower + idx);
1041 * Create (analog or logic) sigrok channels for the VCD signals. Create
1042 * multiple sigrok channels for vector input since sigrok has no concept
1043 * of multi-bit signals. Create a channel group for the vector's bits
1044 * though to reflect that they form a unit. This is beneficial when UIs
1045 * support optional "collapsed" displays of channel groups (like
1046 * "parallel bus, hex output").
1048 * Defer channel creation until after completion of parsing the input
1049 * file header. Make sure to create all logic channels first before the
1050 * analog channels get created. This avoids issues with the mapping of
1051 * channel indices to bitmap positions in the sample buffer.
1053 static void create_channels(const struct sr_input *in,
1054 struct sr_dev_inst *sdi, enum sr_channeltype ch_type)
1056 struct context *inc;
1059 struct vcd_channel *vcd_ch;
1062 struct sr_channel_group *cg;
1063 struct sr_channel *ch;
1068 if (ch_type > SR_CHANNEL_LOGIC)
1069 ch_idx += inc->logic_count;
1070 if (ch_type > SR_CHANNEL_ANALOG)
1071 ch_idx += inc->analog_count;
1072 for (l = inc->channels; l; l = l->next) {
1074 if (vcd_ch->type != ch_type)
1077 if (vcd_ch->size != 1) {
1078 cg = g_malloc0(sizeof(*cg));
1079 cg->name = g_strdup(vcd_ch->name);
1081 for (size_idx = 0; size_idx < vcd_ch->size; size_idx++) {
1082 ch_name = get_channel_name(vcd_ch, size_idx);
1083 sr_dbg("sigrok channel idx %zu, name %s, type %s, en %d.",
1085 ch_type == SR_CHANNEL_ANALOG ? "A" : "L", TRUE);
1086 ch = sr_channel_new(sdi, ch_idx, ch_type, TRUE, ch_name);
1090 cg->channels = g_slist_append(cg->channels, ch);
1093 sdi->channel_groups = g_slist_append(sdi->channel_groups, cg);
1097 static void create_feeds(const struct sr_input *in)
1099 struct context *inc;
1101 struct vcd_channel *vcd_ch;
1103 struct sr_channel *ch;
1107 /* Create one feed for logic data. */
1108 if (inc->logic_count) {
1109 inc->unit_size = (inc->logic_count + 7) / 8;
1110 inc->feed_logic = feed_queue_logic_alloc(in->sdi,
1111 CHUNK_SIZE / inc->unit_size, inc->unit_size);
1114 /* Create one feed per analog channel. */
1115 for (l = inc->channels; l; l = l->next) {
1117 if (vcd_ch->type != SR_CHANNEL_ANALOG)
1119 ch_idx = vcd_ch->array_index;
1120 ch_idx += inc->logic_count;
1121 ch = g_slist_nth_data(in->sdi->channels, ch_idx);
1122 vcd_ch->feed_analog = feed_queue_analog_alloc(in->sdi,
1123 CHUNK_SIZE / sizeof(float),
1124 vcd_ch->submit_digits, ch);
1129 * Keep track of a previously created channel list, in preparation of
1130 * re-reading the input file. Gets called from reset()/cleanup() paths.
1132 static void keep_header_for_reread(const struct sr_input *in)
1134 struct context *inc;
1138 g_slist_free_full(inc->prev.sr_groups, cg_free);
1139 inc->prev.sr_groups = in->sdi->channel_groups;
1140 in->sdi->channel_groups = NULL;
1142 g_slist_free_full(inc->prev.sr_channels, sr_channel_free_cb);
1143 inc->prev.sr_channels = in->sdi->channels;
1144 in->sdi->channels = NULL;
1148 * Check whether the input file is being re-read, and refuse operation
1149 * when essential parameters of the acquisition have changed in ways
1150 * that are unexpected to calling applications. Gets called after the
1151 * file header got parsed (again).
1153 * Changing the channel list across re-imports of the same file is not
1154 * supported, by design and for valid reasons, see bug #1215 for details.
1155 * Users are expected to start new sessions when they change these
1156 * essential parameters in the acquisition's setup. When we accept the
1157 * re-read file, then make sure to keep using the previous channel list,
1158 * applications may still reference them.
1160 static gboolean check_header_in_reread(const struct sr_input *in)
1162 struct context *inc;
1169 if (!inc->prev.sr_channels)
1172 if (sr_channel_lists_differ(inc->prev.sr_channels, in->sdi->channels)) {
1173 sr_err("Channel list change not supported for file re-read.");
1177 g_slist_free_full(in->sdi->channel_groups, cg_free);
1178 in->sdi->channel_groups = inc->prev.sr_groups;
1179 inc->prev.sr_groups = NULL;
1181 g_slist_free_full(in->sdi->channels, sr_channel_free_cb);
1182 in->sdi->channels = inc->prev.sr_channels;
1183 inc->prev.sr_channels = NULL;
1188 /* Parse VCD file header sections (rate and variables declarations). */
1189 static int parse_header(const struct sr_input *in, GString *buf)
1191 struct context *inc;
1193 char *name, *contents;
1199 /* Parse sections until complete header was seen. */
1201 name = contents = NULL;
1202 inc->conv_bits.max_bits = 1;
1203 while (parse_section(buf, &name, &contents)) {
1204 sr_dbg("Section '%s', contents '%s'.", name, contents);
1206 if (g_strcmp0(name, "enddefinitions") == 0) {
1210 if (g_strcmp0(name, "timescale") == 0) {
1211 if (parse_timescale(inc, contents) != SR_OK)
1215 if (g_strcmp0(name, "scope") == 0) {
1216 if (parse_scope(inc, contents, FALSE) != SR_OK)
1220 if (g_strcmp0(name, "upscope") == 0) {
1221 if (parse_scope(inc, NULL, TRUE) != SR_OK)
1225 if (g_strcmp0(name, "var") == 0) {
1226 if (parse_header_var(inc, contents) != SR_OK)
1243 inc->got_header = status;
1247 /* Create sigrok channels here, late, logic before analog. */
1248 create_channels(in, in->sdi, SR_CHANNEL_LOGIC);
1249 create_channels(in, in->sdi, SR_CHANNEL_ANALOG);
1250 if (!check_header_in_reread(in))
1255 * Allocate space for text to number conversion, and buffers to
1256 * hold current sample values before submission to the session
1257 * feed. Allocate one buffer for all logic bits, and another for
1258 * all floating point values of all analog channels.
1260 * The buffers get updated when the VCD input stream communicates
1261 * value changes. Upon reception of VCD timestamps, the buffer can
1262 * provide the previously received values, to "fill in the gaps"
1263 * in the generation of a continuous stream of samples for the
1266 size = (inc->conv_bits.max_bits + 7) / 8;
1267 inc->conv_bits.unit_size = size;
1268 inc->conv_bits.value = g_malloc0(size);
1269 if (!inc->conv_bits.value)
1270 return SR_ERR_MALLOC;
1272 size = (inc->logic_count + 7) / 8;
1273 inc->unit_size = size;
1274 inc->current_logic = g_malloc0(size);
1275 if (inc->unit_size && !inc->current_logic)
1276 return SR_ERR_MALLOC;
1277 size = sizeof(inc->current_floats[0]) * inc->analog_count;
1278 inc->current_floats = g_malloc0(size);
1279 if (size && !inc->current_floats)
1280 return SR_ERR_MALLOC;
1281 for (size = 0; size < inc->analog_count; size++)
1282 inc->current_floats[size] = 0.;
1284 ret = ts_stats_prep(inc);
1292 * Add N copies of previously received values to the session, before
1293 * subsequent value changes will update the data buffer. Locally buffer
1294 * sample data to minimize the number of send() calls.
1296 static void add_samples(const struct sr_input *in, size_t count, gboolean flush)
1298 struct context *inc;
1300 struct vcd_channel *vcd_ch;
1301 struct feed_queue_analog *q;
1306 if (inc->logic_count) {
1307 feed_queue_logic_submit(inc->feed_logic,
1308 inc->current_logic, count);
1310 feed_queue_logic_flush(inc->feed_logic);
1312 for (ch_list = inc->channels; ch_list; ch_list = ch_list->next) {
1313 vcd_ch = ch_list->data;
1314 if (vcd_ch->type != SR_CHANNEL_ANALOG)
1316 q = vcd_ch->feed_analog;
1319 value = inc->current_floats[vcd_ch->array_index];
1320 feed_queue_analog_submit(q, value, count);
1322 feed_queue_analog_flush(q);
1326 static gint vcd_compare_id(gconstpointer a, gconstpointer b)
1328 return strcmp((const char *)a, (const char *)b);
1331 static gboolean is_ignored(struct context *inc, const char *id)
1335 ignored = g_slist_find_custom(inc->ignored_signals, id, vcd_compare_id);
1336 return ignored != NULL;
1340 * Get an analog channel's value from a bit pattern (VCD 'integer' type).
1341 * The implementation assumes a maximum integer width (64bit), the API
1342 * doesn't (beyond the return data type). The use of SR_CHANNEL_ANALOG
1343 * channels may further constraint the number of significant digits
1344 * (current asumption: float -> 23bit).
1346 static float get_int_val(uint8_t *in_bits_data, size_t in_bits_count)
1349 size_t byte_count, byte_idx;
1350 float flt_value; /* typeof(inc->current_floats[0]) */
1352 /* Convert bit pattern to integer number (limited range). */
1354 byte_count = (in_bits_count + 7) / 8;
1355 for (byte_idx = 0; byte_idx < byte_count; byte_idx++) {
1356 if (byte_idx >= sizeof(int_value))
1358 int_value |= *in_bits_data++ << (byte_idx * 8);
1360 flt_value = int_value;
1366 * Set a logic channel's level depending on the VCD signal's identifier
1367 * and parsed value. Multi-bit VCD values will affect several sigrok
1368 * channels. One VCD signal name can translate to several sigrok channels.
1370 static void process_bits(struct context *inc, char *identifier,
1371 uint8_t *in_bits_data, size_t in_bits_count)
1376 struct vcd_channel *vcd_ch;
1379 uint8_t *in_bit_ptr, in_bit_mask;
1380 uint8_t *out_bit_ptr, out_bit_mask;
1386 for (l = inc->channels; l; l = l->next) {
1388 if (g_strcmp0(identifier, vcd_ch->identifier) != 0)
1390 if (vcd_ch->type == SR_CHANNEL_ANALOG) {
1391 /* Special case for 'integer' VCD signal types. */
1392 size = vcd_ch->size; /* Flag for "VCD signal found". */
1394 int_val = get_int_val(in_bits_data, in_bits_count);
1397 inc->current_floats[vcd_ch->array_index] = int_val;
1400 if (vcd_ch->type != SR_CHANNEL_LOGIC)
1402 sr_spew("Processing %s data, id '%s', ch %zu sz %zu",
1403 (size == 1) ? "bit" : "vector",
1404 identifier, vcd_ch->array_index, vcd_ch->size);
1406 /* Found our (logic) channel. Setup in/out bit positions. */
1407 size = vcd_ch->size;
1408 in_bit_ptr = in_bits_data;
1409 in_bit_mask = 1 << 0;
1410 out_bit_ptr = &inc->current_logic[vcd_ch->byte_idx];
1411 out_bit_mask = vcd_ch->bit_mask;
1414 * Pass VCD input bit(s) to sigrok logic bits. Conversion
1415 * must be done repeatedly because one VCD signal name
1416 * can translate to several sigrok channels, and shifting
1417 * a previously computed bit field to another channel's
1418 * position in the buffer would be nearly as expensive,
1419 * and certain would increase complexity of the code.
1421 for (bit_idx = 0; bit_idx < size; bit_idx++) {
1422 /* Get the bit value from input data. */
1424 if (bit_idx < in_bits_count) {
1425 bit_val = *in_bit_ptr & in_bit_mask;
1428 in_bit_mask = 1 << 0;
1432 /* Manipulate the sample buffer data image. */
1434 *out_bit_ptr |= out_bit_mask;
1436 *out_bit_ptr &= ~out_bit_mask;
1437 /* Update output position after bitmap update. */
1439 if (!out_bit_mask) {
1440 out_bit_mask = 1 << 0;
1445 if (!size && !is_ignored(inc, identifier))
1446 sr_warn("VCD signal not found for ID '%s'.", identifier);
1450 * Set an analog channel's value from a floating point number. One
1451 * VCD signal name can translate to several sigrok channels.
1453 static void process_real(struct context *inc, char *identifier, float real_val)
1457 struct vcd_channel *vcd_ch;
1460 for (l = inc->channels; l; l = l->next) {
1462 if (vcd_ch->type != SR_CHANNEL_ANALOG)
1464 if (g_strcmp0(identifier, vcd_ch->identifier) != 0)
1467 /* Found our (analog) channel. */
1469 sr_spew("Processing real data, id '%s', ch %zu, val %.16g",
1470 identifier, vcd_ch->array_index, real_val);
1471 inc->current_floats[vcd_ch->array_index] = real_val;
1473 if (!found && !is_ignored(inc, identifier))
1474 sr_warn("VCD signal not found for ID '%s'.", identifier);
1478 * Converts a bit position's text character to a number value.
1480 * TODO Check for complete coverage of Verilog's standard logic values
1481 * (IEEE-1364). The set is said to be “01XZHUWL-”, which only a part of
1482 * is handled here. What would be the complete mapping?
1483 * - 0/L -> bit value 0
1484 * - 1/H -> bit value 1
1485 * - X "don't care" -> TODO
1486 * - Z "high impedance" -> TODO
1487 * - W "weak(?)" -> TODO
1488 * - U "undefined" -> TODO
1489 * - '-' "TODO" -> TODO
1491 * For simplicity, this input module implementation maps "known low"
1492 * values to 0, and "known high" values to 1. All other values will
1493 * end up assuming "low" (return number 0), while callers might warn.
1494 * It's up to users to provide compatible input data, or accept the
1495 * warnings. Silently accepting unknown input data is not desirable.
1497 static uint8_t vcd_char_to_value(char bit_char, int *warn)
1500 bit_char = g_ascii_tolower(bit_char);
1502 /* Convert the "undisputed" variants. */
1503 if (bit_char == '0' || bit_char == 'l')
1505 if (bit_char == '1' || bit_char == 'h')
1508 /* Convert the "uncertain" variants. */
1511 if (bit_char == 'x' || bit_char == 'z')
1513 if (bit_char == 'u')
1515 if (bit_char == '-')
1518 /* Unhandled input text. */
1523 * Check the validity of a VCD string value. It's essential to reliably
1524 * accept valid data which the community uses in the field, yet robustly
1525 * reject invalid data for users' awareness. Since IEEE 1800-2017 would
1526 * not discuss the representation of this data type, it's assumed to not
1527 * be an official feature of the VCD file format. This implementation is
1528 * an educated guess after inspection of other arbitrary implementations,
1529 * not backed by any specification or public documentation.
1531 * A quick summary of the implemented assumptions: Must be a sequence of
1532 * ASCII printables. Must not contain whitespace. Might contain escape
1533 * sequences: A backslash followed by a single character, like '\n' or
1534 * '\\'. Or a backslash and the letter x followed by two hex digits,
1535 * like '\x20'. Or a backslash followed by three octal digits, like
1536 * '\007'. As an exception also accepts a single digit '\0' but only at
1537 * the text end. The string value may be empty, but must not be NULL.
1539 * This implementation assumes an ASCII based platform for simplicity
1540 * and readability. Should be a given on sigrok supported platforms.
1542 static gboolean vcd_string_valid(const char *s)
1551 /* Reject non-printable ASCII chars including DEL. */
1556 /* Deeper inspection of escape sequences. */
1560 case 'a': /* BEL, bell aka "alarm" */
1561 case 'b': /* BS, back space */
1562 case 't': /* TAB, tabulator */
1563 case 'n': /* NL, newline */
1564 case 'v': /* VT, vertical tabulator */
1565 case 'f': /* FF, form feed */
1566 case 'r': /* CR, carriage return */
1567 case '"': /* double quotes */
1568 case '\'': /* tick, single quote */
1569 case '?': /* question mark */
1570 case '\\': /* backslash */
1572 case 'x': /* \xNN two hex digits */
1574 if (!g_ascii_isxdigit(c))
1577 if (!g_ascii_isxdigit(c))
1580 case '0': /* \NNN three octal digits */
1588 /* Special case '\0' at end of text. */
1589 if (c == '0' && !*s)
1592 * First digit was covered by the outer
1593 * switch(). Two more digits to check.
1596 if (!g_ascii_isdigit(c) || c > '7')
1599 if (!g_ascii_isdigit(c) || c > '7')
1611 /* Parse one text line of the data section. */
1612 static int parse_textline(const struct sr_input *in, char *lines)
1614 struct context *inc;
1617 size_t word_count, word_idx;
1618 char *curr_word, *next_word, curr_first;
1619 gboolean is_timestamp, is_section;
1620 gboolean is_real, is_multibit, is_singlebit, is_string;
1622 char *identifier, *endptr;
1628 * Split the caller's text lines into a list of space separated
1629 * words. Note that some of the branches consume the very next
1630 * words as well, and assume that both adjacent words will be
1631 * available when the first word is seen. This constraint applies
1632 * to bit vector data, multi-bit integers and real (float) data,
1633 * as well as single-bit data with whitespace before its
1634 * identifier (if that's valid in VCD, we'd accept it here).
1635 * The fact that callers always pass complete text lines should
1636 * make this assumption acceptable.
1639 words = split_text_line(inc, lines, &word_count);
1640 for (word_idx = 0; word_idx < word_count; word_idx++) {
1642 * Make the next two words available, to simpilify code
1643 * paths below. The second word is optional here.
1645 curr_word = words[word_idx];
1646 if (!curr_word && !curr_word[0])
1648 curr_first = g_ascii_tolower(curr_word[0]);
1649 next_word = words[word_idx + 1];
1650 if (next_word && !next_word[0])
1654 * Optionally skip some sections that can be interleaved
1655 * with data (and may or may not be supported by this
1656 * input module). If the section is not skipped but the
1657 * $end keyword needs to get tracked, specifically handle
1658 * this case, for improved robustness (still reject files
1659 * which happen to use invalid syntax).
1661 if (inc->skip_until_end) {
1662 if (strcmp(curr_word, "$end") == 0) {
1663 /* Done with unhandled/unknown section. */
1664 sr_dbg("done skipping until $end");
1665 inc->skip_until_end = FALSE;
1667 sr_spew("skipping word: %s", curr_word);
1671 if (inc->ignore_end_keyword) {
1672 if (strcmp(curr_word, "$end") == 0) {
1673 sr_dbg("done ignoring $end keyword");
1674 inc->ignore_end_keyword = FALSE;
1680 * There may be $keyword sections inside the data part of
1681 * the input file. Do inspect some of the sections' content
1682 * but ignore their surrounding keywords. Silently skip
1683 * unsupported section types (which transparently covers
1684 * $comment sections).
1686 is_section = curr_first == '$' && curr_word[1];
1688 gboolean inspect_data;
1690 inspect_data = FALSE;
1691 inspect_data |= g_strcmp0(curr_word, "$dumpvars") == 0;
1692 inspect_data |= g_strcmp0(curr_word, "$dumpon") == 0;
1693 inspect_data |= g_strcmp0(curr_word, "$dumpoff") == 0;
1695 /* Ignore keywords, yet parse contents. */
1696 sr_dbg("%s section, will parse content", curr_word);
1697 inc->ignore_end_keyword = TRUE;
1699 /* Ignore section from here up to $end. */
1700 sr_dbg("%s section, will skip until $end", curr_word);
1701 inc->skip_until_end = TRUE;
1707 * Numbers prefixed by '#' are timestamps, which translate
1708 * to sigrok sample numbers. Apply optional downsampling,
1709 * and apply the 'skip' logic. Check the recent timestamp
1710 * for plausibility. Submit the corresponding number of
1711 * samples of previously accumulated data values to the
1714 is_timestamp = curr_first == '#' && g_ascii_isdigit(curr_word[1]);
1717 timestamp = strtoull(&curr_word[1], &endptr, 10);
1718 if (!endptr || *endptr) {
1719 sr_err("Invalid timestamp: %s.", curr_word);
1723 sr_spew("Got timestamp: %" PRIu64, timestamp);
1724 ret = ts_stats_check(&inc->ts_stats, timestamp);
1727 if (inc->options.downsample > 1) {
1728 timestamp /= inc->options.downsample;
1729 sr_spew("Downsampled timestamp: %" PRIu64, timestamp);
1733 * Skip < 0 => skip until first timestamp.
1734 * Skip = 0 => don't skip
1735 * Skip > 0 => skip until timestamp >= skip.
1737 if (inc->options.skip_specified && !inc->use_skip) {
1738 sr_dbg("Seeding skip from user spec %" PRIu64,
1739 inc->options.skip_starttime);
1740 inc->prev_timestamp = inc->options.skip_starttime;
1741 inc->use_skip = TRUE;
1743 if (!inc->use_skip) {
1744 sr_dbg("Seeding skip from first timestamp");
1745 inc->options.skip_starttime = timestamp;
1746 inc->prev_timestamp = timestamp;
1747 inc->use_skip = TRUE;
1750 if (inc->options.skip_starttime && timestamp < inc->options.skip_starttime) {
1751 sr_spew("Timestamp skipped, before user spec");
1752 inc->prev_timestamp = inc->options.skip_starttime;
1755 if (timestamp == inc->prev_timestamp) {
1757 * Ignore repeated timestamps (e.g. sigrok
1758 * outputs these). Can also happen when
1759 * downsampling makes distinct input values
1760 * end up at the same scaled down value.
1761 * Also transparently covers the initial
1764 sr_spew("Timestamp is identical to previous timestamp");
1767 if (timestamp < inc->prev_timestamp) {
1768 sr_err("Invalid timestamp: %" PRIu64 " (leap backwards).", timestamp);
1772 if (inc->options.compress) {
1773 /* Compress long idle periods */
1774 count = timestamp - inc->prev_timestamp;
1775 if (count > inc->options.compress) {
1776 sr_dbg("Long idle period, compressing");
1777 count = timestamp - inc->options.compress;
1778 inc->prev_timestamp = count;
1782 /* Generate samples from prev_timestamp up to timestamp - 1. */
1783 count = timestamp - inc->prev_timestamp;
1784 sr_spew("Got a new timestamp, feeding %zu samples", count);
1785 add_samples(in, count, FALSE);
1786 inc->prev_timestamp = timestamp;
1787 inc->data_after_timestamp = FALSE;
1790 inc->data_after_timestamp = TRUE;
1793 * Data values come in different formats, are associated
1794 * with channel identifiers, and correspond to the period
1795 * of time from the most recent timestamp to the next
1798 * Supported input data formats are:
1799 * - S<value> <sep> <id> (value not used, VCD type 'string').
1800 * - R<value> <sep> <id> (analog channel, VCD type 'real').
1801 * - B<value> <sep> <id> (analog channel, VCD type 'integer').
1802 * - B<value> <sep> <id> (logic channels, VCD bit vectors).
1803 * - <value> <id> (logic channel, VCD single-bit values).
1805 * Input values can be:
1806 * - Floating point numbers.
1807 * - Bit strings (which covers multi-bit aka integers
1808 * as well as vectors).
1812 * - Individual bits can be 0/1 which is supported by
1813 * libsigrok, or x or z which is treated like 0 here
1814 * (sigrok lacks support for ternary logic, neither is
1815 * there support for the full IEEE set of values).
1816 * - Single-bit values typically won't be separated from
1817 * the signal identifer, multi-bit values and floats
1818 * are separated (will reference the next word). This
1819 * implementation silently accepts separators for
1820 * single-bit values, too.
1822 is_real = curr_first == 'r' && curr_word[1];
1823 is_multibit = curr_first == 'b' && curr_word[1];
1824 is_singlebit = curr_first == '0' || curr_first == '1';
1825 is_singlebit |= curr_first == 'l' || curr_first == 'h';
1826 is_singlebit |= curr_first == 'x' || curr_first == 'z';
1827 is_singlebit |= curr_first == 'u' || curr_first == '-';
1828 is_string = curr_first == 's';
1833 real_text = &curr_word[1];
1834 identifier = next_word;
1836 if (!*real_text || !identifier || !*identifier) {
1837 sr_err("Unexpected real format.");
1841 sr_spew("Got real data %s for id '%s'.",
1842 real_text, identifier);
1843 if (sr_atof_ascii(real_text, &real_val) != SR_OK) {
1844 sr_err("Cannot convert value: %s.", real_text);
1848 process_real(inc, identifier, real_val);
1852 char *bits_text_start;
1854 char *bits_text, bit_char;
1856 uint8_t *value_ptr, value_mask;
1857 GString *bits_val_text;
1860 * Fold in single-bit code path here? To re-use
1861 * the X/Z support. Current redundancy is few so
1862 * there is little pressure to unify code paths.
1863 * Also multi-bit handling is often different
1864 * from single-bit handling, so the "unified"
1865 * path would often check for special cases. So
1866 * we may never unify code paths at all here.
1868 bits_text = &curr_word[1];
1869 identifier = next_word;
1872 if (!*bits_text || !identifier || !*identifier) {
1873 sr_err("Unexpected integer/vector format.");
1877 sr_spew("Got integer/vector data %s for id '%s'.",
1878 bits_text, identifier);
1881 * Accept a bit string of arbitrary length (sort
1882 * of, within the limits of the previously setup
1883 * conversion buffer). The input text omits the
1884 * leading zeroes, hence we convert from end to
1885 * the start, to get the significant bits. There
1886 * should only be errors for invalid input, or
1887 * for input that is rather strange (data holds
1888 * more bits than the signal's declaration in
1889 * the header suggested). Silently accept data
1890 * that fits in the conversion buffer, and has
1891 * more significant bits than the signal's type
1892 * (that'd be non-sence yet acceptable input).
1894 bits_text_start = bits_text;
1895 bits_text += strlen(bits_text);
1896 bit_count = bits_text - bits_text_start;
1897 if (bit_count > inc->conv_bits.max_bits) {
1898 sr_err("Value exceeds conversion buffer: %s",
1903 memset(inc->conv_bits.value, 0, inc->conv_bits.unit_size);
1904 value_ptr = &inc->conv_bits.value[0];
1905 value_mask = 1 << 0;
1906 inc->conv_bits.sig_count = 0;
1907 while (bits_text > bits_text_start) {
1908 inc->conv_bits.sig_count++;
1909 bit_char = *(--bits_text);
1910 bit_value = vcd_char_to_value(bit_char, NULL);
1911 if (bit_value == 0) {
1913 } else if (bit_value == 1) {
1914 *value_ptr |= value_mask;
1916 inc->conv_bits.sig_count = 0;
1922 value_mask = 1 << 0;
1925 if (!inc->conv_bits.sig_count) {
1926 sr_err("Unexpected vector format: %s",
1931 if (sr_log_loglevel_get() >= SR_LOG_SPEW) {
1932 bits_val_text = sr_hexdump_new(inc->conv_bits.value,
1933 value_ptr - inc->conv_bits.value + 1);
1934 sr_spew("Vector value: %s.", bits_val_text->str);
1935 sr_hexdump_free(bits_val_text);
1938 process_bits(inc, identifier,
1939 inc->conv_bits.value, inc->conv_bits.sig_count);
1943 char *bits_text, bit_char;
1946 /* Get the value text, and signal identifier. */
1947 bits_text = &curr_word[0];
1948 bit_char = *bits_text;
1950 sr_err("Bit value missing.");
1954 identifier = ++bits_text;
1956 identifier = next_word;
1959 if (!identifier || !*identifier) {
1960 sr_err("Identifier missing.");
1965 /* Convert value text to single-bit number. */
1966 bit_value = vcd_char_to_value(bit_char, NULL);
1967 if (bit_value != 0 && bit_value != 1) {
1968 sr_err("Unsupported bit value '%c'.", bit_char);
1972 inc->conv_bits.value[0] = bit_value;
1973 process_bits(inc, identifier, inc->conv_bits.value, 1);
1977 const char *str_value;
1979 str_value = &curr_word[1];
1980 identifier = next_word;
1982 if (!vcd_string_valid(str_value)) {
1983 sr_err("Invalid string data: %s", str_value);
1987 if (!identifier || !*identifier) {
1988 sr_err("String value without identifier.");
1992 sr_spew("Got string data, id '%s', value \"%s\".",
1993 identifier, str_value);
1994 if (!is_ignored(inc, identifier)) {
1995 sr_err("String value for identifier '%s'.",
2003 /* Design choice: Consider unsupported input fatal. */
2004 sr_err("Unknown token '%s'.", curr_word);
2008 free_text_split(inc, words);
2013 static int process_buffer(struct sr_input *in, gboolean is_eof)
2015 struct context *inc;
2016 uint64_t samplerate;
2019 char *rdptr, *endptr, *trimptr;
2024 /* Send feed header and samplerate (once) before sample data. */
2025 if (!inc->started) {
2026 std_session_send_df_header(in->sdi);
2028 samplerate = inc->samplerate / inc->options.downsample;
2030 gvar = g_variant_new_uint64(samplerate);
2031 sr_session_send_meta(in->sdi, SR_CONF_SAMPLERATE, gvar);
2034 inc->started = TRUE;
2038 * Workaround broken generators which output incomplete text
2039 * lines. Enforce the trailing line feed. Proper input is not
2040 * harmed by another empty line of input data.
2043 g_string_append_c(in->buf, '\n');
2045 /* Find and process complete text lines in the input data. */
2047 rdptr = in->buf->str;
2049 rdlen = &in->buf->str[in->buf->len] - rdptr;
2050 endptr = g_strstr_len(rdptr, rdlen, "\n");
2055 while (g_ascii_isspace(*rdptr))
2057 while (trimptr > rdptr && g_ascii_isspace(trimptr[-1]))
2058 *(--trimptr) = '\0';
2063 ret = parse_textline(in, rdptr);
2068 rdlen = rdptr - in->buf->str;
2069 g_string_erase(in->buf, 0, rdlen);
2074 static int format_match(GHashTable *metadata, unsigned int *confidence)
2076 GString *buf, *tmpbuf;
2078 char *name, *contents;
2080 buf = g_hash_table_lookup(metadata,
2081 GINT_TO_POINTER(SR_INPUT_META_HEADER));
2082 tmpbuf = g_string_new_len(buf->str, buf->len);
2085 * If we can parse the first section correctly, then it is
2086 * assumed that the input is in VCD format.
2088 check_remove_bom(tmpbuf);
2089 status = parse_section(tmpbuf, &name, &contents);
2090 g_string_free(tmpbuf, TRUE);
2101 static int init(struct sr_input *in, GHashTable *options)
2103 struct context *inc;
2106 inc = g_malloc0(sizeof(*inc));
2108 data = g_hash_table_lookup(options, "numchannels");
2109 inc->options.maxchannels = g_variant_get_uint32(data);
2111 data = g_hash_table_lookup(options, "downsample");
2112 inc->options.downsample = g_variant_get_uint64(data);
2113 if (inc->options.downsample < 1)
2114 inc->options.downsample = 1;
2116 data = g_hash_table_lookup(options, "compress");
2117 inc->options.compress = g_variant_get_uint64(data);
2118 inc->options.compress /= inc->options.downsample;
2120 data = g_hash_table_lookup(options, "skip");
2122 inc->options.skip_specified = TRUE;
2123 inc->options.skip_starttime = g_variant_get_uint64(data);
2124 if (inc->options.skip_starttime == ~UINT64_C(0)) {
2125 inc->options.skip_specified = FALSE;
2126 inc->options.skip_starttime = 0;
2128 inc->options.skip_starttime /= inc->options.downsample;
2131 in->sdi = g_malloc0(sizeof(*in->sdi));
2134 inc->scope_prefix = g_string_new("\0");
2139 static int receive(struct sr_input *in, GString *buf)
2141 struct context *inc;
2146 /* Collect all input chunks, potential deferred processing. */
2147 g_string_append_len(in->buf, buf->str, buf->len);
2148 if (!inc->got_header && in->buf->len == buf->len)
2149 check_remove_bom(in->buf);
2151 /* Must complete reception of the VCD header first. */
2152 if (!inc->got_header) {
2153 if (!have_header(in->buf))
2155 ret = parse_header(in, in->buf);
2158 /* sdi is ready, notify frontend. */
2159 in->sdi_ready = TRUE;
2163 /* Process sample data. */
2164 ret = process_buffer(in, FALSE);
2169 static int end(struct sr_input *in)
2171 struct context *inc;
2177 /* Must complete processing of previously received chunks. */
2179 ret = process_buffer(in, TRUE);
2183 /* Flush most recently queued sample data when EOF is seen. */
2184 count = inc->data_after_timestamp ? 1 : 0;
2185 add_samples(in, count, TRUE);
2187 /* Optionally suggest downsampling after all input data was seen. */
2188 (void)ts_stats_post(inc, !inc->data_after_timestamp);
2190 /* Must send DF_END when DF_HEADER was sent before. */
2192 std_session_send_df_end(in->sdi);
2197 static void cleanup(struct sr_input *in)
2199 struct context *inc;
2203 keep_header_for_reread(in);
2205 g_slist_free_full(inc->channels, free_channel);
2206 inc->channels = NULL;
2207 feed_queue_logic_free(inc->feed_logic);
2208 inc->feed_logic = NULL;
2209 g_free(inc->conv_bits.value);
2210 inc->conv_bits.value = NULL;
2211 g_free(inc->current_logic);
2212 inc->current_logic = NULL;
2213 g_free(inc->current_floats);
2214 inc->current_floats = NULL;
2215 g_string_free(inc->scope_prefix, TRUE);
2216 inc->scope_prefix = NULL;
2217 g_slist_free_full(inc->ignored_signals, g_free);
2218 inc->ignored_signals = NULL;
2219 free_text_split(inc, NULL);
2222 static int reset(struct sr_input *in)
2224 struct context *inc;
2225 struct vcd_user_opt save;
2226 struct vcd_prev prev;
2230 /* Relase previously allocated resources. */
2232 g_string_truncate(in->buf, 0);
2234 /* Restore part of the context, init() won't run again. */
2235 save = inc->options;
2237 memset(inc, 0, sizeof(*inc));
2238 inc->options = save;
2240 inc->scope_prefix = g_string_new("\0");
2253 static struct sr_option options[] = {
2255 "numchannels", "Max number of sigrok channels",
2256 "The maximum number of sigrok channels to create for VCD input signals.",
2259 [OPT_DOWN_SAMPLE] = {
2260 "downsample", "Downsampling factor",
2261 "Downsample the input file's samplerate, i.e. divide by the specified factor.",
2264 [OPT_SKIP_COUNT] = {
2265 "skip", "Skip this many initial samples",
2266 "Skip samples until the specified timestamp. "
2267 "By default samples start at the first timestamp in the file. "
2268 "Value 0 creates samples starting at timestamp 0. "
2269 "Values above 0 only start processing at the given timestamp.",
2273 "compress", "Compress idle periods",
2274 "Compress idle periods which are longer than the specified number of timescale ticks.",
2277 [OPT_MAX] = ALL_ZERO,
2280 static const struct sr_option *get_options(void)
2282 if (!options[0].def) {
2283 options[OPT_NUM_CHANS].def = g_variant_ref_sink(g_variant_new_uint32(0));
2284 options[OPT_DOWN_SAMPLE].def = g_variant_ref_sink(g_variant_new_uint64(1));
2285 options[OPT_SKIP_COUNT].def = g_variant_ref_sink(g_variant_new_uint64(~UINT64_C(0)));
2286 options[OPT_COMPRESS].def = g_variant_ref_sink(g_variant_new_uint64(0));
2292 SR_PRIV struct sr_input_module input_vcd = {
2295 .desc = "Value Change Dump data",
2296 .exts = (const char*[]){"vcd", NULL},
2297 .metadata = { SR_INPUT_META_HEADER | SR_INPUT_META_REQUIRED },
2298 .options = get_options,
2299 .format_match = format_match,