input/protocoldata: add input module for "protocol values" files

[libsigrok.git] / src / input / protocoldata.c

/*
 * This file is part of the libsigrok project.
 *
 * Copyright (C) 2019-2023 Gerhard Sittig <gerhard.sittig@gmx.net>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/*
 * This input module reads data values from an input stream, and sends
 * the corresponding samples to the sigrok session feed which form the
 * respective waveform, pretending that a logic analyzer had captured
 * wire traffic. This allows to feed data to protocol decoders which
 * were recorded by different means (COM port redirection, pcap(3)
 * recordings, 3rd party bus analyzers). It can also simplify the
 * initial creation of protocol decoders by generating synthetic
 * input data, before real world traffic captures become available.
 *
 * This input module "assumes ideal traffic" and absence of protocol
 * errors. Does _not_ inject error conditions, instead generates valid
 * bit patterns by naively filling blanks to decorate the payload data
 * which the input file provides. To yield a stream of samples which
 * successfully decodes at the recipient's, and upper layer decoders
 * will see valid data which corresponds to the file's content. Edge
 * positions and minute timnig details are not adjustable either in
 * this module (no support for setup or hold times or slew rates etc).
 * The goal is not to emulate a protocol with all its possibilities to
 * the fullest detail. The module's purpose is to simplify the import
 * of values while no capture of the wire traffic was available.
 *
 * There are several approaches to using the input module:
 * - Input data can be a mere bytes sequence. While attributes can get
 *   specified by means of input module options. This is the fastest
 *   approach to accessing raw data that's externally made available.
 * - An optional leading magic literal supports automatic file type
 *   detection, and obsoletes the -I input module selection. Unwanted
 *   automatic detection is possible but very unlikely. The magic text
 *   was chosen such that its occurance at the very start of payload
 *   data is extremely unlikely, and is easy to work around should the
 *   situation happen. Of course specifying input module options does
 *   necessitate the selection of the input module.
 * - When the file type magic is present, an optional header section
 *   can follow, and can carry parameters which obsolete the necessity
 *   to specify input module options. The choice of header section
 *   boundaries again reduces the likelyhood of false detection. When
 *   input module options were specified, they take precedence over
 *   input stream content.
 * - The payload of the input stream (the protocol values) can take
 *   the form of a mere bytes sequence where every byte is a value
 *   (this is the default). Or values can be represented in textual
 *   format when either an input module option or the header section
 *   specify that the input is text. Individual protocol handlers can
 *   also prefer one format over another, while file content and
 *   module options take precedence as usual. Some protocols may not
 *   usefully be described by values only, or may involve values and
 *   numbers larger than a byte, which essentially makes text format
 *   a non-option for these situations.
 * - The text format supports coments which silently get discarded.
 *   As well as pseudo comments which can affect the interpretation
 *   of the input text, and/or can control properties of protocols
 *   that exceed the mere submission of values. Think chip-select or
 *   ACK/NAK slots or similar.
 * - It's understood that the text format is more expensive to process,
 *   but is also more versatile. It's assumed that the 'protocoldata'
 *   input format is used for small or mid size capture lengths. The
 *   input module enables quick access to data that became available
 *   by other means. For higher fidelity of real world traffic and for
 *   long captures the native format should be preferred. For error
 *   injection the VCD format might be a better match.
 * - It should be obvious that raw bytes or input data in text form,
 *   as well as header fields can either be the content of a file on
 *   disk, or can be part of a pipe input. Either the earlier process
 *   in the pipe which provides the values, or an intermediate filter
 *   in the pipe, can provide the decoration.
 *     $ ./gen-values.sh | sigrok-cli -i - ...
 *     $ ./gen-values.sh | cat header - | sigrok-cli -i - ...
 * - Since the input format supports automatic detection as well as
 *   parameter specs by means of input module options as well as in
 *   file content, the format lends itself equally well to pipelined
 *   or scripted as well as interactive use in different applications.
 *   For pipelines, the header as well as the values (as well as any
 *   mix of these pieces) can be kept in separate locations. Generators
 *   need not provide all of the input stream in a single invocation.
 * - As a matter of convenience, especially when targetting upper layer
 *   protocol decoders, users need not construct "correctly configured"
 *   from the lower protocol's perspective) waveforms on the wire.
 *   Instead "naive" waveforms which match the decoders' default options
 *   can be used, which eliminates the need to configure non-default
 *   options in decoders (and redundantly do the same thing in the
 *   input module, just to have them match again).
 *     $ ./gen-values.sh | sigrok-cli \
 *       -i - -I protocoldata:protocol=uart:bitrate=57600:frameformat=8e2 \
 *       -P uart:parity=even:baudrate=57600
 *     $ ./gen-values.sh | sigrok-cli \
 *       -i - -I protocoldata:protocol=uart -P uart,midi
 *
 * Example invocations:
 *
 *   $ sigrok-cli -I protocoldata --show
 *
 *   $ echo "Hello sigrok protocol values!" | \
 *     sigrok-cli \
 *       -I protocoldata:protocol=uart -i - \
 *       -P uart:format=ascii -A uart=rx-data
 *
 *   $ sigrok-cli -i file.bin -P uart -A uart=rx-data
 *   $ sigrok-cli -i file.txt -P uart:rx=rxtx -A uart
 *   $ sigrok-cli -i file.txt --show
 *   $ sigrok-cli -i file.txt -O ascii:width=4000 | $PAGER
 *
 *   $ echo "# -- sigrok protocol data values file --" > header.txt
 *   $ echo "# -- sigrok protocol data header start --" >> header.txt
 *   $ echo "protocol=uart" >> header.txt
 *   $ echo "bitrate=100000" >> header.txt
 *   $ echo "frameformat=8e2" >> header.txt
 *   $ echo "textinput=yes" >> header.txt
 *   $ echo "# -- sigrok protocol data header end --" >> header.txt
 *   $ echo "# textinput: radix=16" > values.txt
 *   $ echo "0f  40 a6 28 fa 78 05 19 ee c2 92 70 58 62 09 a9 f1 ca 44 90 d1 07 19  02  00" >> values.txt
 *   $ head header.txt values.txt
 *   $ cat values.txt | cat header.txt - | \
 *     sigrok-cli -i - -P uart:baudrate=100000:parity=even,sbus_futaba -A sbus_futaba
 *
 *   $ pulseview -i file-spi-text.txt &
 *
 * Known issues:
 * - Only few protocols are implemented so far. Existing handlers have
 *   suggested which infrastructure is required for future extension.
 *   But future handlers may reveal more omissions or assumptions that
 *   need addressing.
 * - Terminology may be inconsistent, because this input module supports
 *   several protocols which often differ in how they use terms. What is
 *   available:
 *   - The input module constructs waveforms that span multiple traces.
 *     Resulting waveforms are said to have a samplerate. Data that is
 *     kept in that waveform can have a bitrate. Which is essential for
 *     asynchronous communication, but could be unimportant for clocked
 *     protocols. Protocol handlers may adjust their output to enforce
 *     a bitrate, but need not. The timing is an approximation anyway,
 *     does not reflect pauses or jitter or turnarounds which real world
 *     traffic would reveal.
 *   - Protocol handlers can generate an arbitrary number of samples for
 *     a protocol data value. A maximum number of samples per value is
 *     assumed. Variable length samples sequences per data value or per
 *     invocation is supported (and can be considered the typical case).
 *   - Protocol handlers can configure differing widths for the samples
 *     that they derived from input data. These quanta get configured
 *     when the frame format gets interpreted, and are assumed to remain
 *     as they are across data value processing.
 *   - Data values can be considered "a frame" (as seen with UART). But
 *     data values could also be "bytes" or "words" in a protocol, while
 *     "frames" or "transfers" are implemented by different means (as
 *     seen with SPI or I2C). The typical approach would be to control a
 *     "select" signal by means of pseudo comments which are interleaved
 *     with data values.
 *   - Data values need not get forwarded to decoders. They might also
 *     control the processing of the following data values as well as
 *     the waveform construction. This is at the discretion of protocol
 *     handlers, think of slave addresses, preceeding field or value
 *     counts before their data values follow, etc.
 * - Users may need to specify more options than expected when the file
 *   content is "incomplete". The sequence of scanning builtin defaults,
 *   then file content provided specs, then user specified specs, is
 *   yet to get done. Until then it helps being explicit and thorough.
 *
 * TODO (arbitrary order, could partially be outdated)
 * - Implement the most appropriate order of option scanning. Use
 *   builtin defaults first, file content then, then user specified
 *   options (when available). This shall be most robust and correct.
 * - Switch to "submit one sample" in feed queue API when available.
 *   The current implementation of this input module uses ugly ifdefs
 *   to adjust to either feed queue API approach.
 * - (obsoleted by the introduction of support for text format input?)
 *   Introduce TLV support for the binary input format? u32be type,
 *   u64be length, u8[] payload. The complexity of the implementation
 *   in the input module, combined with the complexity of generating
 *   the input stream which uses TLV sections, are currently considered
 *   undesirable for this input module. Do we expect huge files where
 *   the computational cost of text conversion causes pain?
 * - Extend the UART protocol handler. Implement separate RX and TX
 *   traces. Support tx-only, rx-only, and tx-then-rx input orders.
 * - Add a 'parallel' protocol handler, which grabs a bit pattern and
 *   derives the waveform in straight forward ways? This would be similar
 *   to the raw binary input module, but the text format could improve
 *   readability, and the input module could generate a clock signal
 *   which isn't part of the input stream. That 'parallel' protocol
 *   could be used as a vehicle to bitbang any other protocol that is
 *   unknown to the input module. The approach is only limited by the
 *   input stream generator's imagination.
 * - Add other protocol variants. The binary input format was very
 *   limiting, the text format could cover a lot of more cases:
 *   - CAN: Pseudo comments can communicate the frame's flags (and
 *     address type etc). The first data value can be the address. The
 *     second data value or a pseudo comment can hold the CAN frame's
 *     data length (bytes count). Other data values are the 0..8 data
 *     bytes. CAN-FD might be possible with minimal adjustment?
 *   - W1: Pseudo comments can start a frame (initiate RESET). First
 *     value can carry frame length. Data bytes follow. Scans can get
 *     represented as raw bytes (bit count results in full 8bit size).
 * - Are more than 8 traces desirable? The initial implementation was
 *   motivated by serial communication (UART). More channels were not
 *   needed so far. Even QuadSPI and Hitachi displays fit onto 8 lines.
 *
 * See the sigrok.org file format wiki page for details about the syntax
 * that is supported by this input module. Or see the top of the source
 * file and its preprocessor symbols to quickly get an idea of known
 * keywords in input files.
 */

#include "config.h"

#include <ctype.h>
#include <libsigrok/libsigrok.h>
#include <string.h>
#include <strings.h>

#include "libsigrok-internal.h"

#define LOG_PREFIX      "input/protocoldata"

#define CHUNK_SIZE      (4 * 1024 * 1024)

/*
 * Support optional automatic file type detection. Support optionally
 * embedded options in a header section after the file detection magic
 * and before the payload data (bytes or text).
 */
#define MAGIC_FILE_TYPE         "# -- sigrok protocol data values file --"
#define TEXT_HEAD_START         "# -- sigrok protocol data header start --"
#define TEXT_HEAD_END           "# -- sigrok protocol data header end --"
#define TEXT_COMM_LEADER        "#"

#define LABEL_SAMPLERATE        "samplerate="
#define LABEL_BITRATE           "bitrate="
#define LABEL_PROTOCOL          "protocol="
#define LABEL_FRAMEFORMAT       "frameformat="
#define LABEL_TEXTINPUT         "textinput="

/*
 * Options which are embedded in pseudo comments and are related to
 * how the input module reads the input text stream. Universally
 * applicable to all text inputs regardless of protocol choice.
 */
#define TEXT_INPUT_PREFIX       "textinput:"
#define TEXT_INPUT_RADIX        "radix="

/*
 * Protocol dependent frame formats, the default and absolute limits.
 * Protocol dependent keywords in pseudo-comments.
 *
 * UART assumes 9x2 as the longest useful frameformat. Additional STOP
 * bits let users insert idle phases between frames, until more general
 * support for inter-frame gaps is in place. By default the protocol
 * handler generously adds a few more idle bit times after a UART frame.
 *
 * SPI assumes exactly 8 bits per "word". And leaves bit slots around
 * the byte transmission, to have space where CS asserts or releases.
 * Including time where SCK changes to its idle level. And requires two
 * samples per bit time (pos and neg clock phase). The "decoration" also
 * helps users' interactive exploration of generated waveforms.
 *
 * I2C generously assumes six quanta per bit slot, to gracefully allow
 * for reliable SCL and SDA transitions regardless of samples that result
 * from prior communication. The longest waveform is a byte (with eight
 * data bits and an ACK slot). Special symbols like START, and STOP will
 * fit into that memory while it is not used to communicate a byte.
 */
#define UART_HANDLER_NAME       "uart"
#define UART_DFLT_SAMPLERATE    SR_MHZ(1)
#define UART_DFLT_BITRATE       115200
#define UART_DFLT_FRAMEFMT      "8n1"
#define UART_MIN_DATABITS       5
#define UART_MAX_DATABITS       9
#define UART_MAX_STOPBITS       20
#define UART_ADD_IDLEBITS       2
#define UART_MAX_WAVELEN        (1 + UART_MAX_DATABITS + 1 + UART_MAX_STOPBITS \
                                + UART_ADD_IDLEBITS)
#define UART_FORMAT_INVERT      "inverted"
/* In addition the usual '8n1' et al are supported. */
#define UART_PSEUDO_BREAK       "break"
#define UART_PSEUDO_IDLE        "idle"

#define SPI_HANDLER_NAME        "spi"
#define SPI_DFLT_SAMPLERATE     SR_MHZ(10)
#define SPI_DFLT_BITRATE        SR_MHZ(1)
#define SPI_DFLT_FRAMEFMT       "cs-low,bits=8,mode=0,msb-first"
#define SPI_MIN_DATABITS        8
#define SPI_MAX_DATABITS        8
#define SPI_MAX_WAVELEN         (2 + 2 * SPI_MAX_DATABITS + 3)
#define SPI_FORMAT_CS_LOW       "cs-low"
#define SPI_FORMAT_CS_HIGH      "cs-high"
#define SPI_FORMAT_DATA_BITS    "bits="
#define SPI_FORMAT_SPI_MODE     "mode="
#define SPI_FORMAT_MODE_CPOL    "cpol="
#define SPI_FORMAT_MODE_CPHA    "cpha="
#define SPI_FORMAT_MSB_FIRST    "msb-first"
#define SPI_FORMAT_LSB_FIRST    "lsb-first"
#define SPI_PSEUDO_MOSI_ONLY    "mosi-only"
#define SPI_PSEUDO_MOSI_FIXED   "mosi-fixed="
#define SPI_PSEUDO_MISO_ONLY    "miso-only"
#define SPI_PSEUDO_MISO_FIXED   "miso-fixed="
#define SPI_PSEUDO_MOSI_MISO    "mosi-then-miso"
#define SPI_PSEUDO_MISO_MOSI    "miso-then-mosi"
#define SPI_PSEUDO_CS_ASSERT    "cs-assert"
#define SPI_PSEUDO_CS_RELEASE   "cs-release"
#define SPI_PSEUDO_CS_NEXT      "cs-auto-next="
#define SPI_PSEUDO_IDLE         "idle"

