X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=libsigrok.h;h=6e024352ab6c8c426c4191b1fee1e01d585a3740;hb=df823ac4445ed6f708136e208c8b8bd4930f4a9e;hp=5589bdc11159e0d9ec8b0ed609dd3201ecec4315;hpb=c1e45c6511eb4e9023095fc364913db85a092651;p=libsigrok.git

diff --git a/libsigrok.h b/libsigrok.h
index 5589bdc1..6e024352 100644
--- a/libsigrok.h
+++ b/libsigrok.h
@@ -17,8 +17,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LIBSIGROK_SIGROK_H
-#define LIBSIGROK_SIGROK_H
+#ifndef LIBSIGROK_LIBSIGROK_H
+#define LIBSIGROK_LIBSIGROK_H
 
 #include <stdio.h>
 #include <sys/time.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
  */
 
 /*
@@ -131,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(). */
@@ -148,17 +149,25 @@ enum {
 
 /** Value for sr_datafeed_packet.type. */
 enum {
+	/** Payload is sr_datafeed_header. */
 	SR_DF_HEADER = 10000,
+	/** End of stream (no further data). */
 	SR_DF_END,
+	/** Payload is struct sr_datafeed_meta */
 	SR_DF_META,
+	/** The trigger matched at this point in the data feed. No payload. */
 	SR_DF_TRIGGER,
+	/** Payload is struct sr_datafeed_logic. */
 	SR_DF_LOGIC,
+	/** Payload is struct sr_datafeed_analog. */
 	SR_DF_ANALOG,
+	/** Beginning of frame. No payload. */
 	SR_DF_FRAME_BEGIN,
+	/** End of frame. No payload. */
 	SR_DF_FRAME_END,
 };
 
-/** Values for sr_datafeed_analog.mq. */
+/** Measured quantity, sr_datafeed_analog.mq. */
 enum {
 	SR_MQ_VOLTAGE = 10000,
 	SR_MQ_CURRENT,
@@ -166,7 +175,9 @@ enum {
 	SR_MQ_CAPACITANCE,
 	SR_MQ_TEMPERATURE,
 	SR_MQ_FREQUENCY,
+	/** Duty cycle, e.g. on/off ratio. */
 	SR_MQ_DUTY_CYCLE,
+	/** Continuity test. */
 	SR_MQ_CONTINUITY,
 	SR_MQ_PULSE_WIDTH,
 	SR_MQ_CONDUCTANCE,
@@ -177,23 +188,37 @@ enum {
 	/** Logarithmic representation of sound pressure relative to a
 	 * reference value. */
 	SR_MQ_SOUND_PRESSURE_LEVEL,
+	/** Carbon monoxide level */
 	SR_MQ_CARBON_MONOXIDE,
+	/** Humidity */
 	SR_MQ_RELATIVE_HUMIDITY,
-	SR_MQ_TIME,		/**< Time */
+	/** Time */
+	SR_MQ_TIME,
 };
 
-/** Values for sr_datafeed_analog.unit. */
+/** Unit of measured quantity, sr_datafeed_analog.unit. */
 enum {
+	/** Volt */
 	SR_UNIT_VOLT = 10000,
+	/** Ampere (current). */
 	SR_UNIT_AMPERE,
+	/** Ohm (resistance). */
 	SR_UNIT_OHM,
+	/** Farad (capacity). */
 	SR_UNIT_FARAD,
+	/** Kelvin (temperature). */
 	SR_UNIT_KELVIN,
+	/** Degrees Celsius (temperature). */
 	SR_UNIT_CELSIUS,
+	/** Degrees Fahrenheit (temperature). */
 	SR_UNIT_FAHRENHEIT,
+	/** Hertz (frequency, 1/s, [Hz]). */
 	SR_UNIT_HERTZ,
+	/** Percent value. */
 	SR_UNIT_PERCENTAGE,
+	/** Boolean value. */
 	SR_UNIT_BOOLEAN,
+	/** Time in seconds. */
 	SR_UNIT_SECOND,
 	/** Unit of conductance, the inverse of resistance. */
 	SR_UNIT_SIEMENS,
@@ -218,9 +243,13 @@ enum {
 	 * represented as the fraction of number of particles of the substance.
 	 */
 	SR_UNIT_CONCENTRATION,
+	/** Revolutions per minute. */
 	SR_UNIT_REVOLUTIONS_PER_MINUTE,
+	/** Apparent power [VA]. */
 	SR_UNIT_VOLT_AMPERE,
+	/** Real power [W]. */
 	SR_UNIT_WATT,
+	/** Consumption [Wh]. */
 	SR_UNIT_WATT_HOUR,
 };
 
@@ -270,39 +299,56 @@ enum {
 	SR_MQFLAG_SPL_PCT_OVER_ALARM = 0x10000,
 	/** Time is duration (as opposed to epoch, ...). */
 	SR_MQFLAG_DURATION = 0x20000,
+	/** Device is in "avg" mode, averaging upon each new value. */
+	SR_MQFLAG_AVG = 0x40000,
 };
 
+/**
+ * @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. */
 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;
+	/** Number of samples in data */
 	int num_samples;
-	/** Measured quantity (voltage, current, temperature, and so on). */
+	/** 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. */
@@ -324,6 +370,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;
@@ -337,9 +384,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);
 
@@ -349,9 +397,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);
 
@@ -372,7 +421,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);
 };
