Protocol decoder output

NOTE: This page is currently work-in-progress.

A protocol decoder (PD) can output various different things that libsigrokdecode frontends (or other protocol decoders) can use for different purposes.

The following types of protocol decoder output are currently implemented or planned to be implemented later: annotations, binary output, reports, proto output.

Annotations

Annotations (the OUTPUT_ANN output type) are meant to be displayed to the user via a frontend (GUI, command-line, or other).

They are specifically not meant for any usage other than displaying, i.e. no further processing is done on them, no dumping to file formats, or anything similar to that.

While it is technically possible to a certain degree to e.g. parse the decoder annotation output that (command-line or other) frontends print, and do further processing on that (using sed, awk, grep, perl, or other tools), that is risky since the format of the respective frontend's output and the PD output itself can change at any time and is specifically not designed to be easily processable programmatically in any way, shape, or form.

There is a better facility for this kind of usage in libsigrokdecode though, see Binary output below.

Every protocol decoder can output an arbitrary number of different annotation types. Not all protocol decoders have to output annotations, though (this is optional). There are also various PDs that are used for several other purposes (not for generating output to be displayed in frontends), and they thus don't output annotations at all.

Binary output

Binary output (the OUTPUT_BINARY output type) is not meant for direct displaying to the user by a frontend. Instead, it is some kind of representation of decoded data, in some specific format, that can be saved to file and/or loaded by (or piped into) other applications and/or be further processed via other tools.

Every protocol decoder can output an arbitrary number of different "binary" output formats. Not all protocol decoders have to have binary output, though (this is optional).

Reports

Reports are certain pieces of additional information a protocol decoder can output, for a frontend to display to a user.

In contrast to annotations, this information is not specific to a certain subset of samples. Instead, it is information that applies to the full sample set (the full input that is decoded). Reports are only generated when the decoding run is finished.

Every protocol decoder can output an arbitrary number of different types of reports (each of them applies to the whole dataset). Not all protocol decoders have to have report output, though (this is optional).

Proto output

Proto output (the OUTPUT_PROTO output type) is used by PDs to pass data on to other (stacked) PDs. It is specifically not used in any way, shape, or form by frontends (only by other PDs). It is not passed to a frontend at all.

On the implementation level libsigrokdecode passes arbitrary Python objects from one (Python) decoder to the next (stacked one). The contents of those objects are entirely up to the lower-level PD, and every PD uses a different, suitable format that is useful for the specific protocol at hand, and easy to use by stacked decoders. There is no standard format for this output (and there cannot be any). Every PD that provides OUTPUT_PROTO documents the format of its output, so that authors of stacked PDs know how to use it.

Every protocol decoder can output OUTPUT_PROTO data for other PDs. Not all protocol decoders have to have OUTPUT_PROTO output, though (this is optional). There are protocol decoders that, for example, only output annotations, or only output binary formats, and don't (yet) have any OUTPUT_PROTO data to be used by stacked decoders. Decoders without OUTPUT_PROTO output cannot be used by any stacked PDs, of course.