Protocol decoder API

This page describes how libsigrokdecode Protocol Decoders (PDs) work.

See also Protocol decoder HOWTO for a quick introduction of how to write your own decoders.

Architecture

The frontend gets input from the user on which PDs to use in an acquisition session. It then configures these into the session with session_pd_add(). As the first PD is added, the session sets up an additional datafeed callback to itself, which it uses as input to the first PD in the stack. The output of that is sent to the frontend, along with its original datafeed, as well as fed into the next PD in the stack.

The frontend thus gets the raw datafeed as well as a feed from every PD in the stack. Which of these different feeds is actually displayed to the user is a matter of configuration or selection by the user; it should be possible, for example, to have sigrok-cli print only the top of the PD stack's output on stdout.

• All PDs are written in Python (>= 3.0).
• Every PD registers its name, description, capabilities, etc.
• PDs will be stacked together, so the user can construct a decoding pipeline. The control of communication to/from PDs is done by the PD controller code in libsigrokdecode.
• The data feed into the PDs will be streamed, so they will run in real time as the data comes in from the hardware (or from a file).
• In order to keep PDs simple, they don't have to deal with the intricacies of the datafeed packets. Instead, the PD controller will hide the details from the Python code:
  • When receiving a DF_HEADER packet going to a PD, the controller intercepts the packet and instead generates a DF_HEADER "coming from" that PD across the session bus, with that PD's output characteristics (which it derived from the PD's register dictionary).
  • Data packets get translated into a bytestream, which the PDs access through an API: the function get() is a blocking call into the controller, which only returns when a datafeed packet has arrived, and its payload queued up for the PD.
  • DF_END packets are translated into a call to decode() with an empty data set.

API

Backend library

A Python module called sigrokdecode is provided. Every protocol decoder must import this. It contains the following items:

• the Decoder object

Every protocol decoder must subclass this object.

• OUTPUT_ANN

Constant used to register annotation output, used as argument to the register() function. sigrok-cli shows the annotation output of a decoder stack's topmost decoder, Pulseview shows annotation output as bars or as circles (if the duration of the annotation is zero).

• OUTPUT_PYTHON

Constant used to register python output, used as argument to the register() function. Python output is passed as input to a decoder that is stacked onto the current decoder. The format of the data that is given to the put() function should be documented for the authors of the higher level decoders, for example with a comment at the top of the decoders source file.

• OUTPUT_BINARY

Constant used to register binary output, used as argument to the register() function. The format of the data that is outputted is not specified, it's up to the author of the decoder to choose an appropriate format. For example, the UART decoder outputs the raw bytes that it decodes, but the output could also be an image file for a decoder that decodes a display protocol. sigrok-cli can be used to redirect the binary output of a decoder into a file, see the documentation of its --protocol-decoder-binary option.

• OUTPUT_META

Constant used to register metadata output, used as argument to the register() function.

• put(startsample, endsample, output_id, data)

This is used to provide the decoded data back into the backend. It takes the same arguments as the decode() function. output_id is an output identifier returned by the register() function. The data parameter's arrays must be of whatever length is appropriate to this PD's output. In other words, it must match the PD's native unitsize.

Decoder class functions

Required functions

• start()

This function is called before the beginning of the decoding. This is the place to register() the output types.

• decode(startsample, endsample, data)

This is a function that will be called by the PD controller whenever it has a chunk of data for the module to handle.

Argument	Description
startsample	The absolute samplenumber of the first sample in this chunk of data.
endsample	The absolute samplenumber of the last sample in this chunk of data.
data	A list containing items of data, such as samples or output from protocol decoders lower on the stack. Each item consists of an array of type B, which is an unsigned char. The length of this array corresponds with the unitsize value returned by the get_meta() call.

Decoder registration

A PD's Decoder class must contain a few attributes specifying metadata about the PD. The following keys can be used:

