libsigrok  0.5.2
sigrok hardware access and backend library
Functions
Devices

Device handling in libsigrok. More...

Functions

SR_PRIV void sr_channel_free_cb (void *p)
 Wrapper around sr_channel_free(), suitable for glib iterators. More...
 
int sr_dev_channel_name_set (struct sr_channel *channel, const char *name)
 Set the name of the specified channel. More...
 
int sr_dev_channel_enable (struct sr_channel *channel, gboolean state)
 Enable or disable a channel. More...
 
SR_PRIV gboolean sr_channels_differ (struct sr_channel *ch1, struct sr_channel *ch2)
 Compare two channels, return whether they differ. More...
 
SR_PRIV gboolean sr_channel_lists_differ (GSList *l1, GSList *l2)
 Compare two channel lists, return whether they differ. More...
 
gboolean sr_dev_has_option (const struct sr_dev_inst *sdi, int key)
 Determine whether the specified device instance has the specified capability. More...
 
GArray * sr_dev_options (const struct sr_dev_driver *driver, const struct sr_dev_inst *sdi, const struct sr_channel_group *cg)
 Enumerate the configuration options of the specified item. More...
 
int sr_dev_config_capabilities_list (const struct sr_dev_inst *sdi, const struct sr_channel_group *cg, const int key)
 Enumerate the configuration capabilities supported by a device instance for a given configuration key. More...
 
struct sr_dev_inst * sr_dev_inst_user_new (const char *vendor, const char *model, const char *version)
 Allocate and init a new user-generated device instance. More...
 
int sr_dev_inst_channel_add (struct sr_dev_inst *sdi, int index, int type, const char *name)
 Add a new channel to the specified device instance. More...
 
GSList * sr_dev_list (const struct sr_dev_driver *driver)
 Get the list of devices/instances of the specified driver. More...
 
int sr_dev_clear (const struct sr_dev_driver *driver)
 Clear the list of device instances a driver knows about. More...
 
int sr_dev_open (struct sr_dev_inst *sdi)
 Open the specified device instance. More...
 
int sr_dev_close (struct sr_dev_inst *sdi)
 Close the specified device instance. More...
 
struct sr_dev_driversr_dev_inst_driver_get (const struct sr_dev_inst *sdi)
 Queries a device instances' driver. More...
 
const char * sr_dev_inst_vendor_get (const struct sr_dev_inst *sdi)
 Queries a device instances' vendor. More...
 
const char * sr_dev_inst_model_get (const struct sr_dev_inst *sdi)
 Queries a device instances' model. More...
 
const char * sr_dev_inst_version_get (const struct sr_dev_inst *sdi)
 Queries a device instances' version. More...
 
const char * sr_dev_inst_sernum_get (const struct sr_dev_inst *sdi)
 Queries a device instances' serial number. More...
 
const char * sr_dev_inst_connid_get (const struct sr_dev_inst *sdi)
 Queries a device instances' connection identifier. More...
 
GSList * sr_dev_inst_channels_get (const struct sr_dev_inst *sdi)
 Queries a device instances' channel list. More...
 
GSList * sr_dev_inst_channel_groups_get (const struct sr_dev_inst *sdi)
 Queries a device instances' channel groups list. More...
 

Detailed Description

Device handling in libsigrok.

Function Documentation

SR_PRIV void sr_channel_free_cb ( void *  p)

Wrapper around sr_channel_free(), suitable for glib iterators.

Definition at line 97 of file device.c.

SR_PRIV gboolean sr_channel_lists_differ ( GSList *  l1,
GSList *  l2 
)

Compare two channel lists, return whether they differ.

Listing the same set of channels but in a different order is considered a difference in the lists.

Parameters
[in]l1First channel list.
[in]l2Second channel list.
Returns
#TRUE upon differences or unexpected input, #FALSE otherwise.

Definition at line 234 of file device.c.

References sr_channel::index, and sr_channels_differ().

+ Here is the call graph for this function:

SR_PRIV gboolean sr_channels_differ ( struct sr_channel ch1,
struct sr_channel ch2 
)

Compare two channels, return whether they differ.

The channels' names and types are checked. The enabled state is not considered a condition for difference. The test is motivated by the desire to detect changes in the configuration of acquisition setups between re-reads of an input file.

Parameters
[in]ch1First channel.
[in]ch2Second channel.
Returns
#TRUE upon differences or unexpected input, #FALSE otherwise.

Definition at line 208 of file device.c.

References sr_channel::name, and sr_channel::type.

Referenced by sr_channel_lists_differ().

