2 * This file is part of the libsigrok project.
4 * Copyright (C) 2014 Bert Vermeulen <bert@biot.com>
6 * This program is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <http://www.gnu.org/licenses/>.
22 #include <libsigrok/libsigrok.h>
23 #include "libsigrok-internal.h"
26 #define LOG_PREFIX "output"
32 * Output module handling.
36 * @defgroup grp_output Output modules
38 * Output module handling.
40 * libsigrok supports several output modules for file formats such as binary,
41 * VCD, csv, and so on. It provides an output API that frontends can use.
42 * New output modules can be added/implemented in libsigrok without having
43 * to change the frontends at all.
45 * All output modules are fed data in a stream. Devices that can stream data
46 * into libsigrok, instead of storing and then transferring the whole buffer,
47 * can thus generate output live.
49 * Output modules generate a newly allocated GString. The caller is then
50 * expected to free this with g_string_free() when finished with it.
56 extern SR_PRIV struct sr_output_module output_bits;
57 extern SR_PRIV struct sr_output_module output_hex;
58 extern SR_PRIV struct sr_output_module output_ascii;
59 extern SR_PRIV struct sr_output_module output_binary;
60 extern SR_PRIV struct sr_output_module output_vcd;
61 extern SR_PRIV struct sr_output_module output_ols;
62 extern SR_PRIV struct sr_output_module output_chronovu_la8;
63 extern SR_PRIV struct sr_output_module output_csv;
64 extern SR_PRIV struct sr_output_module output_analog;
65 extern SR_PRIV struct sr_output_module output_srzip;
66 extern SR_PRIV struct sr_output_module output_wav;
67 extern SR_PRIV struct sr_output_module output_wavedrom;
68 extern SR_PRIV struct sr_output_module output_null;
71 static const struct sr_output_module *output_module_list[] = {
89 * Returns a NULL-terminated list of all available output modules.
93 SR_API const struct sr_output_module **sr_output_list(void)
95 return output_module_list;
99 * Returns the specified output module's ID.
103 SR_API const char *sr_output_id_get(const struct sr_output_module *omod)
106 sr_err("Invalid output module NULL!");
114 * Returns the specified output module's name.
118 SR_API const char *sr_output_name_get(const struct sr_output_module *omod)
121 sr_err("Invalid output module NULL!");
129 * Returns the specified output module's description.
133 SR_API const char *sr_output_description_get(const struct sr_output_module *omod)
136 sr_err("Invalid output module NULL!");
144 * Returns the specified output module's file extensions typical for the file
145 * format, as a NULL terminated array, or returns a NULL pointer if there is
146 * no preferred extension.
147 * @note these are a suggestions only.
151 SR_API const char *const *sr_output_extensions_get(
152 const struct sr_output_module *omod)
155 sr_err("Invalid output module NULL!");
163 * Checks whether a given flag is set.
165 * @see sr_output_flag
168 SR_API gboolean sr_output_test_flag(const struct sr_output_module *omod,
171 return (flag & omod->flags);
175 * Return the output module with the specified ID, or NULL if no module
176 * with that id is found.
180 SR_API const struct sr_output_module *sr_output_find(char *id)
184 for (i = 0; output_module_list[i]; i++) {
185 if (!strcmp(output_module_list[i]->id, id))
186 return output_module_list[i];
193 * Returns a NULL-terminated array of struct sr_option, or NULL if the
194 * module takes no options.
196 * Each call to this function must be followed by a call to
197 * sr_output_options_free().
201 SR_API const struct sr_option **sr_output_options_get(const struct sr_output_module *omod)
203 const struct sr_option *mod_opts, **opts;
206 if (!omod || !omod->options)
209 mod_opts = omod->options();
211 for (size = 0; mod_opts[size].id; size++)
213 opts = g_malloc((size + 1) * sizeof(struct sr_option *));
215 for (i = 0; i < size; i++)
216 opts[i] = &mod_opts[i];
223 * After a call to sr_output_options_get(), this function cleans up all
224 * resources returned by that call.
228 SR_API void sr_output_options_free(const struct sr_option **options)
235 for (i = 0; options[i]; i++) {
236 if (options[i]->def) {
237 g_variant_unref(options[i]->def);
238 ((struct sr_option *)options[i])->def = NULL;
241 if (options[i]->values) {
242 g_slist_free_full(options[i]->values, (GDestroyNotify)g_variant_unref);
243 ((struct sr_option *)options[i])->values = NULL;
250 * Create a new output instance using the specified output module.
252 * <code>options</code> is a *HashTable with the keys corresponding with
253 * the module options' <code>id</code> field. The values should be GVariant
254 * pointers with sunk * references, of the same GVariantType as the option's
257 * The sr_dev_inst passed in can be used by the instance to determine
258 * channel names, samplerate, and so on.
262 SR_API const struct sr_output *sr_output_new(const struct sr_output_module *omod,
263 GHashTable *options, const struct sr_dev_inst *sdi,
264 const char *filename)
266 struct sr_output *op;
267 const struct sr_option *mod_opts;
268 const GVariantType *gvt;
269 GHashTable *new_opts;
274 op = g_malloc(sizeof(struct sr_output));
277 op->filename = g_strdup(filename);
279 new_opts = g_hash_table_new_full(g_str_hash, g_str_equal, g_free,
280 (GDestroyNotify)g_variant_unref);
282 mod_opts = omod->options();
283 for (i = 0; mod_opts[i].id; i++) {
284 if (options && g_hash_table_lookup_extended(options,
285 mod_opts[i].id, &key, &value)) {
286 /* Pass option along. */
287 gvt = g_variant_get_type(mod_opts[i].def);
288 if (!g_variant_is_of_type(value, gvt)) {
289 sr_err("Invalid type for '%s' option.",
294 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
295 g_variant_ref(value));
297 /* Option not given: insert the default value. */
298 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
299 g_variant_ref(mod_opts[i].def));
303 /* Make sure no invalid options were given. */
305 g_hash_table_iter_init(&iter, options);
306 while (g_hash_table_iter_next(&iter, &key, &value)) {
307 if (!g_hash_table_lookup(new_opts, key)) {
308 sr_err("Output module '%s' has no option '%s'",
309 omod->id, (char *)key);
310 g_hash_table_destroy(new_opts);
318 if (op->module->init && op->module->init(op, new_opts) != SR_OK) {
323 g_hash_table_destroy(new_opts);
329 * Send a packet to the specified output instance.
331 * The instance's output is returned as a newly allocated GString,
332 * which must be freed by the caller.
336 SR_API int sr_output_send(const struct sr_output *o,
337 const struct sr_datafeed_packet *packet, GString **out)
339 return o->module->receive(o, packet, out);
343 * Free the specified output instance and all associated resources.
347 SR_API int sr_output_free(const struct sr_output *o)
355 if (o->module->cleanup)
356 ret = o->module->cleanup((struct sr_output *)o);
357 g_free((char *)o->filename);