ols: move device context creation from protocol.c to api.c

The get_metadata() routine was unfortunately named, and surprisingly did
more than its name suggested. Rename the routine to contain the ols_
prefix. Run communication to the device in protocol.c, but keep sdi and
devc creation in api.c where they are expected during maintenance. This
"unhides" where stuff is happening, and eliminates redundancy between
the models which support meta data to announce their features, and other
"compatibles" which are covered by generic fallback data.

kingst-la2016: add support for "probe names" scan option

Add support for the SR_CONF_PROBE_NAMES scan option. Optionally assign
user specified channel names instead of the driver's builtin names.

fx2lafw: add support for "probe names" scan option

Add support for the SR_CONF_PROBE_NAMES scan option. Optionally assign
user specified channel names instead of the driver's builtin names.

It's essential to create sdi and devc before scanning the probe names
spec. The previous logic which printed channel names to a local buffer
got replaced by a const table of channel names. This commit is a little
longer because checks are added, to make sure that future models with
more channels won't exceed the static const tables.

This implementation exclusively allows to specify logic channel names.
Analog channels keep the open coded naming pattern. Because the driver
supports different models with differing numbers of channels of several
types, covering analog channels in the "probe names" feature requires
more runtime effort to create the table of default channel names for the
specific device that was found. This remains as an option for a later
commit.

asix-sigma: add support for "probe names" scan option

Add support for the SR_CONF_PROBE_NAMES scan option. Optionally assign
user specified channel names instead of the driver's builtin names.

This commit is a little more involved because channel names are also
referenced as external clock source. The lack of 'const' decoration in
the glib API and the presence of 'const' in the std_*() routines require
some intermediate storage and casts and duplicate length determination.
This is considered more desirable than a redundant length field in devc.

asix-omega-rtm-cli: add support for "probe names" scan option

Add support for the SR_CONF_PROBE_NAMES scan option. Optionally assign
user specified channel names instead of the driver's builtin names.

strutil: add common parse logic for SR_CONF_PROBE_NAMES input specs

Add the public sr_parse_probe_names() and sr_free_probe_names() routines
so that device drivers can share a maximum amount of support code. The
input spec can either carry a list of names for individual signals, or
aliases can expand to a set of multiple signals which e.g. correspond
to a protocol or other popular/typical sets of signals. Which increases
usability. Order of items is arbitrary, recursion is not supported (yet
this internal implementation detail may change in a future version).

In the absence of an SR_CONF_PROBE_NAMES value the driver's list of
channel names is returned. Which yields completely backwards compatible
behaviour -- drivers can unconditionally call the parse routine. In the
presence of a configuration value the user spec is taken, aliases get
expanded (alias lookup is case insensitive).

Calling drivers can either have the list capped to a maximum size (pin
count is a natural limit), or get the result of whatever the user has
specified (dynamic size, grows as specs require). The user's probe names
by default get padded with the device's builtin probe names, unless the
spec starts with a '-' (dash), then exclusively the specified signal
names are used.

Calling code which resides in individual device drivers remains minimal.
Behaviour of individual drivers should be identical or very similar from
the user's perspective. The implementation is not tuned for performance,
the logic only executes once during device scan and is not sensitive.

This implementation supports the following aliases for maximum user's
convenience, covering the libsigrokdecode supported protocols with many
signals or with complicated names: ac97 i2c ieee488 jtag jtag-opt lpc
lpc-opt mcs48 microwire sdcard_sd seven_segment spi swd uart usb z80.
The "-opt" variants carry more optional signals which users may want to
inspect sometimes, while often the low logic channel count of typical
devices severely constraints how many signals can get assigned. Let
users pick what they prefer. A mix of a non-opt alias plus a few hand
listed extras is another option.

Adding more aliases is straight forward, and transparently benefts all
participating device drivers.

Outside of isolated inspection of a single protocol (special purpose
traffic recorders), combinations are useful as well to quickly assign
many signals in complex MCU setups which then require fewer adjustment
than full manual configuration:

  $ sigrok-cli -d ...:probe_names=jtag,rtck
  $ sigrok-cli -d ...:probe_names=spi,i2c,uart,r,g,b,clock,data,usb
  $ sigrok-cli -d ...:probe_names=ieee488,uart,led
  $ pulseview -d ...:probe_names=ieee488,uart,led

hwdriver: introduce SR_CONF_PROBE_NAMES config key (scan option)

Device drivers assign a fixed set of probe names during scan. Users can
rename previously created channels in the GUI as well as in the CLI,
though this is tedious, and depends on the application, as well as
depends on the names which the driver initially used to assign. Manual
assignment of protocol decoder inputs to device channel names is as
tedious.

Introduce the SR_CONF_PROBE_NAMES scan option, which assigns the user
provided names to the device's probes during scan already (for those
drivers which support the option). This commit declares the config key
but does not affect any driver yet.

serial_hid: improve and tighten "find USB" for the HID transport

The .find_usb() method of the HID transport previously returned
connections which lacked the "hid/" prefix and chip type, thus could
later not be used with open() and data communication calls. Add the
missing decoration.

As a minor optimization, lookup the chip type and name from the caller's
VID:PID pair already if it's specific enough, still lookup the chip for
every enumerated device if the caller's VID:PID pair is unspecific.

