Input API

From Sigrok

Sigrok can process acquisition data in several different ways. Aside from acquiring data from a hardware device, it can also take it from a file in various formats. The Input API described here is intended to make supporting a new file format easier.

Like everything in sigrok that handles data, processing is done in a streaming manner -- input should be supplied to sigrok a chunk at a time. This way anything that processes data can do so in real time, without the user having to wait for the whole thing to be finished.

Contents 1 Creating a new module 2 Namespace 3 Structures 3.1 struct input_format 3.1.1 extension 3.1.2 description 3.1.3 format_match, in_loadfile 4 Global functions 4.1 struct io_format *io_list(void) 5 Per-module callback functions 5.1 int format_match(char *filename) 5.2 int in_loadfile(char *filename)

Creating a new module

• create the source file in the backend/input directory. You can use input_skeleton.c as a handy template.
• reference your source file in the file backend/input.c twice: once to pull in the external declaration, and once in the input_module_list[] array.

Namespace

Every input module is "pluggable", meaning it's handled as being separate from the main libsigrok, but linked in to it statically. To keep things modular and separate like this, functions should be declared static, with only the registration struct exported for use into the wider namespace.

Structures

struct input_format

struct input_format { char *extension; char *description; int (*format_match) (char *filename); int (*in_loadfile) (char *filename); };

extension

This is the file extension for this format. When loading a file with this extension, this input module will be used to process the data.

It is also used by the sigrok CLI, to select this format for use. For example, calling the CLI with -f hex will select the hexadecimal text output format, but when saved to a file with no extension in the filename, will be added to it.

description

A short description of the format in freeform text. This will be displayed by the sigrok GUI, when selecting the output format for saving a file.

format_match, in_loadfile

These are function references to your module's callbacks. See below for more information on each callback.

Global functions

struct io_format *io_list(void)

Returns a NULL-terminated list of pointers to struct io_format, defining which formats are available for use.

Per-module callback functions

The format_match callback returns a boolean value. All other callbacks return SIGROK_OK if all went well, or another SIGROK_ERR_* code in case of error.

int format_match(char *filename)

This function checks if the given filename is something it can load and parse. Returns TRUE if this module knows the format, or FALSE if it doesn't.

int in_loadfile(char *filename)

Load a file, parsing the input according to the file's format. This function will send datafeed packets to the session bus, so the calling frontend must have registered its session callbacks beforehand.

The packet types sent across the session bus by this function must include at least DF_HEADER, DF_END, and an appropriate data type such as DF_LOGIC8. It may also send a DF_TRIGGER packet if appropriate.