libsigrok  0.2.2
sigrok hardware access and backend library
 All Data Structures Files Functions Variables Typedefs Enumerator Macros Groups Pages
Data Structures | Macros | Typedefs | Enumerations
libsigrok.h File Reference

The public libsigrok header file to be used by frontends. More...

#include <stdio.h>
#include <sys/time.h>
#include <stdint.h>
#include <inttypes.h>
#include <glib.h>
#include "proto.h"
#include "version.h"
+ Include dependency graph for libsigrok.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  sr_datafeed_packet
 
struct  sr_datafeed_header
 
struct  sr_datafeed_meta
 
struct  sr_datafeed_logic
 
struct  sr_datafeed_analog
 
struct  sr_input
 Input (file) format struct. More...
 
struct  sr_input_format
 
struct  sr_output
 Output (file) format struct. More...
 
struct  sr_output_format
 
struct  sr_probe
 
struct  sr_config
 
struct  sr_config_info
 
struct  sr_dev_inst
 
struct  sr_dev_driver
 
struct  sr_session
 

Macros

#define SR_MAX_PROBENAME_LEN   32
 
#define SR_HZ(n)   (n)
 
#define SR_KHZ(n)   ((n) * (uint64_t)(1000ULL))
 
#define SR_MHZ(n)   ((n) * (uint64_t)(1000000ULL))
 
#define SR_GHZ(n)   ((n) * (uint64_t)(1000000000ULL))
 
#define SR_HZ_TO_NS(n)   ((uint64_t)(1000000000ULL) / (n))
 
#define SR_API   __attribute__((visibility("default")))
 
#define SR_PRIV   __attribute__((visibility("hidden")))
 

Typedefs

typedef int(* sr_receive_data_callback_t )(int fd, int revents, void *cb_data)
 

Enumerations

enum  {
  SR_OK = 0,
  SR_ERR = -1,
  SR_ERR_MALLOC = -2,
  SR_ERR_ARG = -3,
  SR_ERR_BUG = -4,
  SR_ERR_SAMPLERATE = -5,
  SR_ERR_NA = -6,
  SR_ERR_DEV_CLOSED = -7,
  SR_ERR_TIMEOUT = -8
}
 Status/error codes returned by libsigrok functions. More...
 
enum  {
  SR_LOG_NONE = 0,
  SR_LOG_ERR = 1,
  SR_LOG_WARN = 2,
  SR_LOG_INFO = 3,
  SR_LOG_DBG = 4,
  SR_LOG_SPEW = 5
}
 libsigrok loglevels. More...
 
enum  {
  SR_T_UINT64 = 10000,
  SR_T_CHAR,
  SR_T_BOOL,
  SR_T_FLOAT,
  SR_T_RATIONAL_PERIOD,
  SR_T_RATIONAL_VOLT,
  SR_T_KEYVALUE,
  SR_T_UINT64_RANGE,
  SR_T_DOUBLE_RANGE
}
 Data types used by sr_config_info(). More...
 
enum  {
  SR_DF_HEADER = 10000,
  SR_DF_END,
  SR_DF_META,
  SR_DF_TRIGGER,
  SR_DF_LOGIC,
  SR_DF_ANALOG,
  SR_DF_FRAME_BEGIN,
  SR_DF_FRAME_END
}
 Value for sr_datafeed_packet.type. More...
 
enum  {
  SR_MQ_VOLTAGE = 10000,
  SR_MQ_CURRENT,
  SR_MQ_RESISTANCE,
  SR_MQ_CAPACITANCE,
  SR_MQ_TEMPERATURE,
  SR_MQ_FREQUENCY,
  SR_MQ_DUTY_CYCLE,
  SR_MQ_CONTINUITY,
  SR_MQ_PULSE_WIDTH,
  SR_MQ_CONDUCTANCE,
  SR_MQ_POWER,
  SR_MQ_GAIN,
  SR_MQ_SOUND_PRESSURE_LEVEL,
  SR_MQ_CARBON_MONOXIDE,
  SR_MQ_RELATIVE_HUMIDITY
}
 Values for sr_datafeed_analog.mq. More...
 
enum  {
  SR_UNIT_VOLT = 10000,
  SR_UNIT_AMPERE,
  SR_UNIT_OHM,
  SR_UNIT_FARAD,
  SR_UNIT_KELVIN,
  SR_UNIT_CELSIUS,
  SR_UNIT_FAHRENHEIT,
  SR_UNIT_HERTZ,
  SR_UNIT_PERCENTAGE,
  SR_UNIT_BOOLEAN,
  SR_UNIT_SECOND,
  SR_UNIT_SIEMENS,
  SR_UNIT_DECIBEL_MW,
  SR_UNIT_DECIBEL_VOLT,
  SR_UNIT_UNITLESS,
  SR_UNIT_DECIBEL_SPL,
  SR_UNIT_CONCENTRATION,
  SR_UNIT_REVOLUTIONS_PER_MINUTE,
  SR_UNIT_VOLT_AMPERE,
  SR_UNIT_WATT,
  SR_UNIT_WATT_HOUR
}
 Values for sr_datafeed_analog.unit. More...
 
enum  {
  SR_MQFLAG_AC = 0x01,
  SR_MQFLAG_DC = 0x02,
  SR_MQFLAG_RMS = 0x04,
  SR_MQFLAG_DIODE = 0x08,
  SR_MQFLAG_HOLD = 0x10,
  SR_MQFLAG_MAX = 0x20,
  SR_MQFLAG_MIN = 0x40,
  SR_MQFLAG_AUTORANGE = 0x80,
  SR_MQFLAG_RELATIVE = 0x100,
  SR_MQFLAG_SPL_FREQ_WEIGHT_A = 0x200,
  SR_MQFLAG_SPL_FREQ_WEIGHT_C = 0x400,
  SR_MQFLAG_SPL_FREQ_WEIGHT_Z = 0x800,
  SR_MQFLAG_SPL_FREQ_WEIGHT_FLAT = 0x1000,
  SR_MQFLAG_SPL_TIME_WEIGHT_S = 0x2000,
  SR_MQFLAG_SPL_TIME_WEIGHT_F = 0x4000,
  SR_MQFLAG_SPL_LAT = 0x8000,
  SR_MQFLAG_SPL_PCT_OVER_ALARM = 0x10000
}
 Values for sr_datafeed_analog.flags. More...
 
enum  {
  SR_PROBE_LOGIC = 10000,
  SR_PROBE_ANALOG
}
 
enum  {
  SR_CONF_LOGIC_ANALYZER = 10000,
  SR_CONF_OSCILLOSCOPE,
  SR_CONF_MULTIMETER,
  SR_CONF_DEMO_DEV,
  SR_CONF_SOUNDLEVELMETER,
  SR_CONF_THERMOMETER,
  SR_CONF_HYGROMETER,
  SR_CONF_ENERGYMETER,
  SR_CONF_CONN = 20000,
  SR_CONF_SERIALCOMM,
  SR_CONF_SAMPLERATE = 30000,
  SR_CONF_CAPTURE_RATIO,
  SR_CONF_PATTERN_MODE,
  SR_CONF_RLE,
  SR_CONF_TRIGGER_SLOPE,
  SR_CONF_TRIGGER_SOURCE,
  SR_CONF_HORIZ_TRIGGERPOS,
  SR_CONF_BUFFERSIZE,
  SR_CONF_TIMEBASE,
  SR_CONF_FILTER,
  SR_CONF_VDIV,
  SR_CONF_COUPLING,
  SR_CONF_TRIGGER_TYPE,
  SR_CONF_SAMPLE_INTERVAL,
  SR_CONF_NUM_TIMEBASE,
  SR_CONF_NUM_VDIV,
  SR_CONF_SPL_WEIGHT_FREQ,
  SR_CONF_SPL_WEIGHT_TIME,
  SR_CONF_SPL_MEASUREMENT_RANGE,
  SR_CONF_HOLD_MAX,
  SR_CONF_HOLD_MIN,
  SR_CONF_VOLTAGE_THRESHOLD,
  SR_CONF_EXTERNAL_CLOCK,
  SR_CONF_SWAP,
  SR_CONF_SCAN_OPTIONS = 40000,
  SR_CONF_DEVICE_OPTIONS,
  SR_CONF_SESSIONFILE,
  SR_CONF_CAPTUREFILE,
  SR_CONF_CAPTURE_UNITSIZE,
  SR_CONF_CAPTURE_NUM_PROBES,
  SR_CONF_POWER_OFF,
  SR_CONF_DATA_SOURCE,
  SR_CONF_LIMIT_MSEC = 50000,
  SR_CONF_LIMIT_SAMPLES,
  SR_CONF_LIMIT_FRAMES,
  SR_CONF_CONTINUOUS,
  SR_CONF_DATALOG
}
 
enum  {
  SR_INST_USB = 10000,
  SR_INST_SERIAL
}
 Types of device instances (sr_dev_inst). More...
 
enum  {
  SR_ST_NOT_FOUND = 10000,
  SR_ST_INITIALIZING,
  SR_ST_INACTIVE,
  SR_ST_ACTIVE,
  SR_ST_STOPPING
}
 Device instance status. More...
 

Detailed Description

The public libsigrok header file to be used by frontends.

This is the only file that libsigrok users (frontends) are supposed to use and #include. There are other header files which get installed with libsigrok, but those are not meant to be used directly by frontends.

The correct way to get/use the libsigrok API functions is:

* #include <libsigrok/libsigrok.h>
*

Definition in file libsigrok.h.

Macro Definition Documentation

#define SR_API   __attribute__((visibility("default")))

Definition at line 121 of file libsigrok.h.

#define SR_GHZ (   n)    ((n) * (uint64_t)(1000000000ULL))

Definition at line 89 of file libsigrok.h.

Referenced by sr_parse_sizestring(), sr_period_string(), and sr_si_string_u64().

#define SR_HZ (   n)    (n)

Definition at line 86 of file libsigrok.h.

Referenced by sr_si_string_u64().

#define SR_HZ_TO_NS (   n)    ((uint64_t)(1000000000ULL) / (n))

Definition at line 91 of file libsigrok.h.

#define SR_KHZ (   n)    ((n) * (uint64_t)(1000ULL))

Definition at line 87 of file libsigrok.h.

Referenced by sr_parse_sizestring(), sr_period_string(), and sr_si_string_u64().

#define SR_MAX_PROBENAME_LEN   32

Definition at line 83 of file libsigrok.h.

Referenced by sr_session_load().

#define SR_MHZ (   n)    ((n) * (uint64_t)(1000000ULL))

Definition at line 88 of file libsigrok.h.

Referenced by sr_parse_sizestring(), sr_period_string(), and sr_si_string_u64().

#define SR_PRIV   __attribute__((visibility("hidden")))

Definition at line 128 of file libsigrok.h.

Typedef Documentation

typedef int(* sr_receive_data_callback_t)(int fd, int revents, void *cb_data)

Definition at line 133 of file libsigrok.h.

Enumeration Type Documentation

anonymous enum

Status/error codes returned by libsigrok functions.

Enumerator
SR_OK 

No error.

SR_ERR 

Generic/unspecified error.

SR_ERR_MALLOC 

Malloc/calloc/realloc error.

SR_ERR_ARG 

Function argument error.

SR_ERR_BUG 

Errors hinting at internal bugs.

SR_ERR_SAMPLERATE 

Incorrect samplerate.

SR_ERR_NA 

Not applicable.

SR_ERR_DEV_CLOSED 

Device is closed, but needs to be open.

SR_ERR_TIMEOUT 

A timeout occurred.

Definition at line 66 of file libsigrok.h.

anonymous enum

libsigrok loglevels.

Enumerator
SR_LOG_NONE 

Output no messages at all.

SR_LOG_ERR 

Output error messages.

SR_LOG_WARN 

Output warnings.

SR_LOG_INFO 

Output informational messages.

SR_LOG_DBG 

Output debug messages.

SR_LOG_SPEW 

Output very noisy debug messages.

Definition at line 94 of file libsigrok.h.

anonymous enum

Device instance status.

Enumerator
SR_ST_NOT_FOUND 

The device instance was not found.

SR_ST_INITIALIZING 

The device instance was found, but is still booting.

SR_ST_INACTIVE 

The device instance is live, but not in use.

SR_ST_ACTIVE 

The device instance is actively in use in a session.

SR_ST_STOPPING 

The device is winding down its session.

Definition at line 793 of file libsigrok.h.

anonymous enum

Data types used by sr_config_info().

Enumerator
SR_T_UINT64 
SR_T_CHAR 
SR_T_BOOL 
SR_T_FLOAT 
SR_T_RATIONAL_PERIOD 
SR_T_RATIONAL_VOLT 
SR_T_KEYVALUE 
SR_T_UINT64_RANGE 
SR_T_DOUBLE_RANGE 

Definition at line 136 of file libsigrok.h.

anonymous enum

Value for sr_datafeed_packet.type.

Enumerator
SR_DF_HEADER 
SR_DF_END 
SR_DF_META 
SR_DF_TRIGGER 
SR_DF_LOGIC 
SR_DF_ANALOG 
SR_DF_FRAME_BEGIN 
SR_DF_FRAME_END 

Definition at line 149 of file libsigrok.h.

anonymous enum

Values for sr_datafeed_analog.mq.

Enumerator
SR_MQ_VOLTAGE 
SR_MQ_CURRENT 
SR_MQ_RESISTANCE 
SR_MQ_CAPACITANCE 
SR_MQ_TEMPERATURE 
SR_MQ_FREQUENCY 
SR_MQ_DUTY_CYCLE 
SR_MQ_CONTINUITY 
SR_MQ_PULSE_WIDTH 
SR_MQ_CONDUCTANCE 
SR_MQ_POWER 

Electrical power, usually in W, or dBm.

SR_MQ_GAIN 

