Difference between revisions of "Hardware driver API"

From sigrok
Jump to navigation Jump to search
Line 39: Line 39:
* '''close(int device_index)'''<br />Close the specified device.
* '''close(int device_index)'''<br />Close the specified device.


* '''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 must be cast according to the type of information returned:
* '''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.
** DI_IDENTIFIER: String identifying this specific device in the system, in case more than one is connected.
** DI_INSTANCE: Returns a pointer to a [[Formats_and_structures#device_instances|struct sigrok_device_instance]].
** DI_NUM_PROBES: The number of probes connected to this device (integer).
** 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 uint64_t.
** DI_SAMPLERATES: Returns a pointer to a [[Formats_and_structures#Sample_rates|struct samplerates]].


* '''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:
* '''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:

Revision as of 13:19, 28 March 2010

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 string describing this driver. It will be referenced in saved session files.
  • 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.
  • 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.

Informative capabilities

  • HWCAP_LOGIC_ANALYZER
This plugin supplies a logic analyzer.

Configurable capabilities

  • HWCAP_SAMPLERATE
The sample rate in Hz (uint64_t).
  • 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).