Protocol decoder API

This page describes how Protocol Decoders (PDs) work in sigrok.

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. Only source code will be used (i.e. no .pyc or .pyo files).
• Every PD registers its name, description, capabilities, etc by populating a hash (dictionary) in its own main namespace called "register".
• 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.
• 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).
  • data packets get translated into a bytestream, which the PDs access through an API: the function get_sample() 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 an EOF on the get_sample() call.

API

A PD must contain at least a populated dictionary register which defines the name, capabilities etc of the PD. The following keys can be used:

Key	Type	Description
Protocol Decoder information
id	required	A short unique identifier for this protocol. It should be all-lowercase, and only contains a-z, 0-9 and underscores. The sigrok CLI uses this to specify PDs.
description	required	A freeform one-line description of the decoder. Used when listing available PDs.
in	required	The type of input this decoder needs. If the decoder takes input from a logic analyzer driver, this should be set to 'logic', which maps to DF_LOGIC the datafeed type. If it takes input from another PD, it should be set to the value of the 'out' key of that PD. It should conform to the same rules as the id key.
out	optional	If this decoder can feed decoded data back into the datafeed stream, its output 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.
author	optional	Name and optionally email address of the author of this PD.
version	optional	Version of this PD.
Available functions
start	required	Reference to a python function that will be called to start the decoder. The PD controller will call this function when the first packet with real data in it comes in on the stream. See below for arguments to this function.
report	optional	If given, this is a reference to a function which returns a report in freeform text, describing some analysis done on the stream. For example, PDs for counting logic level transitioons, bit rate analysis and so on would use this to report back. This function is typically only called at the end of the stream, so the whole stream is analyzed. However, the function may be called at any time -- possibly giving an analysis of data received up until that point.
Protocol Decoder configuration
probes	optional	For the 'logic' input type this is a required key. it lists the probes (pins) the logic analyzer should feed to this PD, in order for it to make sense of the data. 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 can be either a string with the probe name (`"SCLK"`) or a list with the probe name and description, such as `["SCLK", "Clock"]`.
options	optional	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]`.

Here's an example for an SPI decoder:

register = {
 'id': 'spi',
 'description': 'SPI',
 'author': 'Sigrok project',
 'in': 'logic',
 'out': 'spi',
 'probes': [
   ['sclk', 'Clock, also known as sck or clk'],
   'mosi',
   'miso',
   ['ncs', 'Chip Select, also known as cs'],
 ],
 'options': {
   'cpol': ['Clock polarity', 0],
   'cpha': ['Clock phase', 0],
   'wordsize': ['Word size (in bits)', 8],
 },
 'start': start,
}

The start function should look like this:

def spi_start(probes, samplerate)

This function is called by libsigrokdecode at the start of a session which has this PD in its pipeline. It should implement a loop calling get_sample(), and only return when an EOF is detected in that loop.

The probes argument is a list containing probe names, in the order in which they will be returned from get_sample().

The samplerate argument is specified in Hz.

Ideas

• Sending analysis results back from the plugin, e.g. timestamps or sample IDs with structured results:
  • Protocol overhead e.g. start bits
  • Commands e.g. opcodes
  • Command parameters e.g. address following a READ command
  • Extracted data
  • String to display over the data ("opcode READ")
  • Data (e.g. 10) + length in bits (e.g. 2)
  • Results can overlap, as in e.g. "READ address 0x08" and "opcode 10"