Tighten the result set of the HID transport's USB search. Only return
connections which involve one of the supported chips. The other devices
very probably cannot be used to connect to measurement equipment anyway,
listing mice and keyboards and other unrelated stuff was found to be not
so useful.

serial_hid: restrict .list() result set, supported chips only

The --list-serial output was excessively large for the HID transport,
listing mice and keyboards and other stuff that could never by used
for serial communication. Especially when one device provided multiple
interfaces, and on Windows where paths are rather long by default.

Limit the result set of the HID transport's .list() operation. Only
consider connections that we know how to communicate to (supported
chip type). The others are not usable anyway, so there is no point in
presenting them to the user.

microchip-pickit2: silence compiler warnings (NULL dereference)

Check pointers for validity before dereferencing them. This silences the
following compiler warnings:

../src/hardware/microchip-pickit2/api.c:275:8: warning: Access to field 'conn' results in a dereference of a null pointer (loaded from variable 'sdi')
                if (!sdi->conn)
../src/hardware/microchip-pickit2/api.c:281:10: warning: Access to field 'samplerates' results in a dereference of a null pointer (loaded from variable 'devc')
                rate = devc->samplerates[devc->curr_samplerate_idx];
../src/hardware/microchip-pickit2/api.c:287:11: warning: Access to field 'captureratios' results in a dereference of a null pointer (loaded from variable 'devc')
                ratio = devc->captureratios[devc->curr_captureratio_idx];

korad-kaxxxxp: silence compiler warning (unused value)

Do inspect the return value of the routine which sends the command
before retrieving the response. This silences the following warnings:

../src/hardware/korad-kaxxxxp/protocol.c:179:3: warning: Value stored to 'ret' is never read
                ret = korad_kaxxxxp_send_cmd(serial, "IOUT1?");
../src/hardware/korad-kaxxxxp/protocol.c:184:3: warning: Value stored to 'ret' is never read
                ret = korad_kaxxxxp_send_cmd(serial, "ISET1?");
../src/hardware/korad-kaxxxxp/protocol.c:189:3: warning: Value stored to 'ret' is never read
                ret = korad_kaxxxxp_send_cmd(serial, "VOUT1?");
../src/hardware/korad-kaxxxxp/protocol.c:194:3: warning: Value stored to 'ret' is never read
                ret = korad_kaxxxxp_send_cmd(serial, "VSET1?");
../src/hardware/korad-kaxxxxp/protocol.c:202:3: warning: Value stored to 'ret' is never read
                ret = korad_kaxxxxp_send_cmd(serial, "STATUS?");

dmm/eev121gw: silence compiler warning (unused value)

Silence a compiler warning about not using an assigned value in later
instructions. This is about the EEVBlog 121GW meter's date and device
number in received serial packets, which are worth keeping around for
future versions of the driver.

../src/dmm/eev121gw.c:728:2: warning: Value stored to 'raw_serial' is never read
        raw_serial = RB32(&buf[OFF_SERIAL_3]);

dmm/bm86x: improve robustness of secondary display parsing

Return with unset MQ when parsing the number value for the secondary
display of BM86x fails. So that no invalid measurement result gets sent
to the session bus.

Reported-By: a helpful compiler warning
../src/dmm/bm86x.c:290:3: warning: Value stored to 'ret' is never read
                ret = brymen_bm86x_parse_digits(&buf[9], 4, txtbuf,

serial_hid: silence compiler warning (unused value)

Silence a compiler warning about assigning a value to a variable that's
not used in subsequent instructions. This 'have_chip' condition is worth
keeping around, in case the HID chip search code receives updates later.
Removing the assignment may complicate maintenance, or result in
incomplete diagnostics during research.

../src/serial_hid.c:1066:3: warning: Value stored to 'have_chip' is never read
                have_chip = 1;

serial_bt: silence compiler warning (unused value)

Drop assignments of values to variables which never took effect. Drop
assignments which strictly speaking were not required, but were added in
the past to silence warnings in different compiler versions.

../src/serial_bt.c:168:2: warning: Value stored to 'type' is never read
        type = SER_BT_CONN_UNKNOWN;

../src/serial_bt.c:507:2: warning: Value stored to 'now_us' is never read
        now_us = 0;     /* Silence a (false) compiler warning. */

Shuffle variable declarations into the rough order in which they are
used in the function's body.

uni-t-dmm: sort supported devices, sort in the ut71x group

uni-t-dmm: sort supported devices, sort in the fs9721 group

uni-t-dmm: sort supported devices, sort in the es519xx group

Sort the items in the uni-t-dmm driver's es519xx group.

uni-t-dmm: sort supported devices, collect the vc870 group

uni-t-dmm: sort supported devices, collect the fs9922 group

uni-t-dmm: sort supported devices, collect the es519xx group

uni-t-dmm: sort supported devices, collect the ut71x group

uni-t-dmm: sort supported devices, collect the fs9721 group

Sort the list of supported devices in the uni-t-dmm driver, for easier
synchronization to the serial-dmm list of devices. This commit takes
care of fs9721 items (collects them in a group, still unsorted for now).

hameg-hmo: re-add 20V/div and 50V/div vertical scales (RTB2K)

The absence of the 20V and 50V choices in the driver resulted in failed
probe/scan when the device happened to be configured to these values
(which is more probable with disabled channels). Re-introduce vdivs[]
items which unconditionally were removed in commit 4f3cb1eaf727. Use
them for RTB2K models, stick with at most 10V/div for all other models
to remain compatible with the previous implementation.

[ use 'git diff -U25' to see the models and verify the change ]

scpi: comment on indefinite length block data (unsupported here)

It's fine that the current SCPI implementation in libsigrok exclusively
supports definite length block response data. It is what most supported
devices or all of them are speaking. But the implementation of the
indefinite length case assumed that the block is empty when the response
starts with #0, and returned successful although receive data was not
taken at all.

Rephrase the test condition for successful reception. Return an error
code in the unsupported case. Emit an error message to remain aware. Let
users report when that communication pattern is seen in the field. Add
comments with references to the specs, in case the feature will receive
support later.

ols: also reflect successful identify response in diagnostics

The ols driver's scan() routine used to present the identification
response to users when the scan failed, but would not when the scan
succeeded.

Since multiple response literals are supported, it's considered useful
to see these, too, in case of successful device detection. Emit debug
messages for developers' awareness.

ols: make connection ID available

Implement a getter for the SR_CONF_CONN config key in the ols driver.

resource: add support for SIGROK_FIRMWARE_PATH env variable

The optional SIGROK_FIRMWARE_DIR environment variable accepts a single
directory specification. The SIGROK_FIRMWARE_PATH variable accepts a
list of directories to search firmware images. The list separator is
platform dependent (colon or semicolon). Empty items are explicitly
ignored. Both variables get evaluated. Behaviour remains backwards
compatible, just gets extended for increased usability.

usb: move connection string parsing out of USB enumeration/search

The sr_usb_find() routine inspects an input specification in textual
format, as well as scans for USB devices that match the caller specified
address. Factor out the text parsing including range checks for address
numbers. This part of the source code also does not depend on the libusb
library's availability.

Adjust the sr_usb_find() routine's data types for result variables. This
commit changes user visible diagnostics messages, since text parsing and
USB device lookup happen in distinct locations and don't share knowledge.

input/wav: undo "create channels once" workaround

Undo the essence of commit 9e850040db5c which added a workaround to
create sigrok channels only once, and keep reusing them across every
file import (without checking details). Which was obsoleted by the
recent channel list check on file re-load, including proper response
when essential file properties have changed.

Indentation changes. See a whitespace ignoring diff for the essence.

input/wav: add channel list checks for file re-read

Do for the WAV input module what commit 08f8421a9e82 did for VCD. Check
the channel list for consistency across re-imports of the same file.
This addresses the WAV part of bug #1241.

This commit also changes the WAV module's reset() method's behaviour.
The previous implementation only created channels once, and re-used that
channel list when the file got re-read. Which could cause issues when
the file's properties changed between re-runs. This implementation
always creates the channel list upon every file import, and ensures a
consistent channel list across re-imports. This follows the approach
that was taken in all other input modules before.

drivers: update comment on "driver list" linker section

Update and slightly extend the comment on the "__sr_driver_list"
linker section which holds a list of all drivers which were built
into the libsigrok library.

serial-dmm: fix typo in comment

dmm/bm86x: check more bytes in DMM packet (undocumented by vendor)

User johnch reported via IRC that bm86x meters can lose sync to the
packet stream which goes unnoticed and tries to process invalid data.

Tighten the packet validity check, compare four bytes of the third chunk
in the DMM packet. This improves reliability, but isn't backed by vendor
documentation. It's yet to get determined whether other existing devices
don't provide the four-byte magic pattern.

scpi-dmm: add "switch to local" support for Agilent protocol

Send "SYST:LOC" to Agilent protocol speaking scpi-dmm devices at the end
of the probe (--scan) as well as in close (--show, --samples, etc). This
ends "remote" and re-enters "local" mode after programmatic use. Should
increase usability, eliminates the need for manual intervention before
subsequent DMM use. Was tested with a Keysight DMM. Does not affect the
HP protocol speaking devices.

korad-kaxxxxp: add an entry for Korad KD3005P V4.1

Renames the previous entry to _V20, and adds _V41 to the list.

[ gsi: squash commits, fixup whitespace, sort order, reword message ]

strutil: avoid glib/platform conversion calls for empty input

It appears that either glib or some underlying platform library code for
text to number conversion yields unexpected values for return codes,
errno, and "end pointer" when _none_ of the input could get converted.
This was reported for MacOS, did not reproduce on Linux. The reported
issue was addressed in commit 51bf39a1633c, this implementation is just
much more conservative and hopefully easier to verify since it's more
explicit.

Rephrase the rational text to number conversion to avoid the problematic
input cases. Address style nits while we are here in the hope to improve
readability: Move initial assignment and subsequent updates of variables
closer together for easier verification.

Accept optional leading whitespace. Accept numbers like "123." in
addition to the previously supported ".123" formats. But insist that one
of the integral or fractional parts must be present. Try harder to setup
non-zero errno values for other failed conversion attempts beyond failed
library calls (the strtol(3) manpage suggests so in the ERRORS section).

This implementation passes on Linux, but has not been tested with MacOS
which appears to have a pickier library implementation.

hp-3478a: Handle NULL dereference in read, write and list.

hp-3478a: revert the recent NULL dereference check in config API routines

Undo commit 020df861e0eb before replacing it with something better.

device: don't accept empty names for sigrok channels

It's unexpected when sigrok channels "have no name". Previous versions
would not strictly enforce non-empty names and could let empty names
slip in, but application code was reported to be confused when it
happened. The benefit of having channels "with no names" is questioned.

Adjust the public API routines. Accept missing name specs in the
sr_channel_new() routine for maximum backwards compatibility. Reject
missing names in sr_dev_channel_name_set() so that empty or non-empty
names can only be replaced by non-empty names. Check the return code of
sr_channel_new() in sr_dev_inst_channel_add() so that failed channel
creation gets propagated to callers. The current implementation will
never fail sr_channel_new(), but future versions might.

None of libsigrok code (device drivers, input modules) assign empty
names to channels. Applications still need to get checked. A future
commit might make names in sr_channel_new() mandatory.

dmm/bm52x: silence compiler warning related to printf() buffer size

Increase another text buffer's size to cover the maximum length that an
integer could occupy in theory. Which amends commit 46a36bf0bb2e.

The previous implementation did not suffer from any issue, we know the
number of recordings in the BM52x DMM to remain small. This change only
silences a compiler warning, doesn't change the parser's behaviour.

README.devices: mention that kingst-la2016 requires firmware files

README.devices: explicitly discuss serial-over-HID in the UNI-T section

This amends commit f736691d1323. Explictly mention that USB cables for
UNI-T devices and rebrands transparently work with libsigrok's serial
communication over HID cables. Mention that uni-t-dmm is redundant.

input: decorate sr_input_find() parameter as const

The caller's input module name is only read for comparison. Decorate it
with the 'const' attribute to simplify calling application code.

README.devices: add an UT-D04 on Windows section (libwdi and hidapi)

A user reported that the Windows driver which is assigned to the CH9325
based UT-D04 cable neither provides a genuine serial port nor shows up
in the sigrok enumeration which additionally uses HIDAPI. Mention that
assigning a different Windows driver can help in that case.

README.devices: add Windows and Zadig discussion near the udev section

Add a section on Windows and device driver assignments by means of Zadig
after the section on Linux udev rules and permissions. Reference the
wiki page for the Windows platform.

README: Mention optional nettle dependency.

One of the USB load drivers depends on the nettle library. Add it to the
README file as another optional dependency.

configure.ac: consider libusb_os_handle absence non-fatal on Windows

Keep checking for the libusb_os_handle data type's presence, but don't
consider its absence on Windows fatal. Recent mainline libusb provides
something similar to the event abstraction branch under the common API.
Assume that it's the integrators' or packagers' responsibility to either
use a recent library or a patched older library for sigrok builds.

All other non-Windows platforms remain unaffected, the presence check
never was fatal there. The data type check itself needs to remain in
place because the usb.c source code adjusts to its presence.

hp-3478a: use symbolic name for status register bit field

The hp_3478a_receive_data() routine uses SPOLL to only communicate
measurement data when they have become available. Use a symbolic name
for the tested bitfield for consistency with other driver locations
and for improved readability.

udev: add Asix Omega USB identification to udev rules

kingst-la2016: cope with 800MHz base clock for 500MHz models

The LA5016 uses an 800MHz base clock to derive the samplerate from. And
communicates divider 1 to configure the 500MHz rate. And does support
the 200MHz rate (divider 4). Which also makes the 10kHz lower boundary
unavailable on some models. Update the capture configuration logic, the
config API routines, and associated comments. Discuss how streaming may
make finer grained rates tables desirable (but stick with 1/2/5 for now).

kingst-la2016: zero pad FPGA bitstream to 4KiB boundaries

The 2KiB padding worked for LA2016 but kept looking susipcious. Pad the
FPGA bitstream to 4KiB boundaries, which unbreaks LA5016 and still works
with LA2016.

kingst-la2016: introduce base clock independent from max samplerate

The LA1010 devices are said to use an 800MHz base clock to derive the
samplerate of up to 100MHz from. Add this information to the list of
known devices, and adjust the samplerate dividier code path.

Keep value 0 in that column for all devices where the base clock and the
maximum samplerate are identical. For awareness during maintenance. Make
the untypical devices stand out.

kingst-la2016: add more device types and their EEPROM magic numbers

Extend the EEPROM content check which identifies device types. Inspect
the full set of four bytes before falling back to weaker checks of two
bytes per copy. Prefer the longest run of consistent data that is found
first. Some devices are said to require inspection of byte[2] in
addition to byte[0], to tell different models apart which share the
same byte[0] value.

This was exclusively tested on LA2016 hardware. The details were derived
from the https://github.com/AlexUg/sigrok implementation (which claims
support for LA1010, the LA50xx details may be untested there as well).
The model database also includes items which are not supported by this
driver implementation, to provide the maximum amount of information to
users which became available during scan.

tests: address printf format issues, spotted by clang on macos

The sr_rational data type has int64_t and uint64_t members, but analog.c
and strutil.c source code used "%ld" and "%lu" formats. Use PRIu64 et al
instead.

  .../libsigrok/tests/strutil.c:125:14: warning: format specifies type 'long' but the argument has type 'int64_t' (aka 'long long') [-Wformat]
                      input, rational.p, rational.q);
                             ^~~~~~~~~~
  /usr/local/Cellar/check/0.15.2/include/check.h:472:77: note: expanded from macro 'fail_unless'
      _ck_assert_failed(__FILE__, __LINE__, "Assertion '"#expr"' failed" , ## __VA_ARGS__, NULL)
                                                                            ^~~~~~~~~~~

Also make test stimulus static. It's a constant vector of literals and
is exclusively used in the test routine, need not occupy stack space.

kingst-la2016: comment on FPGA register at offset 0x0004 (unused)

The vendor firmware optionally keeps reading u32 values from the FPGA
register at offset 0x0004 outside of acquisition periods. To present
the input pin's current level and changes "in real time" in the GUI.
The sigrok driver does not use this information, but it's useful to
have the comment in the source code.

kingst-la2016: prefer boolean data type for bool information

The la2016_is_idle() routine provided boolean information in an
'int' data type. Prefer gboolean instead.

kingst-la2016: stop acquisition when USB device was lost

Check for the condition when the USB device has gone away in the middle
of getting communicated to. Terminate acquisition in that case, instead
of trying to continue.

kingst-la2016: add support for streaming mode, works for 16 channels

Implement support for streaming mode and announce the SR_CONF_CONTINUOUS
config key. Automatically enable streaming mode for devices which don't
have local memory. Device identification, firmware download, and capture
setup are identical to "normal mode" as the vendor calls it. But the
sequence of submitting USB transfers by the host and starting capture
data transmission on the device differs. The phase of supervising the
hardware driven acquisition does not apply. Capture data is immediately
streamed to the host after initiating the acquisition.

The capture data memory layout dramatically differs. Samples are not
compressed, and samples taken at several points in time are kept in the
same memory cell. Processing is a little more expensive, bits need more
shuffling. Lack of compression makes the acquisition in stream mode
heavily depend on the reliability of USB bulk communication. The vendor
software assumes a 300Mbps boundary, and also enforces it by disabling
channels depending on the samplerate. The sigrok driver accepts any user
specified configuration, and merely warns for high amounts of traffic.
Local tests successfully communicated 320Mbps. Slow samplerates result
in slow arrival of more sample data, which periodically gets flushed to
improve usability. Thresholds when to start pushing may need tuning.

This implementation was tested with LA2016 and up to 16 channels. Other
devices are untested, especially LA1010 which lacks local memory and
thus exclusively supports streaming, and devices with 32 channels where
capture data memory layout may differ from devices with 16 channels (yet
to get verified).

kingst-la2016: experiment with USB bulk size and pool count

The previous implementation used a pool of 32 USB bulk transfers of up
to 256KiB size each. Using a pool did speedup capture data downloads,
using more transfers or larger buffers would not make a difference.
Slightly reduce the total memory consumption again, change the setup to
8 transfers of up to 512KiB each, which results in a total of 4MiB for
pending USB communication. These numbers are as arbitrary as any other.
No attempt was made to automatically derive the values from acquisition
parameters like samplerate and samples count.

kingst-la2016: use a pool of USB bulk transfers, speedup download

Use a pool of 32 USB bulk transfers of up to 256KiB size each. Which
doubles throughput and reduces the time to download the capture data
after acquisition has completed.

kingst-la2016: move USB bulk transfer handling to helper routines

Concentrate all support code which handles USB bulk transfers for the
capture data download in a set of helper routines: memory allocation
and release, submission and cancellation including re-submission after
a previous completion.

Submit host side transfers earlier, between the configuration and the
start of USB bulk transfers in the device. Allocate transfers and their
buffers at the first acquisition start. Keep allocated buffers across
several acquisition periods. Relase transfers and their buffers when the
device closes. Allocate buffers of fixed size (always 256KiB, no longer
depends on the remainder of the currently downloaded capture data).

Acquisition stop cancels all currently submitted transfers, and does
postprocess their (cancelled) completion without re-submitting. This
avoids "spilling" pending transfers into the next acquisition cycle.

Name the helper routines in preparation of using multiple transfers.
Stick with a single transfer in this commit to simplify review. Use a
longer USB receive timeout (500ms for capture data, in contrast to
200ms for control transfers).

kingst-la2016: move capture download details out of USB xfer handling

Ideally the USB transfer handling logic and the interpretation of the
downloaded capture data would not be as intertwined. The current
implementation assumes a rather specific capture model ("normal mode"
as it's called in the vendor software), and would not work in streaming
mode.

Move as many details out of the receive_transfer() routine and into the
send_chunk() data processing routine as we can. Which only leaves error
code paths and USB transfer re-submission, which get addressed in a
subsequent commit.

use common channel group allocation/release code

Eliminate individual open coded alloc and release code for channel
groups in hardware drivers and input modules. Use common code instead.

This commit affects: arachnid-labs-re-load-pro, atten-pps3xxx,
baylibre-acme, dcttech-usbrelay, demo, dreamsourcelab-dslogic, fx2lafw,
gwinstek-gds-800, gwinstek-gpd, hameg-hmo, hantek-4032l, hantek-6xxx,
hantek-dso, hp-3457a, hp-59306a, hung-chang-dso-2100, itech-it8500,
lecroy-xstream, maynuo-m97, microchip-pickit2, motech-lps-30x, rigol-dg,
rigol-ds, scpi-pps, siglent-sds, yokogawa-dlm, input/vcd.

kingst-la2016: add my copyright for recent improvements

The usability improvements, firmware speedups, portability and robustness
improvements, and style cleanup were non-trivial. Add my copyright to the
Kingst LA2016 driver source code.

kingst-la2016: spew pretty FPGA register dump for development support

Implement a pretty registers dump, and call it when the FPGA bitstream
content gets checked and when hardware controlled acquisition completes.
Generate this FPGA registers dump at spew log level, accept a caller
provided address range to further reduce verbosity as needed.

This is mostly motivated by developer's curiousity. To suport research
when previously unknown models are seen. Or to see which other details
are available as an acquisition executes. Or to check whether some of
the previously written configuration could be read back.

kingst-la2016: unconditionally construct MCU firmware filename

Always call the MCU firmware download routine that is implemented in the
protocol.c source file when the api.c scan routine executes. But only
conditionally load the MCU firmware to the probed device when strictly
necessary. This makes filename information available to users since
these details are essential for the operation of a device, yet keeps
intimate firmware implementation details in the appropriate location
in the implementation.

kingst-la2016: weaken run state check in hardware initialization

Weaken the check for plausible run states in the early read and test
immediately after the initial hardware configuration. The strict pattern
used to not match when an earlier session successfully triggered (digits
0x9 vs 0xd in the register's LSB positions). The test was never fatal,
it's just for information.

kingst-la2016: balance frame begin and frame end emission

Track when frame begin was sent to the session, to conditionally send
frame end only when begin was sent. This is useful because frame markers
get deferred for quite some time when triggers are involved. Acquisition
stop may occur before the start of a capture was seen or processed.

kingst-la2016: symbolic names for capture mode, trigger config comments

Use symbolic names for the capture mode (sample to RAM before download
to the host). Comment on potentially misleading field names in the
trigger configuration (enabled vs triggering channels masks). Don't
rename the fields yet until the assumption is verified.

kingst-la2016: determine packets per chunk at runtime per model

The layout of capture data in memory most probably depends on devices'
channel counts. Chunks of 16 bytes each could either carry 5 samples of
16bit data with an 8bit repeat count, or 3 samples with 32bit data each.
Derive the number of packets per chunk at runtime from the connected
device type. Which could unbreak the LA5032 device but is yet untested.
It's an educated guess.

kingst-la2016: extend model support (100/500 MHz, 32 channels)

Extend the code paths which handle supported samplerates and channel
counts. Explicitly test for 100/200/500 MHz rate, and 16/32 channels.
Raise errors for unexpected configurations. Keep all internal data in
32bit wide entities. Pick a suitable unitsize for logic data at runtime
depending on the detected model.

The capture data memory layout for 32 channel devices is yet to get
verified. The implementation is based on an educated guess only.

kingst-la2016: rephrase USB bulk transfer size padding constraint

Always round up capture data USB bulk transfer sizes to full EP 6 packet
sizes. The previous implementation suggested that it's only required for
smaller transfers, but it's just a coincidence that the upper limit of
256KiB happened to also be a multiple of the 512B packet size.

It's assumed that capping at the absolute size limit and always padding
is more readable and as reliable as the previous if-else logic was.

Rephrase the round up by means of integer multiplication instead of
bit twiddling. Compilers should get what is intended, humans may prefer
to read the former.

kingst-la2016: developer comment on capture data layout for 32ch models

The implementation assumes that capture data comes in 16byte chunks
which carry 5 packets of one 16bit sample and an 8bit repeat count each.
Which may not apply to models with 32 channels, the current compile time
literal may need to become a runtime depending value. Add a comment.

kingst-la2016: keep FPGA active after device close

When the sigrok driver closes as the application shuts down, acquisition
of logic input channels will have completed. Generation of PWM signals
on output channels can be desirable to keep up. Do not de-initialize the
FPGA hardware in the close code path. Which allows to configure PWM by
means of sigrok-cli and use the signals between program invocations that
reconfigure the generator. Users can always disable channels before the
application shuts down if they prefer to. Similar use was seen with PSUs.
Make this approach a compile time option.

kingst-la2016: use more specific error codes than SR_ERR

At least reflect whether arguments were invalid, whether communication
failed (I/O), or whether data was unexpected.

kingst-la2016: reword buffer size in FPGA register access

Phrase communication buffer sizes in terms of FPGA register width,
instead of totalling the sizes of different bitfield width. Comment
where buffers are shared among different accesses, for awareness
during maintenance.

Introduce an "unknown register at offset 0x30" such that REG_TRIGGER
access can follow the pattern of determining the FPGA register's width.

kingst-la2016: rename samplerate member in device context

The "current samplerate" attribute of the device context became obsolete
when the maximum samplerate became a property of the model which a device
context references.

kingst-la2016: remove complex logic threshold voltage support

Remove the complex implementation of the three config key support to
specify the logic input threshold voltage, as well as the compile time
switch to pick from alternative implementations. This approach is easy
to come back to later when desired, its removal is in a separate VCS
commit. Getting the full -4.0..+4.0V range and continuous adjustment
would be nice to have. But it's essential for users today to see the
currently effective voltage in UIs.

kingst-la2016: reduce a little if-deffery in logic threshold support

Move a logic threshold related switch case to the location where its
sibling config keys reside. Which eliminates a separate distant chunk
under an ifdef which should not have been there in the first place.

Make the presence of a device context member depend on the choice of
simple or complex threshold support. The simple approach exclusively
requires one index into the discrete set of a few voltages.

kingst-la2016: implement alternative simpler threshold voltage config

The complex setup with three config keys that heavily interact with each
other did not work from the user's perspective. It's unfortunate how the
configuration of one item changed another item's value. The GUI would
not provide labels which reflect the currently configured voltage value,
the list of presets was never presented in the GUI.

Implement something that is both simpler and works with sigrok-cli as
well as pulseview. Reduce the set of choices and only provide a discrete
list of voltages. Yet try to cover most logic families and typical use
cases. This alternative approach exists in addition to the previously
implemented approach, and is selected by compile time switches. Ideally
the logic input threshold voltage would be a property of the "Logic"
channel group, but the GUI then won't display the option. That's why it
currently remains a global device option.

Pass the user specified voltage as a value from api.c to protocol.c
which eliminates intimate knowledge of the config API's internal details
(especially with the compile time options in api.c).

kingst-la2016: adjust config param checks, threshold range check

After scan() completed the conn= can no longer be unknown. The firmware
was loaded and became effective (and communication was tested) before we
get to the config getter. Check PWM period and duty cycle value ranges
in the config setter.

Use symbolic names in the threshold voltage range check when protocol.c
forwards the configured value to the device.

kingst-la2016: sort protocol.h priv routines in order of use

Sort the SR_PRIV la2016_*() routines in protocol.h in order of typical
use, improving navigation during maintenance. Keep protocolc. as is to
reduce the diff size.

kingst-la2016: add PWM channel groups, announce as signal generator

Create the "Logic" and the "PWMx" channel goups, implement support to
get and set frequency, duty cycle, and enabled state. Announce the
device as a signal generator, too.

Handling of "Logic" config keys is prepared but empty in this commit.

kingst-la2016: reduce scope of a few more declarations

Reduce the number of "top level declarations" in the protocol.h header.
Move hardware register related structs and capture data layout literals
to protocol.c where they are exclusively used. Move the capture info (a
set of values which describe the most recently completed acquisition)
into the device context itself.

kingst-la2016: rework the device side of PWM configuration

Assign an initial PWM configuration during scan (arbitrary frequencies
at 50% duty cycle as before, but off by default). Ideally the initial
assignment gets updated by user specs at runtime, and hardware gets
configured as needed from internal data which was kept at defaults or
updated from user specs.

Combine the previous enable_pwm() and configure_pwm() routines into
set_pwm_config() which configures one channel in the device's hardware
(and transparently controls the enable flag). This eliminates the
unfortunate "channel unrolling" in the helper's API. Which eliminates
la2016_init_params() which redundantly configured the logic threshold
(done upon acquisition start again) and kept reassigning PWM parameters
across multiple open calls.

Providing the config API to adjust PWM settings remains to be done.

kingst-la2016: complete hardware setup in probe, set features in open

Complete all of the MCU firmware load, device type identification, FPGA
bitstream load, and FPGA initialization by the end of scan(). This gives
an easily usable device of known capabilities for the remaining driver
lifetime, which just needs to get opened by connection ID (which was
retrieved during scan).

I still don't like how the driver's open() configures PWM without user
provided specs. And enforcing the logic threshold is redundant before
acquisition start. This needs more attention later.

kingst-la2016: improve diagnostics in device type detection

Adjust the pieces of information that are shown at different verbosity
levels in the EEPROM read code path which identifies Kingst LA models.
Present something even more readable to regular users, yet keep details
available for developers when previously unknown devices are seen. Show
raw byte dumps at highest verbosity levels, to simplify the addition of
more supported devices.

kingst-la2016: rework acquisition limits, improve CLI use

Remove the rather arbitrary previous limits of 5MSa at 100MSa/s and 5%
capture ratio. Start with the highest available samplerate (per model)
and without any samples count limit. Use 50% capture ratio which is as
arbitrary a choice as the previous value but matches what scopes do.
Drop the lower samples count limit. (An arbitrary check encoded in the
library refuses to set a value of 0, so starting with 0 is the only way
of starting unlimited and being able to optionally specify a limit.)

This results in improved CLI use out of the box. Either of --samples or
--time works as expected, and both can be used in combination. The GUI
starts from a samples count limit by default that is consistent with
other devices. Users should be happy.

Accept any samplerate spec which is covered by hardware constraints.
Keep user provided specs unmodified for later reference, map these to
hardware register values which get forwarded to the device in a best
effort manner.

Make too high sample count limits non-fatal, just cap at 10GSa length.
The device's hardware compression which is affected by input signal
patterns already kept resulting in potentially shorter captures than
configured. There is no surprise here for users either. Use the model
dependent sample memory capacity to derive maximum pre-trigger memory
sizes, which eliminates another arbitrary magic number in the driver.

kingst-la2016: identify device type in scan() already

The vendor's design choice won't let us detect the device type from USB
enumeration data alone. EEPROM content must be read, which involves MCU
firmware communication, which only becomes available after the recently
uploaded firmware image becomes available. This extends the execution
time of the Kingst LA driver's scan() routine, but only if devices are
connected, and only for their first occurance after plugin. Subsequent
scans are quick.

Knowing the device type in the scan routine simplifies the open routine,
and allows model specific default parameters. The vendor's design choice
again won't let us read back previously configured values, each program
startup must assume a default configuration.

This implementation uses lots of small helpers to avoid open coding USB
communication details in several places. In theory up to 32 channels are
prepared, but all currently supported models have 16 channels. Different
memory sizes and channel counts are not yet effective in the acquisition
setup or session feed. The previous implementation of device open still
did too many things (configure PWM before user specs were received). A
future implementation needs to better pick which activities to run at
which points in time.

kingst-la2016: rephrase samplerate list code path, prepare 500MHz

Rephrase the config_list() SR_CONF_SAMPLERATE branch for improved
readability. A list of supported rates gets derived from the current
device's maximum rate. Naming the tables after device models instead
of maximum rates is unexpected.

Drop the "odd" looking 4/8MHz items. Which results in consistent 1/2/5
steps in all decades. With hardware compression there is no gain to be
expected from using 4/8MHz instead of 5/10MHz. (Vendor software does
not provide that choice either.)

Add a list of samplerates for 500MHz models. These won't provide the
200MHz value, because it cannot result from the device's base clock
and an integer divider. Needs to be 250MHz instead. This is untested,
needs to get verified when a 500MHz model will be supported.

device: provide glib compatible callback to free usb dev inst

Provide the sr_usb_dev_inst_free_cb() routine with a compatible
signature for g_slist_free_full().

device: introduce common helpers for channel group allocation

Provide common logic in device.c which allocates and releases an
sr_channel_group struct. The logicport import module had a local
implementation with a slightly different API. Accept an optional sdi
reference to automatically extend the sdi->channel_groups member.

kingst-la2016: use common support for sw limits and session feed

Use common sw_limits and feed_queue helpers. Which makes --time specs
for acquisition duration available, and dramatically reduces complexity
in the send_chunk() routine. Which improves usability and reliability
and maintainability at the same time.

Assign default rate/depth/ratio in scan() already when the devc gets
created. Make an msecs timeout stop the acquisition if the hardware has
not seen the desired number of samples or exhausted its memory before.
Immediately start recording in the absence of trigger specs, drop the
pre-trigger phase in that case. Shuffle the order of activities in the
periodic receive callback. Send headers before enabling communication,
end communication before sending end markers to the session feed. Cope
when USB data is received after the configured acquisition got processed
(the hardware always overshoots due to compression and chunking). Extend
comments and diag messages.

USB receive timeouts are not fatal any longer. They even were seen
during regular operation at higher log levels. Which resulted in one
capture getting split across several "frames" unexpectedly.

Acquisition limits are not enforced most precisely in this commit, as
this would be more expensive. A little overshoot of up to 1.5kSa seems
acceptable (up to five packets with an 8bit repeat count each).

kingst-la2016: more checks on configured rate/depth/channels

Extend the list of supported samplerates, start from 10kHz (used to
start at 20kHz before). Comment on hardware constraints which limit
the available rates, for awareness during maintenance.

Move the check for enabled channels from api.c to protocol.c, it was
only used for the trigger configuration. Rename the routine since it
never configured any channels, only got the list of currently enabled
channels to pass on to the device. Extend the range checks for the
rate and depth on acquisition start, also check the lower limits.

Moving codes which references declarations required that definitions
also moved to public location of greater scope. This is acceptable since
all of them remain local to the kingst-la2016 driver. Stick with names
as they are used right now to reduce the diff and help reviewers, these
can get unified in a later commit.

kingst-la2016: rename logic channels to match product's labels

Rename the logic channels to "CH0" to "CH15". To match the labels on the
cover of the device which users will be expecting to see in applications.
Which also happens to match the vendor's software and user manual.

kingst-la2016: style nits in FPGA code path and threshold selection

Check sigrok routine return codes for SR_OK not zero. The snprintf(3)
routine does include the NUL termination in the length spec. Use size_t
for the threshold selection which in essence is an enumeration.

kingst-la2016: coding style, separate declaration from instructions

kingst-la2016: address style issues in api.c scan and open

Improve readability and fixup coding style of the scan(), dev_open(),
and la2016_dev_open() routines. Factor out common subexpressions, trim
text line length, adjust data types, eliminate sizeof() type redundancy.
Propagate returned error codes, check the USB enumeration result before
iteration. Drop the devc member which used to hold the sigrok context.
Release the sample data conversion buffer when acquisition start fails.

kingst-la2016: separate complex calls from caller's control flow

Don't mix complex invocations with their evaluation of the return value
and change of flow in the source code. This is even more important for
indented multi-line argument lists and indented conditional branches
which follow. As a byproduct this reduces text line length and further
increases readability. Break other long lines. This commit picks low
hanging fruit, leaves more complex cases for another commit.