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.

kingst-la2016: rephrase sample data to session feed logic

Comment on the layout of the incoming captured data for awareness during
maintenance. Rephrase the send_chunk() routine for improved readability.
Eliminate too short i, j, k variables. Comment on the non-obvious flush
condition for the conversion buffer. Prefer "sample" in variable names
to not confuse captures with the device's run state. Eliminate another
literal 2 which slipped through in an earlier commit. Adjust data types.

kingst-la2016: style nit, drop unnecessary typedefs

These typedefs in the previous implementation merely seem to save a few
key strokes while typing. Not good enough a reason to keep them.

kingst-la2016: style nits in enable/configure PWM

Prefer booleans in the enable code path. Rename set_pwm() to better tell
apart enable and configure activities. Check more constraints on input
parameters. Adress minor style issues. Ideally enable_pwm() would not
open code the number of PWM channels in its routine signature.

kingst-la2016: renames to better reflect sequence of activities

The previous implementation started on a single model with lots of
experiments, and could benefit from a cleanup after more knowledge was
gathered. Rename variables and routines to better reflect what actually
is happening, use more suitable data types. Drop unused devc members.
Fixup typos in diagnostics, protect against MSB issues in bitmasks.

The USB scan just yields one of the supported devices, its model is
unknown at this time. The list of enabled channels is determined upon
acquisition start when the trigger configuration gets created. The
device executes captures in hardware to internal RAM, while the driver
waits for the acquisition to complete, before downloading sample data
to the PC. Feeding sample data to the session ends when the data is
exhausted (a good condition is yet to get found). An optional trigger
marker is put into the stream of samples but only if a trigger was
configured.

kingst-la2016: use symbolic names for device run state

Rephrase the run_state() routine in terms of symbolic identifiers,
eliminate magic numbers in the code. Extend comments on run state even
more to help reviewers. Reduce indentation in the optional logging when
the value changes.

It's assumed that the "current state and mask equals a typical pattern?"
phrase better reflects the purpose of a check, and is easier to verify
than hex numbers in a context where bit field meanings matter and not
all adjacent bits are involved).

This implementation no longer assumes that "sample to DRAM" is set. In
theory capture to internal RAM versus streaming via USB should not matter
when the acquisition state is queried.

std: remove open coded array items count, make floats stand out

Replace the open coded literal 2 in std.c routines, prefer ARRAY_SIZE()
instead in the GVariant construction. To not confuse that item count with
other literals 2 which are related to avoiding floating point issues by
using an epsilon around an imprecise value. See a larger context for an
illustration of the commit's motivation.

Use literal 2.0 instead of 2 where floating point numbers are involved.
To raise awareness during maintenance.

std: epsilon for std_gvar_min_max_step_thresholds() upper limit

Adjust the std_gvar_min_max_step_thresholds() routine which iterates
over a range of threshold voltages that are specified by their lower and
upper bounds and a step (stride). Allow for an epsilon in the loop's end
condition to span the full driver's announced set of values and not stop
prematurely.

The issue was observed with Kingst LA2016 which announces a range from
0.4V to 4.0V in steps of 0.1V, while the config list ends at the 3.9V
value and would have omitted the 4.0V upper bound.

kingst-la2016: adjust register layout in acquisition configuration

The FPGA register space to configure acquisition parameters is unusual
in the sense that some 34bit values are kept in 40bit registers, while
other 32bit values are kept in 24bit registers (stores MSB only). This
answers the question how to communicate a limit of 10 billion samples
in a 32bit register (a doubt about the previous implementation). :)

Reported-By: Kevin Grant <redacted> in github PR 169

tests: cover u24le and u40le in endianess conversion tests

Add a tiny test case which covers the principal operation of the u24le
and u40le endianess writers. Expect to see the correct number of bytes
and the significant bits. This test does not explicitly check for the
absence of adjacent garbage which a naive writer implementation might
leave behind outside of the significant bounds.

libsigrok-internal.h: add 24bit and 40bit endianess aware byte stream writers

Implement primitives to write u24le and u40le integers, including auto
increments for the write position. These are motivated by Kingst LA2016
maintenance.

kingst-la2016: rephrase creation of the acquisition configuration