+ Here is the caller graph for this function:

int sr_dev_channel_enable ( struct sr_channel channel,
gboolean  state 
)

Enable or disable a channel.

Parameters
[in]channelThe channel to enable or disable. Must not be NULL.
[in]stateTRUE to enable the channel, FALSE to disable.
Returns
SR_OK on success or SR_ERR on failure. In case of invalid arguments, SR_ERR_ARG is returned and the channel enabled state remains unchanged.
Since
0.3.0

Definition at line 140 of file device.c.

References sr_channel::enabled, sr_channel::sdi, SR_ERR_ARG, and SR_OK.

Referenced by sr_session_load().

+ Here is the caller graph for this function:

int sr_dev_channel_name_set ( struct sr_channel channel,
const char *  name 
)

Set the name of the specified channel.

If the channel already has a different name assigned to it, it will be removed, and the new name will be saved instead.

Parameters
[in]channelThe channel whose name to set. Must not be NULL.
[in]nameThe new name that the specified channel should get. A copy of the string is made.
Returns
SR_OK on success, or SR_ERR_ARG on invalid arguments.
Since
0.3.0

Definition at line 116 of file device.c.

References sr_channel::name, SR_ERR_ARG, and SR_OK.

Referenced by sr_session_load().

+ Here is the caller graph for this function:

int sr_dev_clear ( const struct sr_dev_driver driver)

Clear the list of device instances a driver knows about.

Parameters
driverThe driver to use. This must be a pointer to one of the entries returned by sr_driver_list(). Must not be NULL.
Return values
SR_OKSuccess.
SR_ERR_ARGInvalid driver.
Since
0.2.0

Definition at line 625 of file device.c.

References sr_dev_driver::context, sr_dev_driver::dev_clear, SR_ERR_ARG, and SR_OK.

int sr_dev_close ( struct sr_dev_inst *  sdi)

Close the specified device instance.

If the device instance is not open (sdi->status != SR_ST_ACTIVE), SR_ERR_DEV_CLOSED will be returned and no closing will be attempted.

Note: sdi->status will be set to SR_ST_INACTIVE, regardless of whether there are any errors during closing of the device instance (any errors will be reported via error code and log message, though).

Parameters
sdiDevice instance to use. Must not be NULL.
Return values
SR_OKSuccess.
SR_ERR_ARGInvalid arguments.
SR_ERR_DEV_CLOSEDDevice instance was not active.
SR_ERROther error.
Since
0.2.0

Definition at line 706 of file device.c.

References SR_ERR_ARG, SR_ERR_DEV_CLOSED, SR_ST_ACTIVE, and SR_ST_INACTIVE.

int sr_dev_config_capabilities_list ( const struct sr_dev_inst *  sdi,
const struct sr_channel_group cg,
const int  key 
)

Enumerate the configuration capabilities supported by a device instance for a given configuration key.

Parameters
sdiPointer to the device instance to be checked. Must not be NULL. If the device's 'driver' field is NULL (virtual device), this function will always return FALSE (virtual devices don't have a hardware capabilities list).
cgPointer to a channel group, if a specific channel group is to be checked. Must be NULL to check device-wide options.
[in]keyThe option that should be checked for is supported by the specified device.
Return values
Abitmask of enum sr_configcap values, which will be zero for invalid inputs or if the key is unsupported.
Since
0.4.0

Definition at line 365 of file device.c.

References SR_OK.

gboolean sr_dev_has_option ( const struct sr_dev_inst *  sdi,
int  key 
)

Determine whether the specified device instance has the specified capability.

Parameters
sdiPointer to the device instance to be checked. Must not be NULL. If the device's 'driver' field is NULL (virtual device), this function will always return FALSE (virtual devices don't have a hardware capabilities list).
[in]keyThe option that should be checked for is supported by the specified device.
Return values
TRUEDevice has the specified option.
FALSEDevice does not have the specified option, invalid input parameters or other error conditions.
Since
0.2.0

Definition at line 273 of file device.c.

References SR_OK.

int sr_dev_inst_channel_add ( struct sr_dev_inst *  sdi,
int  index,
int  type,
const char *  name 
)

Add a new channel to the specified device instance.

Parameters
[in]indexThe index of this channel, starting at 0. Logic channels will be encoded according to this index in SR_DF_LOGIC packets.
[in]typeChannel type (SR_CHANNEL_LOGIC, ...)
[in]nameName of channel.
Returns
SR_OK Success.
SR_OK Invalid argument.

Definition at line 428 of file device.c.

References SR_ERR_ARG, SR_INST_USER, and SR_OK.

GSList* sr_dev_inst_channel_groups_get ( const struct sr_dev_inst *  sdi)

Queries a device instances' channel groups list.

Parameters
sdiDevice instance to use. Must not be NULL.
Returns
The GSList of channel groups or NULL.

Definition at line 901 of file device.c.

GSList* sr_dev_inst_channels_get ( const struct sr_dev_inst *  sdi)

Queries a device instances' channel list.

Parameters
sdiDevice instance to use. Must not be NULL.
Returns
The GSList of channels or NULL.

Definition at line 886 of file device.c.

const char* sr_dev_inst_connid_get ( const struct sr_dev_inst *  sdi)

Queries a device instances' connection identifier.

Parameters
sdiDevice instance to use. Must not be NULL.
Returns
A copy of the connection ID string or NULL. The caller is responsible for g_free()ing the string when it is no longer needed.

Definition at line 807 of file device.c.

References SR_INST_SCPI, SR_INST_SERIAL, and SR_INST_USB.

struct sr_dev_driver* sr_dev_inst_driver_get ( const struct sr_dev_inst *  sdi)

Queries a device instances' driver.

Parameters
sdiDevice instance to use. Must not be NULL.
Returns
The driver instance or NULL on error.

Definition at line 731 of file device.c.

const char* sr_dev_inst_model_get ( const struct sr_dev_inst *  sdi)

Queries a device instances' model.

Parameters
sdiDevice instance to use. Must not be NULL.
Returns
The model string or NULL.

Definition at line 761 of file device.c.

const char* sr_dev_inst_sernum_get ( const struct sr_dev_inst *  sdi)

Queries a device instances' serial number.

Parameters
sdiDevice instance to use. Must not be NULL.
Returns
The serial number string or NULL.

Definition at line 791 of file device.c.

struct sr_dev_inst* sr_dev_inst_user_new ( const char *  vendor,
const char *  model,
const char *  version 
)

Allocate and init a new user-generated device instance.

Parameters
vendorDevice vendor.
modelDevice model.
versionDevice version.
Return values
structsr_dev_inst *. Dynamically allocated, free using sr_dev_inst_free().

Definition at line 403 of file device.c.

References SR_INST_USER.

const char* sr_dev_inst_vendor_get ( const struct sr_dev_inst *  sdi)

Queries a device instances' vendor.

Parameters
sdiDevice instance to use. Must not be NULL.
Returns
The vendor string or NULL.

Definition at line 746 of file device.c.

const char* sr_dev_inst_version_get ( const struct sr_dev_inst *  sdi)

Queries a device instances' version.

Parameters
sdiDevice instance to use. Must not be NULL.
Returns
The version string or NULL.

Definition at line 776 of file device.c.

GSList* sr_dev_list ( const struct sr_dev_driver driver)

Get the list of devices/instances of the specified driver.

Parameters
driverThe driver to use. Must not be NULL.
Returns
The list of devices/instances of this driver, or NULL upon errors or if the list is empty.
Since
0.2.0

Definition at line 606 of file device.c.

References sr_dev_driver::dev_list.

int sr_dev_open ( struct sr_dev_inst *  sdi)

Open the specified device instance.

If the device instance is already open (sdi->status == SR_ST_ACTIVE), SR_ERR will be returned and no re-opening of the device will be attempted.

If opening was successful, sdi->status is set to SR_ST_ACTIVE, otherwise it will be left unchanged.

Parameters
sdiDevice instance to use. Must not be NULL.
Return values
SR_OKSuccess.
SR_ERR_ARGInvalid arguments.
SR_ERRDevice instance was already active, or other error.
Since
0.2.0

Definition at line 664 of file device.c.

References SR_ERR, SR_ERR_ARG, SR_OK, and SR_ST_ACTIVE.

GArray* sr_dev_options ( const struct sr_dev_driver driver,
const struct sr_dev_inst *  sdi,
const struct sr_channel_group cg 
)

Enumerate the configuration options of the specified item.

Parameters
driverPointer to the driver to be checked. Must not be NULL.
sdiPointer to the device instance to be checked. May be NULL to check driver options.
cgPointer to a channel group, if a specific channel group is to be checked. Must be NULL to check device-wide options.
Returns
A GArray * of enum sr_configkey values, or NULL on invalid arguments. The array must be freed by the caller using g_array_free().
Since
0.4.0

Definition at line 315 of file device.c.

References sr_dev_driver::config_list, and SR_OK.