libsigrok
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Functions
device.c File Reference
#include <stdio.h>
#include <glib.h>
#include "sigrok.h"
#include "sigrok-internal.h"
Include dependency graph for device.c:

Go to the source code of this file.

Functions

SR_API int sr_dev_scan (void)
 Scan the system for attached logic analyzers / devices. More...
 
SR_API GSList * sr_dev_list (void)
 Return the list of logic analyzer devices libsigrok has detected. More...
 
SR_API struct sr_devsr_dev_new (const struct sr_dev_driver *driver, int driver_index)
 Create a new device. More...
 
SR_API int sr_dev_probe_add (struct sr_dev *dev, const char *name)
 Add a probe with the specified name to the specified device. More...
 
SR_API struct sr_probesr_dev_probe_find (const struct sr_dev *dev, int probenum)
 Find the probe with the specified number in the specified device. More...
 
SR_API int sr_dev_probe_name_set (struct sr_dev *dev, int probenum, const char *name)
 Set the name of the specified probe in the specified device. More...
 
SR_API int sr_dev_trigger_remove_all (struct sr_dev *dev)
 Remove all triggers set up for the specified device. More...
 
SR_API int sr_dev_trigger_set (struct sr_dev *dev, int probenum, const char *trigger)
 Add a trigger to the specified device (and the specified probe). More...
 
SR_API gboolean sr_dev_has_hwcap (const struct sr_dev *dev, int hwcap)
 Determine whether the specified device has the specified capability. More...
 
SR_API int sr_dev_info_get (const struct sr_dev *dev, int id, const void **data)
 Returns information about the given device. More...
 

Function Documentation

SR_API gboolean sr_dev_has_hwcap ( const struct sr_dev dev,
int  hwcap 
)

Determine whether the specified device has the specified capability.

