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