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 <string.h>
  21 #include "libsigrok.h"
  22 #include "libsigrok-internal.h"
  23
  24 #define LOG_PREFIX "output"
  25
  26 /**
  27  * @file
  28  *
  29  * Output module handling.
  30  */
  31
  32 /**
  33  * @defgroup grp_output Output modules
  34  *
  35  * Output module handling.
  36  *
  37  * libsigrok supports several output modules for file formats such as binary,
  38  * VCD, gnuplot, and so on. It provides an output API that frontends can use.
  39  * New output modules can be added/implemented in libsigrok without having
  40  * to change the frontends at all.
  41  *
  42  * All output modules are fed data in a stream. Devices that can stream data
  43  * into libsigrok, instead of storing and then transferring the whole buffer,
  44  * can thus generate output live.
  45  *
  46  * Output modules generate a newly allocated GString. The caller is then
  47  * expected to free this with g_string_free() when finished with it.
  48  *
  49  * @{
  50  */
  51
  52 /** @cond PRIVATE */
  53 extern SR_PRIV struct sr_output_module output_bits;
  54 extern SR_PRIV struct sr_output_module output_hex;
  55 extern SR_PRIV struct sr_output_module output_ascii;
  56 extern SR_PRIV struct sr_output_module output_binary;
  57 extern SR_PRIV struct sr_output_module output_vcd;
  58 extern SR_PRIV struct sr_output_module output_ols;
  59 extern SR_PRIV struct sr_output_module output_gnuplot;
  60 extern SR_PRIV struct sr_output_module output_chronovu_la8;
  61 extern SR_PRIV struct sr_output_module output_csv;
  62 extern SR_PRIV struct sr_output_module output_analog;
  63 extern SR_PRIV struct sr_output_module output_srzip;
  64 extern SR_PRIV struct sr_output_module output_wav;
  65 /* @endcond */
  66
  67 static const struct sr_output_module *output_module_list[] = {
  68         &output_ascii,
  69         &output_binary,
  70         &output_bits,
  71         &output_csv,
  72         &output_gnuplot,
  73         &output_hex,
  74         &output_ols,
  75         &output_vcd,
  76         &output_chronovu_la8,
  77         &output_analog,
  78         &output_srzip,
  79         &output_wav,
  80         NULL,
  81 };
  82
  83 /**
  84  * Returns a NULL-terminated list of all available output modules.
  85  *
  86  * @since 0.4.0
  87  */
  88 SR_API const struct sr_output_module **sr_output_list(void)
  89 {
  90         return output_module_list;
  91 }
  92
  93 /**
  94  * Returns the specified output module's ID.
  95  *
  96  * @since 0.4.0
  97  */
  98 SR_API const char *sr_output_id_get(const struct sr_output_module *omod)
  99 {
 100         if (!omod) {
 101                 sr_err("Invalid output module NULL!");
 102                 return NULL;
 103         }
 104
 105         return omod->id;
 106 }
 107
 108 /**
 109  * Returns the specified output module's name.
 110  *
 111  * @since 0.4.0
 112  */
 113 SR_API const char *sr_output_name_get(const struct sr_output_module *omod)
 114 {
 115         if (!omod) {
 116                 sr_err("Invalid output module NULL!");
 117                 return NULL;
 118         }
 119
 120         return omod->name;
 121 }
 122
 123 /**
 124  * Returns the specified output module's description.
 125  *
 126  * @since 0.4.0
 127  */
 128 SR_API const char *sr_output_description_get(const struct sr_output_module *omod)
 129 {
 130         if (!omod) {
 131                 sr_err("Invalid output module NULL!");
 132                 return NULL;
 133         }
 134
 135         return omod->desc;
 136 }
 137
 138 /**
 139  * Returns the specified output module's file extensions typical for the file
 140  * format, as a NULL terminated array, or returns a NULL pointer if there is
 141  * no preferred extension.
 142  * @note these are a suggestions only.
 143  *
 144  * @since 0.4.0
 145  */
 146 SR_API const char *const *sr_output_extensions_get(
 147                 const struct sr_output_module *omod)
 148 {
 149         if (!omod) {
 150                 sr_err("Invalid output module NULL!");
 151                 return NULL;
 152         }
 153
 154         return omod->exts;
 155 }
 156
 157 /**
 158  * Return the output module with the specified ID, or NULL if no module
 159  * with that id is found.
 160  *
 161  * @since 0.4.0
 162  */
 163 SR_API const struct sr_output_module *sr_output_find(char *id)
 164 {
 165         int i;
 166
 167         for (i = 0; output_module_list[i]; i++) {
 168                 if (!strcmp(output_module_list[i]->id, id))
 169                         return output_module_list[i];
 170         }
 171
 172         return NULL;
 173 }
 174
 175 /**
 176  * Returns a NULL-terminated array of struct sr_option, or NULL if the
 177  * module takes no options.
 178  *
 179  * Each call to this function must be followed by a call to
 180  * sr_output_options_free().
 181  *
 182  * @since 0.4.0
 183  */
 184 SR_API const struct sr_option **sr_output_options_get(const struct sr_output_module *omod)
 185 {
 186         const struct sr_option *mod_opts, **opts;
 187         int size, i;
 188
 189         if (!omod || !omod->options)
 190                 return NULL;
 191
 192         mod_opts = omod->options();
 193
 194         for (size = 0; mod_opts[size].id; size++)
 195                 ;
 196         opts = g_malloc((size + 1) * sizeof(struct sr_option *));
 197
 198         for (i = 0; i < size; i++)
 199                 opts[i] = &mod_opts[i];
 200         opts[i] = NULL;
 201
 202         return opts;
 203 }
 204
 205 /**
 206  * After a call to sr_output_options_get(), this function cleans up all
 207  * resources returned by that call.
 208  *
 209  * @since 0.4.0
 210  */
 211 SR_API void sr_output_options_free(const struct sr_option **options)
 212 {
 213         int i;
 214
 215         if (!options)
 216                 return;
 217
 218         for (i = 0; options[i]; i++) {
 219                 if (options[i]->def) {
 220                         g_variant_unref(options[i]->def);
 221                         ((struct sr_option *)options[i])->def = NULL;
 222                 }
 223
 224                 if (options[i]->values) {
 225                         g_slist_free_full(options[i]->values, (GDestroyNotify)g_variant_unref);
 226                         ((struct sr_option *)options[i])->values = NULL;
 227                 }
 228         }
 229         g_free(options);
 230 }
 231
 232 /**
 233  * Create a new output instance using the specified output module.
 234  *
 235  * <code>options</code> is a *HashTable with the keys corresponding with
 236  * the module options' <code>id</code> field. The values should be GVariant
 237  * pointers with sunk * references, of the same GVariantType as the option's
 238  * default value.
 239  *
 240  * The sr_dev_inst passed in can be used by the instance to determine
 241  * channel names, samplerate, and so on.
 242  *
 243  * @since 0.4.0
 244  */
 245 SR_API const struct sr_output *sr_output_new(const struct sr_output_module *omod,
 246                 GHashTable *options, const struct sr_dev_inst *sdi)
 247 {
 248         struct sr_output *op;
 249         const struct sr_option *mod_opts;
 250         const GVariantType *gvt;
 251         GHashTable *new_opts;
 252         GHashTableIter iter;
 253         gpointer key, value;
 254         int i;
 255
 256         op = g_malloc(sizeof(struct sr_output));
 257         op->module = omod;
 258         op->sdi = sdi;
 259
 260         new_opts = g_hash_table_new_full(g_str_hash, g_str_equal, g_free,
 261                         (GDestroyNotify)g_variant_unref);
 262         if (omod->options) {
 263                 mod_opts = omod->options();
 264                 for (i = 0; mod_opts[i].id; i++) {
 265                         if (options && g_hash_table_lookup_extended(options,
 266                                         mod_opts[i].id, &key, &value)) {
 267                                 /* Pass option along. */
 268                                 gvt = g_variant_get_type(mod_opts[i].def);
 269                                 if (!g_variant_is_of_type(value, gvt)) {
 270                                         sr_err("Invalid type for '%s' option.", key);
 271                                         g_free(op);
 272                                         return NULL;
 273                                 }
 274                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 275                                                 g_variant_ref(value));
 276                         } else {
 277                                 /* Option not given: insert the default value. */
 278                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 279                                                 g_variant_ref(mod_opts[i].def));
 280                         }
 281                 }
 282
 283                 /* Make sure no invalid options were given. */
 284                 if (options) {
 285                         g_hash_table_iter_init(&iter, options);
 286                         while (g_hash_table_iter_next(&iter, &key, &value)) {
 287                                 if (!g_hash_table_lookup(new_opts, key)) {
 288                                         sr_err("Output module '%s' has no option '%s'", omod->id, key);
 289                                         g_hash_table_destroy(new_opts);
 290                                         g_free(op);
 291                                         return NULL;
 292                                 }
 293                         }
 294                 }
 295         }
 296
 297         if (op->module->init && op->module->init(op, new_opts) != SR_OK) {
 298                 g_free(op);
 299                 op = NULL;
 300         }
 301         if (new_opts)
 302                 g_hash_table_destroy(new_opts);
 303
 304         return op;
 305 }
 306
 307 /**
 308  * Send a packet to the specified output instance.
 309  *
 310  * The instance's output is returned as a newly allocated GString,
 311  * which must be freed by the caller.
 312  *
 313  * @since 0.4.0
 314  */
 315 SR_API int sr_output_send(const struct sr_output *o,
 316                 const struct sr_datafeed_packet *packet, GString **out)
 317 {
 318         return o->module->receive(o, packet, out);
 319 }
 320
 321 /**
 322  * Free the specified output instance and all associated resources.
 323  *
 324  * @since 0.4.0
 325  */
 326 SR_API int sr_output_free(const struct sr_output *o)
 327 {
 328         int ret;
 329
 330         if (!o)
 331                 return SR_ERR_ARG;
 332
 333         ret = SR_OK;
 334         if (o->module->cleanup)
 335                 ret = o->module->cleanup((struct sr_output *)o);
 336         g_free((gpointer)o);
 337
 338         return ret;
 339 }
 340
 341 /** @} */