Parameters
devPointer to the device 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).
hwcapThe capability that should be checked (whether it's supported by the specified device).
Returns
TRUE, if the device has the specified capability, FALSE otherwise. FALSE is also returned upon invalid input parameters or other error conditions.

Definition at line 376 of file device.c.

References sr_dev::driver, sr_dev_driver::hwcap_get_all, sr_dbg(), sr_err(), and sr_spew().

Referenced by init(), and sr_session_save().

Here is the call graph for this function:

SR_API int sr_dev_info_get ( const struct sr_dev dev,
int  id,
const void **  data 
)

Returns information about the given device.

Parameters
devPointer to the device to be checked. Must not be NULL. The device's 'driver' field must not be NULL either.
idThe type of information.
dataThe return value. Must not be NULL.
Returns
SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR upon other errors.

Definition at line 427 of file device.c.

References sr_dev_driver::dev_info_get, sr_dev::driver, sr_dev::driver_index, SR_ERR, SR_ERR_ARG, and SR_OK.

SR_API GSList* sr_dev_list ( void  )

Return the list of logic analyzer devices libsigrok has detected.

If the libsigrok-internal device list is empty, a scan for attached devices – via a call to sr_dev_scan() – is performed first.

TODO: Error handling?

Returns
The list (GSList) of detected devices, or NULL if none were found.

Definition at line 92 of file device.c.

References sr_dev_scan().

Here is the call graph for this function:

SR_API struct sr_dev* sr_dev_new ( const struct sr_dev_driver driver,
int  driver_index 
)
read

Create a new device.

The device is added to the (libsigrok-internal) list of devices, but additionally a pointer to the newly created device is also returned.

The device has no probes attached to it yet after this call. You can use sr_dev_probe_add() to add one or more probes.

TODO: Should return int, so that we can return SR_OK, SR_ERR_* etc.

It is the caller's responsibility to g_free() the allocated memory when no longer needed. TODO: Using which API function?

Parameters
driverTODO. If 'driver' is NULL, the created device is a "virtual" one.
driver_indexTODO
Returns
Pointer to the newly allocated device, or NULL upon errors.

Definition at line 120 of file device.c.

References sr_dev::driver, sr_dev::driver_index, and sr_err().

Referenced by sr_driver_init(), and sr_session_load().

Here is the call graph for this function:

SR_API int sr_dev_probe_add ( struct sr_dev dev,
const char *  name 
)

Add a probe with the specified name to the specified device.

The added probe is automatically enabled (the 'enabled' field is TRUE).

The 'trigger' field of the added probe is set to NULL. A trigger can be added via sr_dev_trigger_set().

TODO: Are duplicate names allowed? TODO: Do we enforce a maximum probe number for a device? TODO: Error if the max. probe number for the specific LA is reached, e.g. if the caller tries to add more probes than the device actually has.

Parameters
devThe device to which to add a probe with the specified name. Must not be NULL.
nameThe name of the probe to add to this device. Must not be NULL. TODO: Maximum length, allowed characters, etc.
Returns
SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors, or SR_ERR_ARG upon invalid arguments. If something other than SR_OK is returned, 'dev' is unchanged.

Definition at line 161 of file device.c.

References sr_probe::enabled, sr_probe::index, sr_probe::name, sr_dev::probes, sr_err(), SR_ERR_ARG, SR_ERR_MALLOC, SR_OK, and sr_probe::trigger.

Referenced by sr_driver_init(), and sr_session_load().

Here is the call graph for this function:

SR_API struct sr_probe* sr_dev_probe_find ( const struct sr_dev dev,
int  probenum 
)
read

Find the probe with the specified number in the specified device.

TODO

Parameters
devTODO. Must not be NULL.
probenumThe number of the probe whose 'struct sr_probe' we want. Note that the probe numbers start at 1 (not 0!).

TODO: Should return int. TODO: probenum should be unsigned.

Returns
A pointer to the requested probe's 'struct sr_probe', or NULL if the probe could not be found.

Definition at line 209 of file device.c.

References sr_probe::index, sr_dev::probes, and sr_err().

Referenced by sr_dev_probe_name_set(), sr_dev_trigger_remove_all(), and sr_dev_trigger_set().

Here is the call graph for this function:

SR_API int sr_dev_probe_name_set ( struct sr_dev dev,
int  probenum,
const char *  name 
)

Set the name of the specified probe in the specified device.

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

Parameters
devTODO
probenumThe number of the probe whose name to set. Note that the probe numbers start at 1 (not 0!).
nameThe new name that the specified probe should get.
Returns
SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR upon other errors. If something other than SR_OK is returned, 'dev' is unchanged.

Definition at line 250 of file device.c.

References sr_probe::name, sr_dev_probe_find(), SR_ERR, sr_err(), SR_ERR_ARG, and SR_OK.

Referenced by sr_session_load().

Here is the call graph for this function:

SR_API int sr_dev_scan ( void  )

Scan the system for attached logic analyzers / devices.

This will try to autodetect all supported logic analyzer devices:

  • Those attached via USB (can be reliably detected via USB VID/PID).
  • Those using a (real or virtual) serial port (detected by sending device-specific commands to all OS-specific serial port devices such as /dev/ttyS*, /dev/ttyUSB*, /dev/ttyACM*, and others). The autodetection for this kind of devices can potentially be unreliable.

    Also, sending various bytes/commands to (all!) devices which happen to be attached to the system via a (real or virtual) serial port can be problematic. There is no way for libsigrok to know how unknown devices react to the bytes libsigrok sends. Potentially they could lead to the device getting into invalid/error states, losing/overwriting data, or...

In addition to the detection, the devices that are found are also initialized automatically. On some devices, this involves a firmware upload, or other such measures.

The order in which the system is scanned for devices is not specified. The caller should not assume or rely on any specific order.

After the system has been scanned for devices, the list of detected (and supported) devices can be acquired via sr_dev_list().

TODO: Error checks? TODO: Option to only scan for specific devices or device classes.

Returns
SR_OK upon success, SR_ERR_BUG upon internal errors.

Definition at line 60 of file device.c.

References sr_driver_init(), sr_driver_list(), sr_err(), SR_ERR_BUG, and SR_OK.

Referenced by sr_dev_list().

Here is the call graph for this function:

SR_API int sr_dev_trigger_remove_all ( struct sr_dev dev)

Remove all triggers set up for the specified device.

TODO: Better description.

Parameters
devTODO
Returns
SR_OK upon success, SR_ERR_ARG upon invalid arguments. If something other than SR_OK is returned, 'dev' is unchanged.

Definition at line 286 of file device.c.

References sr_dev::probes, sr_dev_probe_find(), sr_err(), SR_ERR_ARG, SR_OK, and sr_probe::trigger.

Here is the call graph for this function:

SR_API int sr_dev_trigger_set ( struct sr_dev dev,
int  probenum,
const char *  trigger 
)

Add a trigger to the specified device (and the specified probe).

If the specified probe of this device already has a trigger, it will be silently replaced.

TODO: Better description. TODO: Describe valid format of the 'trigger' string.

Parameters
devTODO. Must not be NULL.
probenumThe number of the probe. TODO. Note that the probe numbers start at 1 (not 0!).
triggerTODO. TODO: Is NULL allowed?
Returns
SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR upon other errors. If something other than SR_OK is returned, 'dev' is unchanged.

Definition at line 332 of file device.c.

References sr_dbg(), sr_dev_probe_find(), SR_ERR, sr_err(), SR_ERR_ARG, SR_OK, and sr_probe::trigger.

Referenced by sr_session_load().

Here is the call graph for this function: