X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=include%2Flibsigrok%2Flibsigrok.h;h=56b4f16f1342c8e4e1629266d441bebe691ef855;hb=3ea46116dea1636222ec528c2708d99adff1b4bc;hp=3a2c900accc14b8132c01c9d6d66edd136477b67;hpb=63d0fb752830fa8ea225ed9a9776e44a0ba66928;p=libsigrok.git
diff --git a/include/libsigrok/libsigrok.h b/include/libsigrok/libsigrok.h
index 3a2c900a..56b4f16f 100644
--- a/include/libsigrok/libsigrok.h
+++ b/include/libsigrok/libsigrok.h
@@ -64,6 +64,7 @@ extern "C" {
/** Status/error codes returned by libsigrok functions. */
enum sr_error_code {
+ SR_OK_CONTINUE = 1, /**< Keep going. */
SR_OK = 0, /**< No error. */
SR_ERR = -1, /**< Generic/unspecified error. */
SR_ERR_MALLOC = -2, /**< Malloc/calloc/realloc error. */
@@ -74,6 +75,7 @@ enum sr_error_code {
SR_ERR_DEV_CLOSED = -7, /**< Device is closed, but must be open. */
SR_ERR_TIMEOUT = -8, /**< A timeout occurred. */
SR_ERR_CHANNEL_GROUP = -9, /**< A channel group must be specified. */
+ SR_ERR_DATA =-10, /**< Data is invalid. */
/*
* Note: When adding entries here, don't forget to also update the
@@ -199,6 +201,26 @@ enum sr_mq {
SR_MQ_WIND_SPEED,
/** Pressure */
SR_MQ_PRESSURE,
+ /** Parallel inductance (LCR meter model). */
+ SR_MQ_PARALLEL_INDUCTANCE,
+ /** Parallel capacitance (LCR meter model). */
+ SR_MQ_PARALLEL_CAPACITANCE,
+ /** Parallel resistance (LCR meter model). */
+ SR_MQ_PARALLEL_RESISTANCE,
+ /** Serial inductance (LCR meter model). */
+ SR_MQ_SERIAL_INDUCTANCE,
+ /** Serial capacitance (LCR meter model). */
+ SR_MQ_SERIAL_CAPACITANCE,
+ /** Serial resistance (LCR meter model). */
+ SR_MQ_SERIAL_RESISTANCE,
+ /** Dissipation factor. */
+ SR_MQ_DISSIPATION_FACTOR,
+ /** Quality factor. */
+ SR_MQ_QUALITY_FACTOR,
+ /** Phase angle. */
+ SR_MQ_PHASE_ANGLE,
+ /** Difference from reference value. */
+ SR_MQ_DIFFERENCE,
};
/** Unit of measured quantity, sr_datafeed_analog.unit. */
@@ -262,6 +284,10 @@ enum sr_unit {
SR_UNIT_HECTOPASCAL,
/** Relative humidity assuming air temperature of 293 kelvin (%rF). */
SR_UNIT_HUMIDITY_293K,
+ /** Plane angle in 1/360th of a full circle. */
+ SR_UNIT_DEGREE,
+ /** Henry (inductance). */
+ SR_UNIT_HENRY,
};
/** Values for sr_datafeed_analog.flags. */
@@ -312,6 +338,12 @@ enum sr_mqflag {
SR_MQFLAG_DURATION = 0x20000,
/** Device is in "avg" mode, averaging upon each new value. */
SR_MQFLAG_AVG = 0x40000,
+ /** Reference value shown. */
+ SR_MQFLAG_REFERENCE = 0x80000,
+ /** Device selects the measured quantity automatically. */
+ SR_MQFLAG_AUTOMQ = 0x100000,
+ /** Device selects the measurement model automatically. */
+ SR_MQFLAG_AUTOMODEL = 0x200000,
};
enum sr_trigger_matches {
@@ -429,174 +461,24 @@ struct sr_datafeed_analog {
float *data;
};
-/** Input (file) format struct. */
-struct sr_input {
- /**
- * A pointer to this input format's 'struct sr_input_format'.
- * The frontend can use this to call the module's callbacks.
- */
- struct sr_input_format *format;
-
- GHashTable *param;
-
- struct sr_dev_inst *sdi;
-
- void *internal;
-};
-
-/** Input (file) format driver. */
-struct sr_input_format {
- /** The unique ID for this input format. Must not be NULL. */
+/** Generic option struct used by various subsystems. */
+struct sr_option {
+ /* Short name suitable for commandline usage, [a-z0-9-]. */
char *id;
-
- /**
- * A short description of the input format, which can (for example)
- * be displayed to the user by frontends. Must not be NULL.
- */
- char *description;
-
- /**
- * Check if this input module can load and parse the specified file.
- *
- * @param[in] filename The name (and path) of the file to check.
- *
- * @retval TRUE This module knows the format.
- * @retval FALSE This module does not know the format.
- */
- int (*format_match) (const char *filename);
-
- /**
- * Initialize the input module.
- *
- * @param in A pointer to a valid 'struct sr_input' that the caller
- * has to allocate and provide to this function. It is also
- * the responsibility of the caller to free it later.
- * @param[in] filename The name (and path) of the file to use.
- *
- * @retval SR_OK Success
- * @retval other Negative error code.
- */
- int (*init) (struct sr_input *in, const char *filename);
-
- /**
- * Load a file, parsing the input according to the file's format.
- *
- * This function will send datafeed packets to the session bus, so
- * the calling frontend must have registered its session callbacks
- * beforehand.
- *
- * The packet types sent across the session bus by this function must
- * include at least SR_DF_HEADER, SR_DF_END, and an appropriate data
- * type such as SR_DF_LOGIC. It may also send a SR_DF_TRIGGER packet
- * if appropriate.
- *
- * @param in A pointer to a valid 'struct sr_input' that the caller
- * has to allocate and provide to this function. It is also
- * the responsibility of the caller to free it later.
- * @param filename The name (and path) of the file to use.
- *
- * @retval SR_OK Success
- * @retval other Negative error code.
- */
- int (*loadfile) (struct sr_input *in, const char *filename);
-};
-
-/** Output (file) format struct. */
-struct sr_output {
- /** A pointer to this output's format. */
- struct sr_output_format *format;
-
- /**
- * The device for which this output module is creating output. This
- * can be used by the module to find out channel names and numbers.
- */
- const struct sr_dev_inst *sdi;
-
- /**
- * An optional parameter which the frontend can pass in to the
- * output module. How the string is interpreted is entirely up to
- * the module.
- */
- GHashTable *params;
-
- /**
- * A generic pointer which can be used by the module to keep internal
- * state between calls into its callback functions.
- *
- * For example, the module might store a pointer to a chunk of output
- * there, and only flush it when it reaches a certain size.
- */
- void *internal;
+ /* Short name suitable for GUI usage, can contain UTF-8. */
+ char *name;
+ /* Description of the option, in a sentence. */
+ char *desc;
+ /* Default value for this option. */
+ GVariant *def;
+ /* List of possible values, if this is an option with few values. */
+ GSList *values;
};
-/** Output (file) format driver. */
-struct sr_output_format {
- /**
- * A unique ID for this output format. Must not be NULL.
- *
- * It can be used by frontends to select this output format for use.
- *
- * For example, calling sigrok-cli with -O hex will
- * select the hexadecimal text output format.
- */
- char *id;
-
- /**
- * A short description of the output format. Must not be NULL.
- *
- * This can be displayed by frontends, e.g. when selecting the output
- * format for saving a file.
- */
- char *description;
-
- /**
- * This function is called once, at the beginning of an output stream.
- *
- * The device struct will be available in the output struct passed in,
- * as well as the param field -- which may be NULL or an empty string,
- * if no parameter was passed.
- *
- * The module can use this to initialize itself, create a struct for
- * keeping state and storing it in the internal field.
- *
- * @param o Pointer to the respective 'struct sr_output'.
- *
- * @retval SR_OK Success
- * @retval other Negative error code.
- */
- int (*init) (struct sr_output *o);
-
- /**
- * This function is passed a copy of every packed in the data feed.
- * Any output generated by the output module in response to the
- * packet should be returned in a newly allocated GString
- * out, which will be freed by the caller.
- *
- * Packets not of interest to the output module can just be ignored,
- * and the out parameter set to NULL.
- *
- * @param o Pointer to the respective 'struct sr_output'.
- * @param sdi The device instance that generated the packet.
- * @param packet The complete packet.
- * @param out A pointer where a GString * should be stored if
- * the module generates output, or NULL if not.
- *
- * @retval SR_OK Success
- * @retval other Negative error code.
- */
- int (*receive) (struct sr_output *o,
- const struct sr_datafeed_packet *packet, GString **out);
-
- /**
- * This function is called after the caller is finished using
- * the output module, and can be used to free any internal
- * resources the module may keep.
- *
- * @retval SR_OK Success
- * @retval other Negative error code.
- */
- int (*cleanup) (struct sr_output *o);
-};
+struct sr_input;
+struct sr_input_module;
+struct sr_output;
+struct sr_output_module;
/** Constants for channel type. */
enum sr_channeltype {
@@ -617,6 +499,8 @@ struct sr_channel {
gboolean enabled;
/** Name of channel. */
char *name;
+ /** Private data for driver use. */
+ void *priv;
};
/** Structure for groups of channels that have common properties. */
@@ -632,7 +516,7 @@ struct sr_channel_group {
/** Used for setting or getting value of a config item. */
struct sr_config {
/** Config key like SR_CONF_CONN, etc. */
- int key;
+ uint32_t key;
/** Key-specific data. */
GVariant *data;
};
@@ -640,7 +524,7 @@ struct sr_config {
/** Information about a config key. */
struct sr_config_info {
/** Config key like SR_CONF_CONN, etc. */
- int key;
+ uint32_t key;
/** Data type like SR_T_STRING, etc. */
int datatype;
/** Id string, e.g. "serialcomm". */
@@ -651,6 +535,11 @@ struct sr_config_info {
char *description;
};
+#define SR_CONF_GET (1 << 31)
+#define SR_CONF_SET (1 << 30)
+#define SR_CONF_LIST (1 << 29)
+#define SR_CONF_MASK 0x1fffffff
+
/** Constants for device classes */
enum sr_configkey {
/*--- Device classes ------------------------------------------------*/
@@ -685,6 +574,9 @@ enum sr_configkey {
/** Programmable power supply. */
SR_CONF_POWER_SUPPLY,
+ /** LCR meter. */
+ SR_CONF_LCR_METER,
+
/*--- Driver scan options -------------------------------------------*/
/**
@@ -809,33 +701,120 @@ enum sr_configkey {
/** The device supports setting the number of analog channels. */
SR_CONF_NUM_ANALOG_CHANNELS,
- /** Output voltage. */
+ /**
+ * Output voltage.
+ * @arg type: double
+ * @arg get: get output voltage
+ */
SR_CONF_OUTPUT_VOLTAGE,
- /** Maximum output voltage. */
+ /**
+ * Maximum output voltage.
+ * @arg type: double
+ * @arg get: get maximum output voltage limit
+ * @arg set: change output voltage limit
+ */
SR_CONF_OUTPUT_VOLTAGE_MAX,
- /** Output current. */
+ /**
+ * Output current.
+ * @arg type: double
+ * @arg get: get output current
+ */
SR_CONF_OUTPUT_CURRENT,
- /** Maximum output current. */
+ /**
+ * Maximum output current.
+ * @arg type: double
+ * @arg get: get maximum output voltage limit
+ * @arg set: change output voltage limit
+ */
SR_CONF_OUTPUT_CURRENT_MAX,
- /** Enabling/disabling output. */
+ /**
+ * Enabling/disabling output.
+ * @arg type: boolean
+ * @arg get: @b true if currently enabled
+ * @arg set: enable/disable
+ */
SR_CONF_OUTPUT_ENABLED,
- /** Channel output configuration. */
- SR_CONF_OUTPUT_CHANNEL,
+ /**
+ * Output channel configuration.
+ * @arg type: string
+ * @arg get: get current setting
+ * @arg set: change current setting
+ * @arg list: array of possible values
+ */
+ SR_CONF_OUTPUT_CHANNEL_CONFIG,
+
+ /**
+ * Over-voltage protection (OVP) feature
+ * @arg type: boolean
+ * @arg get: @b true if currently enabled
+ * @arg set: enable/disable
+ */
+ SR_CONF_OVER_VOLTAGE_PROTECTION_ENABLED,
+
+ /**
+ * Over-voltage protection (OVP) active
+ * @arg type: boolean
+ * @arg get: @b true if device has activated OVP, i.e. the output voltage
+ * exceeds the over-voltage protection threshold.
+ */
+ SR_CONF_OVER_VOLTAGE_PROTECTION_ACTIVE,
- /** Over-voltage protection (OVP) */
- SR_CONF_OVER_VOLTAGE_PROTECTION,
+ /**
+ * Over-voltage protection (OVP) threshold
+ * @arg type: double (voltage)
+ * @arg get: get current threshold
+ * @arg set: set new threshold
+ */
+ SR_CONF_OVER_VOLTAGE_PROTECTION_THRESHOLD,
- /** Over-current protection (OCP) */
- SR_CONF_OVER_CURRENT_PROTECTION,
+ /**
+ * Over-current protection (OCP) feature
+ * @arg type: boolean
+ * @arg get: @b true if currently enabled
+ * @arg set: enable/disable
+ */
+ SR_CONF_OVER_CURRENT_PROTECTION_ENABLED,
+
+ /**
+ * Over-current protection (OCP) active
+ * @arg type: boolean
+ * @arg get: @b true if device has activated OCP, i.e. the output current
+ * exceeds the over-current protection threshold.
+ */
+ SR_CONF_OVER_CURRENT_PROTECTION_ACTIVE,
+
+ /**
+ * Over-current protection (OCP) threshold
+ * @arg type: double (current)
+ * @arg get: get current threshold
+ * @arg set: set new threshold
+ */
+ SR_CONF_OVER_CURRENT_PROTECTION_THRESHOLD,
/** Choice of clock edge for external clock ("r" or "f"). */
SR_CONF_CLOCK_EDGE,
+ /** Amplitude of a source without strictly-defined MQ. */
+ SR_CONF_AMPLITUDE,
+
+ /**
+ * Output channel regulation
+ * get: "CV", "CC" or "UR", denoting constant voltage, constant current
+ * or unregulated.
+ */
+ SR_CONF_OUTPUT_REGULATION,
+
+ /** Over-temperature protection (OTP) */
+ SR_CONF_OVER_TEMPERATURE_PROTECTION,
+
+ /** Output frequency in Hz. */
+ SR_CONF_OUTPUT_FREQUENCY,
+
/*--- Special stuff -------------------------------------------------*/
/** Scan options supported by the driver. */
@@ -913,8 +892,6 @@ enum sr_configkey {
struct sr_dev_inst {
/** Device driver. */
struct sr_dev_driver *driver;
- /** Index of device in driver. */
- int index;
/** Device instance status. SR_ST_NOT_FOUND, etc. */
int status;
/** Device instance type. SR_INST_USB, etc. */
@@ -925,6 +902,10 @@ struct sr_dev_inst {
char *model;
/** Device version. */
char *version;
+ /** Serial number. */
+ char *serial_num;
+ /** Connection string to uniquely identify devices. */
+ char *connection_id;
/** List of channels. */
GSList *channels;
/** List of sr_channel_group structs */
@@ -992,12 +973,12 @@ struct sr_dev_driver {
/** Query value of a configuration key in driver or given device instance.
* @see sr_config_get().
*/
- int (*config_get) (int id, GVariant **data,
+ int (*config_get) (uint32_t key, GVariant **data,
const struct sr_dev_inst *sdi,
const struct sr_channel_group *cg);
/** Set value of a configuration key in driver or a given device instance.
* @see sr_config_set(). */
- int (*config_set) (int id, GVariant *data,
+ int (*config_set) (uint32_t key, GVariant *data,
const struct sr_dev_inst *sdi,
const struct sr_channel_group *cg);
/** Channel status change.
@@ -1010,7 +991,7 @@ struct sr_dev_driver {
/** List all possible values for a configuration key in a device instance.
* @see sr_config_list().
*/
- int (*config_list) (int info_id, GVariant **data,
+ int (*config_list) (uint32_t key, GVariant **data,
const struct sr_dev_inst *sdi,
const struct sr_channel_group *cg);