serial_hid: add iokit= prefix for the Mac IOKit special case

Rephrase the logic which turns HIDAPI paths returned from enumerations
into something that can be used with conn= device options. Rearrange
code paths and rename variables to hopefully increase readability, and
to prepare support for more conditions in future implementations.

Replace the "IOService:" prefix on recent Mac versions with the "iokit="
literal, to eliminate the previously unhandled colon in path names. This
resolves bug #1586.

Move the allocation of a writable buffer from the callers to the callee,
to simplify multiple call sites, and most of all because the caller need
not be aware of the buffer's required size (input and output size can
differ in either direction).

Update the conn=hid/ section in README.devices, add the iokit= prefix.

output/csv: complete and improve timestamp construction support

Unbreak the timestamp calculation when session data is received in
multiple packets. Avoid a division by zero when the samplerate is not
known yet the time column is requested. Only calculate timestamps when
the time column is requested. Use floating point during the scaling,
only convert to integer immediately before printing. Change line breaks
to not split a complex sub-expression across several lines.

output/csv: Avoid accumulated timestamp error for odd samplerates

The conversion of sample rates to sample periods and the repeated
addition of truncated values (integer variables) resulted in the
accumulation of errors in the timestamp column for odd samplerate
values. How to reproduce:

  $ sigrok-cli -d demo:analog_channels=0 \
      -c samplerate=6000000 --samples 1200001 \
      -O csv:time=true | tail

Accept the additional cost to reduce the error. Always get the timestamp
in a new calculation based on the sample number and the sample rate.

This addresses bug #1027.

Signed-off-by: Earle F. Philhower, III <redacted>
[ gsi: rephrased commit message, how to reprodue ]

gwinstek-gpd: Add missing SW limits API calls.

sw_limits: add const for limits param for config_get

The sr_sw_limits_config_get() routine exclusively reads the 'limits'
parameter, need not write to it. Add the 'const' attribute.

serial: make failed flush() in open() non-fatal, CP2110 flush() return

Commit cb828f1b3e00 introduced an unconditional flush() call in the
open() routine's body, and passed its return value in verbatim form to
open() callers. Some of the transports/cables for serial communication
yield the SR_ERR_NA return value. Consider this a non-fatal condition.

Unbreak the CP2110 HID chip's flush() implementation. Don't expect a
return value of 0 from HID write calls, instead expect to see the number
of written bytes for successful calls.

This was tested with ch9325 (UT-D04), cp2110 (UT-D09) and bu86x.

gwinstek-gpd: Add support to old (hardware) revision units.

Manufacturer revised hardware design without changing model numbers at some point.
Old units have firmware that behaves differently. Responses are terminated with \r
instead of \n. And STATUS? command response format is different.

gwinstek-gpd: Add support for GPD-3303S.

output/ascii: data type nits, rephrase sample bit access

Use size types for counters, unsigned for bit manipulation. Trigger
position needs to remain a signed int (must be possible to go negative
for "not here", and strictly remains within the output text line length,
so should be good).

Rephrase the nested loop during bit extraction from logic packets, and
how a channel's value at a given sample number gets accessed. Eliminate
redundancy in that spot, to improve readability and simplify maintenance.

output/ascii: style nits in name alignment and trigger flush

Unobfuscate the implementation of the recent channel name alignment and
trigger position flush, address other style nits of earlier versions:

Don't need a GString for runtime constant channel names (which also
suffered from a mismatch of declaration and allocation). Don't need to
"construct space" when printf(3) can align the value. Pre-allocate text
buffers with more appropriate length when known in advance. Drop another
unused variable. Eliminate data type redundancy in malloc(3) calls. Make
sure to get zeroed memory, disabled channels can result in assignment
gaps. Use consistent brace style and separate variable declaration from
use (no RAII here).

Excess text line length remains, there has been a lot of it in the
previous implementation. It is left for another commit.

Tested with:

  $ sigrok-cli -d demo:analog_channels=0:logic_channels=4 --samples 40 -O ascii -t D3=r -w

output/ascii: Also print trigger marker for "short" data lines

The trigger position would be missing in the output text when the number of
available samples is less than the configured text line length. Do flush the
trigger marker for the last chunk of accumulated samples, too.

How to reproduce:

  $ sigrok-cli -d ... --samples 32 -O ascii:width=128

[ gsi: rephrased commit message ]

output/ascii: Vertically align logic channel names

This results in vertical alignment of sample data and trigger positions.
The implementation assumes that the channel names' byte count corresponds
to the space which they occupy on screen. Channel names with umlauts still
may suffer from misalignment.

[ gsi: rephrased commit message ]

output/ascii: Remove unused variable

analog: avoid double free in '-O analog' shutdown path

Do void the 'def' and 'values' references for '-O analog' module options
in the shutdown path, to avoid double free calls.

output/srzip: improve robustness (analog-only acquisition)

For pure analog acquisition without logic data the ZIP creation code
path resulted in a division by zero. Skip the bytes to samples math in
that case. How to reproduce:

  $ sigrok-cli -d demo:logic_channels=0:analog_channels=1 --samples 20 -o file.sr

Avoid a dependency on malloc(0) behaviour while we are here. Add a
warning on data feed submitter implementation issues, to not silently
drop the data, which could surprise users. This ShouldNotHappen(TM) for
correct implementations where channel counts and unit size agree, but
was observed with incomplete out-of-tree implementations. Eliminate
a data type redundancy in another malloc() call.

scpi-dmm: Add Agilent 34410A.

serial: flush() after open() in the serial core.

Quite some drivers flush the serial port after opening it. And quite
some don't although they should. Factor this out, so serial_open() will
always flush the port. The removal in the drivers was done with this
small coccinelle script:

@@
struct sr_serial_dev_inst *serial;
@@

        serial_open(serial, ...)
        ... when != serial
-       serial_flush(serial);

and then the results and the unmatched findings of serial_flush() were
audited.

Signed-off-by: Wolfram Sang <redacted>

bt: drop bt_put_le16() dependency (not universally available)

Eliminate the dependency on the non-portable bt_put_le16() routine. It
isn't available in all supported BlueZ versions, and won't be available
in other platform backends. Prefer write_u16le() which is available on
all sigrok supported platforms.

input: use common support to send samplerate meta packet

input/saleae: reduce the format match routine's greed

Only return OK from the format match routine when either of the tested
conditions reliably matched. Return an error in all other cases. This
avoids that the Saleae module is "winning a contest" due to even the
weakest condition, and then is not able to handle the input file.

input/saleae: introduce input module for Saleae Logic exported files

Start the implementation of an input module which covers Saleae Logic's
export files. CSV and VCD are handled by other modules, this one accepts
binary exports for Logic1 digital data (every sample, and when changed),
Logic1 analog data, Logic2 digital data, and Logic2 analog data.

The newer file format versions contain header information and can get
auto-detected, the older formats require a user spec. Some of the file
formats lack essential information in the file content, thus require
another user spec (samplerate for digital data is an example).

The .logicdata file format is unknown, and is not supported. The .sal
format could get added later, but requires local file I/O in the input
module, which current common infrastructure does not provide.

libsigrok-internal: add endianess helpers for floating point types

Extend the common set of endianess conversion helpers. Cover readers and
writers for little endian single and double precision and 64bit integer
values, including support to advance the read/write position.

input/vcd: unbreak the logic which skips a user specified period

Rephrase the default value for the 'skip' option and the detection of a
user specified value. This is tricky because: Sample numbers are kept in
64bit values. Skip and downsample are fed to formulae so we want them
both to be unsigned. Yet absence of a user spec as well as possible user
values 0 and positive must be told apart. Use all-ones for the default
of "-1" which translates to "first timestamp", users need not be able to
specify that negative value.

Make sure to only downsample 'skip' values when the user specified some.
Which avoids the undesired insertion of huge idle gaps at the start of
the capture. An earlier implementation had to check for -1, this recent
version uses an unsigned number in combination with a boolean flag to
achieve this.

Reword some diagnostics messages, and print the samples count between
timestamps while we are here. Add a check for successful text to number
conversion of timestamp values.

How to reproduce:

  $ pulseview -i file.vcd
  $ pulseview -i file.vcd -I vcd:downsample=5
  $ pulseview -i file.vcd -I vcd:skip=111381600

Example file:

  $timescale 1 ns $end
  $scope module top $end
  $var wire 1 ! d1 $end
  $upscope $end
  $enddefinitions $end
  #111381815
  0!
  #111381905
  1!
  #111381990
  0!
  #111382075

output/srzip: queue samples before ZIP operation

Accumulate samples from multiple session feed packets before sending
them off to ZIP archive operations. This improves throughput for those
setups where acquisition devices or input modules provide only few
samples per session feed send call.