Touch up the set_sample_config() routine's implementation. Separate the
calculation of parameter values from the construction of FPGA register
access instructions. Comment on seemingly redundant pre-trigger settings
which relate to each other in non-obvious ways. Consider unsupported
samplerates fatal: With a clock input of 100MHz to 500MHz and a lowest
user settable samplerate of 20kHz the 16bit divider shall never overrun.
If it does then a driver author was not aware during maintenance. Tweak
diagnostics for improved usability. Drop an unused devc member.

kingst-la2016: rephrase manufacture date and device type support

The "purchase date" reader asssumed a little endian host when reading
16bit data from the device. Use endianess aware readers instead. Which
also unobfuscates the YY and MM positions in the byte array (comments
were plenty, but the code would not reflect what happened). Rephrase
the consistency check in the date and magic code paths (the inverted
bits), better reflect the XOR approach.

Prefer the "manufacture date" term since that's what the vendor is aware
of, while the customer's date of purchase or the dealer's shelf time are
unknown to vendors.

Split complex invocation from caller's flow control to improve
readability of the code path. Which also trims text line length.

kingst-la2016: endianess and redundancy in run state gatherer

The run_state() routine assumed a little endian host. Get the device's
16bits run state by means of an endianess aware reader instead. Reduce
redundancy in the run state change diagnostics. Individually determine
the run state name, but use common code to print that information. Use
short hex literals to better reflect that only the lowest nibble gets
inspected, all other bits' meaning are unknown to us.

It remains uncertain why the state progress logic keeps checking the
"sample to DRAM" bit field. In theory these states should also work for
streaming. May just not have come up yet in the absence of support.

kingst-la2016: address endianess issue in data feed submission

Capture data was taken from the device in an endianess aware manner, but
submission to the session feed assumed a little endian host (and casted
an u8 pointer to u16 items, which is bad). Use an endianess aware writer
before sending accumulated sample data to the sigrok session. Address
remaining open coded byte counts in several send_chunk() places.

The conversion from LE (the device) to the host and to LE (the session)
may appear redundant, but is worth keeping in place when other models
with 32 channels should get added in a future implementation.

kingst-la2016: shuffle code order to follow application perspective

Sort "set threshold voltage" code blocks into numerical order of voltage
levels for improved readability. It's surprising to find ">= 2.9V" then
"<= -0.4V" and then "between those" at the end.

Move the la2016_has_triggered() routine next to run_state() since both
of them inspect the device's current run state. Closer inspection even
suggests that one is named inappropriately (not renamed in this commit,
to help reviewers).

The purpose of the set_run_mode() routine's argument most probably is
"mode", and not the surprising "fast blinking". Indicators may just be
a byproduct of setting mode to run or halt.

Make the set_defaults() invocation in la2016_init_device() stand out
more perceivably. Don't hide it in a return statement.

kingst-la2016: unobfuscate "user specified threshold" reference

Use a symbolic name for the "user specified input threshold" item's
position in the set of choices. Stick with array size for the complete
list of items instead of hiding the size behind an unrelated name. This
improves readability of the config get/set/list routines. Trim a text
line length while we are here.

The single variable for several purposes (user specified value, and
fixed value derived from currently selected choice out of a premade
set) still looks suspicious, and is not addressed in this commit.

kingst-la2016: concentrate magic numbers in central location

Eliminate open coded magic values which are spilled across the driver's
implementation. Concentrate tunables or derived values in a central spot
at the top of the source files near other declarations. Rephrase some
values to better reflect their purpose or magnitude.

Few values remain dubious. Add TODO comments for awareness.

kingst-la2016: rephrase FPGA bitstream content zero padding

The upload_fpga_bitstream() routine open codes a magic length for the
padded file content, which is hard to relate to a firmware file size,
and impossible to spot during maintenance. Declare an assumed chunk size
instead and let the resource file handling code path determine the needed
length of zero padding. Drop an unneeded device context member variable.

kingst-la2016: make FPGA bitstream upload optional

Separate the FPGA bitstream upload logic into the strict file content
upload, and the register access to initialize and enable a currently
loaded bitstream. Check before upload whether a working bitstream is
available in the device.

This eliminates a 600ms delay in every device open code path after the
initial upload. Which speeds up the start of an acquisition. Works in
Pulseview as well as sigrok-cli, even across process invocations.

