Difference between revisions of "Protocol decoders"

From sigrok
Jump to navigation Jump to search
m
Line 1: Line 1:
This page describes how Protocol Decoders (PDs) work in sigrok.
This is a list of ideas for specific protocol decoders we might want to write in the future (or users might want to contribute).
 
== 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 both 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 [[Command-line|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, descriptionm, capabilities, etc by populating a hash (dict) 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 python controller.
* 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 python interface in libsigrokdecode 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.
** 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 two definitions


* a populated dict '''register''' which defines the name, capabilities etc of the PD.
See [[Protocol decoder API]] for details on how the decoders work in sigrok.
This is an example:
 
register = {
  'id': 'spi',
  'description': 'SPI',
  'protocol in': 'raw',
  'probes': {
    ['sclk', "sck", "clk"],
    ["mosi", "simo", "sdi", "di", "si"],
    ["miso", "somi", "sdo", "do", "so"],
    ["ncs", "cs", "csb", "nss", "ste"],
  ],
  'protocol out': 'bytes'
}
 
* a function called '''run()''' which is called by libsigrokdecode. It is defined like this:
 
def run(num_probes, samplerate=None)
 
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.
 
 
== Protocol decoders ==
 
This is a list of ideas for specific protocol decoders we might want to write in the future (or users might want to contribute).


=== Low-level decoders ===
== Low-level decoders ==


'''Standard protocols that have raw signals/samples as input:'''
'''Standard protocols that have raw signals/samples as input:'''
Line 201: Line 157:
... and many, many more.
... and many, many more.


=== High-level decoders ===
== High-level decoders ==


'''Protocols that do not have raw signals/samples as input, but rather an already-preprocessed bytestream generated by one of the low-level decoders:'''
'''Protocols that do not have raw signals/samples as input, but rather an already-preprocessed bytestream generated by one of the low-level decoders:'''
Line 259: Line 215:
* ...
* ...


== Ideas ==


* Plugin system for protocol decoding:
__FORCETOC__
** Should support SPI, I2C, RS232/UART and many many more protocols, see above.
** Should be easy to add support for additional/custom protocols, e.g. AT93C46:
*** CS (chip select)
*** SK (clock)
*** DI (data from chip to outside)
*** DO (data from outside into chip)
*** Has start bit, opcodes, data following transmission
** A protocol as simple as this should be doable to implement without code, only the description of the meaning of the various pins.
* PD plugins '''must''' be GUI-independent: they must always work on any [[GUI]] present in sigrok. The plugin interface must therefore provide hooks for:
** Providing data from core to plugin - stream or dump.
** Sending analysis results back from the plugin, e.g. timestamps or sample IDs with structured results:
*** Type:
**** 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"
* This also opens up the possibility of producing e.g. a protocol analysis report from the main code.
* All PD plugins are written in Python.
** We embed a scripting language (Python) for very simple transforms and/or additional display; e.g. 4-bit interface to HD44780 LCD, take two nibbles in sequence, based on clock line, and assemble them into a whole byte. Scripted plugin could do this, then pass the data back to the UI for display.

Revision as of 01:59, 1 May 2010

This is a list of ideas for specific protocol decoders we might want to write in the future (or users might want to contribute).

See Protocol decoder API for details on how the decoders work in sigrok.

Low-level decoders

Standard protocols that have raw signals/samples as input:

Protocol Status Comments
Basic / microcontrollers / embedded
SPI 0%
I2C 0%
USART/RS232 0%
Automotive / industrial / embedded
CAN 0%
Embedded
JTAG 0%
PC
USB 1.1 0%
USB 2.0 0%
USB 3 0%
LPC 0%
FWH 0%
ISA 0%
PCI 0%
SMBus 0%
Consumer IR
Nokia NRC17 0%
Sony SIRC 0%
Philips RC-5 0%
Philips RC-6 0%
Philips RC-MM 0%
Philips RECS80 0%
Miscellaneous
IrDA 0%

... and many, many more.

Custom / application-specific protocols that have raw signals/samples as input:

Protocol Status Comments
Serial EEPROMs
AT93C46 0% Atmel AT93C46 serial EEPROM protocol
Displays
HD44780 0% HD44780 character LCD protocol

... and many, many more.

Non-protocol data analysis decoders / analyzers that have raw signals/samples as input:

  • Number of clock cycles / rising-edges / falling-edges / transitions / etc. (total or per-signal)
  • Min/Max/Avg distance between two events (rising edge, falling edge, signal lenths, etc.)
  • ...

... and many, many more.

High-level decoders

Protocols that do not have raw signals/samples as input, but rather an already-preprocessed bytestream generated by one of the low-level decoders:

Protocol Input protocol Status Comments
Serial EEPROMs
TODO SPI 0% SPI-attached serial EEPROM. Datasheet: TODO.
Displays
SA8807A SPI 0% SPI-attached LCD. Datasheet: Sames SA8807A.
EA eDIPTFT43-A I2C 0% I2C-attached LCD. Datasheet: EA eDIPTFT43-A.
TODO USART/RS232 0% TODO
ADC
AD7291 USART/RS232 0% I2C-attached ADC. Datasheet: Analog Devices AD7291.

... and many, many more.

Non-protocol data analysis decoders / analyzers:

  • How many data bytes are in the data stream?
  • What's the min/max/avg data value?
  • ...


Retrieved from "https://sigrok.org/w/index.php?title=Protocol_decoders&oldid=479"