Gain (a transistor's gain, or hFE, for example).

SR_MQ_SOUND_PRESSURE_LEVEL 

Logarithmic representation of sound pressure relative to a reference value.

SR_MQ_CARBON_MONOXIDE 
SR_MQ_RELATIVE_HUMIDITY 

Definition at line 161 of file libsigrok.h.

anonymous enum

Values for sr_datafeed_analog.unit.

Enumerator
SR_UNIT_VOLT 
SR_UNIT_AMPERE 
SR_UNIT_OHM 
SR_UNIT_FARAD 
SR_UNIT_KELVIN 
SR_UNIT_CELSIUS 
SR_UNIT_FAHRENHEIT 
SR_UNIT_HERTZ 
SR_UNIT_PERCENTAGE 
SR_UNIT_BOOLEAN 
SR_UNIT_SECOND 
SR_UNIT_SIEMENS 

Unit of conductance, the inverse of resistance.

SR_UNIT_DECIBEL_MW 

An absolute measurement of power, in decibels, referenced to 1 milliwatt (dBu).

SR_UNIT_DECIBEL_VOLT 

Voltage in decibel, referenced to 1 volt (dBV).

SR_UNIT_UNITLESS 

Measurements that intrinsically do not have units attached, such as ratios, gains, etc.

Specifically, a transistor's gain (hFE) is a unitless quantity, for example.

SR_UNIT_DECIBEL_SPL 

Sound pressure level relative so 20 micropascals.

SR_UNIT_CONCENTRATION 

Normalized (0 to 1) concentration of a substance or compound with 0 representing a concentration of 0%, and 1 being 100%.

This is represented as the fraction of number of particles of the substance.

SR_UNIT_REVOLUTIONS_PER_MINUTE 
SR_UNIT_VOLT_AMPERE 
SR_UNIT_WATT 
SR_UNIT_WATT_HOUR 

Definition at line 184 of file libsigrok.h.

anonymous enum

Values for sr_datafeed_analog.flags.

Enumerator
SR_MQFLAG_AC 

Voltage measurement is alternating current (AC).

SR_MQFLAG_DC 

Voltage measurement is direct current (DC).

SR_MQFLAG_RMS 

This is a true RMS measurement.

SR_MQFLAG_DIODE 

Value is voltage drop across a diode, or NAN.

SR_MQFLAG_HOLD 

Device is in "hold" mode (repeating the last measurement).

SR_MQFLAG_MAX 

Device is in "max" mode, only updating upon a new max value.

SR_MQFLAG_MIN 

Device is in "min" mode, only updating upon a new min value.

SR_MQFLAG_AUTORANGE 

Device is in autoranging mode.

SR_MQFLAG_RELATIVE 

Device is in relative mode.

SR_MQFLAG_SPL_FREQ_WEIGHT_A 

Sound pressure level is A-weighted in the frequency domain, according to IEC 61672:2003.

SR_MQFLAG_SPL_FREQ_WEIGHT_C 

Sound pressure level is C-weighted in the frequency domain, according to IEC 61672:2003.

SR_MQFLAG_SPL_FREQ_WEIGHT_Z 

Sound pressure level is Z-weighted (i.e.

not at all) in the frequency domain, according to IEC 61672:2003.

SR_MQFLAG_SPL_FREQ_WEIGHT_FLAT 

Sound pressure level is not weighted in the frequency domain, albeit without standards-defined low and high frequency limits.

SR_MQFLAG_SPL_TIME_WEIGHT_S 

Sound pressure level measurement is S-weighted (1s) in the time domain.

SR_MQFLAG_SPL_TIME_WEIGHT_F 

Sound pressure level measurement is F-weighted (125ms) in the time domain.

SR_MQFLAG_SPL_LAT 

Sound pressure level is time-averaged (LAT), also known as Equivalent Continuous A-weighted Sound Level (LEQ).

SR_MQFLAG_SPL_PCT_OVER_ALARM 

Sound pressure level represented as a percentage of measurements that were over a preset alarm level.

Definition at line 226 of file libsigrok.h.

anonymous enum
Enumerator
SR_PROBE_LOGIC 
SR_PROBE_ANALOG 

Definition at line 538 of file libsigrok.h.

anonymous enum
Enumerator
SR_CONF_LOGIC_ANALYZER 

The device can act as logic analyzer.

SR_CONF_OSCILLOSCOPE 

The device can act as an oscilloscope.

SR_CONF_MULTIMETER 

The device can act as a multimeter.

SR_CONF_DEMO_DEV 

The device is a demo device.

SR_CONF_SOUNDLEVELMETER 

The device can act as a sound level meter.

SR_CONF_THERMOMETER 

The device can measure temperature.

SR_CONF_HYGROMETER 

The device can measure humidity.

SR_CONF_ENERGYMETER 

The device can measure energy consumption.

SR_CONF_CONN 

Specification on how to connect to a device.

In combination with SR_CONF_SERIALCOMM, this is a serial port in the form which makes sense to the OS (e.g., /dev/ttyS0). Otherwise this specifies a USB device, either in the form of

<bus>.<address> 

(decimal, e.g. 1.65) or

<vendorid>.<productid> 

(hexadecimal, e.g. 1d6b.0001).

SR_CONF_SERIALCOMM 

Serial communication specification, in the form:

<baudrate>/<databits><parity><stopbits> 

Example: 9600/8n1

The string may also be followed by one or more special settings, in the form "/key=value". Supported keys and their values are:

rts 0,1 set the port's RTS pin to low or high dtr 0,1 set the port's DTR pin to low or high flow 0 no flow control 1 hardware-based (RTS/CTS) flow control 2 software-based (XON/XOFF) flow control

This is always an optional parameter, since a driver typically knows the speed at which the device wants to communicate.

SR_CONF_SAMPLERATE 

The device supports setting its samplerate, in Hz.

SR_CONF_CAPTURE_RATIO 

The device supports setting a pre/post-trigger capture ratio.

SR_CONF_PATTERN_MODE 

The device supports setting a pattern (pattern generator mode).

SR_CONF_RLE 

The device supports Run Length Encoding.

SR_CONF_TRIGGER_SLOPE 

The device supports setting trigger slope.

SR_CONF_TRIGGER_SOURCE 

Trigger source.

SR_CONF_HORIZ_TRIGGERPOS 

Horizontal trigger position.

SR_CONF_BUFFERSIZE 

Buffer size.

SR_CONF_TIMEBASE 

Time base.

SR_CONF_FILTER 

Filter.

SR_CONF_VDIV 

Volts/div.

SR_CONF_COUPLING 

Coupling.

SR_CONF_TRIGGER_TYPE 

Trigger types.

SR_CONF_SAMPLE_INTERVAL 

The device supports setting its sample interval, in ms.

SR_CONF_NUM_TIMEBASE 

Number of timebases, as related to SR_CONF_TIMEBASE.

SR_CONF_NUM_VDIV 

Number of vertical divisions, as related to SR_CONF_VDIV.

SR_CONF_SPL_WEIGHT_FREQ 

Sound pressure level frequency weighting.

SR_CONF_SPL_WEIGHT_TIME 

Sound pressure level time weighting.

SR_CONF_SPL_MEASUREMENT_RANGE 

Sound pressure level measurement range.

SR_CONF_HOLD_MAX 

Max hold mode.

SR_CONF_HOLD_MIN 

Min hold mode.

SR_CONF_VOLTAGE_THRESHOLD 

Logic low-high threshold range.

SR_CONF_EXTERNAL_CLOCK 

The device supports using a external clock.

SR_CONF_SWAP 

The device supports swapping channels.

Typical this is between buffered and unbuffered channels.

SR_CONF_SCAN_OPTIONS 

Scan options supported by the driver.

SR_CONF_DEVICE_OPTIONS 

Device options for a particular device.

SR_CONF_SESSIONFILE 

Session filename.

SR_CONF_CAPTUREFILE 

The device supports specifying a capturefile to inject.

SR_CONF_CAPTURE_UNITSIZE 

The device supports specifying the capturefile unit size.

SR_CONF_CAPTURE_NUM_PROBES 

The device supports setting the number of probes.

SR_CONF_POWER_OFF 

Power off the device.

SR_CONF_DATA_SOURCE 

Data source for acquisition.

If not present, acquisition from the device is always "live", i.e. acquisition starts when the frontend asks and the results are sent out as soon as possible.

If present, it indicates that either the device has no live acquisition capability (for example a pure data logger), or there is a choice. sr_config_list() returns those choices.

In any case if a device has live acquisition capabilities, it is always the default.

SR_CONF_LIMIT_MSEC 

The device supports setting a sample time limit (how long the sample acquisition should run, in ms).

SR_CONF_LIMIT_SAMPLES 

The device supports setting a sample number limit (how many samples should be acquired).

SR_CONF_LIMIT_FRAMES 

The device supports setting a frame limit (how many frames should be acquired).

SR_CONF_CONTINUOUS 

The device supports continuous sampling.

Neither a time limit nor a sample number limit has to be supplied, it will just acquire samples continuously, until explicitly stopped by a certain command.

SR_CONF_DATALOG 

The device has internal storage, into which data is logged.

This starts or stops the internal logging.

Definition at line 565 of file libsigrok.h.

anonymous enum

Types of device instances (sr_dev_inst).

Enumerator
SR_INST_USB 

Device instance type for USB devices.

SR_INST_SERIAL 

Device instance type for serial port devices.

Definition at line 785 of file libsigrok.h.