Unfortunately test conditions are rather weak, they are constrained by
an arbitrary vendor's choice. Stricter checks can get added later if
the need arises (when incompatible device firmware versions are seen,
and more reliable test criteria become available). The implementation
lends itself to transparent robustness improvements.

kingst-la2016: rephrase USB renum code path after firmware upload

The dev_open() routine postprocesses USB renumeration after a previous
FX2 MCU firmware upload. Concentrate all tunables in the driver's header
file, and discuss their meaning in relation to each other. Rephrase the
logic to start checking earlier, and keep checking for longer, adjust
diagnostics in the process. Void the "firmware uploaded" flag when the
upload took effect. Consistently use u64 for timestamps. Rename a few
variables to improve readabilty.

kingst-la2016: address style nits, brace location, indentation

Avoid indentation by means of spaces, and excess indentation. Break long
text lines. Adjust braces location to match the sigrok project's style.

kingst-la2016: rephrase comments for style, readability, and text length

Rephrase comments in the Kingst LA2016 driver to better match the sigrok
project's style. Consistently start with capitals and end in punctuation.
Use all upper case for acronyms to improve readability.

Keep text lines to an acceptable length. Use consistent open and close
phrases for multi-line comments. Drop C++ style comments. Add braces
where comments and one-line code results in multi-line branches of flow
control statements.

This commit also consistently uses lower case for hex literals, and
unobfuscates a few other literals: Use 0xff everywhere for unknown USB
addresses, prefer 1800 * 1000 over 18e5 for a 1.8 seconds interval.

kingst-la2016: rephrase diagnostics to improve user perception

Rephrase diagnostics messages so that users easier can digest them. Keep
implementation details out of messages which are seen by default, stick
those into developer centric messages that correspond to higher verbosity
levels. Consistently start with capital letters and end in punctuation.
Drop exclamation marks. Use all caps for acronyms. Don't break format
strings so that developers can search for messages reported by users.
Break a few long source code text lines (but not all of them).

kingst-la2016: style nits, consistent #define indentation

Consistently use TAB characters to indent #define directives' values.
Remove an unused directive. See whitespace ignoring diff for review.

kingst-la2016: style nits, remove not needed include directives

kingst-la2016: sort include directives

kingst-la2016: move acquisition abort from api.c to protocol.c

There was the abort_acquisition() routine (whithout a prefix) and the
la2016_abort_acquisition() routine (with a prefix). Fold the termination
of USB reception into the drivers's SR_PRIV routine which resides in
protocol.c, which eliminates the misplaced api.c implementation. Change
a few more receive callback related routines from SR_PRIV to static now
that their calls are intra compile unit.

kingst-la2016: move USB communication from api.c to protocol.c

Move the Kingst LA2016 driver's "receive data" callback (device's
USB communication) to protocol.c where it belongs. This is a pure
move between source code files, behaviour does not change.

kingst-la2016: rename routine before moving from api.c to protocol.c

The Kingst LA2016 driver implementation would not follow the typical
separation of api.c and protocol.c responsibilities, instead encodes
USB communication to the device on the api.c side. Rename a driver
routine before moving it between files, provide an SR_PRIV decoration.

rdtech-dps: Use big endian register access for DPS devices

Adresses an issue which was introduced in commit d7a4dad881bf.

Fixes bug #1760

Signed-off-by: Volodymyr Ananiev <redacted>

rigol-ds: improve robustness in samplerate getting code path

The rigol-ds driver's acquisition start routine tries to determine the
samplerate, which depends on devices' protocol version and communication
of SCPI requests. The logic potentially used an uninitialized variable
(for protocol versions below V3).

Rephrase the samplerate getting code path, apply stricter checks and
extend diagnostics. Make sure the XINC retrieval did yield a non-zero
value, to also avoid a division by zero.

