View source for 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 sr_device_plugin {
 	/* plugin-specific */
 	char *name;
 	char *longname;
 	int api_version;
 	int (*init) (const char *deviceinfo);
 	void (*cleanup) (void);
 
 	/* device-specific */
 	int (*opendev) (int device_index);
 	int (*closedev) (int device_index);
 	void *(*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'''<br />A short string describing this driver. It will be referenced in saved session files.

* '''longname'''<br />A long string describing this driver. It will be shown to the user.

* '''api_version'''<br />Currently defined as 1.

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

* '''init(const char *deviceinfo)'''<br />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()'''<br />Called before the plugin is unloaded. Release any resources the plugin might be holding.

* '''opendev(int device_index)'''<br />Open the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''closedev(int device_index)'''<br />Close the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''get_device_info(int device_index, int device_info_id)'''<br />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.
** SR_DI_INSTANCE: Returns a pointer to a [[Formats_and_structures#device_instances|struct sigrok_device_instance]].
** SR_DI_NUM_PROBES: The number of probes connected to this device (integer).
** SR_DI_PROBE_NAMES: The probe names on this device (array of char*).
** SR_DI_SAMPLERATES: Returns a pointer to a [[Formats_and_structures#Sample_rates|struct samplerates]].
** SR_DI_TRIGGER_TYPES: Types of trigger supported, out of "01crf" (char *).
** SR_DI_CUR_SAMPLERATE: The currently set samplerate in Hz (uint64_t).
** SR_DI_PATTERNMODES: Supported pattern generator modes (array ov char*).

* '''get_status(int device_index)'''<br />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()'''<br />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)'''<br />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)'''<br />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)'''<br />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