src/output/output.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2014 Bert Vermeulen <bert@biot.com>
   5  *
   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.
  10  *
  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.
  15  *
  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/>.
  18  */
  19
  20 #include <config.h>
  21 #include <string.h>
  22 #include <libsigrok/libsigrok.h>
  23 #include "libsigrok-internal.h"
  24
  25 /** @cond PRIVATE */
  26 #define LOG_PREFIX "output"
  27 /** @endcond */
  28
  29 /**
  30  * @file
  31  *
  32  * Output module handling.
  33  */
  34
  35 /**
  36  * @defgroup grp_output Output modules
  37  *
  38  * Output module handling.
  39  *
  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.
  44  *
  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.
  48  *
  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.
  51  *
  52  * @{
  53  */
  54
  55 /** @cond PRIVATE */
  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;
  69 /** @endcond */
  70
  71 static const struct sr_output_module *output_module_list[] = {
  72         &output_ascii,
  73         &output_binary,
  74         &output_bits,
  75         &output_csv,
  76         &output_hex,
  77         &output_ols,
  78         &output_vcd,
  79         &output_chronovu_la8,
  80         &output_analog,
  81         &output_srzip,
  82         &output_wav,
  83         &output_wavedrom,
  84         &output_null,
  85         NULL,
  86 };
  87
  88 /**
  89  * Returns a NULL-terminated list of all available output modules.
  90  *
  91  * @since 0.4.0
  92  */
  93 SR_API const struct sr_output_module **sr_output_list(void)
  94 {
  95         return output_module_list;
  96 }
  97
  98 /**
  99  * Returns the specified output module's ID.
 100  *
 101  * @since 0.4.0
 102  */
 103 SR_API const char *sr_output_id_get(const struct sr_output_module *omod)
 104 {
 105         if (!omod) {
 106                 sr_err("Invalid output module NULL!");
 107                 return NULL;
 108         }
 109
 110         return omod->id;
 111 }
 112
 113 /**
 114  * Returns the specified output module's name.
 115  *
 116  * @since 0.4.0
 117  */
 118 SR_API const char *sr_output_name_get(const struct sr_output_module *omod)
 119 {
 120         if (!omod) {
 121                 sr_err("Invalid output module NULL!");
 122                 return NULL;
 123         }
 124
 125         return omod->name;
 126 }
 127
 128 /**
 129  * Returns the specified output module's description.
 130  *
 131  * @since 0.4.0
 132  */
 133 SR_API const char *sr_output_description_get(const struct sr_output_module *omod)
 134 {
 135         if (!omod) {
 136                 sr_err("Invalid output module NULL!");
 137                 return NULL;
 138         }
 139
 140         return omod->desc;
 141 }
 142
 143 /**
 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.
 148  *
 149  * @since 0.4.0
 150  */
 151 SR_API const char *const *sr_output_extensions_get(
 152                 const struct sr_output_module *omod)
 153 {
 154         if (!omod) {
 155                 sr_err("Invalid output module NULL!");
 156                 return NULL;
 157         }
 158
 159         return omod->exts;
 160 }
 161
 162 /*
 163  * Checks whether a given flag is set.
 164  *
 165  * @see sr_output_flag
 166  * @since 0.4.0
 167  */
 168 SR_API gboolean sr_output_test_flag(const struct sr_output_module *omod,
 169                 uint64_t flag)
 170 {
 171         return (flag & omod->flags);
 172 }
 173
 174 /**
 175  * Return the output module with the specified ID, or NULL if no module
 176  * with that id is found.
 177  *
 178  * @since 0.4.0
 179  */
 180 SR_API const struct sr_output_module *sr_output_find(char *id)
 181 {
 182         int i;
 183
 184         for (i = 0; output_module_list[i]; i++) {
 185                 if (!strcmp(output_module_list[i]->id, id))
 186                         return output_module_list[i];
 187         }
 188
 189         return NULL;
 190 }
 191
 192 /**
 193  * Returns a NULL-terminated array of struct sr_option, or NULL if the
 194  * module takes no options.
 195  *
 196  * Each call to this function must be followed by a call to
 197  * sr_output_options_free().
 198  *
 199  * @since 0.4.0
 200  */
 201 SR_API const struct sr_option **sr_output_options_get(const struct sr_output_module *omod)
 202 {
 203         const struct sr_option *mod_opts, **opts;
 204         int size, i;
 205
 206         if (!omod || !omod->options)
 207                 return NULL;
 208
 209         mod_opts = omod->options();
 210
 211         for (size = 0; mod_opts[size].id; size++)
 212                 ;
 213         opts = g_malloc((size + 1) * sizeof(struct sr_option *));
 214
 215         for (i = 0; i < size; i++)
 216                 opts[i] = &mod_opts[i];
 217         opts[i] = NULL;
 218
 219         return opts;
 220 }
 221
 222 /**
 223  * After a call to sr_output_options_get(), this function cleans up all
 224  * resources returned by that call.
 225  *
 226  * @since 0.4.0
 227  */
 228 SR_API void sr_output_options_free(const struct sr_option **options)
 229 {
 230         int i;
 231
 232         if (!options)
 233                 return;
 234
 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;
 239                 }
 240
 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;
 244                 }
 245         }
 246         g_free(options);
 247 }
 248
 249 /**
 250  * Create a new output instance using the specified output module.
 251  *
 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
 255  * default value.
 256  *
 257  * The sr_dev_inst passed in can be used by the instance to determine
 258  * channel names, samplerate, and so on.
 259  *
 260  * @since 0.4.0
 261  */
 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)
 265 {
 266         struct sr_output *op;
 267         const struct sr_option *mod_opts;
 268         const GVariantType *gvt;
 269         GHashTable *new_opts;
 270         GHashTableIter iter;
 271         gpointer key, value;
 272         int i;
 273
 274         op = g_malloc(sizeof(struct sr_output));
 275         op->module = omod;
 276         op->sdi = sdi;
 277         op->filename = g_strdup(filename);
 278
 279         new_opts = g_hash_table_new_full(g_str_hash, g_str_equal, g_free,
 280                         (GDestroyNotify)g_variant_unref);
 281         if (omod->options) {
 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.",
 290                                                 (char *)key);
 291                                         g_free(op);
 292                                         return NULL;
 293                                 }
 294                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 295                                                 g_variant_ref(value));
 296                         } else {
 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));
 300                         }
 301                 }
 302
 303                 /* Make sure no invalid options were given. */
 304                 if (options) {
 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);
 311                                         g_free(op);
 312                                         return NULL;
 313                                 }
 314                         }
 315                 }
 316         }
 317
 318         if (op->module->init && op->module->init(op, new_opts) != SR_OK) {
 319                 g_free(op);
 320                 op = NULL;
 321         }
 322         if (new_opts)
 323                 g_hash_table_destroy(new_opts);
 324
 325         return op;
 326 }
 327
 328 /**
 329  * Send a packet to the specified output instance.
 330  *
 331  * The instance's output is returned as a newly allocated GString,
 332  * which must be freed by the caller.
 333  *
 334  * @since 0.4.0
 335  */
 336 SR_API int sr_output_send(const struct sr_output *o,
 337                 const struct sr_datafeed_packet *packet, GString **out)
 338 {
 339         return o->module->receive(o, packet, out);
 340 }
 341
 342 /**
 343  * Free the specified output instance and all associated resources.
 344  *
 345  * @since 0.4.0
 346  */
 347 SR_API int sr_output_free(const struct sr_output *o)
 348 {
 349         int ret;
 350
 351         if (!o)
 352                 return SR_ERR_ARG;
 353
 354         ret = SR_OK;
 355         if (o->module->cleanup)
 356                 ret = o->module->cleanup((struct sr_output *)o);
 357         g_free((char *)o->filename);
 358         g_free((gpointer)o);
 359
 360         return ret;
 361 }
 362
 363 /** @} */