This version also splits large packets from applications into smaller
ZIP members (if the application's packet size is larger than the output
module's local buffer size). If that is not desired, the implementation
needs adjustment to immediately pass larger blocks to ZIP operations
(after potentially flushing previously queued data) instead of looping.

This fixes bug #974.

output/vcd: support analog data, more channels, minor cleanup

Extend and rephrase the VCD output module, to support mixed signal data,
support higher channel counts, and address other minor issues.

Increase the number of VCD identifiers which can get generated. Bump the
limit from 94 to 18346 channels. Prefer single letter names for backwards
compatibility for the first channels. Use two or three letter identifiers
as needed for higher channel counts.

Add support for analog channels, and carefully organize a queue such
that timestamps and their data only get written after input data for
_all_ channels was received from the session feed. Provide IEEE754
double precision values for maximum compatibility with other VCD aware
software, although sigrok internally passes analog data with single
precision. This makes potential later adjustment transparent to external
software.

Factor out and rephrase code while we are here. This implementation
avoids glib calls where they'd hurt performance. A local pool reduces
malloc() pressure to increase throughput. String manipulation is tuned
for simplicity and reduced cost. Special code paths were added to tune
the use cases where mixed signals are not involved (immediate write to
the output text, bypassing the output module's local queue).

An srzip input implementation detail still makes the VCD output consume
lots of memory during merge sort of channels' data. See bug #1566.

Other nits got addressed in bypassing: Adjust data types. Separate the
gathering of detail information and the construction of the VCD header
text to simplify review and future maintenance. Skip VCD identifiers for
disabled channels. Emit a final timestamp to flush the last sample, and
communicate the total capture length.

Update comments. Update the copyright for recent non-trivial changes.

input/vcd: rework VCD file import logic (vector, integer, real)

Extend and rework the VCD input module: accept more data types, improve
usability, fix known issues.

Add support for bit vectors (arbitrary width), multi-bit integer values
(absolute 64bit width limit, internal limitation to single precision),
and floating point numbers ('real' in VCD, single precision in sigrok).
Unfortunately sigrok neither has concepts of multi-bit logic channels
nor IEEE-1364 stdlogic values, the input module maps input data to
strict boolean and multiple logic channels. A vector's channels are
named and grouped to reflect their relation. VCD 'integer' types are
mapped to sigrok analog channels. Add support for scoped signal names,
and the re-use of one VCD signal name for multiple variables.

Rework file and text handling. Only skip pointless UTF-8 BOMs before
file content (not between sections). Handle lack of line termination at
the end of the input file. Process individual lines of input chunks,
avoid glib calls when they'd result in malloc pressure, and severely
degrade performance. Avoid expensive string operations in hot loops.

Rearrange the order of parse steps, to simplify maintenance and review:
end of section, new section, timestamp, data values, unsupported. Flush
previously queued values in the absence of a final timestamp. Unbreak
$comment sections in the data part. Apply stricter checks to input data,
and propagate errors. Avoid silent operation (weak warnings can go
unnoticed) which yields results that are unexpected to users. Unbreak
the combination of 'downsample' with 'skip' and 'compress'. Reduce noise
when users limit the number of channels while the input file contains
more data (keep a list of consciously ignored channels). Do warn or
error out for serious and unexpected conditions.

Address minor issues. Use common support for datafeed submission. Keep
user specified options across file re-load. Fixup data type nits, move
complex code blocks into separate routines. Sort the groups of routines,
put helpers first and concentrate public routines at the bottom. Extend
the builtin help text. Update comments, update the copyright for the
non-trivial changes.

Fixes bug #776 by adding support for bit vectors.
Fixes bug #1476 by flushing most recently received sample data.

input: introduce helper for buffered submission of sample data

Input modules often find themselves in the situation where sample data
was received and could be sent to the session bus, but submission should
get deferred to reduce the number of send calls and provide larger data
chunks in these calls. Introduce common support code for buffered sample
data submission (both logic and analog), provide a simple alloc, submit,
flush, and free API.

input/binary: align sr_session_send() chunks to unit size

The input/binary module chops raw input data into chunks and sends these
to the session feed. The total size of input chunks got aligned to the
unit size, the session feed output didn't. Make sure to align session
packets with the input data's unit size, too.

This fixes bug #1582.

bindings/ruby: Bump minimum requirement to Ruby 2.5.0.

This version is known to work with the current code-base and recent
SWIG versions, whereas e.g. Ruby 2.3.x is known to not work (anymore).

This "fixes" the remaining parts of bug #1526.

fx2lafw: Use 1 as default for frame limit and reset num_frames

fx2lafw: Add support for frames

When using a number of frames that is not 1, the driver will read
samples up to its limit and then wait for another trigger. This will be
repeated until the configured number of frames has been finished.

Korad-kaxxxxp: Add model Tenma 72-2550

Fix #1576 by handling DSO1000B's CHAN#:PROB? responses

serial-lcr: Allow retrieving frame limit

rigol-ds: Allow retrieving frame limit

hantek-dso: Allow retrieving frame limit

hameg-hmo: Allow retrieving frame limit

gwinstek-gds-800: Allow retrieving frame limit

scpi_usbtmc_libusb: Retry if a Bulk-IN request starts with an empty packet

This seems to make the Rigol DS1054Z work.  It's still a bit janky --
on a live capture, sample 688 (zero-based) out of the 1200-sample
frame seems to consistently contain garbage.  I'm not sure what's
going on.

scpi_usbtmc_libusb: Check that bulk in requests read the entire header

The Rigol DS1054Z sometimes returns zero bytes in response to a bulk in
request.  sigrok ends up reading out of bounds and failing ungracefully
when this happens.  Check that libusb returned a full USBTMC header and
fail gracefully if it did not.

rigol-ds: Improve short block handling

When a short block is received, clean up the header state so that the
next block can be read.

Based on a patch for #1011 by Aleksander Alsekseev.

rigol-ds: Send some commands on 1st frame only

This can speed up reading of multiple segments by a factor 2 (9s vs 18s
when reading 5 frames with 2 channels and 7 kSa)

rigol-ds: Experimental support for segmented data with PROTOCOL_V3 models

rigol-ds: Experimental support for V5 frame reading

rigol-ds: Add support for reading segmented data for protocol v4

rigol-ds: Fix reading data from internal memory

According to the programming manual, one should issue

    :WAV:RES
    :WAV:BEG

before reading data from internal memory. Without this, the wrong data
will be returned.

rigol-ds: Get correct samplerate for Memory and Segmented sources

Read it at the start of acquisition. This prevents requests for
the SR from interfering with ongoing transfers.

This fixes bug #1217.

rigol-ds: Do not stop reading after the first frame

std: avoid doube close

I want to fix this double-close issue I see with my OLS:

First close at the end of a 'scan':

sr: [00:00.045171] openbench-logic-sniffer: Got metadata key 0x00, metadata ends.
sr: [00:00.045178] openbench-logic-sniffer: Disabling demux mode.
sr: [00:00.045186] serial: Closing serial port /dev/ttyACM0.

Second one as part of hwdriver cleanup:

sr: [00:00.046088] hwdriver: Cleaning up all drivers.
sr: [00:00.046108] serial: Closing serial port /dev/ttyACM0.
sr: [00:00.046116] serial-libsp: Cannot close unopened serial port /dev/ttyACM0.

So, before closing a second time, check if the device is not idle.

I am optimistic this could fix bugs #1151 and #1275, too.

Signed-off-by: Wolfram Sang <redacted>

korad-kaxxxxp: Add KA3005P v5.5

Signed-off-by: Walter Goossens <redacted>

Revert "bindings/ruby: Disable Ruby bindings until we have a fix for #1526."

This reverts commit 49d130200dc3217f99f3f7750fbc20d6c046bcf7.

The Ruby bindings build has been fixed now.

bindings/ruby: Fix ruby SWIG bindings generation

bindings/swig/doc.py generates a swig interface file for ruby bindings
that includes docstrings with comments braces ( /* and */ ) like this:

  %feature("docstring") sigrok::Channel::type "/* Type of this channel. */\n";
  %feature("docstring") sigrok::Channel::enabled "/* Enabled status of this channel. */\n";

SWIG generates *.cxx and adds its own braces to the docstring:

/*/* Document-class: Sigrok::Error
Exception thrown when an error code is returned by any libsigrok call. */
*/

this causes compilation error for Ruby bindings.

To fix the error we should not add extra braces to the docstring.
With this patch libsigrok compiles fine with with ruby 2.7 and swig 4.0.2.

Fixes bug #1526

Signed-off-by: Anatol Pomozov <redacted>

openbench-logic-sniffer: improve error messages when scanning ID

- always say 'ID' when the ID command failed
- print hexdump of a faulty ID because on a stalled device we may get
  0x00 bytes which would terminate the string early.

Signed-off-by: Wolfram Sang <redacted>

kingst-la2016: improved bitstream upload and fix for v3.4.2

of vendor's bitstream.
is now tested to work with version 3.4.0 and 3.4.2.

[fixes #1559]

udev: Add Kingst LA2016 VID/PID.

kingst-la2016: Use ARRAY_SIZE.

kingst-la2016: tested with idVendor=77a1, idProduct=01a2

rdtech-tc: Add initial support for the RDTech TC66C

This changeset adds support for the RDTech TC66C USB power meter.

Currently, the driver reports the following channels:
  * V: VBus voltage
  * I: VBus current
  * D+: D+ voltage
  * D-: D- voltage
  * E: Energy consumed in threshold-based recording mode.

The number of significant digits shown for each channel has been set
to match the number of digits shown on the device.

Usage example:

sigrok-cli -d rdtech-tc:conn=/dev/ttyACM0 --scan

Known issues:

  * BLE support is currently unimplemented. This uses a different
    command set, but the same poll data format.

Kudos to Ben V. Brown for reverse engineering some of the protocol and
documenting the encryption key used for poll data.

Signed-off-by: Andreas Sandberg <redacted>

src/crc.c: Add missing file.

crc: Factor out CRC16 implementation from Modbus

Being able to calculate a CRC16 is useful in multiple places, factor
this into a new module with CRC implementation. This module currently
only supports ANSI/Modbus/USB flavor of CRC16.

Signed-off-by: Andreas Sandberg <redacted>

rdtech-um: Add initial support for the RDTech UMxx series

This changeset adds support for the RDTech UMxx series of USB power
meters. The driver has been tested with the RDTech UM24C, but should
support the UM24C, UM25C, and the UM34C.

Currently, the driver reports the following channels:
  * V: VBus voltage
  * I: VBus current
  * D+: D+ voltage
  * D-: D- voltage
  * T: Device temperature
  * E: Energy consumed in threshold-based recording mode.

The number of significant digits shown for each channel has been set
to match the number of digits shown on a UM24C.

Missing features:

  * There is currently no support for configuring threshold-based
    recording from sigrok, but this can be done on the device itself.

  * Fast charging mode currently not logged.

Usage example:

sigrok-cli -d rdtech-um:conn=bt/rfcomm/MAC --scan
sigrok-cli -d rdtech-um:conn=/dev/rfcomm0 --scan

Known issues:

  * When using sigrok's Bluetooth transport implementation, the device
    is disconnected between probing and sampling. Some devices (e.g.,
    the UM24C), dislikes this and can't be reconnected reliably for
    sampling. This is not an issue when setting up a rfcomm device
    manually and using it as a serial port.

Kudos to Sven Slootweg for documenting most of the protocol.

Signed-off-by: Andreas Sandberg <redacted>

binary_helpers: Drop unnecessary malloc check.

(as per HACKING)

binary_helpers: Add helper for devices with binary data

Many devices receive a struct with binary values when polled. Many of
these values will correspond channels in sigrok. This
change introduces helper functions for automatically reading and
scaling such values and sending them down a sigrok analog channel.

Signed-off-by: Andreas Sandberg <redacted>

libsigrok.h: Add SR_MQ_ENERGY

uni-t-ut181a: comment on how to start a recording

The meter allows remote controlled start of recordings, but requires a
few parameters where it's uncertain how to most appropriately get these
by means of SR_CONF_* keys.

Introduce SR_CONF_SET support for SR_CONF_DATALOG to raise awareness,
but leave the implementation empty for now. Leave a TODO comment which
discusses the meter's commands that one might want to use from here.

uni-t-ut181a: implement device driver for the UNI-T UT181A multimeter

Extend the previously introduced skeleton driver for UNI-T UT181A. Introduce
support for the full multimeter's protocol as it was documented by the ut181a
project. Which covers the retrieval of live readings, saved measurements, and
recordings, in all of the meter's modes and including relative, min/max, and
peak submodes. This implementation also parses compare mode (limits check)
responses, although it cannot express the result in terms of the session feed.

Announce the device as a multimeter as well as a thermometer, it supports
up to two probes including difference mode. When in doubt, prefer usability
over feature coverage (the driver side reflects all properties of the meter,
but not all features can get controlled by the driver). The probe routine
requires that users specify the serial port, and enable serial communication
on the meter.

Several TODO items remain. Comments in the driver code discuss limitations
of the current implementation, as well as cases where the meter's features
don't map well to sigrok's internal presentation. This implementation also
contains (optional, off by default) diagnostics for research on the serial
protocol.

uni-t-ut181a: Initial driver skeleton.

asix-sigma: discuss usability of data pattern trigger specs

When data patterns for trigger specs span multiple bits, users may not
want to specify long lists of "<ch>=<lvl>" conditions for sigrok-cli's
--trigger option, and count channels by hand. Or click a dozen dialogs
to specify one data pattern, or modify a previous specification. Setups
with few traces may accept that, "data heavy" setups like parallel data
or address bus inspection may not.

Add comments which discuss the potential use of SR_CONF_TRIGGER_PATTERN.
Outline a syntax which may be flexible enough _and_ acceptable to users,
support data patterns and edge triggers alike, in several presentations
that serve different use cases.  This commit exclusively adds comments,
does not change behaviour.

Update a comment in the user spec to internal format trigger spec parser
to expand on hardware constraints and implementation limitations. Rename
an identifier which checks the number of edge conditions, not the number
of accepted trigger spec details.

asix-sigma: unconditionally re-enable trigger support code

Trigger support became operational again. Drop the compile time switch
which disabled the previously incomplete implementation.

This resolves bug #359.

asix-sigma: complete and extend capture mode supervision

Parse trigger specs early when acquisition starts, timeout calculation
needs to reflect on it. Either immediately start an acquisition timeout
for trigger-less configurations. Or prepare a timeout which spans the
post-trigger period, but only start its active period when the trigger
match was detected by the device's hardware.

Extend mode tracking during acquisition to handle other special cases.
Terminate acquisition when the user specified sample count limit exceeds
the hardware capacity, or when no limits were specified and the device's
memory is exhausted.

There is a slight inaccuracy in this approach, but the implementation
fails on the safe side. When both user specified limits and triggers are
involved, then at least the user specified time or sample count span is
provided. Usually more data is sent to the session feed, and all of the
requested period is covered. This is because of the software poll period
and the potential to start the timeout slightly late. As well as having
added some slack for hardware pipelines in the timeout calculation.

asix-sigma: download sample memory in multiple receive calls

The previous implementation ran the complete sample memory retrieval
in a single call to the receive callback. Which in combination with
slow USB communication and deep memory could block application logic
for rather long periods of time.

Rephrase the download_capture() routine such that it can spread its
workload across multiple invocations. Run the acquisition stop and
resource allocation for the download, the interpretation of a set of
DRAM lines, and the resource cleanup, as needed. And keep calling the
download routine until completion of the interpretation of the sample
memory region of interest. The workload size per invocation may need
more adjustment.

The previous implementation could stall UI progress for some 20-30s.
This change lets users perceive UI progress while sample memory gets
retrieved and interpreted.

This resolves bug #1005.

asix-sigma: drop obsolete "trigger countdown" in sample interpretation

Recent commits added "position tracking" for interesting spots in the
sample stream and the current iteration pointer. Which obsoletes the
counters for remaining items until trigger, the "triggered here" flags,
as well as the unfortunate "rewind a little" workaround which lacked a
comment on its motivation or implementation details.

asix-sigma: re-enable software check for exact trigger position

The hardware provided trigger match location is inaccurate. Do check
sample values against the initial trigger condition spec for a short
range of the retrieved sample data, to refine the trigger marker's
position which is sent to the session feed.

Temporarily ignore the optional sample count limit for trigger-using
acquisitions, to reduce the diff size and simplify review. Since the
hardware transparently compresses sample data, we cannot reliably
determine where to start the download and interpretation of sample data,
and the submission to the session feed. Starting early in the sample
memory content, and sticking with the strict sample count limit, could
clip submission before the actual trigger position.

This implementation provides _at least_ the requested amount of data,
and does cover the spot of interest (the trigger position). This, and
the trigger support's having become operational again, is considered an
important improvement. The inaccuracy is considered acceptable for now.
Trigger-less acquisition does enforce the exact sample count limit.

asix-sigma: rephrase sample memory iteration position and trigger check

Rephrase how the sample memory iteration position gets tracked, increment
after every event slot already. Update the "last seen sample" status more
often (an event slot can hold several sample items). Arrange for a period
of time where software will check sample data for trigger matches. This
improves the precision of the hardware provided trigger match location.

Do send hardware provided trigger locations to the session feed even if
the software check found no match on the data content. This covers user
initiated button presses (which can unblock the acquisition when the
application provided trigger condition never matches).

Note that this implementation does manage the window of supervision, but
does not yet check the sample values against the trigger condition. This
gets added later.

asix-sigma: rework outer sample download loop (DRAM lines iteration)

Factor USB data transfer out of the code path which interprets sample
memory content. Keep internal state of sample memory download in the
device context. This eliminates local variables, and ideally allows a
future implementation to spread chunked downloads across several read
callbacks, which would improve UI responsiveness.

Update comments while we are here. Address minor portability nits (ull
suffix vs UINT64_C macro). The inner loops (iterating clusters and their
events which contain individual samples) are not affected by this commit.

asix-sigma: more trigger LUT download rephrase, think 16bit entities

Further rephrase the sigma_write_trigger_lut() routine. It's helpful to
"think" in BE16 quantities to improve readability of LUT address and
parameter downloads. Better matches the vendor's documentation. Also use
a better name for the "trigger select 2" register content.

asix-sigma: concentrate more sample memory interpretation params

Start moving parameters into the device context which are related to the
interpretation of sample memory content. This can simplify error paths,
allow to release resources late. And ideally sample memory download and
interpretation could spread across several receive callbacks, improving
UI responsiveness. Also makes total and current dimensions available to
deeper nesting levels in the interpretation, which currently don't have
access to these details.

asix-sigma: concentrate parameters for sample memory interpretation

Create a sub struct in the device context which keeps those parameters
which are related to sample memory interpretation. Which also obsoletes
the 'state' struct and only leaves the 'state' enum as a remainder.

Use the "samples per event" condition instead of the samplerate when
extracting a number of samples from an event's storage. Rename the
de-interleaving routines to better reflect their purpose.

asix-sigma: force strict boolen arith in LUT item manipulation

Mechanically adjust the add_trigger_function() routine to address nits,
attempt to improve maintainability.

Raise awareness of the fact that strict binary arithmetics is done (bit
operators are used), the strict 0..1 set of values needs to be enforced,
and mere "logical truthness" is not good enough in this spot. Explicitly
check for bit positions instead of "shifting out" the bit of interest
and have the 0/1 value result nearly by coincidence.

Extend comments. Group related instructions and separate them from other
groups. Reduce the scope of the rather generic i, j, tmp named variables
which are just too easy to get wrong.

asix-sigma: use more helpers for bit mask creation

Rename macros to better reflect which of them check a bit position, and
which span a bit field of given width. Adjust more call sites to use the
macros. This takes tedium out of maintenance as well as review. Has the
minor benefit of somewhat shortening text lines, and eliminating nested
parentheses (or getting perceived as if it would).

asix-sigma: rephrase limits management, use sub structure

Move the acquisition limits related variables into a sub struct within
the device context. Over time they became numerous, and might grow more
in the future.

asix-sigma: track whether triggers were specified when acquisition started

There are several separate conditions which the driver needs to tell
apart. There is a compile time switch whether trigger support shall be
built in. There is the condition whether acquisition start involved a
user provided trigger spec. And there is the hardware flag whether a
previously configured trigger condition matched and where its position
is.

Only accept user provided trigger specs when trigger support is builtin.
(The get/set/list availability and spec passing is done in applications
outside of the library, we better check just to make sure.) Only setup
the trigger related hardware parameters when a spec was provided. Only
check for trigger positions when the hardware detected a match.

asix-sigma: enable trigger support code (development HACK)

Enable the compile time option which builds trigger support code into
the asix-sigma driver. This is a development hack. Trigger support in
the driver is incomplete and currently not operational.

asix-sigma: data type nits, minor variable renames

Address remaining data type nits. Use more appropriate types for sizes
and counters and indices, as well as for booleans.

Prefer more verbose variable names in a few spots to avoid the rather
generic 'i' symbol, especially in complex code paths with deeply nested
flow control or with long distances between declaration and use. Re-use
an existing buffer in the acquisition start for command sequences which
setup trigger in/out as well as clock parameters.

Introduce some variables which may seem unnecessary. But these are
useful for research during maintenance.

This is a mechanical adjustment, behaviour does not change.

asix-sigma: prepare configuration re-use across sigrok sessions

Introduce the required infrastructure to store successfully applied
configuration data in hardware registers. This lets the probe phase of
the next sigrok session pick up where the previous session left. Which
improves usability, and increases performance by eliminating delays in
the acquisition start, by not repeating unnecessary firmware uploads.

The vendor documentation suggests there would be FPGA registers that are
available for application use ("plugin configuration"). Unfortunately
experiments show that registers beyond address 0x0f don't hold the data
which was written to them. As do unused registers in the first page. So
the desirable feature is not operational in this implementation. There
could be different netlist versions which I'm not aware of, or there
could be flaws in this driver implementation. This needs more attention.

asix-sigma: nits in the hardware configuration declaration

Stop assuming that C language variables whould have a specific memory
layout that applications could rely on. Use normal data types in higher
abstraction layers, drop non-portable bit fields. Use existing macros
for the creation of bit masks of a given width.

sw_limits: start msec timeout period only after start() call

When application code used the common SW limits API, the call sequence
of init() then set() then check() already kept expiring, which is rather
unexpected. The timeout period should only start when start() is called,
check() should not signal expiration before the start() call.

The specific use case is the combination of an msecs timeout and capture
ratio when triggers are used. The post-trigger period only starts when
the trigger match was seen, even though its length is already known when
the acquisition starts. It's desirable to run the start() call for the
post-trigger timeout late, and not terminate the acquisition before the
trigger match.

serial: accept bitrate only serialcomm= spec, default to 8n1 frames

The previous implementation considered both the UART bitrate and the
frame format mandatory, users had to specify "/8n1" as well just to
change the bitrate.

This commit makes the frame format optional, and defaults to 8n1 which
is so popular these days. When specified, the frame format still needs
to preceed the other optional flow and handshake flags, for maximum
backwards compatibility, and equal robustness in the process of parsing
serialcomm= specs.

Unfortunately device drivers cannot specify their preferred or default
UART frame format. Which means that users still need to provide these
when a device does not use 8n1. This is not a regression, the previous
implementation always needed the frame format spec.

asix-sigma: update comment on channel names (vendor doc says "1-16")

Eliminate doubt from a comment on ASIX SIGMA's channel names which was
introduced in commit d261dbbfcc73. Publicly available documentation does
agree their names start at "1" and go up to "16".

asix-sigma: add support for external clock

The 50MHz netlist supports the use of an external clock. Any of the 16
channels can use any of its edges to have another sample taken from all
the other pins. It's nice that the hardware does track timestamps, which
results in an exact reproduction of the input signals' timing with 20ns
resolution, although the clock is externally provided and need not have
a fixed rate.

asix-sigma: more trigger spec to register values conversion sync with doc

Rephrase more parts of sigma_build_basic_trigger() to closer match the
vendor documentation. Use the M3Q name. Be explicit about "parameters"
setup (even if that means to assign zero values, comments help there).
Using three BE16 items for the parameters improves readability.

asix-sigma: rephrase trigger LUT creation (mechanical change)

Rephrase the sigma_build_basic_trigger() and build_lut_entry() routines
to hopefully improve readability. Avoid the use of short and generic
identifiers which are just too easy to confuse with each other and the
1 literal and negation operator in deeply nested loops and complex
expressions that span several text lines. Reduce indentation where
appropriate. Concentrate initialization and use of variables such that
reviewers need less context for verification.

This is a purely mechanical change, the function of triggers remains
untested for now. Setting "selres" in that spot is suspicious, too.

asix-sigma: rephrase trigger LUT upload to hardware for readability

Rephrase the sigma_write_trigger_lut() routine to work on "a higher
level" of abstraction. Avoid short and most of all generic variable
names. Use identifiers that are closer to the vendor documentation.

asix-sigma: rephrase and extend register access for readability

Reduce the probability of errors during maintenance, and also increase
readability. Replace open coded nibble extraction and bit positions by
accessor helpers and symbolic identifiers. Adjust existing math where it
did not match the vendor documentation. Always communicate 8bit register
addresses, don't assume that application use remains within a specific
"page". Provide more FPGA register access primitives so that call sites
need not re-invent FPGA command sequence construction. Remove remaining
open coded endianess conversion in DRAM access.

asix-sigma: rephrase firmware dependent param upload at acquisition start

The 100/200MHz supporting FPGA netlists differ in their register set
from 50MHz netlists. Adjust the parameter download at acquisition start.

Raise awareness of the "TriggerSelect" and "TriggerSelect2" difference
(the former only exists in 50MHz netlists, the latter's meaning differs
between firmware variants). "ClockSelect" semantics also differs between
netlists. Stop sending four bytes to a register that is just one byte
deep, channel selection happened to work by mere coincidence.

Eliminate a few more magic numbers, unobfuscate respective code paths.
Though some questions remain (trigger related, not a blocker for now,
needs to get addressed later).

asix-sigma: keep remaining samplerate handling in protocol.c

Make the list of supported samplerates an internal detail of the
protocol.c source file. Have the api.c source file retrieve the list
as well as the currently configured value by means of query routines.

Ideally the current rate could get retrieved from hardware at runtime.
A future driver implementation could do that. This version sticks with
the lowest supported rate, as in the previous version.

asix-sigma: cosmetics, sort protocol.h function groups

Sort "semi public" routines and "global data" of the asix-sigma driver
in the protocol.h header file by their use. Add comments. This improves
maintenance of the driver source.

asix-sigma: prepare FTDI open/close for "optional open"

Move all of the FTDI connection handling from api.c to protocol.c, and
prepare "forced" and "optional" open/close. This allows future driver
code to gracefully handle situations where FPGA registers need to get
accessed, while the caller may be inside or outside the "opened" period
of the session. This is motivated by automatic netlist type and sample
rate detection, to avoid the cost of repeated firmware uploads.

asix-sigma: improve error propagation, increase robustness

Detect more error conditions, and unbreak those code paths where wrong
data was forwarded. It's essential to tell the USB communication layer,
sigrok API error codes, and glib mainloop receive callbacks apart. Since
the compiler won't notice, maintainers have to be extra careful.

Rephrase diagnostics messages. The debug and spew levels are intended
for developers, but the error/warn/info levels will get presented to
users, should read more fluently and speak from the application's POV.
Allow long text lines in source code, to not break string literals which
users will report and developers need to search for (this matches Linux
kernel coding style).

This commit also combines the retrieval of sample memory fill level,
trigger position, and status flags. Since these values span an adjacent
set of FPGA registers. Which reduces USB communication overhead, and
simplifies error handling. The helper routine considers the retrieval
of each of these values as optional from the caller's perspective, to
simplify other use cases (mode check during acquisition, before sample
download after acquisition has stopped).

INIT pin sensing after PROG pin pulsing was reworked, to handle the
technicalities of the FTDI chip and its USB communication and the FTDI
library which is an external dependency of this device driver. Captures
of USB traffic suggest that pin state is communicated at arbitrary times.

asix-sigma: style nits, expression complexity, information locality

Address minor style nits to improve readability and simplify review. The
sizeof() expressions need not duplicate data type details. Concentrate
the assignment to, update of, and evaluation of variables in closer
proximity to reduce potential for errors during maintenance. Separate
the gathering of input data and the check for their availability from
each other, to simplify expressions and better reflect the logic's flow.