X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=libsigrok.h;h=86995690009474329279a416bb2358e067ca1383;hb=04cb915716ecdc1ee26440b4c09bc2f2de183631;hp=dbd0c594f0097461218ca713aa82fd8f6ef9becf;hpb=9fd6bc205433eae242960e9e976d28ac0fd20254;p=libsigrok.git

diff --git a/libsigrok.h b/libsigrok.h
index dbd0c594..86995690 100644
--- a/libsigrok.h
+++ b/libsigrok.h
@@ -41,9 +41,9 @@ extern "C" {
  *
  * The correct way to get/use the libsigrok API functions is:
  *
- * @code{.c}
- *   #include <libsigrok/libsigrok.h>
- * @endcode
+   @code{.c}
+     #include <libsigrok/libsigrok.h>
+   @endcode
  */
 
 /*
@@ -73,6 +73,7 @@ enum {
 	SR_ERR_NA         = -6, /**< Not applicable. */
 	SR_ERR_DEV_CLOSED = -7, /**< Device is closed, but needs to be open. */
 	SR_ERR_TIMEOUT    = -8, /**< A timeout occurred. */
+	SR_ERR_PROBE_GROUP= -9, /**< A probe group must be specified. */
 
 	/*
 	 * Note: When adding entries here, don't forget to also update the
@@ -130,6 +131,7 @@ enum {
 #define SR_PRIV
 #endif
 
+/** Type definition for callback function for data reception. */
 typedef int (*sr_receive_data_callback_t)(int fd, int revents, void *cb_data);
 
 /** Data types used by sr_config_info(). */
@@ -141,21 +143,24 @@ enum {
 	SR_T_RATIONAL_PERIOD,
 	SR_T_RATIONAL_VOLT,
 	SR_T_KEYVALUE,
+	SR_T_UINT64_RANGE,
+	SR_T_DOUBLE_RANGE,
 };
 
 /** Value for sr_datafeed_packet.type. */
 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,
+	SR_DF_HEADER = 10000,	/**< Payload is sr_datafeed_header. */
+	SR_DF_END,		/**< End of stream (no further data). */
+	SR_DF_META,		/**< Payload is struct sr_datafeed_meta */
+	SR_DF_TRIGGER,	/**< The trigger matched at this point in the data feed.
+			No payload. */
+	SR_DF_LOGIC,	/**< Payload is struct sr_datafeed_logic. */
+	SR_DF_ANALOG,	/**< Payload is struct sr_datafeed_analog. */
+	SR_DF_FRAME_BEGIN,	/**< Beginning of frame. No payload. */
+	SR_DF_FRAME_END,	/**< End of frame. No payload. */
 };
 
