Formats and structures

This document describes various formats used by sigrok.

Data feed

The data feed format is used to transfer data feeds internally within sigrok. It is created by a hardware plugin (or the session load code) by taking raw data and adding metadata to it. A feed packet consists of a packet type, followed by a structure particular to that data type.

Data feed packet

struct datafeed_packet {
	uint16_t type;
	uint16_t length;
	void *payload;
};

Packet types

DF_HEADER:

This the first packet in any data stream. The payload consists of the following struct:

struct datafeed_header {
	int feed_version;
	struct timeval starttime;
	uint64_t samplerate;
	int protocol_id;
	int num_probes;
};

DF_END: End of stream (no further data).

DF_TRIGGER: The trigger matched at this point in the data feed. There is no payload in this packet, but the next data to come in will be the samples that matched the trigger.

DF_LOGIC8: Raw logic analyzer data. Unitsize is 1 byte, describing up to 8 probes worth of data, one sample per bit. MSB = first probe. Unused bits are set to zero.

DF_LOGIC16: Raw logic analyzer data. Unitsize is 2 bytes, describing up to 16 probes worth of data, one sample per bit. MSB = first probe. Unused bits are set to zero.

DF_LOGIC24: Raw logic analyzer data. Unitsize is 3 bytes, describing up to 24 probes worth of data, one sample per bit. MSB = first probe. Unused bits are set to zero.

DF_LOGIC32: Raw logic analyzer data. Unitsize is 4 bytes, describing up to 32 probes worth of data, one sample per bit. MSB = first probe. Unused bits are set to zero.

Data store

The data store consists of a series of chunks of memory, storing raw samples. The chunks are used to reduce the need for the system to provide a single contiguous area of memory for a potentially large dataset, while allowing the dataset to grow easily as data streams in.

Data store size is kept as small as possible by only storing as much data as is actually used, regardless of the sample size provided by a data feed. For example, a raw logic analyzer feed that comes in as a 4-byte unit of which only 4 probes (and thus 4 bits) are used, will use only 1 byte per unit.

struct datastore {
	/* size in bytes of the number of units stored in this datastore */
	int unitsize;
	unsigned int num_units;
	GSList *chunklist;
};

Session file

A sigrok session file contains all the raw data captured in a session, and various metadata identifying the source, pin names, and so on. The file extension of a session file is 'sigrok'. The file format is a ZIP file, containing the following files:

version: Contains the version of the session format used in this ZIP file, as an ASCII string. The starting version is 1.

metadata: This is a key-value file (.ini-like) containing the following keys in the [main] section:

• probes: Number of probes in this data feed.
• probename[]: An indexed list of probe names. The probe index starts at 1.
• trigger[]: An indexed list of triggers configured on the probes. The probe index starts at 1.
• analyzers: A list of protocol analyzers that was used on this data feed at the time it was saved, separated by a space, with the first entry representing the bottom of the analysis stack. Regardless of this list, the data feed saved is always the raw feed.
• starttime: High-resolution timestamp denoting the date + time the data was originally captured, in RFC 3339 format e.g. 2009-04-13 11:35:08.538429857+02:00.
• freqdiv: Sample frequency expressed as 1s / freqdiv.
• unitsize: The size (in bytes) of a single data unit in the data feed.
• device: The name of the device that was used to capture this data feed originally.
• port: The port to which the capture device was connected.

Unused probes have no probename defined, and probes that have no trigger defined are not mentioned in this file. Only relevant data is stored.

raw: This file contains the raw signal data, in network-endian format. The size of a unit is set in the "metadata" file.

device instances

This structure is created by a hardware driver/ It uniquely identifies one device in the system, regardless of how that device is connected.

struct sigrok_device_instance {
    int index;
    int status;
    int instance_type;
    char *vendor;
    char *model;
    char *version;
    union {
        struct usb_device_instance *usb;
        struct serial_device_instance *serial;
    };
};

index

A counter identifying different devices handled by the same driver, starting at 0.

status

Can be one of:

• ST_INITIALIZING: the device is not yet ready -- for example, it's still booting, or a firmware upload is in progress.
• ST_INACTIVE: the device is ready.
• ST_ACTIVE: the device is currently in use.

instance_type

If this is USB_INSTANCE, the usb field points to:

struct usb_device_instance {
    uint8_t bus;
    uint8_t address;
    struct libusb_device_handle *devhdl;
};

If instance_type is SERIAL_INSTANCE, the serial field points to:

struct serial_device_instance {
    char *port;
    int fd;
};

vendor, model, version

These are strings ready for display, identifying the device. The version string may be empty, or may have extensive information regarding hardware version, firmware version, on-board memory and so on.