Key	Description
api_version	The libsigrokdecode API version which this module uses. This is currently 1.
id	A short unique identifier for this protocol decoder. It should be all-lowercase, and only contains a-z, 0-9 and underscores. This must match the PD's Python module name (subdirectory name in the decoders directory). The sigrok-cli tool uses this to specify PDs on the command-line. Examples: 'jtag', 'sdcard_spi', 'uart'.
name	The name of the decoder. Used when listing available PDs. Examples: 'JTAG', 'SD card (SPI mode)', 'UART'.
longname	The (long) name of the decoder. Used when listing available PDs. Example: 'Joint Test Action Group (IEEE 1149.1)', 'Secure Digital card (SPI mode)', 'Universal Asynchronous Receiver/Transmitter'.
desc	A freeform one-line description of the decoder. Used when listing available PDs. Should end with a full stop. Example: 'Protocol for testing, debugging, and flashing ICs.', 'Secure Digital card (SPI mode) low-level protocol.', 'Asynchronous, serial bus.'.
license	The license under which the module is provided. This must be either gplv2+ (meaning the GNU General Public License 2 or later), or gplv3+ (GNU General Public License 3 or later). No other licenses for modules are permitted in libsigrokdecode.
inputs	The list of types of input this decoder needs. If the decoder takes input from a logic analyzer driver, this should be set to logic, which maps to SR_DF_LOGIC, the datafeed type. If it takes input from another PD, it should be set to the value of the outputs key of that PD. It should conform to the same rules as the id key (lowercase, no spaces, and so on).
outputs	The list of types of output this decoder produces. If this decoder can feed decoded data back into the datafeed stream, its outputs will be identified with this key's value. It should conform to the same rules as the id key. If not specified, this decoder cannot feed data back into the stream. This typically means it only does analysis on the whole stream, producing a report at the end of acquisition.
probes	This key lists the probes (pins) the hardware should feed to this PD. The probes in this list MUST be present in the data; the PD will not be able to work without them. For example, an SPI decoder has to know which probe has the clock, which has the chip select, and so on. This key contains a list of probe entries, where each entry is of the Python dict with the keys id, name, and desc. Example: {'id': 'rx', 'name': 'RX', 'desc': 'UART receive line'}.
optional_probes	The list of probes the PD can make use of, but are not strictly required. The list is in the same format as that of the probes key, above. This list is allowed to be empty if the respective protocol has no optional probes.
options	A dictionary with options for this decoder. The keys should follow the same rules as for the id key above, and each value is a list consisting of a short freeform description of the option, and the default value for that option. For example, an SPI decoder might have an entry with key cpol, and value ['Clock polarity', 0]. This list can be empty, if the PD has no options.
annotations	A list of annotation types this protocol decoder can output. Elements of this list are tupes consisting of an identifier string and a human readable description string. The identifier string can be used in the options of sigrok-cli to select the specific annotation type, and should therefore not contain whitespace or special characters
annotation_rows	Annotation rows are used to group multiple annotation types together. The elements of this list are three element tuples consisting of: An identifier string. A human readable description string. A tuple containing the indices of the the annotation types in the annotations list. See the example on the Protocol decoder HOWTO page for more information on this attribute.
binary	A list of binary types this protocol decoder can output, same format as the annotations list.

• register(output_type)

This function is used to register the output that will be generated by the decoder, its argument should be one of the OUTPUT_... constants described above. The function returns an identifier that can then be used as the output_id argument of the put() function.

See the Protocol decoder HOWTO#pd.py for an example.

File structure

Code

See Protocol decoder HOWTO#Files.

Source code and copyright

The module MUST come with source code in the form of .py files. No pre-compiled code should be present, Python or otherwise. The module must not use any helpers that are not provided as source code under the same license as the module itself.

The Decoder class must have a license declaration (see above), stating the license under which all the contents in the module directory are provided.

Example files

Every protocol decoder module MUST come with example input and output files that put the decoder through its paces. All corner cases the decoder can handle must be triggered by the example files. Please submit the example files for inclusion in the sigrok-dumps repository.