-/** Values for sr_datafeed_analog.mq. */
+/** Measured quantity, sr_datafeed_analog.mq. */
 enum {
 	SR_MQ_VOLTAGE = 10000,
 	SR_MQ_CURRENT,
@@ -163,36 +168,34 @@ enum {
 	SR_MQ_CAPACITANCE,
 	SR_MQ_TEMPERATURE,
 	SR_MQ_FREQUENCY,
-	SR_MQ_DUTY_CYCLE,
-	SR_MQ_CONTINUITY,
+	SR_MQ_DUTY_CYCLE,	/**< Duty cycle, e.g. on/off ratio. */
+	SR_MQ_CONTINUITY,	/**< Continuity test. */
 	SR_MQ_PULSE_WIDTH,
 	SR_MQ_CONDUCTANCE,
-	/** Electrical power, usually in W, or dBm. */
-	SR_MQ_POWER,
-	/** Gain (a transistor's gain, or hFE, for example). */
-	SR_MQ_GAIN,
+	SR_MQ_POWER,		/**< Electrical power, usually in W, or dBm. */
+	SR_MQ_GAIN,	/**< Gain (a transistor's gain, or hFE, for example). */
 	/** Logarithmic representation of sound pressure relative to a
 	 * reference value. */
 	SR_MQ_SOUND_PRESSURE_LEVEL,
-	SR_MQ_CARBON_MONOXIDE,
-	SR_MQ_RELATIVE_HUMIDITY,
+	SR_MQ_CARBON_MONOXIDE,   /**< Carbon monoxide level */
+	SR_MQ_RELATIVE_HUMIDITY,/**< Humidity */
+	SR_MQ_TIME,		/**< Time */
 };
 
-/** Values for sr_datafeed_analog.unit. */
+/** Unit of measured quantity, sr_datafeed_analog.unit. */
 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,
-	/** Unit of conductance, the inverse of resistance. */
-	SR_UNIT_SIEMENS,
+	SR_UNIT_VOLT = 10000, /**< Volt */
+	SR_UNIT_AMPERE,	      /**< Ampere (current). */
+	SR_UNIT_OHM,	      /**< Ohm (resistance). */
+	SR_UNIT_FARAD,	      /**< Farad (capacity). */
+	SR_UNIT_KELVIN,	      /**< Kelvin (temperature). */
+	SR_UNIT_CELSIUS,      /**< Degrees Celsius (temperature). */
+	SR_UNIT_FAHRENHEIT,   /**< Degrees Fahrenheit (temperature). */
+	SR_UNIT_HERTZ,	      /**< Hertz (frequency, 1/s, [Hz]). */
+	SR_UNIT_PERCENTAGE,   /**< Percent value. */
+	SR_UNIT_BOOLEAN,      /**< Boolean value. */
+	SR_UNIT_SECOND,	      /**< Time in seconds. */
+	SR_UNIT_SIEMENS, /**< Unit of conductance, the inverse of resistance. */
 	/**
 	 * An absolute measurement of power, in decibels, referenced to
 	 * 1 milliwatt (dBu).
@@ -214,6 +217,10 @@ enum {
 	 * represented as the fraction of number of particles of the substance.
 	 */
 	SR_UNIT_CONCENTRATION,
+	SR_UNIT_REVOLUTIONS_PER_MINUTE, /**< Revolutions per minute. */
+	SR_UNIT_VOLT_AMPERE,	/**< Apparent power [VA]. */
+	SR_UNIT_WATT,		/**< Real power [W]. */
+	SR_UNIT_WATT_HOUR,	/**< Consumption [Wh]. */
 };
 
 /** Values for sr_datafeed_analog.flags. */
@@ -260,39 +267,48 @@ enum {
 	/** Sound pressure level represented as a percentage of measurements
 	 * that were over a preset alarm level. */
 	SR_MQFLAG_SPL_PCT_OVER_ALARM = 0x10000,
+	/** Time is duration (as opposed to epoch, ...). */
+	SR_MQFLAG_DURATION = 0x20000,
 };
 
+/** sigrok context (opaque). @see sr_init(), sr_exit(). */
 struct sr_context;
 
+/** Packet in a sigrok data feed. */
 struct sr_datafeed_packet {
 	uint16_t type;
 	const void *payload;
 };
 
+/** Header of a sigrok data feed. */
 struct sr_datafeed_header {
 	int feed_version;
 	struct timeval starttime;
 };
 
+/** Datafeed payload for type SR_DF_META. */
 struct sr_datafeed_meta {
 	GSList *config;
 };
 
+/** Logic datafeed payload for type SR_DF_LOGIC. */
 struct sr_datafeed_logic {
 	uint64_t length;
 	uint16_t unitsize;
 	void *data;
 };
 
