src/output/output.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2010-2012 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_wav;
  64 /* @endcond */
  65
  66 static const struct sr_output_module *output_module_list[] = {
  67         &output_ascii,
  68         &output_binary,
  69         &output_bits,
  70         &output_csv,
  71         &output_gnuplot,
  72         &output_hex,
  73         &output_ols,
  74         &output_vcd,
  75         &output_chronovu_la8,
  76         &output_analog,
  77         &output_wav,
  78         NULL,
  79 };
  80
  81 /**
  82  * Returns a NULL-terminated list of all the available output modules.
  83  *
  84  * @since 0.4.0
  85  */
  86 SR_API const struct sr_output_module **sr_output_list(void)
  87 {
  88         return output_module_list;
  89 }
  90
  91 /**
  92  * Returns the specified output module's ID.
  93  *
  94  * @since 0.4.0
  95  */
  96 SR_API const char *sr_output_id_get(const struct sr_output_module *o)
  97 {
  98         if (!o) {
  99                 sr_err("Invalid output module NULL!");
 100                 return NULL;
 101         }
 102
 103         return o->id;
 104 }
 105
 106 /**
 107  * Returns the specified output module's name.
 108  *
 109  * @since 0.4.0
 110  */
 111 SR_API const char *sr_output_name_get(const struct sr_output_module *o)
 112 {
 113         if (!o) {
 114                 sr_err("Invalid output module NULL!");
 115                 return NULL;
 116         }
 117
 118         return o->name;
 119 }
 120
 121 /**
 122  * Returns the specified output module's description.
 123  *
 124  * @since 0.4.0
 125  */
 126 SR_API const char *sr_output_description_get(const struct sr_output_module *o)
 127 {
 128         if (!o) {
 129                 sr_err("Invalid output module NULL!");
 130                 return NULL;
 131         }
 132
 133         return o->desc;
 134 }
 135
 136 /**
 137  * Return the output module with the specified ID, or NULL if no module
 138  * with that id is found.
 139  *
 140  * @since 0.4.0
 141  */
 142 SR_API const struct sr_output_module *sr_output_find(char *id)
 143 {
 144         int i;
 145
 146         for (i = 0; output_module_list[i]; i++) {
 147                 if (!strcmp(output_module_list[i]->id, id))
 148                         return output_module_list[i];
 149         }
 150
 151         return NULL;
 152 }
 153
 154 /**
 155  * Returns a NULL-terminated array of struct sr_option, or NULL if the
 156  * module takes no options.
 157  *
 158  * Each call to this function must be followed by a call to
 159  * sr_output_options_free().
 160  *
 161  * @since 0.4.0
 162  */
 163 SR_API const struct sr_option *sr_output_options_get(const struct sr_output_module *o)
 164 {
 165
 166         if (!o || !o->options)
 167                 return NULL;
 168
 169         return o->options();
 170 }
 171
 172 /**
 173  * After a call to sr_output_options_get(), this function cleans up all
 174  * the resources allocated by that call.
 175  *
 176  * @since 0.4.0
 177  */
 178 SR_API void sr_output_options_free(const struct sr_output_module *o)
 179 {
 180         struct sr_option *opt;
 181
 182         if (!o || !o->options)
 183                 return;
 184
 185         for (opt = o->options(); opt->id; opt++) {
 186                 if (opt->def) {
 187                         g_variant_unref(opt->def);
 188                         opt->def = NULL;
 189                 }
 190
 191                 if (opt->values) {
 192                         g_slist_free_full(opt->values, (GDestroyNotify)g_variant_unref);
 193                         opt->values = NULL;
 194                 }
 195         }
 196 }
 197
 198 /**
 199  * Create a new output instance using the specified output module.
 200  *
 201  * <code>options</code> is a *HashTable with the keys corresponding with
 202  * the module options' <code>id</code> field. The values should be GVariant
 203  * pointers with sunk * references, of the same GVariantType as the option's
 204  * default value.
 205  *
 206  * The sr_dev_inst passed in can be used by the instance to determine
 207  * channel names, samplerate, and so on.
 208  *
 209  * @since 0.4.0
 210  */
 211 SR_API const struct sr_output *sr_output_new(const struct sr_output_module *o,
 212                 GHashTable *options, const struct sr_dev_inst *sdi)
 213 {
 214         struct sr_output *op;
 215         struct sr_option *mod_opts;
 216         const GVariantType *gvt;
 217         GHashTable *new_opts;
 218         GHashTableIter iter;
 219         gpointer key, value;
 220         int i;
 221
 222         op = g_malloc(sizeof(struct sr_output));
 223         op->module = o;
 224         op->sdi = sdi;
 225
 226         if (options) {
 227                 new_opts = g_hash_table_new_full(g_str_hash, g_str_equal, g_free,
 228                                 (GDestroyNotify)g_variant_unref);
 229                 mod_opts = o->options();
 230                 for (i = 0; mod_opts[i].id; i++) {
 231                         if (g_hash_table_lookup_extended(options, mod_opts[i].id,
 232                                         &key, &value)) {
 233                                 /* Option not given: insert the default value. */
 234                                 gvt = g_variant_get_type(mod_opts[i].def);
 235                                 if (!g_variant_is_of_type(value, gvt)) {
 236                                         sr_err("Invalid type for '%s' option.", key);
 237                                         g_free(op);
 238                                         return NULL;
 239                                 }
 240                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 241                                                 g_variant_ref(value));
 242                         } else {
 243                                 /* Pass option along. */
 244                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 245                                                 g_variant_ref(mod_opts[i].def));
 246                         }
 247                 }
 248
 249                 /* Make sure no invalid options were given. */
 250                 g_hash_table_iter_init(&iter, options);
 251                 while (g_hash_table_iter_next(&iter, &key, &value)) {
 252                         if (!g_hash_table_lookup(new_opts, key)) {
 253                                 sr_err("Output module '%s' has no option '%s'", o->id, key);
 254                                 g_hash_table_destroy(new_opts);
 255                                 g_free(op);
 256                                 return NULL;
 257                         }
 258                 }
 259         } else
 260                 new_opts = NULL;
 261
 262         if (op->module->init && op->module->init(op, new_opts) != SR_OK) {
 263                 g_hash_table_destroy(new_opts);
 264                 g_free(op);
 265                 op = NULL;
 266         }
 267         g_hash_table_destroy(new_opts);
 268
 269         return op;
 270 }
 271
 272 /**
 273  * Send a packet to the specified output instance.
 274  *
 275  * The instance's output is returned as a newly allocated GString,
 276  * which must be freed by the caller.
 277  *
 278  * @since 0.4.0
 279  */
 280 SR_API int sr_output_send(const struct sr_output *o,
 281                 const struct sr_datafeed_packet *packet, GString **out)
 282 {
 283         return o->module->receive(o, packet, out);
 284 }
 285
 286 /**
 287  * Free the specified output instance and all associated resources.
 288  *
 289  * @since 0.4.0
 290  */
 291 SR_API int sr_output_free(const struct sr_output *o)
 292 {
 293         int ret;
 294
 295         if (!o)
 296                 return SR_ERR_ARG;
 297
 298         ret = SR_OK;
 299         if (o->module->cleanup)
 300                 ret = o->module->cleanup((struct sr_output *)o);
 301         g_free((gpointer)o);
 302
 303         return ret;
 304 }
 305
 306 /** @} */