Hardware driver API

Hardware plugin 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;
	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 freeform string describing the device handled by this plugin.

• 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 must be cast according to the type of information returned:

• DI_IDENTIFIER: string identifying this specific device in the system, in case more than one is connected.
• DI_NUM_PROBES: the number of probes connected to this device (integer).
• DI_SAMPLE_RATES: the samples rates this device supports, as a 0-terminated array of float.

• 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 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.

Informative capabilities

• HWCAP_LOGIC_ANALYZER

This plugin supplies a logic analyzer.

Configurable capabilities

• HWCAP_SAMPLERATE

The sample rate in Mhz.

• HWCAP_LIMIT_SECONDS

How long the acquisition should last.

• HWCAP_LIMIT_SAMPLES

How many samples to acquire in the session.