+/** Analog datafeed payload for type SR_DF_ANALOG. */
 struct sr_datafeed_analog {
 	/** The probes for which data is included in this packet. */
 	GSList *probes;
-	int num_samples;
-	/** Measured quantity (voltage, current, temperature, and so on). */
+	int num_samples;	/**< Number of samples in data */
+	/** Measured quantity (voltage, current, temperature, and so on).
+	 *  Use SR_MQ_VOLTAGE, ... */
 	int mq;
-	/** Unit in which the MQ is measured. */
+	/** Unit in which the MQ is measured. Use SR_UNIT_VOLT, ... */
 	int unit;
-	/** Bitmap with extra information about the MQ. */
+	/** Bitmap with extra information about the MQ. Use SR_MQFLAG_AC, ... */
 	uint64_t mqflags;
 	/** The analog value(s). The data is interleaved according to
 	 * the probes list. */
@@ -314,6 +330,7 @@ struct sr_input {
 	void *internal;
 };
 
+/** Input (file) format driver. */
 struct sr_input_format {
 	/** The unique ID for this input format. Must not be NULL. */
 	char *id;
@@ -327,9 +344,10 @@ struct sr_input_format {
 	/**
 	 * Check if this input module can load and parse the specified file.
 	 *
-	 * @param filename The name (and path) of the file to check.
+	 * @param[in] filename The name (and path) of the file to check.
 	 *
-	 * @return TRUE if this module knows the format, FALSE if it doesn't.
+	 * @retval TRUE This module knows the format.
+	 * @retval FALSE This module does not know the format.
 	 */
 	int (*format_match) (const char *filename);
 
@@ -339,9 +357,10 @@ struct sr_input_format {
 	 * @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.
+	 * @param[in] filename The name (and path) of the file to use.
 	 *
-	 * @return SR_OK upon success, a negative error code upon failure.
+	 * @retval SR_OK Success
+	 * @retval other Negative error code.
 	 */
 	int (*init) (struct sr_input *in, const char *filename);
 
@@ -362,7 +381,8 @@ struct sr_input_format {
 	 *           the responsibility of the caller to free it later.
 	 * @param filename The name (and path) of the file to use.
 	 *
-	 * @return SR_OK upon success, a negative error code upon failure.
+	 * @retval SR_OK Success
+	 * @retval other Negative error code.
 	 */
 	int (*loadfile) (struct sr_input *in, const char *filename);
 };
@@ -398,6 +418,7 @@ struct sr_output {
 	void *internal;
 };
 
+/** Output (file) format driver. */
 struct sr_output_format {
 	/**
 	 * A unique ID for this output format. Must not be NULL.
@@ -417,7 +438,7 @@ struct sr_output_format {
 	 */
 	char *description;
 
-	int df_type;
+	int df_type;	/**< Datafeed type, SR_DF_HEADER, etc. */
 
 	/**
 	 * This function is called once, at the beginning of an output stream.
@@ -431,7 +452,8 @@ struct sr_output_format {
 	 *
 	 * @param o Pointer to the respective 'struct sr_output'.
 	 *
-	 * @return SR_OK upon success, a negative error code otherwise.
+	 * @retval SR_OK Success
+	 * @retval other Negative error code.
 	 */
 	int (*init) (struct sr_output *o);
 
@@ -463,7 +485,8 @@ struct sr_output_format {
 	 * @param data_out Pointer to the allocated output buffer.
 	 * @param length_out Length (in bytes) of the output.
 	 *
-	 * @return SR_OK upon success, a negative error code otherwise.
+	 * @retval SR_OK Success
+	 * @retval other Negative error code.
 	 */
 	int (*data) (struct sr_output *o, const uint8_t *data_in,
 		     uint64_t length_in, uint8_t **data_out,
@@ -494,7 +517,8 @@ struct sr_output_format {
 	 * @param data_out Pointer to the allocated output buffer.
 	 * @param length_out Length (in bytes) of the output.
 	 *
-	 * @return SR_OK upon success, a negative error code otherwise.
+	 * @retval SR_OK Success
+	 * @retval other Negative error code.
 	 */
 	int (*event) (struct sr_output *o, int event_type, uint8_t **data_out,
 			uint64_t *length_out);
@@ -514,7 +538,8 @@ struct sr_output_format {
 	 * @param out A pointer where a GString * should be stored if
 	 * the module generates output, or NULL if not.
 	 *
-	 * @return SR_OK upon success, a negative error code otherwise.
+	 * @retval SR_OK Success
+	 * @retval other Negative error code.
 	 */
 	int (*receive) (struct sr_output *o, const struct sr_dev_inst *sdi,
 			const struct sr_datafeed_packet *packet, GString **out);
@@ -524,38 +549,54 @@ struct sr_output_format {
 	 * the output module, and can be used to free any internal
 	 * resources the module may keep.
 	 *
-	 * @return SR_OK upon success, a negative error code otherwise.
+	 * @retval SR_OK Success
+	 * @retval other Negative error code.
 	 */
 	int (*cleanup) (struct sr_output *o);
 };
 
+/** Constants for probe type. */
 enum {
-	SR_PROBE_LOGIC = 10000,
-	SR_PROBE_ANALOG,
+    SR_PROBE_LOGIC = 10000, /**< Probe type is logic probe. */
+    SR_PROBE_ANALOG,        /**< Probe type is analog probe. */
 };
 
+/** Information on single probe. */
 struct sr_probe {
-	/* The index field will go: use g_slist_length(sdi->probes) instead. */
-	int index;
-	int type;
-	gboolean enabled;
+        int index; /**< Number of probe, starting at 0. @deprecated The
+                index field will go: use g_slist_length(sdi->probes) instead. */
+	int type;	/**< Probe type (SR_PROBE_LOGIC, ...) */
+	gboolean enabled;   /**< Is this probe enabled? */
+	char *name;/**< Name of probe. */
+	char *trigger;/**< Trigger string, format like used by sigrok-cli */
+};
+
+/** Structure for groups of probes that have common properties. */
+struct sr_probe_group {
+	/** Name of the probe group. */
 	char *name;
-	char *trigger;
+	/** List of sr_probe structs of the probes belonging to this group. */
+	GSList *probes;
+	/** Private data for driver use. */
+	void *priv;
 };
 
+/** Used for setting or getting value of a config item. */
 struct sr_config {
-	int key;
-	GVariant *data;
+	int key;		/**< Config key like SR_CONF_CONN, etc. */
+	GVariant *data;		/**< Key-specific data. */
 };
 
+/** Information about a config key. */
 struct sr_config_info {
-	int key;
-	int datatype;
-	char *id;
-	char *name;
-	char *description;
+	int key;		/**< Config key like SR_CONF_CONN, etc. */
+	int datatype;		/**< Data type like SR_T_CHAR, etc. */
+	char *id;		/**< Id string, e.g. "serialcomm". */
+	char *name;		/**< Name, e.g. "Serial communication". */
+	char *description;	/**< Verbose description (unused currently). */
 };
 
+/** Constants for device classes */
 enum {
 	/*--- Device classes ------------------------------------------------*/
 
@@ -580,6 +621,9 @@ enum {
 	/** The device can measure humidity. */
 	SR_CONF_HYGROMETER,
 
+	/** The device can measure energy consumption. */
+	SR_CONF_ENERGYMETER,
+
 	/*--- Driver scan options -------------------------------------------*/
 
 	/**
@@ -609,7 +653,7 @@ enum {
 	 * 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.
 	 */
@@ -671,12 +715,27 @@ enum {
 	/** Sound pressure level time weighting.  */
 	SR_CONF_SPL_WEIGHT_TIME,
 
+	/** Sound pressure level measurement range.  */
+	SR_CONF_SPL_MEASUREMENT_RANGE,
+
 	/** Max hold mode. */
 	SR_CONF_HOLD_MAX,
 
 	/** Min hold mode. */
 	SR_CONF_HOLD_MIN,
 
+	/** Logic low-high threshold range. */
+	SR_CONF_VOLTAGE_THRESHOLD,
+
+	/** The device supports using a external clock. */
+	SR_CONF_EXTERNAL_CLOCK,
+
+	/**
+	 * The device supports swapping channels. Typical this is between
+	 * buffered and unbuffered channels.
+	 */
+	SR_CONF_SWAP,
+
 	/*--- Special stuff -------------------------------------------------*/
 
 	/** Scan options supported by the driver. */
@@ -697,6 +756,21 @@ enum {
 	/** The device supports setting the number of probes. */
 	SR_CONF_CAPTURE_NUM_PROBES,
 
+	/** Power off the device. */
+	SR_CONF_POWER_OFF,
+
+	/** 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_DATA_SOURCE,
+
 	/*--- Acquisition modes ---------------------------------------------*/
 
 	/**
@@ -729,28 +803,34 @@ enum {
 	SR_CONF_DATALOG,
 };
 
+/** @private
+ *  Device instance data
+ */
 struct sr_dev_inst {
-	struct sr_dev_driver *driver;
-	int index;
-	int status;
-	int inst_type;
-	char *vendor;
-	char *model;
-	char *version;
-	GSList *probes;
-	void *conn;
-	void *priv;
+	struct sr_dev_driver *driver;   /**< Device driver. */
+	int index;	/**< Index of device in driver. */
+	int status;	/**< Device instance status. SR_ST_NOT_FOUND, etc. */
+	int inst_type;	/**< Device instance type. SR_INST_USB, etc. */
+	char *vendor;	/**< Device vendor. */
+	char *model;	/**< Device model. */
+	char *version;	/**< Device version. */
+	GSList *probes;	/**< List of probes. */
+	GSList *probe_groups;	/**< List of sr_probe_group structs */
+	void *conn;	/**< Device instance connection data (used?) */
+	void *priv;	/**< Device instance private data (used?) */
 };
 
-/** Types of device instances (sr_dev_inst). */
+/** Types of device instance, struct sr_dev_inst.type */
 enum {
 	/** Device instance type for USB devices. */
 	SR_INST_USB = 10000,
 	/** Device instance type for serial port devices. */
 	SR_INST_SERIAL,
+	/** Device instance type for SCPI devices. */
+	SR_INST_SCPI,
 };
 
-/** Device instance status. */
+/** Device instance status, struct sr_dev_inst.status */
 enum {
 	/** The device instance was not found. */
 	SR_ST_NOT_FOUND = 10000,
@@ -764,62 +844,44 @@ enum {
 	SR_ST_STOPPING,
 };
 
+/** Device driver data */
 struct sr_dev_driver {
 	/* Driver-specific */
-	char *name;
-	char *longname;
-	int api_version;
-	int (*init) (struct sr_context *sr_ctx);
-	int (*cleanup) (void);
-	GSList *(*scan) (GSList *options);
-	GSList *(*dev_list) (void);
+	char *name;		/**< Driver name */
+	char *longname;		/**< Long name, e.g. device name. */
+	int api_version;	/**< API version (currently 1).	*/
+	int (*init) (struct sr_context *sr_ctx);	/**< Init driver */
+	int (*cleanup) (void);				/**< Free driver */
+	GSList *(*scan) (GSList *options);		/**< Scan for devices */
+	GSList *(*dev_list) (void);			/**< Get device list */
 	int (*dev_clear) (void);
 	int (*config_get) (int id, GVariant **data,
-			const struct sr_dev_inst *sdi);
+			const struct sr_dev_inst *sdi,
+			const struct sr_probe_group *probe_group);
 	int (*config_set) (int id, GVariant *data,
-			const struct sr_dev_inst *sdi);
+			const struct sr_dev_inst *sdi,
+			const struct sr_probe_group *probe_group);
 	int (*config_list) (int info_id, GVariant **data,
-			const struct sr_dev_inst *sdi);
+			const struct sr_dev_inst *sdi,
+			const struct sr_probe_group *probe_group);
 
 	/* Device-specific */
-	int (*dev_open) (struct sr_dev_inst *sdi);
-	int (*dev_close) (struct sr_dev_inst *sdi);
+	int (*dev_open) (struct sr_dev_inst *sdi);	/**< Open device */
+	int (*dev_close) (struct sr_dev_inst *sdi);	/**< Close device */
 	int (*dev_acquisition_start) (const struct sr_dev_inst *sdi,
-			void *cb_data);
+			void *cb_data);	/**< Start data aquisition. */
 	int (*dev_acquisition_stop) (struct sr_dev_inst *sdi,
-			void *cb_data);
+			void *cb_data);	/**< Stop data aquisition. */
 
 	/* Dynamic */
-	void *priv;
+	void *priv;			/**< Device driver private data */
 };
 
-struct sr_session {
-	/** List of struct sr_dev pointers. */
-	GSList *devs;
-	/** List of struct datafeed_callback pointers. */
-	GSList *datafeed_callbacks;
-	GTimeVal starttime;
-
-	unsigned int num_sources;
-
-	/*
-	 * Both "sources" and "pollfds" are of the same size and contain pairs
-	 * of descriptor and callback function. We can not embed the GPollFD
-	 * into the source struct since we want to be able to pass the array
-	 * of all poll descriptors to g_poll().
-	 */
-	struct source *sources;
-	GPollFD *pollfds;
-	int source_timeout;
-
-	/*
-	 * These are our synchronization primitives for stopping the session in
-	 * an async fashion. We need to make sure the session is stopped from
-	 * within the session thread itself.
-	 */
-	GMutex stop_mutex;
-	gboolean abort_session;
-};
+/**
+ * Opaque data structure representing a libsigrok session. None of the fields
+ * of this structure are meant to be accessed directly.
+ */
+struct sr_session;
 
 #include "proto.h"
 #include "version.h"