X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=libsigrok.h;h=bf0b8b295812bfdcd06ea4245274bd33853c5e96;hb=07e1aad5c4d53ee1028613312061f261f1a7800a;hp=63b2a6087cc26c511f93ea681ad5e08c9d53a955;hpb=69e19dd7691f86ac001469d1b319e1358e0d9778;p=libsigrok.git

diff --git a/libsigrok.h b/libsigrok.h
index 63b2a608..bf0b8b29 100644
--- a/libsigrok.h
+++ b/libsigrok.h
@@ -286,6 +286,7 @@ struct sr_datafeed_logic {
 };
 
 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). */
@@ -294,46 +295,214 @@ struct sr_datafeed_analog {
 	int unit;
 	/** Bitmap with extra information about the MQ. */
 	uint64_t mqflags;
-	/** The analog value. */
+	/** The analog value(s). The data is interleaved according to
+	 * the probes list. */
 	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;
 };
 
 struct sr_input_format {
+	/** The unique ID for this input format. Must not be NULL. */
 	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 filename The name (and path) of the file to check.
+	 *
+	 * @return TRUE if this module knows the format, FALSE if it doesn't.
+	 */
 	int (*format_match) (const char *filename);
-	int (*init) (struct sr_input *in);
+
+	/**
+	 * 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 filename The name (and path) of the file to use.
+	 *
+	 * @return SR_OK upon success, a negative error code upon failure.
+	 */
+	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.
+	 *
+	 * @return SR_OK upon success, a negative error code upon failure.
+	 */
 	int (*loadfile) (struct sr_input *in, const char *filename);
 };
 
+/** Output (file) format struct. */
 struct sr_output {
+	/**
+	 * A pointer to this output format's 'struct sr_output_format'.
+	 * The frontend can use this to call the module's callbacks.
+	 */
 	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 probe names and numbers.
+	 */
 	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.
+	 */
 	char *param;
+
+	/**
+	 * 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;
 };
 
 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 <code>-O hex</code> 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;
+
 	int df_type;
+
+	/**
+	 * 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 <code>internal</code> field.
+	 *
+	 * @param o Pointer to the respective 'struct sr_output'.
+	 *
+	 * @return SR_OK upon success, a negative error code otherwise.
+	 */
 	int (*init) (struct sr_output *o);
-	/* Obsolete, use recv() instead. */
+
+	/**
+	 * Whenever a chunk of data comes in, it will be passed to the
+	 * output module via this function. The <code>data_in</code> and
+	 * <code>length_in</code> values refers to this data; the module
+	 * must not alter or g_free() this buffer.
+	 *
+	 * The function must allocate a buffer for storing its output, and
+	 * pass along a pointer to this buffer in the <code>data_out</code>
+	 * parameter, as well as storing the length of the buffer in
+	 * <code>length_out</code>. The calling frontend will g_free()
+	 * this buffer when it's done with it.
+	 *
+	 * IMPORTANT: The memory allocation much happen using a glib memory
+	 * allocation call (not a "normal" malloc) since g_free() will be
+	 * used to free the memory!
+	 *
+	 * If there is no output, this function MUST store NULL in the
+	 * <code>data_out</code> parameter, so the caller knows not to try
+	 * and g_free() it.
+	 *
+	 * Note: This API call is obsolete, use recv() instead.
+	 *
+	 * @param o Pointer to the respective 'struct sr_output'.
+	 * @param data_in Pointer to the input data buffer.
+	 * @param length_in Length of the input.
+	 * @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.
+	 */
 	int (*data) (struct sr_output *o, const uint8_t *data_in,
 		     uint64_t length_in, uint8_t **data_out,
 		     uint64_t *length_out);
-	/* Obsolete, use recv() instead. */
+
+	/**
+	 * This function is called when an event occurs in the datafeed
+	 * which the output module may need to be aware of. No data is
+	 * passed in, only the fact that the event occurs. The following
+	 * events can currently be passed in:
+	 *
+	 *  - SR_DF_TRIGGER: At this point in the datafeed, the trigger
+	 *    matched. The output module may mark this in some way, e.g. by
+	 *    plotting a red line on a graph.
+	 *
+	 *  - SR_DF_END: This marks the end of the datafeed. No more calls
+	 *    into the output module will be done, so this is a good time to
+	 *    free up any memory used to keep state, for example.
+	 *
+	 * Any output generated by this function must have a reference to
+	 * it stored in the <code>data_out</code> and <code>length_out</code>
+	 * parameters, or NULL if no output was generated.
+	 *
+	 * Note: This API call is obsolete, use recv() instead.
+	 *
+	 * @param o Pointer to the respective 'struct sr_output'.
+	 * @param event_type Type of event that occured.
+	 * @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.
+	 */
 	int (*event) (struct sr_output *o, int event_type, uint8_t **data_out,
 		      uint64_t *length_out);
+
 	GString *(*recv) (struct sr_output *o, const struct sr_dev_inst *sdi,
 			const struct sr_datafeed_packet *packet);
+
 	int (*cleanup) (struct sr_output *o);
 };
 
