Difference between revisions of "Hardware driver API"

From sigrok
Jump to navigation Jump to search
Line 35: Line 35:


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


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


* '''close(int device_index)
* '''close(int device_index)
  Close the specified device.
Close the specified device.


* '''get_device_info(int device_index, int device_info_id)'''
* '''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:
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_IDENTIFIER: string identifying this specific device in the system, in case more than one is connected.
Line 57: Line 57:


* '''get_status(int device_index)'''
* '''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:
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_NOT_FOUND:    The device was not found.
   * ST_INITIALIZING:  The device was found, but is still initializing.
   * ST_INITIALIZING:  The device was found, but is still initializing.
Line 64: Line 64:


* '''get_capabilities()''':
* '''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.
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)''':
* '''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.
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(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.
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(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.
Stop acquisition on the specified device. This causes a DF_END packet to be sent to the sesion bus.





Revision as of 21:41, 14 March 2010

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 is a freeform string describing the device handled by this plugin.
  • api_version is currently defined as 1.

The other members of the structure as 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

{{{

  1. !rst
============================= =================================

Capability Description

============================= =================================

HWCAP_LOGIC_ANALYZER This plugin supplies a logic analyzer.

============================= =================================

}}}

Configurable capabilities

{{{

  1. !rst
============================= =======

Capability Value

============================= =======

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.

============================= =======

}}}