#define I2C_HANDLER_NAME        "i2c"
#define I2C_DFLT_SAMPLERATE     SR_MHZ(10)
#define I2C_DFLT_BITRATE        SR_KHZ(400)
#define I2C_DFLT_FRAMEFMT       "addr-7bit"
#define I2C_BITTIME_SLOTS       (1 + 8 + 1 + 1)
#define I2C_BITTIME_QUANTA      6
#define I2C_ADD_IDLESLOTS       2
#define I2C_MAX_WAVELEN         (I2C_BITTIME_QUANTA * I2C_BITTIME_SLOTS + I2C_ADD_IDLESLOTS)
#define I2C_FORMAT_ADDR_7BIT    "addr-7bit"
#define I2C_FORMAT_ADDR_10BIT   "addr-10bit"
#define I2C_PSEUDO_START        "start"
#define I2C_PSEUDO_REP_START    "repeat-start"
#define I2C_PSEUDO_STOP         "stop"
#define I2C_PSEUDO_ADDR_WRITE   "addr-write="
#define I2C_PSEUDO_ADDR_READ    "addr-read="
#define I2C_PSEUDO_ACK_NEXT     "ack-next="
#define I2C_PSEUDO_ACK_ONCE     "ack-next"

enum textinput_t {
        INPUT_UNSPEC,
        INPUT_BYTES,
        INPUT_TEXT,
};

static const char *input_format_texts[] = {
        [INPUT_UNSPEC] = "from-file",
        [INPUT_BYTES] = "raw-bytes",
        [INPUT_TEXT] = "text-format",
};

struct spi_proto_context_t {
        gboolean needs_mosi, has_mosi;
        gboolean needs_miso, has_miso;
        gboolean mosi_first;
        gboolean cs_active;
        size_t auto_cs_remain;
        uint8_t mosi_byte, miso_byte;
        uint8_t mosi_fixed_value;
        gboolean mosi_is_fixed;
        uint8_t miso_fixed_value;
        gboolean miso_is_fixed;
};

struct i2c_proto_context_t {
        size_t ack_remain;
};

struct context;

struct proto_handler_t {
        const char *name;
        struct {
                uint64_t samplerate;
                uint64_t bitrate;
                const char *frame_format;
                enum textinput_t textinput;
        } dflt;
        struct {
                size_t count;
                const char **names;
        } chans;
        size_t priv_size;
        int (*check_opts)(struct context *inc);
        int (*config_frame)(struct context *inc);
        int (*proc_pseudo)(struct sr_input *in, char *text);
        int (*proc_value)(struct context *inc, uint32_t value);
        int (*get_idle_capture)(struct context *inc,
                size_t *bits, uint8_t *lvls);
        int (*get_idle_interframe)(struct context *inc,
                size_t *samples, uint8_t *lvls);
};

struct context {
        /* User provided options. */
        struct user_opts_t {
                uint64_t samplerate;
                uint64_t bitrate;
                const char *proto_name;
                const char *fmt_text;
                enum textinput_t textinput;
        } user_opts;
        /* Derived at runtime. */
        struct {
                uint64_t samplerate;
                uint64_t bitrate;
                uint64_t samples_per_bit;
                char *proto_name;
                char *fmt_text;
                enum textinput_t textinput;
                enum proto_type_t {
                        PROTO_TYPE_NONE,
                        PROTO_TYPE_UART,
                        PROTO_TYPE_SPI,
                        PROTO_TYPE_I2C,
                        PROTO_TYPE_COUNT,
                } protocol_type;
                const struct proto_handler_t *prot_hdl;
                void *prot_priv;
                union {
                        struct uart_frame_fmt_opts {
                                size_t databit_count;
                                enum {
                                        UART_PARITY_NONE,
                                        UART_PARITY_ODD,
                                        UART_PARITY_EVEN,
                                } parity_type;
                                size_t stopbit_count;
                                gboolean half_stopbit;
                                gboolean inverted;
                        } uart;
                        struct spi_frame_fmt_opts {
                                uint8_t cs_polarity;
                                size_t databit_count;
                                gboolean msb_first;
                                gboolean spi_mode_cpol;
                                gboolean spi_mode_cpha;
                        } spi;
                        struct i2c_frame_fmt_opts {
                                gboolean addr_10bit;
                        } i2c;
                } frame_format;
        } curr_opts;
        /* Module stage. Logic output channels. Session feed. */
        gboolean scanned_magic;
        gboolean has_magic;
        gboolean has_header;
        gboolean got_header;
        gboolean started;
        gboolean meta_sent;
        size_t channel_count;
        const char **channel_names;
        struct feed_queue_logic *feed_logic;
        /*
         * Internal state: Allocated space for a theoretical maximum
         * bit count. Filled in bit pattern for the current data value.
         * (Stuffing can result in varying bit counts across frames.)
         *
         * Keep the bits' width in sample numbers, as well as the bits'
         * boundaries relative to the start of the protocol frame's
         * start. Support a number of logic bits per bit time.
         *
         * Implementor's note: Due to development history terminology
         * might slip here. Strictly speaking it's "waveform sections"
         * that hold samples for a given number of cycles. "A bit" in
         * the protocol can occupy multiple of these slots to e.g. have
         * a synchronous clock, or to present setup and hold phases,
         * etc. Sample data spans several logic signal traces. You get
         * the idea ...
         */
        size_t max_frame_bits;  /* Reserved. */
        size_t top_frame_bits;  /* Currently filled. */
        struct {
                size_t mul;
                size_t div;
        } *bit_scale;           /* Quanta scaling. */
        size_t *sample_edges;
        size_t *sample_widths;
        uint8_t *sample_levels; /* Sample data, logic traces. */
        /* Common support for samples updating by manipulation. */
        struct {
                uint8_t idle_levels;
                uint8_t curr_levels;
        } samples;
        /* Internal state of the input text reader. */
        struct {
                int base;
        } read_text;
        /* Manage state across .reset() calls. Robustness. */
        struct proto_prev {
                GSList *sr_channels;
                GSList *sr_groups;
        } prev;
};

/* {{{ frame bits manipulation, waveform construction */

/*
 * Primitives to construct waveforms for a protocol frame, by sequencing
 * samples after data values were seen in the input stream. Individual
 * protocol handlers will use these common routines.
 *
 * The general idea is: The protocol handler's options parser determines
 * the frame format, and derives the maximum number of time slots needed
 * to represent the waveform. Slots can scale differintly, proportions
 * get configured once during initialization. All remaining operation
 * receives arbitrarily interleaved data values and pseudo comments, uses
 * the pre-allocated and pre-scaled time slots to construct waveforms,
 * which then get sent to the session bus as if an acquisition device
 * had captured wire traffic. For clocked signals the "coarse" timing
 * should never be an issue. Protocol handlers are free to use as many
 * time slots per bit time as they please or feel necessary.
 */

static int alloc_frame_storage(struct context *inc)
{
        size_t bits, alloc;

        if (!inc)
                return SR_ERR_ARG;

        if (!inc->max_frame_bits)
                return SR_ERR_DATA;

        inc->top_frame_bits = 0;
        bits = inc->max_frame_bits;

        alloc = bits * sizeof(inc->sample_edges[0]);
        inc->sample_edges = g_malloc0(alloc);
        alloc = bits * sizeof(inc->sample_widths[0]);
        inc->sample_widths = g_malloc0(alloc);
        alloc = bits * sizeof(inc->sample_levels[0]);
        inc->sample_levels = g_malloc0(alloc);
        if (!inc->sample_edges || !inc->sample_widths || !inc->sample_levels)
                return SR_ERR_MALLOC;

        alloc = bits * sizeof(inc->bit_scale[0]);
        inc->bit_scale = g_malloc0(alloc);
        if (!inc->bit_scale)
                return SR_ERR_MALLOC;

        return SR_OK;
}

/*
 * Assign an equal bit width to all bits in the frame. Derive the width
 * from the bitrate and the sampelrate. Protocol handlers optionally can
 * arrange for "odd bit widths" (either fractions, or multiples, or when
 * desired any rational at all). Think half-bits, or think quanta within
 * a bit time, depends on the protocol handler really.
 *
 * Implementation note: The input module assumes that the position of
 * odd length bits will never vary during frame construction. The total
 * length may vary, 'top' can be smaller than 'max' in every iteration.
 * It is assumed that frames with odd-length bits have constant layout,
 * and that stuffing protocols have same-width bits. Odd lengths also
 * can support bit time quanta, while it's assumed that these always use
 * the same layout for all generated frames. This constraint is kept in
 * the implementation, until one of the supported protocols genuinely
 * requires higher flexibility and the involved complexity and runtime
 * cost of per-samplepoint adjustment.
 */
static int assign_bit_widths(struct context *inc)
{
        const struct proto_handler_t *handler;
        int ret;
        double bit_edge, bit_time, this_bit_time;
        uint64_t bit_time_int, bit_time_prev, bit_times_total;
        size_t idx;

        if (!inc)
                return SR_ERR_ARG;

        /*
         * Run the protocol handler's optional configure routine.
         * It derives the maximum number of "bit slots" that are needed
         * to represent a protocol frame's waveform.
         */
        handler = inc->curr_opts.prot_hdl;
        if (handler && handler->config_frame) {
                ret = handler->config_frame(inc);
                if (ret != SR_OK)
                        return ret;
        }

        /* Assign bit widths to the protocol frame's bit positions. */
        bit_time = inc->curr_opts.samplerate;
        bit_time /= inc->curr_opts.bitrate;
        inc->curr_opts.samples_per_bit = bit_time + 0.5;
        sr_dbg("Samplerate %" PRIu64 ", bitrate %" PRIu64 ".",
                inc->curr_opts.samplerate, inc->curr_opts.bitrate);
        sr_dbg("Resulting bit width %.2f samples, int %" PRIu64 ".",
                bit_time, inc->curr_opts.samples_per_bit);
        bit_edge = 0.0;
        bit_time_prev = 0;
        bit_times_total = 0;
        for (idx = 0; idx < inc->max_frame_bits; idx++) {
                this_bit_time = bit_time;
                if (inc->bit_scale[idx].mul)
                        this_bit_time *= inc->bit_scale[idx].mul;
                if (inc->bit_scale[idx].div)
                        this_bit_time /= inc->bit_scale[idx].div;
                bit_edge += this_bit_time;
                bit_time_int = (uint64_t)(bit_edge + 0.5);
                inc->sample_edges[idx] = bit_time_int;
                bit_time_int -= bit_time_prev;
                inc->sample_widths[idx] = bit_time_int;
                bit_time_prev = inc->sample_edges[idx];
                bit_times_total += bit_time_int;
                sr_spew("Bit %zu, width %" PRIu64 ".", idx, bit_time_int);
        }
        sr_dbg("Maximum waveform width: %zu slots, %.2f / %zu samples.",
                inc->max_frame_bits, bit_edge, bit_times_total);

        return SR_OK;
}

/* Start accumulating the samples for a new part of the waveform. */
static int wave_clear_sequence(struct context *inc)
{

        if (!inc)
                return SR_ERR_ARG;

        inc->top_frame_bits = 0;

        return SR_OK;
}

/* Append channels' levels to the waveform for another period of samples. */
static int wave_append_pattern(struct context *inc, uint8_t sample)
{

        if (!inc)
                return SR_ERR_ARG;

        if (inc->top_frame_bits >= inc->max_frame_bits)
                return SR_ERR_DATA;

        inc->sample_levels[inc->top_frame_bits++] = sample;

        return SR_OK;
}

/* Initially assign idle levels, start the buffer from idle state. */
static void sample_buffer_preset(struct context *inc, uint8_t idle_sample)
{
        inc->samples.idle_levels = idle_sample;
        inc->samples.curr_levels = idle_sample;
}

/* Modify the samples buffer by assigning a given traces state. */
static void sample_buffer_assign(struct context *inc, uint8_t sample)
{
        inc->samples.curr_levels = sample;
}

/* Modify the samples buffer by changing individual traces. */
static void sample_buffer_modify(struct context *inc,
        uint8_t set_mask, uint8_t clr_mask)
{
        inc->samples.curr_levels |= set_mask;
        inc->samples.curr_levels &= ~clr_mask;
}

static void sample_buffer_raise(struct context *inc, uint8_t bits)
{
        return sample_buffer_modify(inc, bits, 0);
}

static void sample_buffer_clear(struct context *inc, uint8_t bits)
{
        return sample_buffer_modify(inc, 0, bits);
}

static void sample_buffer_setclr(struct context *inc,
        gboolean level, uint8_t mask)
{
        if (level)
                sample_buffer_raise(inc, mask);
        else
                sample_buffer_clear(inc, mask);
}

static void sample_buffer_toggle(struct context *inc, uint8_t mask)
{
        inc->samples.curr_levels ^= mask;
}

/* Reset current sample buffer to idle state. */
static void sample_buffer_toidle(struct context *inc)
{
        inc->samples.curr_levels = inc->samples.idle_levels;
}

/* Append the buffered samples to the waveform memory. */
static int wave_append_buffer(struct context *inc)
{
        return wave_append_pattern(inc, inc->samples.curr_levels);
}

