dcf77: annotate unexpected bit numbers and values, do not abort execution

Improve robustness of the DCF77 decoder. Cope with "neiter 0 nor 1" bit
values (glitches can break the detection of pulse widths), as well as
unexpected bit numbers (more than 59 pulses per minute, can be a
follow-up error after e.g. glitches break one long pulse into two short
pulses). Do not process this invalid data, do emit error annotations.

dcf77: annotate invalid dow and month fields, do not abort execution

Emit error annotations for invalid day of the week or month numbers,
instead of aborting decoder execution with an exception.

Implementation detail: Neither the Python 'in' keyword nor a .get()
method are available. That's why we have to catch the IndexError
exception.

This fixes bug #1173.

dcf77, lpc: rephrase bit string formatting

Create the text representation of a bit string by means of the builtin
.format() method and an appropriate specifier. Drop the non-obvious
sequence of bin() and slice and zfill() calls.

instance: return SRD_ERR_TERM_REQ when execution shall terminate

The previous implementation internally noticed the "want terminate"
request, and skipped decoder execution to faster get to the end of the
input stream. But an OK return code was provided in that code path, and
more input data was sent by applications (sometimes for many seconds or
few minutes).

Do return a new SRD_ERR_TERM_REQ error code, such that applications can
tell failed execution from requested termination.

instance: drop an unneeded "want wait() to terminate" reset assignment

It's uncertain why srd_inst_decode() which internally gets called by the
public srd_session_send() routine used to clear the want_wait_terminate
flag. This should be cleared upon decoder instance creation and state
reset, gets raised upon termination request, but shall not get cleared
in other spots, especially not upon the availability of new input data
while the stream shall be considered in the "about to terminate, skip
all subsequent execution" state.

log: Move log level check so that it affects all handlers.

Before this change, the loglevel check would only be performed for the
default log handler in libsigrokdecode, but not for other handlers set
via srd_log_callback_set().

This fixes bug #698.

srd_exception_catch(): Beautify traceback logging output.

Decoder_register(): Drop an overly verbose log message.

srd_logv(): Add an explicit fflush().

Show backtrace when decode() aborts due to an error.

The backtrace printing was actually already there, but was emitted using
sr_dbg(), which doesn't show up by default for most users. Make it an
srd_err() so that most users will see it.

This fixes bug #1158.

can: Fix incorrect stuff bit handling.

The decoder assumed a CRC cannot end with a stuffed bit but it actually can,
and the CRC delimiter then comes after the stuffed bit.

Patch by IRC/github user celeron55, wide testing by PeterMortensen, thanks!

Drop overly verbose log messages about (un)loading PDs.

sda2506/qi: Add missing full stop in 'desc' field.

rc_encode: Use different annotation classes for code word addr/data.

rc_encode: Use different annotation classes for different bits.

rc_encode: Add self.putx() helper.

rc_encode: Use common self.ss/self.es naming.

rc_encode: Use += operator where possible.

rc_encode: Drop unneeded casts.

Add initial rc_encode protocol decoder.

test: add simple "no data" test case for decoder "terminate and reset"

Introduce a "reset" group of tests. Whip up a first test step which runs
the "terminate and reset" routine for decoder stacks after session
creation, start, and meta data setup. No input data gets processed, no
decoder output is tested yet.

session: add "terminate and reset" support for protocol stacks

Implement routines which terminate currently pending decoder operations
and reset internal state (on the C and Python sides) for instances as
well as sessions. This allows to re-use previously created stacks for
new input data.

Decoder: check for duplicate register() calls in common backend code

Future implementations might call decoders' start() routine several
times, which makes them call register() again. It's desirable that the
common backend code copes with this condition, such that (the multitude
of) decoder implementations need not work around a specific constraint.

decoder: rephrase .has_channel() argument parse logic

Have the Python C API check the argument type and do the type conversion
already. Raise an IndexError exception when the range check fails.