Address style issues while we are here. Use braces for all branches when
one of them is complex. Eliminate trailing whitespace at ends of lines.

    src/hardware/rigol-ds/api.c:1029:7: warning: variable 'xinc' is used uninitialized whenever '&&' condition is false [-Wsometimes-uninitialized]
                    if (devc->model->series->protocol >= PROTOCOL_V3 &&
                        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    src/hardware/rigol-ds/api.c:1034:28: note: uninitialized use occurs here
                    devc->sample_rate = 1. / xinc;
                                             ^~~~
    src/hardware/rigol-ds/api.c:1029:7: note: remove the '&&' if its condition is always true
                    if (devc->model->series->protocol >= PROTOCOL_V3 &&
                        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    src/hardware/rigol-ds/api.c:1028:13: note: initialize the variable 'xinc' to silence this warning
                    float xinc;
                              ^
                               = 0.0

session: address deprecation of g_memdup(), prepare use of g_memdup2()

The g_memdup() routine was deprecated and (very) soon will become
obsolete. Use g_memdup2() when available, which is preferred for its
use of proper size data types.

This is inspired by pulseview commit cf0109112932 which references the
https://discourse.gnome.org/t/port-your-module-from-g-memdup-to-g-memdup2-now/5538
article.

input/vcd: detect and skip string data types (value not used)

The nMigen utility was reported to emit string values in VCD files (by
means of the pyvcd Python module). The $var declaration specifies the
'string' data type, and text values are prefixed with 's' similar to
integer or real numbers and bit vectors.

It is desirable to process these files and skip the unsupported type
which does not map to any sigrok channel type. Add support to detect the
type in declarations and change entries, skip these change entries and
emit warnings so that users remain aware of the incomplete import. Check
the validity of the entry though, to keep robustness of the existing
implementation of the VCD input module.

The validity check is an educated guess that was written in the absence
of an official specification or any public documentation, encodes rather
arbitrary assumptions. Deals with cases that were reported, may need
more test coverage and future tweaking. This version forbids whitespace
in values, and exclusively accepts printable ASCII in the string
presentation, with a few escape sequences. Empty strings are covered.

This also resolves bug #1757.

Reported-By: Anton Blanchard <redacted> via github PR 157

input/vcd: raise severity of messages about unsupported data types

The VCD input module did check for unsupported data types in $var
declarations. But the emitted message only was of INFO level and thus
would not be seen at the default log level. Use ERR instead to raise
awareness. Let users see by default that the input contains data which
cannot get processed (and why the import terminated prematurely).

This addresses part of bug #1757.

ftdi: address ftdi_usb_purge_buffers() deprecation in libftdi 1.5

The ftdi_usb_purge_buffers() implementation suffered from an incorrect
implementation (inverse semantics). Library version 1.5 introduced a set
of substitute routines, and deprecated the existing purge API. Parameters
are identical, so we get away with a mere replacement of the routine name
which gets invoked. Which simplifies call sites, and concentrates all the
version dependency cruft in a central spot. The fact that all drivers
always flushed RX and TX and never individually also helped.

input/vcd: silence printf() format compiler warning

uni-t-ut181a: drop serial flush() after open()

The driver's call became obsolete when common code added flush() to the
open() sequence.

uni-t-ut181a: silence compiler warning, use of uninitialized variable

The ut181a driver's acquisition start routine may face a previously
unknown data source value, which is potentially unhandled when the
source code becomes inconsistent during maintenance. Add a default
case to handle the condition, which silences a compiler warning.

    src/hardware/uni-t-ut181a/api.c:505:13: warning: variable 'ret' is used uninitialized whenever 'if' condition is false [-Wsometimes-uninitialized]
            } else if (devc->data_source >= DATA_SOURCE_REC_FIRST) {
                       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    src/hardware/uni-t-ut181a/api.c:536:6: note: uninitialized use occurs here
            if (ret < 0)
                ^~~
    src/hardware/uni-t-ut181a/api.c:505:9: note: remove the 'if' if its condition is always true
            } else if (devc->data_source >= DATA_SOURCE_REC_FIRST) {
                   ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    src/hardware/uni-t-ut181a/api.c:467:9: note: initialize the variable 'ret' to silence this warning
            int ret;
                   ^
                    = 0

configure: Hameg HMO does not strictly depend on serial communication

Remove the hameg-hmo driver's dependency on the serial_comm physical
transport. This is too strict a constraint, the scope communicates via
SCPI and can use any of the supported transports.

rdtech-tc/um: silence "missing field identifier" compiler warning

There are rather conservative build setups which complain about missing
fields in initializers. Rephrase the profile sentinels in the rdtech-tc
and rdtech-um drivers for maximum portability across toolchain setups.

  src/hardware/rdtech-um/protocol.c:45:10: warning: missing field 'spec' initializer [-Wmissing-field-initializers]
          { NULL, },
                  ^

binary helpers: add "invalid" enum item, improve readability

The "binary value" helpers would not follow the sigrok project's style
of only using non-zero values for valid enum items (a zero value is
assumed to always represent something "inactive" or "invalid").

Introduce the "invalid" item in the enum declaration to fixup the style
issue. Rephrase the bv_get_value() routine's length specs to improve
readability, match numbers in length specs to the numbers in conversion
routine references.

doc: fix a trivial typo in the ASIX OMEGA section of README.devices

input/stf: move trigger packet emission to feed queue (including flush)

Use the recently extended feed queue API which transparently flushes
previously accumulated logic data before sending a trigger packet.

input: optionally send trigger markers from common feed queue helper

This further simplifies callers, which need not care about flushing
previously queued samples before a trigger packet is sent. The queue
itself handles the order of packet initiation.

configure: make zlib an optional dependency which input/stf depends on

The STF input module calls into the zlib's crc32() routine, although
this dependency is not checked for and need not be satisfied. This went
unnoticed because zlib is rather ubiquitous, most development machines
provide it.

Extend the configure script to check for the zlib presence. Absence is
non-fatal (the library is truly optional). Reflect the version details
in the libsigrok version output, update the README. Make the STF input
module depend on the zlib presence, which makes the module optional.

It's unfortunate that the MiniLZO library which the libsigrok source
embeds does not provide the CRC32 calculation. Else we could have used
it instead of introducing another external dependency.

This implementation attempts to properly separate the autoconf/shell
layer from the automake layer from the C language preprocessor, and
separate the zlib library availability from the compression and CRC32
calculation availability from the STF input module applicability. This
shall prepare more zlib use in future implementations.

serial: move sr_serial_extract_options() out of "have serial comm" condition

The sr_serial_extract_options() routine strictly operates on variables
and is applicable to any driver which accepts conn= specs. No physical
serial communication is involved, the HAVE_SERIAL_COMM condition check
is too strict a constraint.

This silences warnings in build configurations where serial communication
is not available:

   ../src/scpi/scpi.c: In function 'sr_scpi_scan':
  src/scpi/scpi.c:325 col 2: warning: implicit declaration of function 'sr_serial_extract_options' [-Wimplicit-function-declaration]
     (void)sr_serial_extract_options(options, &resource, &serialcomm);
     ^

Implementation detail: List the serial.c source file two times in the
Makefile to avoid confusion when the file is "missing" in the list of
related source files in the "serial comm supported" case. All serial.c
content already was under the HAVE_SERIAL_COMM condition, so compiling
that file in all build configurations is not an issue.

kingst-la2016: handle sdi==NULL in config_list

The hardware driver API specifies that the sdi argument to config_list
is optional and can be NULL. This change handles that case, instead of
dereferencing without a check.

input/stf: introduce support for Asix' Sigma Test File format

Introduce the 'stf' input module which interprets *.stf captures
which are the Asix Sigma vendor software's native format. This
implementation supports Sigma Test Files, but does not support
Omega Test Files because ZIP archive handling is not available
in sigrok input modules. This implementation depends on miniLZO.

The input module was tested with vendor provided example captures.
Automatic file format detection, GUI initiated file re-read, and
50MHz as well as 200MHz captures were tested, and successfully
decode I2C, UART, and USB traffic. The trigger position works
(when the file content is plausible, the USB dump was not).

configure: hook up minilzo to the libsigrok build, reflect its version

Add the minilzo/ directory to the list of source files for the libsigrok
build. Have the minilzo library use the project's config.h file, extend
the set of autoconf checks. This approach follows the documentation in
the README.LZO file. It avoids the dependency on an external library and
its version or configuration.

Reflect the minilzo version in the libsigrok version output. The example
application which ships with the library suggests that failed init calls
typically originate from compile issues. Present the same error message
to sigrok users as the example application does.

minilzo: import content of upstream minilzo-2.10.tar.gz archive

The miniLZO distribution is a stripped down version of the LZO library,
and can be preferrable over the larger external dependency. Import the
content of the upstream's minilzo-2.10.tar.gz archive, which is released
under the GPL and thus is compatible with libsigrok.

README.devices: discuss ASIX OMEGA in RTM CLI mode (vendor application)

A stub sigrok driver can use the vendor's command line application to
make principal Asix Omega operation available. Outline the approach and
discuss the requirements for this setup in the README.devices file.

asix-omega-rtm-cli: Implement RTM for ASIX OMEGA via external CLI process

The ASIX OMEGA vendor software provides a commandline application which
puts the device in "real time mode". The process' stdout provides a
continuous RLE compressed stream of samples for the 16 input signals,
recorded at 200MHz. The sigrok driver starts and terminates this process
for the duration of the acquisition.

This simple approach makes the OMEGA device available in a basic mode of
operation. The samplerate is fixed, hardware triggers are not available.
The binary data format is used to reduce the amount of inter process
communication. The vendor's Windows software also executes in Linux
under wine(1). All device detection, USB communication via FTDI FIFO
mode, firmware download, etc are transparently dealt with. This mode of
operation is an officially supported and documented feature.

The sigrok driver accepts the OMEGARTMCLI environment variable as the
specification of the vendor application's location, or falls back to the
omegartmcli executable name which should be in PATH. The conn= spec in
the sn= format can select one out of multiple connected devices.

The driver was tested on Linux with --samples and --time as well as with
Pulseview and manual acquisition stop while a huge limit was configured
that would not take effect.

asix-omega-rtm-cli: Initial driver skeleton.

sw_limits: extend API to "get remaining counts" before the limit is reached

The current sw_limits API provides routines which interface nicely with
config get/set and Glib data types, and which check whether a limit was
exceeded after previous submission of samples (summary result).

Device drivers may want to check _before_ a limit was reached, some may
want to cap to-get-submitted sample data such that a limit gets reached
but is not exceeded. This need becomes more obvious when devices with
efficient hardware compression "severely overshoot" the user specified
limits when the check is only done late after submission of another
chunk of data which results from uncompression.

Introduce an API routine which gets the remaining count until the limit
is reached. Phrase the implementation for cheapest cost of execution.
These routines may execute in tight loops in acquisition code paths.

input: accept const sdi in feed queue API

The common feed queue support code needs an sdi to submit sample data to
the session feed. Decorate this argument as const to silence compiler
warnings. This matches the sr_session_send() API.

kingst-la2016: setup usb transfer sizes to be multiple of endpoint max packet size, as required by WinUSB RAW_IO policy

zketech-ebd-usb: Minor style fixes

zketech-ebd-usb: Style fixes

zketech-ebd-usb: Multiple fixes and upgrades.

- fix load toggling at acquisition stop
- messages are sent byte per byte with a pause in between since bytes were
  sometimes dropped
- incoming stream is parsed continuously instead of using a fixed length (the
  messages have a constant start/stop)
- add under-voltage threshold (under which the load would stop) as configuration
- add D+/D- voltage measurements as two new channels (had to rename the
  existing to avoid confusion)

kingst-la2016: Minor style fixes

kingst-la2016: add support for kingst la1016

The Kingst LA2016 and LA1016 use the same hardware, just the coding
of authentication IC U10 is different. U10 limits the LA1016 to
using an FPGA bitstream that samples at a maximum of 100MHz. Other
than that, the devices operate identically and the driver just needs
to select the correct bitstream and limit the maximum sample rate
appropriately. This commit adds support for the existing two hardware
revisions of LA1016, which require different bitstreams.

kingst-la2016: avoid filling the log file with redundant messages during long captures

kingst-la2016: add support for both LA2016 hardware revisions

A magic number within the device eeprom identifies the device
type and hardware revision. Using this number, the correct
fpga bitstream is selected and loaded.

kingst-la2016: remove unnecessary initialisation code

The OEM software communicates with device IC U10 to perform challenge-response
authentication, ensuring the device is genuine. We have no knowledge of the
obfuscation or encryption method used. Additionally it is a rolling code, so
the response changes even with same challenge. In any case, we can just ignore
this IC U10, it does not hinder sigrok support. Removing this code from
the initialisation routine. See schematic in wiki for more info on U10.