@@ -408,6 +458,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.
@@ -427,6 +478,7 @@ struct sr_output_format {
 	 */
 	char *description;
 
+	/** Datafeed type, SR_DF_HEADER, etc. */
 	int df_type;
 
 	/**
@@ -441,7 +493,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);
 
@@ -473,7 +526,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,
@@ -504,7 +558,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);
@@ -524,7 +579,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);
@@ -534,22 +590,32 @@ 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,
+	/** Probe type is logic probe. */
+    SR_PROBE_LOGIC = 10000,
+	/** Probe type is analog probe. */
+    SR_PROBE_ANALOG,
 };
 
+/** Information on single probe. */
 struct sr_probe {
-	/* The index field will go: use g_slist_length(sdi->probes) instead. */
+	/** Number of probes, starting at 0. @deprecated The index field
+	 * will go: use g_slist_length(sdi->probes) instead. */
 	int index;
+	/** Probe type (SR_PROBE_LOGIC, ...) */
 	int type;
+	/** Is this probe enabled? */
 	gboolean enabled;
+	/** Name of probe. */
 	char *name;
+	/** Trigger string, format like used by sigrok-cli */
 	char *trigger;
 };
 
@@ -563,19 +629,29 @@ struct sr_probe_group {
 	void *priv;
 };
 
+/** Used for setting or getting value of a config item. */
 struct sr_config {
+	/** Config key like SR_CONF_CONN, etc. */
 	int key;
+	/** Key-specific data. */
 	GVariant *data;
 };
 
+/** Information about a config key. */
 struct sr_config_info {
+	/** Config key like SR_CONF_CONN, etc. */
 	int key;
+	/** Data type like SR_T_CHAR, etc. */
 	int datatype;
+	/** Id string, e.g. "serialcomm". */
 	char *id;
+	/** Name, e.g. "Serial communication". */
 	char *name;
+	/** Verbose description (unused currently). */
 	char *description;
 };
 
+/** Constants for device classes */
 enum {
 	/*--- Device classes ------------------------------------------------*/
 
@@ -782,22 +858,34 @@ enum {
 	SR_CONF_DATALOG,
 };
 
+/** Device instance data
+ */
 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. */
 	int inst_type;
+	/** Device vendor. */
 	char *vendor;
+	/** Device model. */
 	char *model;
+	/** Device version. */
 	char *version;
+	/** List of probes. */
 	GSList *probes;
-	/* List of sr_probe_group structs */
+	/** List of sr_probe_group structs */
 	GSList *probe_groups;
+	/** Device instance connection data (used?) */
 	void *conn;
+	/** Device instance private data (used?) */
 	void *priv;
 };
 
-/** 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,
@@ -807,7 +895,7 @@ enum {
 	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,
@@ -821,14 +909,22 @@ enum {
 	SR_ST_STOPPING,
 };
 
+/** Device driver data */
 struct sr_dev_driver {
 	/* Driver-specific */
+	/** Driver name */
 	char *name;
+	/** Long name, e.g. device name. */
 	char *longname;
+	/** API version (currently 1).	*/
 	int api_version;
+	/** Init driver */
 	int (*init) (struct sr_context *sr_ctx);
+	/** Free driver */
 	int (*cleanup) (void);
+	/** Scan for devices */
 	GSList *(*scan) (GSList *options);
+	/** Get device list */
 	GSList *(*dev_list) (void);
 	int (*dev_clear) (void);
 	int (*config_get) (int id, GVariant **data,
@@ -842,18 +938,25 @@ struct sr_dev_driver {
 			const struct sr_probe_group *probe_group);
 
 	/* 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. */
 	int (*dev_acquisition_start) (const struct sr_dev_inst *sdi,
 			void *cb_data);
+	/** Stop data aquisition. */
 	int (*dev_acquisition_stop) (struct sr_dev_inst *sdi,
 			void *cb_data);
 
 	/* Dynamic */
+	/** Device driver private data */
 	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.
  */