doxygen: Add more output format docs.

This is largely taken from the respective wiki page (with some updates
and improvements), which will be removed in favor of the doxygen docs.

diff --git a/libsigrok.h b/libsigrok.h
index 4601f60be40ba5b4527fa6726ea290a3293961c2..bf0b8b295812bfdcd06ea4245274bd33853c5e96 100644 (file)
--- a/libsigrok.h
+++ b/libsigrok.h
@@ -368,27 +368,141 @@ struct sr_input_format {
        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);
 };
 

diff --git a/output/output.c b/output/output.c
index 91fdf3884d52c0e134a86526cf51d962c5c82226..39dfc7dd926262d853bfd4579b4c818224d85867 100644 (file)
--- a/output/output.c
+++ b/output/output.c
@@ -31,6 +31,20 @@
  *
  * Output file/data format handling.
  *
+ * libsigrok supports several output (file) formats, e.g. binary, VCD,
+ * gnuplot, and so on. It provides an output API that frontends can use.
+ * New output formats can be added/implemented in libsigrok without having
+ * to change the frontends at all.
+ *
+ * All output modules are fed data in a stream. Devices that can stream data
+ * into libsigrok live, instead of storing and then transferring the whole
+ * buffer, can thus generate output live.
+ *
+ * Output modules are responsible for allocating enough memory to store
+ * their own output, and passing a pointer to that memory (and length) of
+ * the allocated memory back to the caller. The caller is then expected to
+ * free this memory when finished with it.
+ *
  * @{
  */