X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=libsigrok.h;h=382f502b470a3a992c868a10b4730344133f864b;hb=53b4680fceab9351fc87b8c5b34854733f5fdac0;hp=f546183e48915f3355c1a20a28f6797a26c13067;hpb=f5027ca481d91fc92ec878d2eec2b6b446d3b7de;p=libsigrok.git

diff --git a/libsigrok.h b/libsigrok.h
index f546183e..382f502b 100644
--- a/libsigrok.h
+++ b/libsigrok.h
@@ -64,16 +64,16 @@ extern "C" {
 
 /** Status/error codes returned by libsigrok functions. */
 enum {
-	SR_OK             =  0, /**< No error. */
-	SR_ERR            = -1, /**< Generic/unspecified error. */
-	SR_ERR_MALLOC     = -2, /**< Malloc/calloc/realloc error. */
-	SR_ERR_ARG        = -3, /**< Function argument error. */
-	SR_ERR_BUG        = -4, /**< Errors hinting at internal bugs. */
-	SR_ERR_SAMPLERATE = -5, /**< Incorrect samplerate. */
-	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. */
+	SR_OK                =  0, /**< No error. */
+	SR_ERR               = -1, /**< Generic/unspecified error. */
+	SR_ERR_MALLOC        = -2, /**< Malloc/calloc/realloc error. */
+	SR_ERR_ARG           = -3, /**< Function argument error. */
+	SR_ERR_BUG           = -4, /**< Errors hinting at internal bugs. */
+	SR_ERR_SAMPLERATE    = -5, /**< Incorrect samplerate. */
+	SR_ERR_NA            = -6, /**< Not applicable. */
+	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. */
 
 	/*
 	 * Note: When adding entries here, don't forget to also update the
@@ -145,6 +145,7 @@ enum {
 	SR_T_KEYVALUE,
 	SR_T_UINT64_RANGE,
 	SR_T_DOUBLE_RANGE,
+	SR_T_INT32,
 };
 
 /** Value for sr_datafeed_packet.type. */
@@ -303,7 +304,14 @@ enum {
 	SR_MQFLAG_AVG = 0x40000,
 };
 
-/** sigrok context (opaque). @see sr_init(), sr_exit(). */
+/**
+ * @struct sr_context
+ * Opaque structure representing a libsigrok context.
+ *
+ * None of the fields of this structure are meant to be accessed directly.
+ *
+ * @see sr_init(), sr_exit().
+ */
 struct sr_context;
 
 /** Packet in a sigrok data feed. */
@@ -599,8 +607,7 @@ enum {
 
 /** Information on single probe. */
 struct sr_probe {
-	/** Number of probes, starting at 0. @deprecated The index field
-	 * will go: use g_slist_length(sdi->probes) instead. */
+	/** Number of probes, starting at 0. */
 	int index;
 	/** Probe type (SR_PROBE_LOGIC, ...) */
 	int type;
@@ -612,12 +619,12 @@ struct sr_probe {
 	char *trigger;
 };
 
-/** Structure for groups of probes that have common properties. */
-struct sr_probe_group {
-	/** Name of the probe group. */
+/** Structure for groups of channels that have common properties. */
+struct sr_channel_group {
+	/** Name of the channel group. */
 	char *name;
-	/** List of sr_probe structs of the probes belonging to this group. */
-	GSList *probes;
+	/** List of sr_probe structs of the channels belonging to this group. */
+	GSList *channels;
 	/** Private data for driver use. */
 	void *priv;
 };
@@ -672,6 +679,12 @@ enum {
 	/** The device can measure energy consumption. */
 	SR_CONF_ENERGYMETER,
 
+	/** The device can demodulate signals. */
+	SR_CONF_DEMODULATOR,
+
+	/** Programmable power supply. */
+	SR_CONF_POWER_SUPPLY,
+
 	/*--- Driver scan options -------------------------------------------*/
 
 	/**
@@ -775,7 +788,7 @@ enum {
 	/** Logic low-high threshold range. */
 	SR_CONF_VOLTAGE_THRESHOLD,
 
-	/** The device supports using a external clock. */
+	/** The device supports using an external clock. */
 	SR_CONF_EXTERNAL_CLOCK,
 
 	/**
@@ -784,6 +797,45 @@ enum {
 	 */
 	SR_CONF_SWAP,
 
+	/** Center frequency.
+	 * The input signal is downmixed by this frequency before the ADC
+	 * anti-aliasing filter.
+	 */
+	SR_CONF_CENTER_FREQUENCY,
+
+	/** The device supports setting the number of logic probes. */
+	SR_CONF_NUM_LOGIC_PROBES,
+
+	/** The device supports setting the number of analog probes. */
+	SR_CONF_NUM_ANALOG_PROBES,
+
+	/** Output voltage. */
+	SR_CONF_OUTPUT_VOLTAGE,
+
+	/** Maximum output voltage. */
+	SR_CONF_OUTPUT_VOLTAGE_MAX,
+
+	/** Output current. */
+	SR_CONF_OUTPUT_CURRENT,
+
+	/** Maximum output current. */
+	SR_CONF_OUTPUT_CURRENT_MAX,
+
+	/** Enabling/disabling output. */
+	SR_CONF_OUTPUT_ENABLED,
+
+	/** Channel output configuration. */
+	SR_CONF_OUTPUT_CHANNEL,
+
+	/** Over-voltage protection (OVP) */
+	SR_CONF_OVER_VOLTAGE_PROTECTION,
+
+	/** Over-current protection (OCP) */
+	SR_CONF_OVER_CURRENT_PROTECTION,
+
+	/** Choice of clock edge for external clock ("r" or "f"). */
+	SR_CONF_CLOCK_EDGE,
+
 	/*--- Special stuff -------------------------------------------------*/
 
 	/** Scan options supported by the driver. */
@@ -801,13 +853,11 @@ enum {
 	/** The device supports specifying the capturefile unit size. */
 	SR_CONF_CAPTURE_UNITSIZE,
 
-	/** 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
+	/**
+	 * 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.
 	 *
@@ -816,7 +866,8 @@ enum {
 	 * 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. */
+	 * is always the default.
+	 */
 	SR_CONF_DATA_SOURCE,
 
 	/*--- Acquisition modes ---------------------------------------------*/
@@ -870,8 +921,8 @@ struct sr_dev_inst {
 	char *version;
 	/** List of probes. */
 	GSList *probes;
-	/** List of sr_probe_group structs */
-	GSList *probe_groups;
+	/** List of sr_channel_group structs */
+	GSList *channel_groups;
 	/** Device instance connection data (used?) */
 	void *conn;
 	/** Device instance private data (used?) */
@@ -902,52 +953,79 @@ enum {
 	SR_ST_STOPPING,
 };
 
-/** Device driver data */
+/** Device driver data. See also http://sigrok.org/wiki/Hardware_driver_API . */
 struct sr_dev_driver {
 	/* Driver-specific */
-	/** Driver name */
+	/** Driver name. Lowercase a-z, 0-9 and dashes (-) only. */
 	char *name;
-	/** Long name, e.g. device name. */
+	/** Long name. Verbose driver name shown to user. */
 	char *longname;
 	/** API version (currently 1).	*/
 	int api_version;
-	/** Init driver */
+	/** Called when driver is loaded, e.g. program startup. */
 	int (*init) (struct sr_context *sr_ctx);
-	/** Free driver */
+	/** Called before driver is unloaded.
+	 *  Driver must free all resouces held by it. */
 	int (*cleanup) (void);
-	/** Scan for devices */
+	/** Scan for devices. Driver should do all initialisation required.
+	 *  Can be called several times, e.g. with different port options.
+	 *  \retval NULL Error or no devices found.
+	 *  \retval other GSList of a struct sr_dev_inst for each device.
+	 *                Must be freed by caller!
+	 */
 	GSList *(*scan) (GSList *options);
-	/** Get device list */
+	/** Get list of device instances the driver knows about.
+	 *  \returns NULL or GSList of a struct sr_dev_inst for each device.
+	 *           Must not be freed by caller!
+	 */
 	GSList *(*dev_list) (void);
+	/** Clear list of devices the driver knows about. */
 	int (*dev_clear) (void);
+	/** Query value of a configuration key in driver or given device instance.
+	 *  @see sr_config_get().
+	 */
 	int (*config_get) (int id, GVariant **data,
 			const struct sr_dev_inst *sdi,
-			const struct sr_probe_group *probe_group);
+			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,
 			const struct sr_dev_inst *sdi,
-			const struct sr_probe_group *probe_group);
+			const struct sr_channel_group *cg);
+	/** Probe status change.
+	 *  @see sr_dev_probe_enable(), sr_dev_trigger_set(). */
+	int (*config_probe_set) (const struct sr_dev_inst *sdi,
+			struct sr_probe *probe, unsigned int changes);
+	/** Apply configuration settings to the device hardware.
+	 *  @see sr_config_commit().*/
+	int (*config_commit) (const struct sr_dev_inst *sdi);
+	/** List all possible values for a configuration key in a device instance.
+	 *  @see sr_config_list().
+	 */
 	int (*config_list) (int info_id, GVariant **data,
 			const struct sr_dev_inst *sdi,
-			const struct sr_probe_group *probe_group);
+			const struct sr_channel_group *cg);
 
 	/* Device-specific */
 	/** Open device */
 	int (*dev_open) (struct sr_dev_inst *sdi);
 	/** Close device */
 	int (*dev_close) (struct sr_dev_inst *sdi);
-	/** Start data aquisition. */
+	/** Begin data acquisition on the specified device. */
 	int (*dev_acquisition_start) (const struct sr_dev_inst *sdi,
 			void *cb_data);
-	/** Stop data aquisition. */
+	/** End data acquisition on the specified device. */
 	int (*dev_acquisition_stop) (struct sr_dev_inst *sdi,
 			void *cb_data);
 
 	/* Dynamic */
-	/** Device driver private data */
+	/** Device driver private data. Initialized by init(). */
 	void *priv;
 };
 
 /**
+ * @struct sr_session
+ *
  * Opaque data structure representing a libsigrok session. None of the fields
  * of this structure are meant to be accessed directly.
  */