Hardware driver API

Every plugin is built as a shared library, dynamically loaded by the backend at startup. The plugin must define a structure as follows:

#include "sigrok.h"

struct device_plugin {
	/* plugin-specific */
	char *name;
	char *longname;
	int api_version;
	int (*init) (char *deviceinfo);
	void (*cleanup) (void);

	/* device-specific */
	int (*open) (int device_index);
	void (*close) (int device_index);
	char *(*get_device_info) (int device_index, int device_info_id);
	int (*get_status) (int device_index);
	int *(*get_capabilities) (void);
	int (*set_configuration) (int device_index, int capability, char *value);
	int (*start_acquisition) (int device_index, gpointer session_device_id);
	void (*stop_acquisition) (int device_index, gpointer session_device_id);
};

#define SIGROK_HARDWARE_PLUGIN   struct device_plugin plugin_info

This structure is the only symbol imported into the backend namespace. The plugin's variables thus cannot conflict with the global sigrok namespace.

• name
  A short string describing this driver. It will be referenced in saved session files.

• longname
  A long string describing this driver. It will be shown to the user.

• api_version
  Currently defined as 1.

The other members of the structure are pointers to plugin callbacks:

• init(char *device)
  Called when the plugin is initially loading into sigrok, typically at program start. The parameter refers to a device name or special file, whichever is applicable for the plugin. Devices which don't need a supplied device, such as USB devices, can simply ignore this parameter. The function returns the number of devices found, and 0 if no suitable device was found. If a device was found, any initialization it needs must be performed here; for example, uploading firmware should be done here.

• cleanup()
  Called before the plugin is unloaded. Release any resources the plugin might be holding.

• open(int device_index)
  Open the specified device. The device index starts at 0.

• close(int device_index)
  Close the specified device.

• get_device_info(int device_index, int device_info_id)
  Returns information about the given device. The type of information is given as device_info_id, one of a set of defined constants. The return value is always a pointer, which points to information specific to the id.
  • DI_INSTANCE: Returns a pointer to a struct sigrok_device_instance.
  • DI_NUM_PROBES: The number of probes connected to this device (integer).
  • DI_SAMPLERATES: Returns a pointer to a struct samplerates.

• get_status(int device_index)
  Returns an integer describing the status of the plugin's connection to a device. This may be one of the following:
  • ST_NOT_FOUND: The device was not found.
  • ST_INITIALIZING: The device was found, but is still initializing.
  • ST_INACTIVE: The device is live, but not in use.
  • ST_ACTIVE: The device is currently in use.

• get_capabilities()
  This function returns a zero-terminated integer array with the plugin's capabilities, in the form of a set of defined constants. Some of these are informative, and some can be used to configure the plugin (or its connected device). The capabilities tables below have an overview of all possible capabilities.

• set_configuration(int device_index, int capability, char *value)
  This is used to configure the plugin and/or connected device. The capability is one of the constants returned from the get_capabilities() call. The value depends on the parameter that is to be configured.

• start_acquisition(int device_index, gpointer session_device_id)
  Start acquisition on the specified device. The session_device_id will be passed along with the data feed of this session, as the first parameter to session bus callbacks.

• stop_acquisition(int device_index, gpointer session_device_id)
  Stop acquisition on the specified device. This causes a DF_END packet to be sent to the sesion bus.

Device classes

• HWCAP_LOGIC_ANALYZER

This device is a logic analyzer.

Device options

• HWCAP_SAMPLERATE

The sample rate in Hz (uint64_t *).

• HWCAP_PROBECONFIG

Probe configuration (GSList *probes)

• HWCAP_CAPTURE_RATIO

Pre-trigger capture ratio, as a percentage of the number of samples returned. The default is 0, meaning capturing only starts after the trigger fired (uint64_t *).

• HWCAP_PATTERN_MODE

Pattern to generate (char **).

Acquisition modes

• HWCAP_LIMIT_MSEC

How long the acquisition should last, in ms (uint64_t).

• HWCAP_LIMIT_SAMPLES

How many samples to acquire in the session (uint64_t).

• HWCAP_CONTINUOUS

Device supports continuous sampling