/* Send idle level before the first generated frame and at end of capture. */
static int send_idle_capture(struct context *inc)
{
        const struct proto_handler_t *handler;
        size_t count;
        uint8_t data;
        int ret;

        handler = inc->curr_opts.prot_hdl;
        if (!handler->get_idle_capture)
                return SR_OK;

        ret = handler->get_idle_capture(inc, &count, &data);
        if (ret != SR_OK)
                return ret;
        count *= inc->curr_opts.samples_per_bit;
        while (count--) {
                ret = feed_queue_logic_submit(inc->feed_logic, &data, sizeof(data));
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

/* Optionally send idle level between protocol frames. */
static int send_idle_interframe(struct context *inc)
{
        const struct proto_handler_t *handler;
        size_t count;
        uint8_t data;
        int ret;

        handler = inc->curr_opts.prot_hdl;
        if (!handler->get_idle_interframe)
                return SR_OK;

        ret = handler->get_idle_interframe(inc, &count, &data);
        if (ret != SR_OK)
                return ret;
        while (count--) {
                ret = feed_queue_logic_submit(inc->feed_logic, &data, sizeof(data));
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

/* Forward the previously accumulated samples of the waveform. */
static int send_frame(struct sr_input *in)
{
        struct context *inc;
        size_t count, index;
        uint8_t data;

        inc = in->priv;

        for (index = 0; index < inc->top_frame_bits; index++) {
                data = inc->sample_levels[index];
                count = inc->sample_widths[index];
                while (count--) {
                        feed_queue_logic_submit(inc->feed_logic,
                                &data, sizeof(data));
                }
        }

        return SR_OK;
}

/* }}} frame bits manipulation */
/* {{{ UART protocol handler */

enum uart_pin_t {
        UART_PIN_RXTX,
};

#define UART_PINMASK_RXTX       (1UL << UART_PIN_RXTX)

/* UART specific options and frame format check. */
static int uart_check_opts(struct context *inc)
{
        struct uart_frame_fmt_opts *fmt_opts;
        const char *fmt_text;
        char **opts, *opt;
        size_t opt_count, opt_idx;
        int ret;
        unsigned long v;
        char par_text;
        char *endp;
        size_t total_bits;

        if (!inc)
                return SR_ERR_ARG;
        fmt_opts = &inc->curr_opts.frame_format.uart;

        /* Apply defaults before reading external spec. */
        memset(fmt_opts, 0, sizeof(*fmt_opts));
        fmt_opts->databit_count = 8;
        fmt_opts->parity_type = UART_PARITY_NONE;
        fmt_opts->stopbit_count = 1;
        fmt_opts->half_stopbit = FALSE;
        fmt_opts->inverted = FALSE;

        /* Provide a default UART frame format. */
        fmt_text = inc->curr_opts.fmt_text;
        if (!fmt_text || !*fmt_text)
                fmt_text = UART_DFLT_FRAMEFMT;
        sr_dbg("UART frame format: %s.", fmt_text);

        /* Parse the comma separated list of user provided options. */
        opts = g_strsplit_set(fmt_text, ", ", 0);
        opt_count = g_strv_length(opts);
        for (opt_idx = 0; opt_idx < opt_count; opt_idx++) {
                opt = opts[opt_idx];
                if (!opt || !*opt)
                        continue;
                sr_spew("UART format option: %s", opt);
                /*
                 * Check for specific keywords. Before falling back to
                 * attempting the "8n1" et al interpretation.
                 */
                if (strcmp(opt, UART_FORMAT_INVERT) == 0) {
                        fmt_opts->inverted = TRUE;
                        continue;
                }
                /* Parse an "8n1", "8e2", "7o1", or similar input spec. */
                /* Get the data bits count. */
                endp = NULL;
                ret = sr_atoul_base(opt, &v, &endp, 10);
                if (ret != SR_OK || !endp)
                        return SR_ERR_DATA;
                opt = endp;
                if (v < UART_MIN_DATABITS || v > UART_MAX_DATABITS)
                        return SR_ERR_DATA;
                fmt_opts->databit_count = v;
                /* Get the parity type. */
                par_text = tolower((int)*opt++);
                switch (par_text) {
                case 'n':
                        fmt_opts->parity_type = UART_PARITY_NONE;
                        break;
                case 'o':
                        fmt_opts->parity_type = UART_PARITY_ODD;
                        break;
                case 'e':
                        fmt_opts->parity_type = UART_PARITY_EVEN;
                        break;
                default:
                        return SR_ERR_DATA;
                }
                /* Get the stop bits count. Supports half bits too. */
                endp = NULL;
                ret = sr_atoul_base(opt, &v, &endp, 10);
                if (ret != SR_OK || !endp)
                        return SR_ERR_DATA;
                opt = endp;
                if (v > UART_MAX_STOPBITS)
                        return SR_ERR_DATA;
                fmt_opts->stopbit_count = v;
                if (g_ascii_strcasecmp(opt, ".5") == 0) {
                        opt += strlen(".5");
                        fmt_opts->half_stopbit = TRUE;
                }
                /* Incomplete consumption of input text is fatal. */
                if (*opt) {
                        sr_err("Unprocessed frame format remainder: %s.", opt);
                        return SR_ERR_DATA;
                }
                continue;
        }
        g_strfreev(opts);

        /*
         * Calculate the total number of bit times in the UART frame.
         * Add a few more bit times to the reserved space. They usually
         * are not occupied during data transmission, but are useful to
         * have for special symbols (BREAK, IDLE).
         */
        total_bits = 1; /* START bit, unconditional. */
        total_bits += fmt_opts->databit_count;
        total_bits += (fmt_opts->parity_type != UART_PARITY_NONE) ? 1 : 0;
        total_bits += fmt_opts->stopbit_count;
        total_bits += fmt_opts->half_stopbit ? 1 : 0;
        total_bits += UART_ADD_IDLEBITS;
        sr_dbg("UART frame: total bits %lu.", total_bits);
        if (total_bits > UART_MAX_WAVELEN)
                return SR_ERR_DATA;
        inc->max_frame_bits = total_bits;

        return SR_OK;
}

/*
 * Configure the frame's bit widths when not identical across the
 * complete frame. Think half STOP bits.
 * Preset the sample data for an idle bus.
 */
static int uart_config_frame(struct context *inc)
{
        struct uart_frame_fmt_opts *fmt_opts;
        size_t bit_idx;
        uint8_t sample;

        if (!inc)
                return SR_ERR_ARG;
        fmt_opts = &inc->curr_opts.frame_format.uart;

        /*
         * Position after the START bit. Advance over DATA, PARITY and
         * (full) STOP bits. Then set the trailing STOP bit to half if
         * needed. Make the trailing IDLE period after a UART frame
         * wider than regular bit times. Add an even wider IDLE period
         * which is used for special symbols.
         */
        bit_idx = 1;
        bit_idx += fmt_opts->databit_count;
        bit_idx += (fmt_opts->parity_type == UART_PARITY_NONE) ? 0 : 1;
        bit_idx += fmt_opts->stopbit_count;
        if (fmt_opts->half_stopbit) {
                sr_dbg("Setting bit index %zu to half width.", bit_idx);
                inc->bit_scale[bit_idx].div = 2;
                bit_idx++;
        }
        inc->bit_scale[bit_idx++].mul = 2;
        inc->bit_scale[bit_idx++].mul = 4;

        /* Start from idle signal levels (high when not inverted). */
        sample = 0;
        if (!fmt_opts->inverted)
                sample |= UART_PINMASK_RXTX;
        sample_buffer_preset(inc, sample);

        return SR_OK;
}

/* Create samples for a special UART frame (IDLE, BREAK). */
static int uart_write_special(struct context *inc, uint8_t level)
{
        struct uart_frame_fmt_opts *fmt_opts;
        int ret;
        size_t bits;

        if (!inc)
                return SR_ERR_ARG;
        fmt_opts = &inc->curr_opts.frame_format.uart;

        ret = wave_clear_sequence(inc);
        if (ret != SR_OK)
                return ret;

        /*
         * Set the same level for all bit slots, covering all of
         * START and DATA (and PARITY) and STOP. This allows the
         * simulation of BREAK and IDLE phases.
         */
        if (fmt_opts->inverted)
                level = !level;
        sample_buffer_setclr(inc, level, UART_PINMASK_RXTX);
        bits = 1; /* START */
        bits += fmt_opts->databit_count;
        bits += (fmt_opts->parity_type != UART_PARITY_NONE) ? 1 : 0;
        bits += fmt_opts->stopbit_count;
        bits += fmt_opts->half_stopbit ? 1 : 0;
        while (bits--) {
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
        }

        /*
         * Force a few more idle bit times. This does not affect a
         * caller requested IDLE symbol. But helps separate (i.e.
         * robustly detect) several caller requested BREAK symbols.
         * Also separates those specials from subsequent data bytes.
         */
        sample_buffer_toidle(inc);
        bits = UART_ADD_IDLEBITS;
        while (bits--) {
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

/* Process UART protocol specific pseudo comments. */
static int uart_proc_pseudo(struct sr_input *in, char *line)
{
        struct context *inc;
        char *word;
        int ret;

        inc = in->priv;

        while (line) {
                word = sr_text_next_word(line, &line);
                if (!word)
                        break;
                if (!*word)
                        continue;
                if (strcmp(word, UART_PSEUDO_BREAK) == 0) {
                        ret = uart_write_special(inc, 0);
                        if (ret != SR_OK)
                                return ret;
                        ret = send_frame(in);
                        if (ret != SR_OK)
                                return ret;
                        continue;
                }
                if (strcmp(word, UART_PSEUDO_IDLE) == 0) {
                        ret = uart_write_special(inc, 1);
                        if (ret != SR_OK)
                                return ret;
                        ret = send_frame(in);
                        if (ret != SR_OK)
                                return ret;
                        continue;
                }
                return SR_ERR_DATA;
        }

        return SR_OK;
}

/*
 * Create the UART frame's waveform for the given data value.
 *
 * In theory the protocol handler could setup START and STOP once during
 * initialization. But the overhead compares to DATA and PARITY is small.
 * And unconditional START/STOP would break the creation of BREAK and
 * IDLE frames, or complicate their construction and recovery afterwards.
 * A future implementation might as well support UART traffic on multiple
 * traces, including interleaved bidirectional communication. So let's
 * keep the implementation simple. Execution time is not a priority.
 */
static int uart_proc_value(struct context *inc, uint32_t value)
{
        struct uart_frame_fmt_opts *fmt_opts;
        int ret;
        size_t bits;
        int par_bit, data_bit;

        if (!inc)
                return SR_ERR_ARG;
        fmt_opts = &inc->curr_opts.frame_format.uart;

        ret = wave_clear_sequence(inc);
        if (ret != SR_OK)
                return ret;

        /* START bit, unconditional, always 0. */
        sample_buffer_clear(inc, UART_PINMASK_RXTX);
        if (fmt_opts->inverted)
                sample_buffer_toggle(inc, UART_PINMASK_RXTX);
        ret = wave_append_buffer(inc);

        /* DATA bits. Track parity here (unconditionally). */
        par_bit = 0;
        bits = fmt_opts->databit_count;
        while (bits--) {
                data_bit = value & 0x01;
                value >>= 1;
                par_bit ^= data_bit;
                if (fmt_opts->inverted)
                        data_bit = !data_bit;
                sample_buffer_setclr(inc, data_bit, UART_PINMASK_RXTX);
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
        }

        /* PARITY bit. Emission is optional. */
        switch (fmt_opts->parity_type) {
        case UART_PARITY_ODD:
                data_bit = par_bit ? 0 : 1;
                bits = 1;
                break;
        case UART_PARITY_EVEN:
                data_bit = par_bit ? 1 : 0;
                bits = 1;
                break;
        default:
                data_bit = 0;
                bits = 0;
                break;
        }
        if (bits) {
                if (fmt_opts->inverted)
                        data_bit = !data_bit;
                sample_buffer_setclr(inc, data_bit, UART_PINMASK_RXTX);
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
        }

        /* STOP bits. Optional. */
        sample_buffer_raise(inc, UART_PINMASK_RXTX);
        if (fmt_opts->inverted)
                sample_buffer_toggle(inc, UART_PINMASK_RXTX);
        bits = fmt_opts->stopbit_count;
        bits += fmt_opts->half_stopbit ? 1 : 0;
        while (bits--) {
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
        }

        /*
         * Force some idle time after the UART frame.
         * A little shorter than for special symbols.
         */
        sample_buffer_toidle(inc);
        bits = UART_ADD_IDLEBITS - 1;
        while (bits--) {
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

/* Start/end the logic trace with a few bit times of idle level. */
static int uart_get_idle_capture(struct context *inc,
        size_t *bitcount, uint8_t *sample)
{

        /* Describe a UART frame's length of idle level. */
        if (bitcount)
                *bitcount = inc->max_frame_bits;
        if (sample)
                *sample = inc->samples.idle_levels;
        return SR_OK;
}

/* Arrange for a few samples of idle level between UART frames. */
static int uart_get_idle_interframe(struct context *inc,
        size_t *samplecount, uint8_t *sample)
{

        (void)inc;

        /*
         * Regular waveform creation for UART frames already includes
         * padding between UART frames. That is why we don't need to
         * add extra inter-frame samples. Yet prepare the implementation
         * for when we need or want to add a few more idle samples.
         */
        if (samplecount) {
                *samplecount = inc->curr_opts.samples_per_bit;
                *samplecount *= 0;
        }
        if (sample)
                *sample = inc->samples.idle_levels;
        return SR_OK;
}

/* }}} UART protocol handler */
/* {{{ SPI protocol handler */

enum spi_pin_t {
        SPI_PIN_SCK,
        SPI_PIN_MISO,
        SPI_PIN_MOSI,
        SPI_PIN_CS,
        SPI_PIN_COUNT,
};

#define SPI_PINMASK_SCK         (1UL << SPI_PIN_SCK)
#define SPI_PINMASK_MISO        (1UL << SPI_PIN_MISO)
#define SPI_PINMASK_MOSI        (1UL << SPI_PIN_MOSI)
#define SPI_PINMASK_CS          (1UL << SPI_PIN_CS)

/* "Forget" data which was seen before. */
static void spi_value_discard_prev_data(struct context *inc)
{
        struct spi_proto_context_t *incs;

        incs = inc->curr_opts.prot_priv;
        incs->has_mosi = !incs->needs_mosi;
        incs->has_miso = !incs->needs_miso;
        incs->mosi_byte = 0;
        incs->miso_byte = 0;
}

/* Check whether all required values for the byte time were seen. */
static gboolean spi_value_is_bytes_complete(struct context *inc)
{
        struct spi_proto_context_t *incs;

        incs = inc->curr_opts.prot_priv;

        return incs->has_mosi && incs->has_miso;
}

/* Arrange for data reception before waveform emission. */
static void spi_pseudo_data_order(struct context *inc,
        gboolean needs_mosi, gboolean needs_miso, gboolean mosi_first)
{
        struct spi_proto_context_t *incs;

        incs = inc->curr_opts.prot_priv;

        incs->needs_mosi = needs_mosi;
        incs->needs_miso = needs_miso;
        incs->mosi_first = mosi_first;
        if (needs_mosi)
                incs->mosi_is_fixed = FALSE;
        if (needs_miso)
                incs->miso_is_fixed = FALSE;
        spi_value_discard_prev_data(inc);
}

static void spi_pseudo_mosi_fixed(struct context *inc, uint8_t v)
{
        struct spi_proto_context_t *incs;

        incs = inc->curr_opts.prot_priv;

        incs->mosi_fixed_value = v;
        incs->mosi_is_fixed = TRUE;
}

static void spi_pseudo_miso_fixed(struct context *inc, uint8_t v)
{
        struct spi_proto_context_t *incs;

        incs = inc->curr_opts.prot_priv;

        incs->miso_fixed_value = v;
        incs->miso_is_fixed = TRUE;
}

/* Explicit CS control. Arrange for next CS level, track state to keep it. */
static void spi_pseudo_select_control(struct context *inc, gboolean cs_active)
{
        struct spi_frame_fmt_opts *fmt_opts;
        struct spi_proto_context_t *incs;
        uint8_t cs_level, sck_level;

        fmt_opts = &inc->curr_opts.frame_format.spi;
        incs = inc->curr_opts.prot_priv;

        /* Track current "CS active" state. */
        incs->cs_active = cs_active;
        incs->auto_cs_remain = 0;

        /* Derive current "CS pin level". Update sample data buffer. */
        cs_level = 1 - fmt_opts->cs_polarity;
        if (incs->cs_active)
                cs_level = fmt_opts->cs_polarity;
        sample_buffer_setclr(inc, cs_level, SPI_PINMASK_CS);

        /* Derive the idle "SCK level" from the SPI mode's CPOL. */
        sck_level = fmt_opts->spi_mode_cpol ? 1 : 0;
        sample_buffer_setclr(inc, sck_level, SPI_PINMASK_SCK);
}

/* Arrange for automatic CS release after transfer length. Starts the phase. */
static void spi_pseudo_auto_select(struct context *inc, size_t length)
{
        struct spi_frame_fmt_opts *fmt_opts;
        struct spi_proto_context_t *incs;
        uint8_t cs_level;

        fmt_opts = &inc->curr_opts.frame_format.spi;
        incs = inc->curr_opts.prot_priv;

        /* Track current "CS active" state. */
        incs->cs_active = TRUE;
        incs->auto_cs_remain = length;

        /* Derive current "CS pin level". Update sample data buffer. */
        cs_level = 1 - fmt_opts->cs_polarity;
        if (incs->cs_active)
                cs_level = fmt_opts->cs_polarity;
        sample_buffer_setclr(inc, cs_level, SPI_PINMASK_CS);
}

/* Check for automatic CS release. Decrements, yields result. No action here. */
static gboolean spi_auto_select_ends(struct context *inc)
{
        struct spi_proto_context_t *incs;

        incs = inc->curr_opts.prot_priv;
        if (!incs->auto_cs_remain)
                return FALSE;

        incs->auto_cs_remain--;
        if (incs->auto_cs_remain)
                return FALSE;

        /*
         * DON'T release CS yet. The last data is yet to get sent.
         * Keep the current "CS pin level", but tell the caller that
         * CS will be released after transmission of that last data.
         */
        return TRUE;
}

/* Update for automatic CS release after last data was sent. */
static void spi_auto_select_update(struct context *inc)
{
        struct spi_frame_fmt_opts *fmt_opts;
        struct spi_proto_context_t *incs;
        uint8_t cs_level;

        fmt_opts = &inc->curr_opts.frame_format.spi;
        incs = inc->curr_opts.prot_priv;

        /* Track current "CS active" state. */
        incs->cs_active = FALSE;
        incs->auto_cs_remain = 0;

        /* Derive current "CS pin level". Map to bits pattern. */
        cs_level = 1 - fmt_opts->cs_polarity;
        sample_buffer_setclr(inc, cs_level, SPI_PINMASK_CS);
}

/*
 * Create the waveforms for one SPI byte. Also cover idle periods:
 * Dummy/padding bytes within a frame with clock. Idle lines outside
 * of frames without clock edges. Optional automatic CS release with
 * resulting inter-frame gap.
 */
static int spi_write_frame_patterns(struct context *inc,
        gboolean idle, gboolean cs_release)
{
        struct spi_proto_context_t *incs;
        struct spi_frame_fmt_opts *fmt_opts;
        int ret;
        uint8_t mosi_bit, miso_bit;
        size_t bits;

        if (!inc)
                return SR_ERR_ARG;
        incs = inc->curr_opts.prot_priv;
        fmt_opts = &inc->curr_opts.frame_format.spi;

        /* Apply fixed values before drawing the waveform. */
        if (incs->mosi_is_fixed)
                incs->mosi_byte = incs->mosi_fixed_value;
        if (incs->miso_is_fixed)
                incs->miso_byte = incs->miso_fixed_value;

        ret = wave_clear_sequence(inc);
        if (ret != SR_OK)
                return ret;

        /* Provide two samples with idle SCK and current CS. */
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /*
         * Provide two samples per DATABIT time slot. Keep CS as is.
         * Toggle SCK according to CPHA specs. Shift out MOSI and MISO
         * in the configured order.
         *
         * Force dummy MOSI/MISO bits for idle bytes within a frame.
         * Skip SCK toggling for idle "frames" outside of active CS.
         */
        bits = fmt_opts->databit_count;
        while (bits--) {
                /*
                 * First half-period. Provide next DATABIT values.
                 * Toggle SCK here when CPHA is set.
                 */
                if (fmt_opts->msb_first) {
                        mosi_bit = incs->mosi_byte & 0x80;
                        miso_bit = incs->miso_byte & 0x80;
                        incs->mosi_byte <<= 1;
                        incs->miso_byte <<= 1;
                } else {
                        mosi_bit = incs->mosi_byte & 0x01;
                        miso_bit = incs->miso_byte & 0x01;
                        incs->mosi_byte >>= 1;
                        incs->miso_byte >>= 1;
                }
                if (incs->cs_active && !idle) {
                        sample_buffer_setclr(inc, mosi_bit, SPI_PINMASK_MOSI);
                        sample_buffer_setclr(inc, miso_bit, SPI_PINMASK_MISO);
                }
                if (fmt_opts->spi_mode_cpha && incs->cs_active)
                        sample_buffer_toggle(inc, SPI_PINMASK_SCK);
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
                /* Second half-period. Keep DATABIT, toggle SCK. */
                if (incs->cs_active)
                        sample_buffer_toggle(inc, SPI_PINMASK_SCK);
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
                /* Toggle SCK again unless done above due to CPHA. */
                if (!fmt_opts->spi_mode_cpha && incs->cs_active)
                        sample_buffer_toggle(inc, SPI_PINMASK_SCK);
        }

        /*
         * Hold the waveform for another sample period. Happens to
         * also communicate the most recent SCK pin level.
         *
         * Optionally auto-release the CS signal after sending the
         * last data byte. Update the CS trace's level. Add another
         * (long) bit slot to present an inter-frame gap.
         */
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;
        if (cs_release)
                spi_auto_select_update(inc);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;
        if (cs_release) {
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

/* SPI specific options and frame format check. */
static int spi_check_opts(struct context *inc)
{
        struct spi_frame_fmt_opts *fmt_opts;
        const char *fmt_text;
        char **opts, *opt;
        size_t opt_count, opt_idx;
        int ret;
        unsigned long v;
        char *endp;
        size_t total_bits;

        if (!inc)
                return SR_ERR_ARG;
        fmt_opts = &inc->curr_opts.frame_format.spi;

        /* Setup defaults before reading external specs. */
        fmt_opts->cs_polarity = 0;
        fmt_opts->databit_count = SPI_MIN_DATABITS;
        fmt_opts->msb_first = TRUE;
        fmt_opts->spi_mode_cpol = FALSE;
        fmt_opts->spi_mode_cpha = FALSE;

        /* Provide a default SPI frame format. */
        fmt_text = inc->curr_opts.fmt_text;
        if (!fmt_text || !*fmt_text)
                fmt_text = SPI_DFLT_FRAMEFMT;
        sr_dbg("SPI frame format: %s.", fmt_text);

        /* Accept comma separated key=value pairs of specs. */
        opts = g_strsplit_set(fmt_text, ", ", 0);
        opt_count = g_strv_length(opts);
        for (opt_idx = 0; opt_idx < opt_count; opt_idx++) {
                opt = opts[opt_idx];
                if (!opt || !*opt)
                        continue;
                sr_spew("SPI format option: %s.", opt);
                if (strcmp(opt, SPI_FORMAT_CS_LOW) == 0) {
                        sr_spew("SPI chip select: low.");
                        fmt_opts->cs_polarity = 0;
                        continue;
                }
                if (strcmp(opt, SPI_FORMAT_CS_HIGH) == 0) {
                        sr_spew("SPI chip select: high.");
                        fmt_opts->cs_polarity = 1;
                        continue;
                }
                if (g_str_has_prefix(opt, SPI_FORMAT_DATA_BITS)) {
                        opt += strlen(SPI_FORMAT_DATA_BITS);
                        endp = NULL;
                        ret = sr_atoul_base(opt, &v, &endp, 10);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("SPI word size: %lu.", v);
                        if (v < SPI_MIN_DATABITS || v > SPI_MAX_DATABITS)
                                return SR_ERR_ARG;
                        fmt_opts->databit_count = v;
                        continue;
                }
                if (g_str_has_prefix(opt, SPI_FORMAT_SPI_MODE)) {
                        opt += strlen(SPI_FORMAT_SPI_MODE);
                        endp = NULL;
                        ret = sr_atoul_base(opt, &v, &endp, 10);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("SPI mode: %lu.", v);
                        if (v > 3)
                                return SR_ERR_ARG;
                        fmt_opts->spi_mode_cpol = v & (1UL << 1);
                        fmt_opts->spi_mode_cpha = v & (1UL << 0);
                        continue;
                }
                if (g_str_has_prefix(opt, SPI_FORMAT_MODE_CPOL)) {
                        opt += strlen(SPI_FORMAT_MODE_CPOL);
                        endp = NULL;
                        ret = sr_atoul_base(opt, &v, &endp, 10);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("SPI cpol: %lu.", v);
                        if (v > 1)
                                return SR_ERR_ARG;
                        fmt_opts->spi_mode_cpol = !!v;
                        continue;
                }
                if (g_str_has_prefix(opt, SPI_FORMAT_MODE_CPHA)) {
                        opt += strlen(SPI_FORMAT_MODE_CPHA);
                        endp = NULL;
                        ret = sr_atoul_base(opt, &v, &endp, 10);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("SPI cpha: %lu.", v);
                        if (v > 1)
                                return SR_ERR_ARG;
                        fmt_opts->spi_mode_cpha = !!v;
                        continue;
                }
                if (strcmp(opt, SPI_FORMAT_MSB_FIRST) == 0) {
                        sr_spew("SPI endianess: MSB first.");
                        fmt_opts->msb_first = 1;
                        continue;
                }
                if (strcmp(opt, SPI_FORMAT_LSB_FIRST) == 0) {
                        sr_spew("SPI endianess: LSB first.");
                        fmt_opts->msb_first = 0;
                        continue;
                }
                return SR_ERR_ARG;
        }
        g_strfreev(opts);

        /*
         * Get the total bit count. Add slack for CS control, and to
         * visually separate bytes in frames. Multiply data bit count
         * for the creation of two clock half-periods.
         */
        total_bits = 2;
        total_bits += 2 * fmt_opts->databit_count;
        total_bits += 3;

        sr_dbg("SPI frame: total bits %lu.", total_bits);
        if (total_bits > SPI_MAX_WAVELEN)
                return SR_ERR_DATA;
        inc->max_frame_bits = total_bits;

        return SR_OK;
}

/*
 * Setup half-width slots for the two halves of a DATABIT time. Keep
 * the "decoration" (CS control) at full width. Setup a rather long
 * last slot for potential inter-frame gaps.
 *
 * Preset CS and SCK from their idle levels according to the frame format
 * configuration. So that idle times outside of SPI transfers are covered
 * with simple logic despite the protocol's flexibility.
 */
static int spi_config_frame(struct context *inc)
{
        struct spi_frame_fmt_opts *fmt_opts;
        size_t bit_idx, bit_count;

        if (!inc)
                return SR_ERR_ARG;
        fmt_opts = &inc->curr_opts.frame_format.spi;

        /* Configure DATABIT positions for half width (for clock period). */
        bit_idx = 2;
        bit_count = fmt_opts->databit_count;
        while (bit_count--) {
                inc->bit_scale[bit_idx + 0].div = 2;
                inc->bit_scale[bit_idx + 1].div = 2;
                bit_idx += 2;
        }
        bit_idx += 2;
        inc->bit_scale[bit_idx].mul = fmt_opts->databit_count;

        /*
         * Seed the protocol handler's internal state before seeing
         * first data values. To properly cover idle periods, and to
         * operate correctly in the absence of pseudo comments.
         *
         * Use internal helpers for sample data initialization. Then
         * grab the resulting pin levels as the idle state.
         */
        spi_value_discard_prev_data(inc);
        spi_pseudo_data_order(inc, TRUE, TRUE, TRUE);
        spi_pseudo_select_control(inc, FALSE);
        sample_buffer_preset(inc, inc->samples.curr_levels);

        return SR_OK;
}

/*
 * Process protocol dependent pseudo comments. Can affect future frame
 * construction and submission, or can immediately emit "inter frame"
 * bit patterns like chip select control.
 */
static int spi_proc_pseudo(struct sr_input *in, char *line)
{
        struct context *inc;
        char *word, *endp;
        int ret;
        unsigned long v;

        inc = in->priv;

        while (line) {
                word = sr_text_next_word(line, &line);
                if (!word)
                        break;
                if (!*word)
                        continue;
                if (strcmp(word, SPI_PSEUDO_MOSI_ONLY) == 0) {
                        sr_spew("SPI pseudo: MOSI only");
                        spi_pseudo_data_order(inc, TRUE, FALSE, TRUE);
                        continue;
                }
                if (g_str_has_prefix(word, SPI_PSEUDO_MOSI_FIXED)) {
                        word += strlen(SPI_PSEUDO_MOSI_FIXED);
                        endp = NULL;
                        ret = sr_atoul_base(word, &v, &endp, inc->read_text.base);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("SPI pseudo: MOSI fixed %lu", v);
                        spi_pseudo_mosi_fixed(inc, v);
                        continue;
                }
                if (strcmp(word, SPI_PSEUDO_MISO_ONLY) == 0) {
                        sr_spew("SPI pseudo: MISO only");
                        spi_pseudo_data_order(inc, FALSE, TRUE, FALSE);
                        continue;
                }
                if (g_str_has_prefix(word, SPI_PSEUDO_MISO_FIXED)) {
                        word += strlen(SPI_PSEUDO_MISO_FIXED);
                        endp = NULL;
                        ret = sr_atoul_base(word, &v, &endp, inc->read_text.base);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("SPI pseudo: MISO fixed %lu", v);
                        spi_pseudo_miso_fixed(inc, v);
                        continue;
                }
                if (strcmp(word, SPI_PSEUDO_MOSI_MISO) == 0) {
                        sr_spew("SPI pseudo: MOSI then MISO");
                        spi_pseudo_data_order(inc, TRUE, TRUE, TRUE);
                        continue;
                }
                if (strcmp(word, SPI_PSEUDO_MISO_MOSI) == 0) {
                        sr_spew("SPI pseudo: MISO then MOSI");
                        spi_pseudo_data_order(inc, TRUE, TRUE, FALSE);
                        continue;
                }
                if (strcmp(word, SPI_PSEUDO_CS_ASSERT) == 0) {
                        sr_spew("SPI pseudo: CS assert");
                        spi_pseudo_select_control(inc, TRUE);
                        continue;
                }
                if (strcmp(word, SPI_PSEUDO_CS_RELEASE) == 0) {
                        sr_spew("SPI pseudo: CS release");
                        /* Release CS. Force IDLE to display the pin change. */
                        spi_pseudo_select_control(inc, FALSE);
                        ret = spi_write_frame_patterns(inc, TRUE, FALSE);
                        if (ret != SR_OK)
                                return ret;
                        ret = send_frame(in);
                        if (ret != SR_OK)
                                return ret;
                        continue;
                }
                if (g_str_has_prefix(word, SPI_PSEUDO_CS_NEXT)) {
                        word += strlen(SPI_PSEUDO_CS_NEXT);
                        endp = NULL;
                        ret = sr_atoul_base(word, &v, &endp, 0);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("SPI pseudo: CS auto next %lu", v);
                        spi_pseudo_auto_select(inc, v);
                        continue;
                }
                if (strcmp(word, SPI_PSEUDO_IDLE) == 0) {
                        sr_spew("SPI pseudo: idle");
                        ret = spi_write_frame_patterns(inc, TRUE, FALSE);
                        if (ret != SR_OK)
                                return ret;
                        ret = send_frame(in);
                        if (ret != SR_OK)
                                return ret;
                        continue;
                }
                return SR_ERR_DATA;
        }

        return SR_OK;
}

/*
 * Create the frame's waveform for the given data value. For bidirectional
 * communication multiple routine invocations accumulate data bits, while
 * the last invocation completes the frame preparation.
 */
static int spi_proc_value(struct context *inc, uint32_t value)
{
        struct spi_proto_context_t *incs;
        gboolean taken;
        int ret;
        gboolean auto_cs_end;

        if (!inc)
                return SR_ERR_ARG;
        incs = inc->curr_opts.prot_priv;

        /*
         * Discard previous data when we get here after having completed
         * a previous frame. This roundtrip from filling in to clearing
         * is required to have the caller emit the waveform that we have
         * constructed after receiving data values.
         */
        if (spi_value_is_bytes_complete(inc)) {
                sr_spew("SPI value: discarding previous data");
                spi_value_discard_prev_data(inc);
        }

        /*
         * Consume the caller provided value. Apply data in the order
         * that was configured before.
         */
        taken = FALSE;
        if (!taken && incs->mosi_first && !incs->has_mosi) {
                sr_spew("SPI value: grabbing MOSI value");
                incs->mosi_byte = value & 0xff;
                incs->has_mosi = TRUE;
                taken = TRUE;
        }
        if (!taken && !incs->has_miso) {
                sr_spew("SPI value: grabbing MISO value");
                incs->miso_byte = value & 0xff;
                incs->has_miso = TRUE;
        }
        if (!taken && !incs->mosi_first && !incs->has_mosi) {
                sr_spew("SPI value: grabbing MOSI value");
                incs->mosi_byte = value & 0xff;
                incs->has_mosi = TRUE;
                taken = TRUE;
        }

        /*
         * Generate the waveform when all data values in a byte time
         * were seen (all MOSI and MISO including their being optional
         * or fixed values).
         *
         * Optionally automatically release CS after a given number of
         * data bytes, when requested by the input stream.
         */
        if (!spi_value_is_bytes_complete(inc)) {
                sr_spew("SPI value: need more values");
                return +1;
        }
        auto_cs_end = spi_auto_select_ends(inc);
        sr_spew("SPI value: frame complete, drawing, auto CS %d", auto_cs_end);
        ret = spi_write_frame_patterns(inc, FALSE, auto_cs_end);
        if (ret != SR_OK)
                return ret;
        return 0;
}

/* Start/end the logic trace with a few bit times of idle level. */
static int spi_get_idle_capture(struct context *inc,
        size_t *bitcount, uint8_t *sample)
{

        /* Describe one byte time of idle level. */
        if (bitcount)
                *bitcount = inc->max_frame_bits;
        if (sample)
                *sample = inc->samples.idle_levels;
        return SR_OK;
}

/* Arrange for a few samples of idle level between UART frames. */
static int spi_get_idle_interframe(struct context *inc,
        size_t *samplecount, uint8_t *sample)
{

        /* Describe four bit times, re-use most recent pin levels. */
        if (samplecount) {
                *samplecount = inc->curr_opts.samples_per_bit;
                *samplecount *= 4;
        }
        if (sample)
                *sample = inc->samples.curr_levels;
        return SR_OK;
}

/* }}} SPI protocol handler */
/* {{{ I2C protocol handler */

enum i2c_pin_t {
        I2C_PIN_SCL,
        I2C_PIN_SDA,
        I2C_PIN_COUNT,
};

#define I2C_PINMASK_SCL         (1UL << I2C_PIN_SCL)
#define I2C_PINMASK_SDA         (1UL << I2C_PIN_SDA)

/* Arrange for automatic ACK for a given number of data bytes. */
static void i2c_auto_ack_start(struct context *inc, size_t count)
{
        struct i2c_proto_context_t *incs;

        incs = inc->curr_opts.prot_priv;
        incs->ack_remain = count;
}

/* Check whether automatic ACK is still applicable. Decrements. */
static gboolean i2c_auto_ack_avail(struct context *inc)
{
        struct i2c_proto_context_t *incs;

        incs = inc->curr_opts.prot_priv;
        if (!incs->ack_remain)
                return FALSE;

        if (incs->ack_remain--)
                return TRUE;
        return FALSE;
}

/* Occupy the slots where START/STOP would be. Keep current levels. */
static int i2c_write_nothing(struct context *inc)
{
        size_t reps;
        int ret;

        reps = I2C_BITTIME_QUANTA;
        while (reps--) {
                ret = wave_append_buffer(inc);
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

/*
 * Construct a START symbol. Occupy a full bit time in the waveform.
 * Can also be used as REPEAT START due to its conservative signalling.
 *
 * Definition of START: Falling SDA while SCL is high.
 * Repeated START: A START without a preceeding STOP.
 */
static int i2c_write_start(struct context *inc)
{
        int ret;

        /*
         * Important! Assumes that either SDA and SCL already are
         * high (true when we come here from an idle bus). Or that
         * SCL already is low before SDA potentially changes (this
         * is true for preceeding START or REPEAT START or DATA BIT
         * symbols).
         *
         * Implementation detail: This START implementation can be
         * used for REPEAT START as well. The signalling sequence is
         * conservatively done.
         */

        /* Enforce SDA high. */
        sample_buffer_raise(inc, I2C_PINMASK_SDA);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Enforce SCL high. */
        sample_buffer_raise(inc, I2C_PINMASK_SCL);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Keep high SCL and high SDA for another period. */
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Falling SDA while SCL is high. */
        sample_buffer_clear(inc, I2C_PINMASK_SDA);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Keep high SCL and low SDA for one more period. */
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /*
         * Lower SCL here already. Which kind of prepares DATA BIT
         * times (fits a data bit's start condition, does not harm).
         * Improves back to back START and (repeated) START as well
         * as STOP without preceeding DATA BIT.
         */
        sample_buffer_clear(inc, I2C_PINMASK_SCL);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        return SR_OK;
}

/*
 * Construct a STOP symbol. Occupy a full bit time in the waveform.
 *
 * Definition of STOP: Rising SDA while SCL is high.
 */
static int i2c_write_stop(struct context *inc)
{
        int ret;

        /* Enforce SCL low before SDA changes. */
        sample_buffer_clear(inc, I2C_PINMASK_SCL);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Enforce SDA low (can change while SCL is low). */
        sample_buffer_clear(inc, I2C_PINMASK_SDA);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Rise SCL high while SDA is low. */
        sample_buffer_raise(inc, I2C_PINMASK_SCL);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Keep high SCL and low SDA for another period. */
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Rising SDA. */
        sample_buffer_raise(inc, I2C_PINMASK_SDA);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Keep high SCL and high SDA for one more periods. */
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        return SR_OK;
}

/*
 * Construct a DATA BIT symbol. Occupy a full bit time in the waveform.
 *
 * SDA can change while SCL is low. SDA must be kept while SCL is high.
 */
static int i2c_write_bit(struct context *inc, uint8_t value)
{
        int ret;

        /* Enforce SCL low before SDA changes. */
        sample_buffer_clear(inc, I2C_PINMASK_SCL);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Setup SDA pin level while SCL is low. */
        sample_buffer_setclr(inc, value, I2C_PINMASK_SDA);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Rising SCL, starting SDA validity. */
        sample_buffer_raise(inc, I2C_PINMASK_SCL);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Keep SDA level with high SCL for two more periods. */
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        /* Falling SCL, terminates SDA validity. */
        sample_buffer_clear(inc, I2C_PINMASK_SCL);
        ret = wave_append_buffer(inc);
        if (ret != SR_OK)
                return ret;

        return SR_OK;
}

/* Create a waveform for the eight data bits and the ACK/NAK slot. */
static int i2c_write_byte(struct context *inc, uint8_t value, uint8_t ack)
{
        size_t bit_mask, bit_value;
        int ret;

        /* Keep an empty bit time before the data byte. */
        ret = i2c_write_nothing(inc);
        if (ret != SR_OK)
                return ret;

        /* Send 8 data bits, MSB first. */
        bit_mask = 0x80;
        while (bit_mask) {
                bit_value = value & bit_mask;
                bit_mask >>= 1;
                ret = i2c_write_bit(inc, bit_value);
                if (ret != SR_OK)
                        return ret;
        }

        /* Send ACK, which is low active. NAK is recessive, high. */
        bit_value = !ack;
        ret = i2c_write_bit(inc, bit_value);
        if (ret != SR_OK)
                return ret;

        /* Keep an empty bit time after the data byte. */
        ret = i2c_write_nothing(inc);
        if (ret != SR_OK)
                return ret;

        return SR_OK;
}

/* Send slave address (7bit or 10bit, 1 or 2 bytes). Consumes one ACK. */
static int i2c_send_address(struct sr_input *in, uint16_t addr, gboolean read)
{
        struct context *inc;
        struct i2c_frame_fmt_opts *fmt_opts;
        gboolean with_ack;
        uint8_t addr_byte, rw_bit;
        int ret;

        inc = in->priv;
        fmt_opts = &inc->curr_opts.frame_format.i2c;

        addr &= 0x3ff;
        rw_bit = read ? 1 : 0;
        with_ack = i2c_auto_ack_avail(inc);

        if (!fmt_opts->addr_10bit) {
                /* 7 bit address, the simple case. */
                addr_byte = addr & 0x7f;
                addr_byte <<= 1;
                addr_byte |= rw_bit;
                sr_spew("I2C 7bit address, byte 0x%" PRIx8, addr_byte);
                ret = wave_clear_sequence(inc);
                if (ret != SR_OK)
                        return ret;
                ret = i2c_write_byte(inc, addr_byte, with_ack);
                if (ret != SR_OK)
                        return ret;
                ret = send_frame(in);
                if (ret != SR_OK)
                        return ret;
        } else {
                /*
                 * 10 bit address, need to write two bytes: First byte
                 * with prefix 0xf0, upper most 2 address bits, and R/W.
                 * Second byte with lower 8 address bits.
                 */
                addr_byte = addr >> 8;
                addr_byte <<= 1;
                addr_byte |= 0xf0;
                addr_byte |= rw_bit;
                sr_spew("I2C 10bit address, byte 0x%" PRIx8, addr_byte);
                ret = wave_clear_sequence(inc);
                if (ret != SR_OK)
                        return ret;
                ret = i2c_write_byte(inc, addr_byte, with_ack);
                if (ret != SR_OK)
                        return ret;
                ret = send_frame(in);
                if (ret != SR_OK)
                        return ret;

                addr_byte = addr & 0xff;
                sr_spew("I2C 10bit address, byte 0x%" PRIx8, addr_byte);
                ret = wave_clear_sequence(inc);
                if (ret != SR_OK)
                        return ret;
                ret = i2c_write_byte(inc, addr_byte, with_ack);
                if (ret != SR_OK)
                        return ret;
                ret = send_frame(in);
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

/* I2C specific options and frame format check. */
static int i2c_check_opts(struct context *inc)
{
        struct i2c_frame_fmt_opts *fmt_opts;
        const char *fmt_text;
        char **opts, *opt;
        size_t opt_count, opt_idx;
        size_t total_bits;

        if (!inc)
                return SR_ERR_ARG;
        fmt_opts = &inc->curr_opts.frame_format.i2c;

        /* Apply defaults before reading external specs. */
        memset(fmt_opts, 0, sizeof(*fmt_opts));
        fmt_opts->addr_10bit = FALSE;

        /* Provide a default I2C frame format. */
        fmt_text = inc->curr_opts.fmt_text;
        if (!fmt_text || !*fmt_text)
                fmt_text = I2C_DFLT_FRAMEFMT;
        sr_dbg("I2C frame format: %s.", fmt_text);

        /* Accept comma separated key=value pairs of specs. */
        opts = g_strsplit_set(fmt_text, ", ", 0);
        opt_count = g_strv_length(opts);
        for (opt_idx = 0; opt_idx < opt_count; opt_idx++) {
                opt = opts[opt_idx];
                if (!opt || !*opt)
                        continue;
                sr_spew("I2C format option: %s.", opt);
                if (strcmp(opt, I2C_FORMAT_ADDR_7BIT) == 0) {
                        sr_spew("I2C address: 7 bit");
                        fmt_opts->addr_10bit = FALSE;
                        continue;
                }
                if (strcmp(opt, I2C_FORMAT_ADDR_10BIT) == 0) {
                        sr_spew("I2C address: 10 bit");
                        fmt_opts->addr_10bit = TRUE;
                        continue;
                }
                return SR_ERR_ARG;
        }
        g_strfreev(opts);

        /* Get the total slot count. Leave plenty room for convenience. */
        total_bits = 0;
        total_bits += I2C_BITTIME_SLOTS;
        total_bits *= I2C_BITTIME_QUANTA;
        total_bits += I2C_ADD_IDLESLOTS;

        sr_dbg("I2C frame: total bits %lu.", total_bits);
        if (total_bits > I2C_MAX_WAVELEN)
                return SR_ERR_DATA;
        inc->max_frame_bits = total_bits;

        return SR_OK;
}

/*
 * Don't bother with wide and narrow slots, just assume equal size for
 * them all. Edges will occupy exactly one sample, then levels are kept.
 * This protocol handler's oversampling should be sufficient for decoders
 * to extract the content from generated waveforms.
 *
 * Start with high levels on SCL and SDA for an idle bus condition.
 */
static int i2c_config_frame(struct context *inc)
{
        struct i2c_proto_context_t *incs;
        size_t bit_idx;
        uint8_t sample;

        if (!inc)
                return SR_ERR_ARG;
        incs = inc->curr_opts.prot_priv;

        memset(incs, 0, sizeof(*incs));
        incs->ack_remain = 0;

        /*
         * Adjust all time slots since they represent a smaller quanta
         * of an I2C bit time.
         */
        for (bit_idx = 0; bit_idx < inc->max_frame_bits; bit_idx++) {
                inc->bit_scale[bit_idx].div = I2C_BITTIME_QUANTA;
        }

        sample = 0;
        sample |= I2C_PINMASK_SCL;
        sample |= I2C_PINMASK_SDA;
        sample_buffer_preset(inc, sample);

        return SR_OK;
}

/*
 * Process protocol dependent pseudo comments. Can affect future frame
 * construction and submission, or can immediately emit "inter frame"
 * bit patterns like START/STOP control. Use wide waveforms for these
 * transfer controls, put the special symbol nicely centered. Supports
 * users during interactive exploration of generated waveforms.
 */
static int i2c_proc_pseudo(struct sr_input *in, char *line)
{
        struct context *inc;
        char *word, *endp;
        int ret;
        unsigned long v;
        size_t bits;

        inc = in->priv;

        while (line) {
                word = sr_text_next_word(line, &line);
                if (!word)
                        break;
                if (!*word)
                        continue;
                sr_spew("I2C pseudo: word %s", word);
                if (strcmp(word, I2C_PSEUDO_START) == 0) {
                        sr_spew("I2C pseudo: send START");
                        ret = wave_clear_sequence(inc);
                        if (ret != SR_OK)
                                return ret;
                        bits = I2C_BITTIME_SLOTS / 2;
                        while (bits--) {
                                ret = i2c_write_nothing(inc);
                                if (ret != SR_OK)
                                        return ret;
                        }
                        ret = i2c_write_start(inc);
                        if (ret != SR_OK)
                                return ret;
                        bits = I2C_BITTIME_SLOTS / 2;
                        while (bits--) {
                                ret = i2c_write_nothing(inc);
                                if (ret != SR_OK)
                                        return ret;
                        }
                        ret = send_frame(in);
                        if (ret != SR_OK)
                                return ret;
                        continue;
                }
                if (strcmp(word, I2C_PSEUDO_REP_START) == 0) {
                        sr_spew("I2C pseudo: send REPEAT START");
                        ret = wave_clear_sequence(inc);
                        if (ret != SR_OK)
                                return ret;
                        bits = I2C_BITTIME_SLOTS / 2;
                        while (bits--) {
                                ret = i2c_write_nothing(inc);
                                if (ret != SR_OK)
                                        return ret;
                        }
                        ret = i2c_write_start(inc);
                        if (ret != SR_OK)
                                return ret;
                        bits = I2C_BITTIME_SLOTS / 2;
                        while (bits--) {
                                ret = i2c_write_nothing(inc);
                                if (ret != SR_OK)
                                        return ret;
                        }
                        ret = send_frame(in);
                        if (ret != SR_OK)
                                return ret;
                        continue;
                }
                if (strcmp(word, I2C_PSEUDO_STOP) == 0) {
                        sr_spew("I2C pseudo: send STOP");
                        ret = wave_clear_sequence(inc);
                        if (ret != SR_OK)
                                return ret;
                        bits = I2C_BITTIME_SLOTS / 2;
                        while (bits--) {
                                ret = i2c_write_nothing(inc);
                                if (ret != SR_OK)
                                        return ret;
                        }
                        ret = i2c_write_stop(inc);
                        if (ret != SR_OK)
                                return ret;
                        bits = I2C_BITTIME_SLOTS / 2;
                        while (bits--) {
                                ret = i2c_write_nothing(inc);
                                if (ret != SR_OK)
                                        return ret;
                        }
                        ret = send_frame(in);
                        if (ret != SR_OK)
                                return ret;
                        continue;
                }
                if (g_str_has_prefix(word, I2C_PSEUDO_ADDR_WRITE)) {
                        word += strlen(I2C_PSEUDO_ADDR_WRITE);
                        endp = NULL;
                        ret = sr_atoul_base(word, &v, &endp, 0);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("I2C pseudo: addr write %lu", v);
                        ret = i2c_send_address(in, v, FALSE);
                        if (ret != SR_OK)
                                return ret;
                        continue;
                }
                if (g_str_has_prefix(word, I2C_PSEUDO_ADDR_READ)) {
                        word += strlen(I2C_PSEUDO_ADDR_READ);
                        endp = NULL;
                        ret = sr_atoul_base(word, &v, &endp, 0);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("I2C pseudo: addr read %lu", v);
                        ret = i2c_send_address(in, v, TRUE);
                        if (ret != SR_OK)
                                return ret;
                        continue;
                }
                if (g_str_has_prefix(word, I2C_PSEUDO_ACK_NEXT)) {
                        word += strlen(I2C_PSEUDO_ACK_NEXT);
                        endp = NULL;
                        ret = sr_atoul_base(word, &v, &endp, 0);
                        if (ret != SR_OK)
                                return ret;
                        if (!endp || *endp)
                                return SR_ERR_ARG;
                        sr_spew("i2c pseudo: ack next %lu", v);
                        i2c_auto_ack_start(inc, v);
                        continue;
                }
                if (strcmp(word, I2C_PSEUDO_ACK_ONCE) == 0) {
                        sr_spew("i2c pseudo: ack once");
                        i2c_auto_ack_start(inc, 1);
                        continue;
                }
                return SR_ERR_DATA;
        }

        return SR_OK;
}

/*
 * Create the frame's waveform for the given data value. Automatically
 * track ACK bits, Fallback to NAK when externally specified ACK counts
 * have expired. The caller sends the waveform that we created.
 */
static int i2c_proc_value(struct context *inc, uint32_t value)
{
        gboolean with_ack;
        int ret;

        if (!inc)
                return SR_ERR_ARG;

        with_ack = i2c_auto_ack_avail(inc);

        ret = wave_clear_sequence(inc);
        if (ret != SR_OK)
                return ret;
        ret = i2c_write_byte(inc, value, with_ack);
        if (ret != SR_OK)
                return ret;

        return 0;
}

/* Start/end the logic trace with a few bit times of idle level. */
static int i2c_get_idle_capture(struct context *inc,
        size_t *bitcount, uint8_t *sample)
{

        /* Describe a byte's time of idle level. */
        if (bitcount)
                *bitcount = I2C_BITTIME_SLOTS;
        if (sample)
                *sample = inc->samples.idle_levels;
        return SR_OK;
}

/* Arrange for a few samples of idle level between UART frames. */
static int i2c_get_idle_interframe(struct context *inc,
        size_t *samplecount, uint8_t *sample)
{

        /* Describe four bit times, re-use the current pin levels. */
        if (samplecount) {
                *samplecount = inc->curr_opts.samples_per_bit;
                *samplecount *= 4;
        }
        if (sample)
                *sample = inc->samples.curr_levels;
        return SR_OK;
}

/* }}} I2C protocol handler */
/* {{{ protocol dispatching */

/*
 * The list of supported protocols and their handlers, including
 * protocol specific defaults. The first item after the NONE slot
 * is the default protocol, and takes effect in the absence of any
 * user provided or file content provided spec.
 */
static const struct proto_handler_t protocols[PROTO_TYPE_COUNT] = {
        [PROTO_TYPE_UART] = {
                UART_HANDLER_NAME,
                {
                        UART_DFLT_SAMPLERATE,
                        UART_DFLT_BITRATE, UART_DFLT_FRAMEFMT,
                        INPUT_BYTES,
                },
                {
                        1, (const char *[]){
                                [UART_PIN_RXTX] = "rxtx",
                        },
                },
                0,
                uart_check_opts,
                uart_config_frame,
                uart_proc_pseudo,
                uart_proc_value,
                uart_get_idle_capture,
                uart_get_idle_interframe,
        },
        [PROTO_TYPE_SPI] = {
                SPI_HANDLER_NAME,
                {
                        SPI_DFLT_SAMPLERATE,
                        SPI_DFLT_BITRATE, SPI_DFLT_FRAMEFMT,
                        INPUT_TEXT,
                },
                {
                        4, (const char *[]){
                                [SPI_PIN_SCK] = "sck",
                                [SPI_PIN_MISO] = "miso",
                                [SPI_PIN_MOSI] = "mosi",
                                [SPI_PIN_CS] = "cs",
                        },
                },
                sizeof(struct spi_proto_context_t),
                spi_check_opts,
                spi_config_frame,
                spi_proc_pseudo,
                spi_proc_value,
                spi_get_idle_capture,
                spi_get_idle_interframe,
        },
        [PROTO_TYPE_I2C] = {
                I2C_HANDLER_NAME,
                {
                        I2C_DFLT_SAMPLERATE,
                        I2C_DFLT_BITRATE, I2C_DFLT_FRAMEFMT,
                        INPUT_TEXT,
                },
                {
                        2, (const char *[]){
                                [I2C_PIN_SCL] = "scl",
                                [I2C_PIN_SDA] = "sda",
                        },
                },
                sizeof(struct i2c_proto_context_t),
                i2c_check_opts,
                i2c_config_frame,
                i2c_proc_pseudo,
                i2c_proc_value,
                i2c_get_idle_capture,
                i2c_get_idle_interframe,
        },
};

static int lookup_protocol_name(struct context *inc)
{
        const char *name;
        const struct proto_handler_t *handler;
        size_t idx;
        void *priv;

        /*
         * Silence compiler warnings. Protocol handlers are free to use
         * several alternative sets of primitives for their operation.
         * Not using part of the API is nothing worth warning about.
         */
        (void)sample_buffer_assign;

        if (!inc)
                return SR_ERR_ARG;
        inc->curr_opts.protocol_type = PROTO_TYPE_NONE;
        inc->curr_opts.prot_hdl = NULL;

        name = inc->curr_opts.proto_name;
        if (!name || !*name) {
                /* Fallback to first item after NONE slot. */
                handler = &protocols[PROTO_TYPE_NONE + 1];
                name = handler->name;
        }

        for (idx = 0; idx < ARRAY_SIZE(protocols); idx++) {
                if (idx == PROTO_TYPE_NONE)
                        continue;
                handler = &protocols[idx];
                if (!handler->name || !*handler->name)
                        continue;
                if (strcmp(name, handler->name) != 0)
                        continue;
                inc->curr_opts.protocol_type = idx;
                inc->curr_opts.prot_hdl = handler;
                if (handler->priv_size) {
                        priv = g_malloc0(handler->priv_size);
                        if (!priv)
                                return SR_ERR_MALLOC;
                        inc->curr_opts.prot_priv = priv;
                }
                return SR_OK;
        }

        return SR_ERR_DATA;
}

/* }}} protocol dispatching */
/* {{{ text/binary input file reader */

/**
 * Checks for UTF BOM, removes it when found at the start of the buffer.
 *
 * @param[in] buf The accumulated input buffer.
 */
static void check_remove_bom(GString *buf)
{
        static const char *bom_text = "\xef\xbb\xbf";

        if (buf->len < strlen(bom_text))
                return;
        if (strncmp(buf->str, bom_text, strlen(bom_text)) != 0)
                return;
        g_string_erase(buf, 0, strlen(bom_text));
}

/**
 * Checks for presence of a caption, yields the position after its text line.
 *
 * @param[in] buf The accumulated input buffer.
 * @param[in] caption The text to search for (NUL terminated ASCII literal).
 * @param[in] max_pos The maximum length to search for.
 *
 * @returns The position after the text line which contains the caption.
 *   Or #NULL when either the caption or the end-of-line was not found.
 */
static char *have_text_line(GString *buf, const char *caption, size_t max_pos)
{
        size_t cap_len, rem_len;
        char *p_read, *p_found;

        cap_len = strlen(caption);
        rem_len = buf->len;
        p_read = buf->str;

        /* Search for the occurance of the caption itself. */
        if (!max_pos) {
                /* Caption must be at the start of the buffer. */
                if (rem_len < cap_len)
                        return NULL;
                if (strncmp(p_read, caption, cap_len) != 0)
                        return NULL;
        } else {
                /* Caption can be anywhere up to a max position. */
                p_found = g_strstr_len(p_read, rem_len, caption);
                if (!p_found)
                        return NULL;
                /* Pretend that caption had been rather long. */
                cap_len += p_found - p_read;
        }

        /*
         * Advance over the caption. Advance over end-of-line. Supports
         * several end-of-line conditions, but rejects unexpected trailer
         * after the caption and before the end-of-line. Always wants LF.
         */
        p_read += cap_len;
        rem_len -= cap_len;
        while (rem_len && *p_read != '\n' && g_ascii_isspace(*p_read)) {
                p_read++;
                rem_len--;
        }
        if (rem_len && *p_read != '\n' && *p_read == '\r') {
                p_read++;
                rem_len--;
        }
        if (rem_len && *p_read == '\n') {
                p_read++;
                rem_len--;
                return p_read;
        }

        return NULL;
}

/**
 * Checks for the presence of the magic string at the start of the file.
 *
 * @param[in] buf The accumulated input buffer.
 * @param[out] next_pos The text after the magic text line.
 *
 * @returns Boolean whether the magic was found.
 *
 * This implementation assumes that the magic file type marker never gets
 * split across receive chunks.
 */
static gboolean have_magic(GString *buf, char **next_pos)
{
        char *next_line;

        if (next_pos)
                *next_pos = NULL;

        next_line = have_text_line(buf, MAGIC_FILE_TYPE, 0);
        if (!next_line)
                return FALSE;

        if (next_pos)
                *next_pos = next_line;

        return TRUE;
}

/**
 * Checks for the presence of the header section at the start of the file.
 *
 * @param[in] buf The accumulated input buffer.
 * @param[out] next_pos The text after the header section.
 *
 * @returns A negative value when the answer is yet unknown (insufficient
 *   input data). Or boolean 0/1 when the header was found absent/present.
 *
 * The caller is supposed to have checked for and removed the magic text
 * for the file type. This routine expects to find the header section
 * boundaries right at the start of the input buffer.
 *
 * This implementation assumes that the header start marker never gets
 * split across receive chunks.
 */
static int have_header(GString *buf, char **next_pos)
{
        char *after_start, *after_end;

        if (next_pos)
                *next_pos = NULL;

        after_start = have_text_line(buf, TEXT_HEAD_START, 0);
        if (!after_start)
                return 0;

        after_end = have_text_line(buf, TEXT_HEAD_END, buf->len);
        if (!after_end)
                return -1;

        if (next_pos)
                *next_pos = after_end;
        return 1;
}

/*
 * Implementation detail: Most parse routines merely accept an input
 * string or at most convert text to numbers. Actual processing of the
 * values or constraints checks are done later when the header section
 * ended and all data was seen, regardless of order of appearance.
 */

static int parse_samplerate(struct context *inc, const char *text)
{
        uint64_t rate;
        int ret;

        ret = sr_parse_sizestring(text, &rate);
        if (ret != SR_OK)
                return SR_ERR_DATA;

        inc->curr_opts.samplerate = rate;

        return SR_OK;
}

static int parse_bitrate(struct context *inc, const char *text)
{
        uint64_t rate;
        int ret;

        ret = sr_parse_sizestring(text, &rate);
        if (ret != SR_OK)
                return SR_ERR_DATA;

        inc->curr_opts.bitrate = rate;

        return SR_OK;
}

static int parse_protocol(struct context *inc, const char *line)
{

        if (!line || !*line)
                return SR_ERR_DATA;

        if (inc->curr_opts.proto_name) {
                free(inc->curr_opts.proto_name);
                inc->curr_opts.proto_name = NULL;
        }
        inc->curr_opts.proto_name = g_strdup(line);
        if (!inc->curr_opts.proto_name)
                return SR_ERR_MALLOC;
        line = inc->curr_opts.proto_name;

        return SR_OK;
}

static int parse_frameformat(struct context *inc, const char *line)
{

        if (!line || !*line)
                return SR_ERR_DATA;

        if (inc->curr_opts.fmt_text) {
                free(inc->curr_opts.fmt_text);
                inc->curr_opts.fmt_text = NULL;
        }
        inc->curr_opts.fmt_text = g_strdup(line);
        if (!inc->curr_opts.fmt_text)
                return SR_ERR_MALLOC;
        line = inc->curr_opts.fmt_text;

        return SR_OK;
}

static int parse_textinput(struct context *inc, const char *text)
{
        gboolean is_text;

        if (!text || !*text)
                return SR_ERR_ARG;

        is_text = sr_parse_boolstring(text);
        inc->curr_opts.textinput = is_text ? INPUT_TEXT : INPUT_BYTES;
        return SR_OK;
}

static int parse_header_line(struct context *inc, const char *line)
{

        /* Silently ignore comment lines. Also covers start/end markers. */
        if (strncmp(line, TEXT_COMM_LEADER, strlen(TEXT_COMM_LEADER)) == 0)
                return SR_OK;

        if (strncmp(line, LABEL_SAMPLERATE, strlen(LABEL_SAMPLERATE)) == 0) {
                line += strlen(LABEL_SAMPLERATE);
                return parse_samplerate(inc, line);
        }
        if (strncmp(line, LABEL_BITRATE, strlen(LABEL_BITRATE)) == 0) {
                line += strlen(LABEL_BITRATE);
                return parse_bitrate(inc, line);
        }
        if (strncmp(line, LABEL_PROTOCOL, strlen(LABEL_PROTOCOL)) == 0) {
                line += strlen(LABEL_PROTOCOL);
                return parse_protocol(inc, line);
        }
        if (strncmp(line, LABEL_FRAMEFORMAT, strlen(LABEL_FRAMEFORMAT)) == 0) {
                line += strlen(LABEL_FRAMEFORMAT);
                return parse_frameformat(inc, line);
        }
        if (strncmp(line, LABEL_TEXTINPUT, strlen(LABEL_TEXTINPUT)) == 0) {
                line += strlen(LABEL_TEXTINPUT);
                return parse_textinput(inc, line);
        }

        /* Unsupported directive. */
        sr_err("Unsupported header directive: %s.", line);

        return SR_ERR_DATA;
}

static int parse_header(struct context *inc, GString *buf, size_t hdr_len)
{
        size_t remain;
        char *curr, *next, *line;
        int ret;

        ret = SR_OK;

        /* The caller determined where the header ends. Read up to there. */
        remain = hdr_len;
        curr = buf->str;
        while (curr && remain) {
                /* Get another text line. Skip empty lines. */
                line = sr_text_next_line(curr, remain, &next, NULL);
                if (!line)
                        break;
                if (next)
                        remain -= next - curr;
                else
                        remain = 0;
                curr = next;
                if (!*line)
                        continue;
                /* Process the non-empty file header text line. */
                sr_dbg("Header line: %s", line);
                ret = parse_header_line(inc, line);
                if (ret != SR_OK)
                        break;
        }

        return ret;
}

/* Process input text reader specific pseudo comment. */
static int process_pseudo_textinput(struct sr_input *in, char *line)
{
        struct context *inc;
        char *word;
        unsigned long v;
        char *endp;
        int ret;

        inc = in->priv;
        while (line) {
                word = sr_text_next_word(line, &line);
                if (!word)
                        break;
                if (!*word)
                        continue;
                if (g_str_has_prefix(word, TEXT_INPUT_RADIX)) {
                        word += strlen(TEXT_INPUT_RADIX);
                        endp = NULL;
                        ret = sr_atoul_base(word, &v, &endp, 10);
                        if (ret != SR_OK)
                                return ret;
                        inc->read_text.base = v;
                        continue;
                }
                return SR_ERR_DATA;
        }

        return SR_OK;
}

/* Process a line of input text. */
static int process_textline(struct sr_input *in, char *line)
{
        struct context *inc;
        const struct proto_handler_t *handler;
        gboolean is_comm, is_pseudo;
        char *word;
        char *endp;
        unsigned long value;
        int ret;

        inc = in->priv;
        handler = inc->curr_opts.prot_hdl;

        /*
         * Check for comments, including pseudo-comments with protocol
         * specific or text reader specific instructions. It's essential
         * to check for "# ${PROTO}:" last, because the implementation
         * of the check advances the read position, cannot rewind when
         * detection fails. But we know that it is a comment and was not
         * a pseudo-comment. So any non-matching data just gets discarded.
         * Matching data gets processed (when handlers exist).
         */
        is_comm = g_str_has_prefix(line, TEXT_COMM_LEADER);
        if (is_comm) {
                line += strlen(TEXT_COMM_LEADER);
                while (isspace(*line))
                        line++;
                is_pseudo = g_str_has_prefix(line, TEXT_INPUT_PREFIX);
                if (is_pseudo) {
                        line += strlen(TEXT_INPUT_PREFIX);
                        while (isspace(*line))
                                line++;
                        sr_dbg("pseudo comment, textinput: %s", line);
                        line = sr_text_trim_spaces(line);
                        return process_pseudo_textinput(in, line);
                }
                is_pseudo = g_str_has_prefix(line, handler->name);
                if (is_pseudo) {
                        line += strlen(handler->name);
                        is_pseudo = *line == ':';
                        if (is_pseudo)
                                line++;
                }
                if (is_pseudo) {
                        while (isspace(*line))
                                line++;
                        sr_dbg("pseudo comment, protocol: %s", line);
                        if (!handler->proc_pseudo)
                                return SR_OK;
                        return handler->proc_pseudo(in, line);
                }
                sr_spew("comment, skipping: %s", line);
                return SR_OK;
        }

        /*
         * Non-empty non-comment lines carry protocol values.
         * (Empty lines are handled transparently when they get here.)
         * Convert text according to previously received instructions.
         * Pass the values to the protocol handler. Flush waveforms
         * when handlers state that their construction has completed.
         */
        sr_spew("got values line: %s", line);
        while (line) {
                word = sr_text_next_word(line, &line);
                if (!word)
                        break;
                if (!*word)
                        continue;
                /* Get another numeric value. */
                endp = NULL;
                ret = sr_atoul_base(word, &value, &endp, inc->read_text.base);
                if (ret != SR_OK)
                        return ret;
                if (!endp || *endp)
                        return SR_ERR_DATA;
                sr_spew("got a value, text [%s] -> number [%lu]", word, value);
                /* Forward the value to the protocol handler. */
                ret = 0;
                if (handler->proc_value)
                        ret = handler->proc_value(inc, value);
                if (ret < 0)
                        return ret;
                /* Flush the waveform when handler signals completion. */
                if (ret > 0)
                        continue;
                ret = send_frame(in);
                if (ret != SR_OK)
                        return ret;
                ret = send_idle_interframe(inc);
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

/* }}} text/binary input file reader */

/*
 * Consistency check of all previously received information. Combines
 * the data file's optional header section, as well as user provided
 * options that were specified during input module creation. User specs
 * take precedence over file content.
 */
static int check_header_user_options(struct context *inc)
{
        int ret;
        const struct proto_handler_t *handler;
        uint64_t rate;
        const char *text;
        enum textinput_t is_text;

        if (!inc)
                return SR_ERR_ARG;

        /* Prefer user specs over file content. */
        rate = inc->user_opts.samplerate;
        if (rate) {
                sr_dbg("Using user samplerate %" PRIu64 ".", rate);
                inc->curr_opts.samplerate = rate;
        }
        rate = inc->user_opts.bitrate;
        if (rate) {
                sr_dbg("Using user bitrate %" PRIu64 ".", rate);
                inc->curr_opts.bitrate = rate;
        }
        text = inc->user_opts.proto_name;
        if (text && *text) {
                sr_dbg("Using user protocol %s.", text);
                ret = parse_protocol(inc, text);
                if (ret != SR_OK)
                        return SR_ERR_DATA;
        }
        text = inc->user_opts.fmt_text;
        if (text && *text) {
                sr_dbg("Using user frame format %s.", text);
                ret = parse_frameformat(inc, text);
                if (ret != SR_OK)
                        return SR_ERR_DATA;
        }
        is_text = inc->user_opts.textinput;
        if (is_text) {
                sr_dbg("Using user textinput %d.", is_text);
                inc->curr_opts.textinput = is_text;
        }

        /* Lookup the protocol (with fallback). Use protocol's defaults. */
        text = inc->curr_opts.proto_name;
        ret = lookup_protocol_name(inc);
        handler = inc->curr_opts.prot_hdl;
        if (ret != SR_OK || !handler) {
                sr_err("Unsupported protocol: %s.", text);
                return SR_ERR_DATA;
        }
        text = handler->name;
        if (!inc->curr_opts.proto_name && text) {
                sr_dbg("Using protocol handler name %s.", text);
                ret = parse_protocol(inc, text);
                if (ret != SR_OK)
                        return SR_ERR_DATA;
        }
        rate = handler->dflt.samplerate;
        if (!inc->curr_opts.samplerate && rate) {
                sr_dbg("Using protocol handler samplerate %" PRIu64 ".", rate);
                inc->curr_opts.samplerate = rate;
        }
        rate = handler->dflt.bitrate;
        if (!inc->curr_opts.bitrate && rate) {
                sr_dbg("Using protocol handler bitrate %" PRIu64 ".", rate);
                inc->curr_opts.bitrate = rate;
        }
        text = handler->dflt.frame_format;
        if (!inc->curr_opts.fmt_text && text && *text) {
                sr_dbg("Using protocol handler frame format %s.", text);
                ret = parse_frameformat(inc, text);
                if (ret != SR_OK)
                        return SR_ERR_DATA;
        }
        is_text = handler->dflt.textinput;
        if (!inc->curr_opts.textinput && is_text) {
                sr_dbg("Using protocol handler text format %d.", is_text);
                inc->curr_opts.textinput = is_text;
        }

        if (!inc->curr_opts.samplerate) {
                sr_err("Need a samplerate.");
                return SR_ERR_DATA;
        }
        if (!inc->curr_opts.bitrate) {
                sr_err("Need a protocol bitrate.");
                return SR_ERR_DATA;
        }

        if (inc->curr_opts.samplerate < inc->curr_opts.bitrate) {
                sr_err("Bitrate cannot exceed samplerate.");
                return SR_ERR_DATA;
        }
        if (inc->curr_opts.samplerate / inc->curr_opts.bitrate < 3)
                sr_warn("Low oversampling, consider higher samplerate.");
        if (inc->curr_opts.prot_hdl->check_opts) {
                ret = inc->curr_opts.prot_hdl->check_opts(inc);
                if (ret != SR_OK) {
                        sr_err("Options failed the protocol's check.");
                        return SR_ERR_DATA;
                }
        }

        return SR_OK;
}

static int create_channels(struct sr_input *in)
{
        struct context *inc;
        struct sr_dev_inst *sdi;
        const struct proto_handler_t *handler;
        size_t index;
        const char *name;

        if (!in)
                return SR_ERR_ARG;
        inc = in->priv;
        if (!inc)
                return SR_ERR_ARG;
        sdi = in->sdi;
        handler = inc->curr_opts.prot_hdl;

        for (index = 0; index < handler->chans.count; index++) {
                name = handler->chans.names[index];
                sr_dbg("Channel %zu name %s.", index, name);
                sr_channel_new(sdi, index, SR_CHANNEL_LOGIC, TRUE, name);
        }

        inc->feed_logic = feed_queue_logic_alloc(in->sdi,
                CHUNK_SIZE, sizeof(uint8_t));
        if (!inc->feed_logic) {
                sr_err("Cannot create session feed.");
                return SR_ERR_MALLOC;
        }

        return SR_OK;
}

/*
 * Keep track of a previously created channel list, in preparation of
 * re-reading the input file. Gets called from reset()/cleanup() paths.
 */
static void keep_header_for_reread(const struct sr_input *in)
{
        struct context *inc;

        inc = in->priv;

        g_slist_free_full(inc->prev.sr_groups, sr_channel_group_free_cb);
        inc->prev.sr_groups = in->sdi->channel_groups;
        in->sdi->channel_groups = NULL;

        g_slist_free_full(inc->prev.sr_channels, sr_channel_free_cb);
        inc->prev.sr_channels = in->sdi->channels;
        in->sdi->channels = NULL;
}

/*
 * Check whether the input file is being re-read, and refuse operation
 * when essential parameters of the acquisition have changed in ways
 * that are unexpected to calling applications. Gets called after the
 * file header got parsed (again).
 *
 * Changing the channel list across re-imports of the same file is not
 * supported, by design and for valid reasons, see bug #1215 for details.
 * Users are expected to start new sessions when they change these
 * essential parameters in the acquisition's setup. When we accept the
 * re-read file, then make sure to keep using the previous channel list,
 * applications may still reference them.
 */
static gboolean check_header_in_reread(const struct sr_input *in)
{
        struct context *inc;

        if (!in)
                return FALSE;
        inc = in->priv;
        if (!inc)
                return FALSE;
        if (!inc->prev.sr_channels)
                return TRUE;

        if (sr_channel_lists_differ(inc->prev.sr_channels, in->sdi->channels)) {
                sr_err("Channel list change not supported for file re-read.");
                return FALSE;
        }

        g_slist_free_full(in->sdi->channel_groups, sr_channel_group_free_cb);
        in->sdi->channel_groups = inc->prev.sr_groups;
        inc->prev.sr_groups = NULL;

        g_slist_free_full(in->sdi->channels, sr_channel_free_cb);
        in->sdi->channels = inc->prev.sr_channels;
        inc->prev.sr_channels = NULL;

        return TRUE;
}

/* Process another chunk of accumulated input data. */
static int process_buffer(struct sr_input *in, gboolean is_eof)
{
        struct context *inc;
        GVariant *gvar;
        int ret;
        GString *buf;
        const struct proto_handler_t *handler;
        size_t seen;
        char *line, *next;
        uint8_t sample;

        inc = in->priv;
        buf = in->buf;
        handler = inc->curr_opts.prot_hdl;

        /*
         * Send feed header and samplerate once before any sample data.
         * Communicate an idle period before the first generated frame.
         */
        if (!inc->started) {
                std_session_send_df_header(in->sdi);
                gvar = g_variant_new_uint64(inc->curr_opts.samplerate);
                ret = sr_session_send_meta(in->sdi, SR_CONF_SAMPLERATE, gvar);
                inc->started = TRUE;
                if (ret != SR_OK)
                        return ret;

                ret = send_idle_capture(inc);
                if (ret != SR_OK)
                        return ret;
        }

        /*
         * Force proper line termination when EOF is seen and the data
         * is in text format. This does not affect binary input, while
         * properly terminated text input does not suffer from another
         * line feed, because empty lines are considered acceptable.
         * Increases robustness for text input from broken generators
         * (popular editors which don't terminate the last line).
         */
        if (inc->curr_opts.textinput == INPUT_TEXT && is_eof) {
                g_string_append_c(buf, '\n');
        }

        /*
         * For text input: Scan for the completion of another text line.
         * Process its values (or pseudo comments). Skip comment lines.
         */
        if (inc->curr_opts.textinput == INPUT_TEXT) do {
                /* Get another line of text. */
                seen = 0;
                line = sr_text_next_line(buf->str, buf->len, &next, &seen);
                if (!line)
                        break;
                /* Process non-empty input lines. */
                ret = *line ? process_textline(in, line) : 0;
                if (ret < 0)
                        return ret;
                /* Discard processed input text. */
                g_string_erase(buf, 0, seen);
        } while (buf->len);

        /*
         * For binary input: Pass data values (individual bytes) to the
         * creation of protocol frames. Send the frame's waveform to
         * logic channels in the session feed when the protocol handler
         * signals the completion of another waveform (zero return value).
         * Non-zero positive values translate to "need more input data".
         * Negative values signal fatal errors. Remove processed input
         * data from the receive buffer.
         */
        if (inc->curr_opts.textinput == INPUT_BYTES) {
                seen = 0;
                while (seen < buf->len) {
                        sample = buf->str[seen++];
                        ret = 0;
                        if (handler->proc_value)
                                ret = handler->proc_value(inc, sample);
                        if (ret < 0)
                                return ret;
                        if (ret > 0)
                                continue;
                        ret = send_frame(in);
                        if (ret != SR_OK)
                                return ret;
                        ret = send_idle_interframe(inc);
                        if (ret != SR_OK)
                                return ret;
                }
                g_string_erase(buf, 0, seen);
        }

        /* Send idle level, and flush when end of input data is seen. */
        if (is_eof) {
                if (buf->len)
                        sr_warn("Unprocessed input data remains.");

                ret = send_idle_capture(inc);
                if (ret != SR_OK)
                        return ret;

                ret = feed_queue_logic_flush(inc->feed_logic);
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

static int format_match(GHashTable *metadata, unsigned int *confidence)
{
        GString *buf, *tmpbuf;
        gboolean has_magic;

        buf = g_hash_table_lookup(metadata,
                GINT_TO_POINTER(SR_INPUT_META_HEADER));
        tmpbuf = g_string_new_len(buf->str, buf->len);

        check_remove_bom(tmpbuf);
        has_magic = have_magic(tmpbuf, NULL);
        g_string_free(tmpbuf, TRUE);

        if (!has_magic)
                return SR_ERR;

        *confidence = 1;
        return SR_OK;
}

static int init(struct sr_input *in, GHashTable *options)
{
        struct context *inc;
        GVariant *gvar;
        uint64_t rate;
        char *copy;
        const char *text;

        in->sdi = g_malloc0(sizeof(*in->sdi));
        inc = g_malloc0(sizeof(*inc));
        in->priv = inc;

        /*
         * Store user specified options for later reference.
         *
         * TODO How to most appropriately hook up size strings with the
         * input module's defaults, and applications and their input
         * dialogs?
         */
        gvar = g_hash_table_lookup(options, "samplerate");
        if (gvar) {
                rate = g_variant_get_uint64(gvar);
                if (rate)
                        sr_dbg("User samplerate %" PRIu64 ".", rate);
                inc->user_opts.samplerate = rate;
        }

        gvar = g_hash_table_lookup(options, "bitrate");
        if (gvar) {
                rate = g_variant_get_uint64(gvar);
                if (rate)
                        sr_dbg("User bitrate %" PRIu64 ".", rate);
                inc->user_opts.bitrate = rate;
        }

        gvar = g_hash_table_lookup(options, "protocol");
        if (gvar) {
                copy = g_strdup(g_variant_get_string(gvar, NULL));
                if (!copy)
                        return SR_ERR_MALLOC;
                if (*copy)
                        sr_dbg("User protocol %s.", copy);
                inc->user_opts.proto_name = copy;
        }

        gvar = g_hash_table_lookup(options, "frameformat");
        if (gvar) {
                copy = g_strdup(g_variant_get_string(gvar, NULL));
                if (!copy)
                        return SR_ERR_MALLOC;
                if (*copy)
                        sr_dbg("User frame format %s.", copy);
                inc->user_opts.fmt_text = copy;
        }

        inc->user_opts.textinput = INPUT_UNSPEC;
        gvar = g_hash_table_lookup(options, "textinput");
        if (gvar) {
                text = g_variant_get_string(gvar, NULL);
                if (!text)
                        return SR_ERR_DATA;
                if (!*text)
                        return SR_ERR_DATA;
                sr_dbg("User text input %s.", text);
                if (strcmp(text, input_format_texts[INPUT_UNSPEC]) == 0) {
                        inc->user_opts.textinput = INPUT_UNSPEC;
                } else if (strcmp(text, input_format_texts[INPUT_BYTES]) == 0) {
                        inc->user_opts.textinput = INPUT_BYTES;
                } else if (strcmp(text, input_format_texts[INPUT_TEXT]) == 0) {
                        inc->user_opts.textinput = INPUT_TEXT;
                } else {
                        return SR_ERR_DATA;
                }
        }

        return SR_OK;
}

static int receive(struct sr_input *in, GString *buf)
{
        struct context *inc;
        char *after_magic, *after_header;
        size_t consumed;
        int ret;

        inc = in->priv;

        /*
         * Accumulate all input chunks, potential deferred processing.
         *
         * Remove an optional BOM at the very start of the input stream.
         * BEWARE! This may affect binary input, and we cannot tell if
         * the input is text or binary at this stage. Though probability
         * for this issue is rather low. Workarounds are available (put
         * another values before the first data which happens to match
         * the BOM pattern, provide text input instead).
         */
        g_string_append_len(in->buf, buf->str, buf->len);
        if (!inc->scanned_magic)
                check_remove_bom(in->buf);

        /*
         * Must complete reception of the (optional) header first. Both
         * end of header and absence of header will: Check options that
         * were seen so far, then start processing the data part.
         */
        if (!inc->got_header) {
                /* Check for magic file type marker. */
                if (!inc->scanned_magic) {
                        inc->has_magic = have_magic(in->buf, &after_magic);
                        inc->scanned_magic = TRUE;
                        if (inc->has_magic) {
                                consumed = after_magic - in->buf->str;
                                sr_dbg("File format magic found (%zu).", consumed);
                                g_string_erase(in->buf, 0, consumed);
                        }
                }

                /* Complete header reception and processing. */
                if (inc->has_magic) {
                        ret = have_header(in->buf, &after_header);
                        if (ret < 0)
                                return SR_OK;
                        inc->has_header = ret;
                        if (inc->has_header) {
                                consumed = after_header - in->buf->str;
                                sr_dbg("File header found (%zu), processing.", consumed);
                                ret = parse_header(inc, in->buf, consumed);
                                if (ret != SR_OK)
                                        return ret;
                                g_string_erase(in->buf, 0, consumed);
                        }
                }
                inc->got_header = TRUE;

                /*
                 * Postprocess the combination of all options. Create
                 * logic channels, prepare resources for data processing.
                 */
                ret = check_header_user_options(inc);
                if (ret != SR_OK)
                        return ret;
                ret = create_channels(in);
                if (ret != SR_OK)
                        return ret;
                if (!check_header_in_reread(in))
                        return SR_ERR_DATA;
                ret = alloc_frame_storage(inc);
                if (ret != SR_OK)
                        return ret;
                ret = assign_bit_widths(inc);
                if (ret != SR_OK)
                        return ret;

                /* Notify the frontend that sdi is ready. */
                in->sdi_ready = TRUE;
                return SR_OK;
        }

        /*
         * Process the input file's data section after the header section
         * was received and processed.
         */
        ret = process_buffer(in, FALSE);

        return ret;
}

static int end(struct sr_input *in)
{
        struct context *inc;
        int ret;

        inc = in->priv;

        /* Must complete processing of previously received chunks. */
        if (in->sdi_ready) {
                ret = process_buffer(in, TRUE);
                if (ret != SR_OK)
                        return ret;
        }

        /* Must send DF_END when DF_HEADER was sent before. */
        if (inc->started) {
                ret = std_session_send_df_end(in->sdi);
                if (ret != SR_OK)
                        return ret;
        }

        return SR_OK;
}

static void cleanup(struct sr_input *in)
{
        struct context *inc;

        inc = in->priv;

        keep_header_for_reread(in);

        g_free(inc->curr_opts.proto_name);
        inc->curr_opts.proto_name = NULL;
        g_free(inc->curr_opts.fmt_text);
        inc->curr_opts.fmt_text = NULL;
        g_free(inc->curr_opts.prot_priv);
        inc->curr_opts.prot_priv = NULL;
        feed_queue_logic_free(inc->feed_logic);
        inc->feed_logic = NULL;
        g_free(inc->sample_edges);
        inc->sample_edges = NULL;
        g_free(inc->sample_widths);
        inc->sample_widths = NULL;
        g_free(inc->sample_levels);
        inc->sample_levels = NULL;
        g_free(inc->bit_scale);
        inc->bit_scale = NULL;
}

static int reset(struct sr_input *in)
{
        struct context *inc;
        struct user_opts_t save_user_opts;
        struct proto_prev save_chans;

        inc = in->priv;

        /* Release previously allocated resources. */
        cleanup(in);
        g_string_truncate(in->buf, 0);

        /* Restore part of the context, init() won't run again. */
        save_user_opts = inc->user_opts;
        save_chans = inc->prev;
        memset(inc, 0, sizeof(*inc));
        inc->user_opts = save_user_opts;
        inc->prev = save_chans;

        return SR_OK;
}

enum proto_option_t {
        OPT_SAMPLERATE,
        OPT_BITRATE,
        OPT_PROTOCOL,
        OPT_FRAME_FORMAT,
        OPT_TEXTINPUT,
        OPT_MAX,
};

static struct sr_option options[] = {
        [OPT_SAMPLERATE] = {
                "samplerate", "Logic data samplerate",
                "Samplerate of generated logic traces",
                NULL, NULL,
        },
        [OPT_BITRATE] = {
                "bitrate", "Protocol bitrate",
                "Bitrate used in protocol's communication",
                NULL, NULL,
        },
        [OPT_PROTOCOL] = {
                "protocol", "Protocol type",
                "The type of protocol to generate waveforms for",
                NULL, NULL,
        },
        [OPT_FRAME_FORMAT] = {
                "frameformat", "Protocol frame format",
                "Textual description of the protocol's frame format",
                NULL, NULL,
        },
        [OPT_TEXTINPUT] = {
                "textinput", "Input data is in text format",
                "Input is not data bytes, but text formatted values",
                NULL, NULL,
        },
        [OPT_MAX] = ALL_ZERO,
};

static const struct sr_option *get_options(void)
{
        GSList *l;
        enum proto_type_t p_idx;
        enum textinput_t t_idx;
        const char *s;

        if (options[0].def)
                return options;

        options[OPT_SAMPLERATE].def = g_variant_ref_sink(g_variant_new_uint64(0));
        options[OPT_BITRATE].def = g_variant_ref_sink(g_variant_new_uint64(0));
        options[OPT_PROTOCOL].def = g_variant_ref_sink(g_variant_new_string(""));
        l = NULL;
        for (p_idx = 0; p_idx < ARRAY_SIZE(protocols); p_idx++) {
                s = protocols[p_idx].name;
                if (!s || !*s)
                        continue;
                l = g_slist_append(l, g_variant_ref_sink(g_variant_new_string(s)));
        }
        options[OPT_PROTOCOL].values = l;
        options[OPT_FRAME_FORMAT].def = g_variant_ref_sink(g_variant_new_string(""));
        l = NULL;
        for (t_idx = INPUT_UNSPEC; t_idx <= INPUT_TEXT; t_idx++) {
                s = input_format_texts[t_idx];
                l = g_slist_append(l, g_variant_ref_sink(g_variant_new_string(s)));
        }
        options[OPT_TEXTINPUT].values = l;
        options[OPT_TEXTINPUT].def = g_variant_ref_sink(g_variant_new_string(
                input_format_texts[INPUT_UNSPEC]));
        return options;
}

SR_PRIV struct sr_input_module input_protocoldata = {
        .id = "protocoldata",
        .name = "Protocol data",
        .desc = "Generate logic traces from protocol's data values",
        .exts = (const char *[]){ "sr-protocol", "protocol", "bin", NULL, },
        .metadata = { SR_INPUT_META_HEADER | SR_INPUT_META_REQUIRED },
        .options = get_options,
        .format_match = format_match,
        .init = init,
        .receive = receive,
        .end = end,
        .reset = reset,
};