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.

DF_ANALOG: Analog data, e.g. from a DMM, including measured quantity, unit and status flags.

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) with the following sections:

• device
  • driver: the name of the driver used to access this device
  • capturefile: the name of the file contained in this zip, which contains the raw samples captured with this device.
  • probe: a probe number, possibly followed by the name and trigger of this probe, e.g. "probe 1 name Clock trigger 01". This is repeated as many times as there are probes.
  • 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".
  • samplerate: the samplerate used for this capture.
  • unitsize: The size (in bytes) of a single data unit in the data feed.
  • 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-1 This file contains the raw signal data, in network-endian format. The size of a unit is set in the "metadata" file. The "1" in the filename just means it's the first capture stored.

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.

Sample rates

In sigrok, sample rates are always represented by a uint64_t value, expressing the rate in Hz. A hardware plugin reports the sample rates it supports with the following struct:

struct samplerates {
    uint64_t low;
    uint64_t high;
    uint64_t step;
    uint64_t *list;
};

The low and high values are the lower and upper bounds of the range supported by the device. If the device supports any rate in between those bounds, the minimum granularity is given in the step field. If a device only supports a specific set of sample rates, and nothing in between, a list of those rates is pointed to by the list field, which is a NULL-terminated array of uint64_t.

Either the step or list fields are filled in; never both. The unused field is set to NULL.