@@ -388,7 +557,7 @@ enum {
 	/** The device can measure humidity. */
 	SR_CONF_HYGROMETER,
 
-	/*--- Driver options ------------------------------------------------*/
+	/*--- Driver scan options -------------------------------------------*/
 
 	/**
 	 * Specification on how to connect to a device.
@@ -461,20 +630,26 @@ enum {
 	/** Coupling. */
 	SR_CONF_COUPLING,
 
+	/** Trigger types.  */
+	SR_CONF_TRIGGER_TYPE,
+
 	/*--- Special stuff -------------------------------------------------*/
 
+	/** Scan options supported by the driver. */
+	SR_CONF_SCAN_OPTIONS = 40000,
+
+	/** Device options for a particular device. */
+	SR_CONF_DEVICE_OPTIONS,
+
 	/** Session filename. */
-	SR_CONF_SESSIONFILE = 40000,
+	SR_CONF_SESSIONFILE,
 
-	/* TODO: Better description. */
 	/** The device supports specifying a capturefile to inject. */
 	SR_CONF_CAPTUREFILE,
 
-	/* TODO: Better description. */
 	/** The device supports specifying the capturefile unit size. */
 	SR_CONF_CAPTURE_UNITSIZE,
 
-	/* TODO: Better description. */
 	/** The device supports setting the number of probes. */
 	SR_CONF_CAPTURE_NUM_PROBES,
 
@@ -540,39 +715,6 @@ enum {
 	SR_ST_STOPPING,
 };
 
-/*
- * TODO: This sucks, you just kinda have to "know" the returned type.
- * TODO: Need a DI to return the number of trigger stages supported.
- */
-
-/** Device info IDs. */
-enum {
-	/** A list of options supported by the driver. */
-	SR_DI_HWOPTS = 10000,
-	/** A list of capabilities supported by the device. */
-	SR_DI_HWCAPS,
-	/** Samplerates supported by this device (struct sr_samplerates). */
-	SR_DI_SAMPLERATES,
-	/** Types of logic trigger supported, out of "01crf" (char *). */
-	SR_DI_TRIGGER_TYPES,
-	/** The currently set samplerate in Hz (uint64_t). */
-	SR_DI_CUR_SAMPLERATE,
-	/** Supported patterns (in pattern generator mode). */
-	SR_DI_PATTERNS,
-	/** Supported buffer sizes. */
-	SR_DI_BUFFERSIZES,
-	/** Supported time bases. */
-	SR_DI_TIMEBASES,
-	/** Supported trigger sources. */
-	SR_DI_TRIGGER_SOURCES,
-	/** Supported filter targets. */
-	SR_DI_FILTERS,
-	/** Valid volts/div values. */
-	SR_DI_VDIVS,
-	/** Coupling options. */
-	SR_DI_COUPLING,
-};
-
 /*
  * A device supports either a range of samplerates with steps of a given
  * granularity, or is limited to a set of defined samplerates. Use either
@@ -595,14 +737,16 @@ struct sr_dev_driver {
 	GSList *(*scan) (GSList *options);
 	GSList *(*dev_list) (void);
 	int (*dev_clear) (void);
+	int (*config_get) (int id, const void **value,
+			const struct sr_dev_inst *sdi);
+	int (*config_set) (int id, const void *value,
+			const struct sr_dev_inst *sdi);
+	int (*config_list) (int info_id, const void **data,
+			const struct sr_dev_inst *sdi);
 
 	/* Device-specific */
 	int (*dev_open) (struct sr_dev_inst *sdi);
 	int (*dev_close) (struct sr_dev_inst *sdi);
-	int (*info_get) (int info_id, const void **data,
-			const struct sr_dev_inst *sdi);
-	int (*dev_config_set) (const struct sr_dev_inst *sdi, int hwcap,
-			const void *value);
 	int (*dev_acquisition_start) (const struct sr_dev_inst *sdi,
 			void *cb_data);
 	int (*dev_acquisition_stop) (struct sr_dev_inst *sdi,