From: Uwe Hermann Date: Fri, 22 Feb 2013 14:12:32 +0000 (+0100) Subject: doxygen: Add more output format docs. X-Git-Tag: dsupstream~261 X-Git-Url: https://sigrok.org/gitweb/?p=libsigrok.git;a=commitdiff_plain;h=07e1aad5c4d53ee1028613312061f261f1a7800a 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 4601f60b..bf0b8b29 100644 --- 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 -O hex 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 internal 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 data_in and + * length_in 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 data_out + * parameter, as well as storing the length of the buffer in + * length_out. 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 + * data_out 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 data_out and length_out + * 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 91fdf388..39dfc7dd 100644 --- 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. + * * @{ */