instance: make sure oldpins array is available after reset

Introduce an oldpins_array_seed() helper routine, to make sure that each
call site which checks previous pin state will find valid data. This was
not always the case after decoder reset, which released the old pin data
while applications would not call srd_inst_new() again.

Preset newly allocated arrays with the default initial pin state, allow
optional application calls to specify differing initial values (when
specified by users), and keep the current state after first data was
processed.

adns5020: Python style nit, fixup whitespace

max7219: introduce constructor and reset() method

The "max7219" decoder used to have no constructor, which made me miss
it when reset() got introduced. Implement those two methods (which do
nothing, and thus won't change behaviour).

microwire: introduce constructor and reset() method

The "microwire" decoder used to have no constructor, which made me miss
it when reset() got introduced. Implement those two methods (which do
nothing, and thus won't change behaviour).

print_searchpaths(): Print decoder and system search paths.

Fix part of #1128 by adding a way to retrieve PD search paths

As this uses g_slist_copy_deep(), we now require glib 2.34.

Add support for SDA2506 EEPROM serial protocol.

Minor whitespace/typo fixes.

dali: Avoid CamelCase in most places.

ir_nec: optionally accept input signals that include the carrier

Introduce optional detection of a carrier signal. Immediately "go active"
when edges are seen. "Go inactive" again in the absence of edges in a
specified period of time. Cope with input signals that already had the
carrier removed.

By default carrier detection is disabled, to remain pixel compatible to
the previous implementation. When a carrier frequency is specified and
thus detection is enabled, edges of already filtered input are shifted
by one carrier period, and thus changes the output of the decoder. For
unfiltered inputs that still contain the carrier, detection of activity
is reliable and immediate, but the active phase is extended by one
period of the carrier frequency (which is considered acceptable).

parallel: expand 'wordsize' description (bits vs cycles)

Users may not know which unit the "wordsize" is supposed to get
specified in. Especially when it's not a number of bits, but instead
the number of bus cycles. Expand the description text accordingly.

stepper_motor: make samplerate meta data optional

Only emit the speed annotations when a sample rate was specified. Cope
with the absence of a sample rate for the input stream. Decoding is
still possible, it's just that no timing information is available.

i2s: make samplerate meta data optional

Only emit sound samplerate information when an input stream sample rate
was specified. Cope with the absence of a sample rate for the input
stream. Decoding is still possible, it's just that no timing information
is available.

i2c: make input samplerate optional

Absence of a samplerate for the input stream should not be fatal. The
protocol decodes fine, we just cannot determine a bitrate for frames.

This addresses part of bug 1076.

configure.ac: explicitly require pkg-config related macro

Make sure the PKG_PROG_PKG_CONFIG macro has become available before it
gets used. This unbreaks configuration in the poky environment (rocko).

graycode, morse, pwm, usb_request, wiegand: cope with absent sample rate

Improve robustness of some more protocol decoders. Few of them never
checked for the availability of a sample rate in the first place, others
checked for the presence of a spec but would not cope with a value of 0.
Some checked the value only after processing it, which could result in
runtime errors.

This change is motivated by bug #1118.

spi: cope when a sample rate of 0 was configured

The explicit test for None was not good enough. Change test conditions
such that sample rates only get processed when they got specified _and_
were not zero.

This fixes bug #1118.

ac97: introduce first AC'97 decoder implementation (bits, slots, binary)

Introduce an "audio and modem control for PC systems" protocol decoder
(referred to as AC'97).

This implementation extracts bits and identifies frames, and annotates
the slots of a frame with mere integer values. Bit fields get decoded
depending on the slot numbers. Bit patterns in audio/modem data slots
can get exported as binary streams.

Some TODO items remain. Register access (read/write) gets annotated, but
neither gets interpreted nor affects the decoding of subsequent frames.
The RESET# line status does not get evaluated.

i2c: Drop obsolete 10bit slave address TODO.

Nobody has seen any such slave in the wild, yet. In the very unlikely
case that someone actually sees or needs this, patches are welcome
though (together with sample .sr files).

counter: make 'reset' signal polarity an option

Allow configuration of the 'reset' signal polarity. Reset counters on
either falling (default) or rising edges.

counter: Make "word reset" an explicit annotation class+row.

Also, add long and short annotation string versions.

Add a trivial "counter" decoder

This decoder just counts the number of falling and/or rising edges. This
is especially useful for diagnosing protocols with a clock signal or a
fixed number of transitions per bit, e.g. pulse length coded.

It also provides a divider, which can be used to e.g. count the number
of words in I²C or SPI transfers.

parallel: implement consistent number formatting

Print all annotations for individual data bit items and for the
de-multiplexed words in a consistent style with leading zeros and
constant width. This shall lend itself better to quick navigation
during visual inspection, as well as automatic processing.

parallel: unbreak and improve "word" de-multiplexing

The previous implementation prepared but never fully enabled the
accumulation of several multi-bit items into words that span multiple
bus cycles (think: address or data de-multiplexing on memory busses).

Complete the accumulation, and fixup the end samplenumber for word
annotations. Fixup the endianess logic (the condition was inverted).
Rephrase calculation to be more Python idiomatic.

Default to word size zero, and only emit word annotations for non-zero
word size specs. This keeps the implementation backwards compatible and
still passes the test suite. Default behaviour is most appropriate for
interactive use in GUI environments, while automated processing will
find consistent behaviour across all setups (non-multiplexed busses, and
multiplexed busses with "words" that span one or multiple cycles).

parallel: cope with sparse input mappings, assume zero for not-connected pins

Cope when users only provide e.g. input lines D0 and D2 to the parallel
decoder. Assume that not-connected pins are "always zero".

Rephrase the .decode() logic which determines .wait() conditions while
we are here, to slightly unobfuscate the implementation.

This fixes bug #1088.

parallel: address minor style nits, no change in behaviour

Remove the redundant .itemcount variable, which exactly corresponds to
the length of the .items array.

Arrange retrieval of options and their evaluation closer to each other
for improved readability.

Use common logic to construct "words" from several multi-bit "items".
Arrange for endianess support by optionally reversing the array before
traversal.

parallel: unify decode() code paths with and without clock signal

Instead of implementing two main loops for operation in the presence and
in the absence of a clock line, use a common main loop which operates on
pre-determined wait conditions.

usb_power_delivery: enforce check order for start-of-packet sequences

The list of a dictionary's keys need not reproduce in identical order
everywhere. Make sure to run all start-of-packet sequence checks in the
decoder implementation in a specific order on each machine, such that
annotations get emitted with identical content and in the same order for
each execution of the decoder.

This fixes the remaining part of bug #1090.

usb_power_delivery: fixup a Python style nit (dict lookup fallback)

Use the dictionary's .get() method in combination with a default result
parameter, instead of an explicit "k in dictvar" test and a conditional
assignment.

usb_power_delivery: enforce numerical order of RDO/PDO flag annotations

Annotations of the USB power delivery decoder contain multiple text
fragments that correspond to several flags in bit fields. The Python
runtime did not guarantee an order of emission and made the test suite
fail.

Sort the order in which RDO and PDO flags related text fragments get
constructed and concatenated. Print text for higher bit positions first
as this might feel more intuitive to users.

This fixes part of bug #1090.

all decoders: introduce a reset() method

Move initialization code of protocol decoders from the constructor to a
new reset() helper method. The libsigrokdecode backend could run this
method several times to clear the decoder's internal state, before new
data from another acquisition gets fed to decode() calls.

ssi32: rename reset() helper method

The ssi32 decoder implements a reset() method which clears internally
accumulated data during decoding. Rename the method before all decoders
will grow a new reset() method that will be used for a different purpose.

mrf24j40: rename reset() helper method

The mrf24j40 decoder implements a reset() method which clears internally
accumulated data during decoding. Rename the method before all decoders
will grow a new reset() method that will be used for a different purpose.

ade77xx: rename reset() helper method

The ade77xx decoder implements a reset() method which clears internally
accumulated data during decoding. Rename the method before all decoders
will grow a new reset() method that will be used for a different purpose.

sdcard_sd: remove unused .reset() method

The decoder's .reset() method seems to partially implement constructor's
assignments, but is not referenced anywhere. There is neither a direct
call site in the remainder of pd.py which uses the "reset" name, and
runtime computation only references "handle_*()" methods for commands
and responses.

Drop the unused .reset() method in the individual decoder before the
introduction of a common .reset() method approach for all decoders.

am230x: rename reset() helper method

The am230x decoder implements a reset() method which clears internal
decoder state. Rename the method before all decoders will grow a new
reset() method that will be used for a different purpose.

eeprom 24xx: rename reset() helper method

ir_nec: Make timing margin relative

This replaces the fixed timing margin with a percentage based tolerance
to better allow for timing inaccuracies, especially for longer timings
like the Leader and Repeat codes.

graycode: Move bitpack/bitunpack to common/.

Add a gray code and rotary encoder protocol decoder.

Add a morse code protocol decoder.

i2s: Fix unportable use of struct.pack

Using the format string 'I' with the default (implied) prefix '@'
results in both word size and endianness being platform dependent.
In this case standard size (32 bits) and little endianness is
required, so the prefix '<' needs to be used.

maple_bus: Add helpers to make the call sites a bit shorter.

Add an initial Maple bus decoder.

instance.c: Removed redundant variable

configure.ac: Added AC_C_BIGENDIAN to autoconf

This is needed so that WORDS_BIGENDIAN is defined on big-endian
systems, which is needed by version.c .

i2s: Set file size to 4Gb

i2s: Make 32-bit wav files

ds243x: Add binary output for data read from EEPROM

Rename ds2432 to ds243x

ds2432: Adapt to allow for DS2433 as well

ds2432: Simplify MAC printing.

ds2432: Add a Maxim DS2432 protocol decoder.

This fixes (parts of) bug #1019.

srd_init(): Print list of decoder search paths in debug output.

Clarify and improve channel map debug output.

usb_request: Remove code duplication, save end sample in central location

usb_request: Handle CONTROL transfer protocol stalls

According to the USB 2.0 spec, 8.5.3.4, a protocol stall condition lasts
until the next SETUP transfer. On reception of the SETUP, adjust the end
sample accordingly, and flush the previous CONTROL transfer.

Fix a unit test.

Only try to acquire the GIL if the Python interpreter is actually
initialized, otherwise there'll be a segfault.

can: introduce clock synchronization (simple implementation)

Check for falling edges (i.e. changes to dominant state) between bits of
a CAN frame, and adjust subsequent bit slots' sample points accordingly.
This is a simple implementation which could get improved later. But it
improves the decoder's reliability when the input signal's rate differs
from the nominal rate.

This fixes bug #990.

Reported-By: PeterMortensen via IRC

can: rename 'bitpos' variable

Consistently use .sample_point for the member variable that corresponds
to the 'sample_point' property. Use 'samplenum' in .get_sample_point()
to reflect that the routine returns a sample number. This eliminates the
'bitpos' identifier which was used for two different things.

self.put(): Eliminate an unneeded malloc/free pair.

Acquire/release the Python GIL where needed to avoid threading issues.

With these additions, frontends can now call libsigrokdecode API
functions from different threads without running into threading issues.

The backend releases the GIL when it is performing tasks that might take
a while and it doesn't need to run Python/C API calls during that time.

This allows frontends to run multiple PD stacks (in multiple frontend
threads) "at the same time" in a time-sharing, "interlocked" manner.
Whenever one of the decoders is inside e.g. self.wait() it releases the
GIL and thus allows other decoders to do some work in the mean time.

The user-visible effect is that for use-cases such as running 3 different
decoder stacks at the same time for an acquisition, the user will not
have to wait for PD 1 to finish decoding, then wait for PD 2 to finish
decoding, and only *then* being able to see annotations from PD 3.

Instead, all three PDs will decode some chunks of data from time to
time, thus the user is able to inspect annotations from all 3 PDs while
the acquisition and decoding is still going on.

HACKING: Prefer git pull requests over mailing list patches.

Also, drop the reference to gitorious.org (no longer available).

pwm: Drop unused 'pins' variable.

ir_rc5: Rephrase open coded value for start bit 1

Make obvious that the start bit's value is 1 in the IDLE stage.

lpc: Improve robustness when decoding unexpected input data

The 'fields' table of state and descriptions is not fully populated,
some slots are missing. Cope with lookup misses when unexpected input
data is not found in the table. Use different error text in annotations
for described but invalid states (the previous implementation used
"reserved / invalid"), and for states that are not described in the
table (introduce the "reserved / unknown" text for conditions that are
not covered by the decoder implementation).

The previous implementation missed the emission of some warnings. When a
"reserved / invalid" description was found, the subsequent exact match
for "reserved" failed and the warning was not emitted. Weaken the test
to emit warnings for either description that has "reserved" in it,
regardless of whether the text was found in the table or is not part of
the table at all.

lpc: Nit, remove an unused variable

onewire_network: Fixup start samplenumber for annotations

Annotations generated by the onewire_network decoder started where bit 1
began, while it should align with the start of bit 0.

guess_bitrate: Eliminate internal state of the decoder

Getting the first edge outside of the loop in .decode() greatly
simplifies the logic, any other edge then is just an update of the
previously collected data, determined by always equal code.

i2c: Don't drop the first sample of input data

The previous implementation of the I2C decoder used to retrieve and not
process the first sample of the input stream. Remove this instruction.

decoders: Rephrase condition-less .wait() calls (self documentation)

Telling .wait() to "skip one sample" slightly obfuscates the intent of
getting the next samples while no condition applies. Explicitly pass no
condition arguments instead, to better reflect the purpose. Coincidently
these .wait() calls will execute in slightly less expensive code paths
in the common code.

decoder: Accept more forms of "unconditional wait()" (None, no args)

The Decoder.wait() method expects a list of dicts, or as a special form
a single dict, to specify the conditions to wait for. An empty dict or
an empty list mean "unconditional wait", requesting the very next sample.

Accept None as well as no arguments at all in Decoder.wait() calls. This
shall better reflect the intent and slightly unobfuscate PD code, as well
as avoid creation of potentially expensive Python objects at the call site.

decoder: Unbreak execution of Decoder.wait() with empty condition

The Decoder.wait() method works as expected when non-empty conditions
are specified by the caller. For empty conditions the implementation was
incomplete, and ended up in an infinite loop because the sample number
got stuck in the current location. Code review revealed more issues like
not getting more input data chunks when needed.

Detect when empty wait() conditions were specified, and re-use existing
code paths for match handling as much as possible. This is achieved by
the manual creation of a SKIP term with the appropriate count value.
It's assumed that naive decoder implementations will run this kind of
condition-less query for every individual sample, which means that
efficiency is important.

Make sample number 0 available to condition-less calls, too. Don't skip
the first sample in the input stream.

usb_signalling: Move another edge detection to common backend code

Rephrase how the 'WAIT IDLE' stage skips over all-low input signals.
Have the next high level on either line detected in common code.

pwm: Fixup sample numbers for binary output

Do reference the period's start and end sample numbers when the
duty cycle is written to the binary output stream. The previous
implementation inappropriately used the period counter instead.

pwm: Eliminate more decoder "state"

Move more items from the Python object's members to local variables of the
decode() method, as they are used there exclusively.

Mark a spot where the binary output references suspicious "sample numbers".