src/input/input.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 <errno.h>
  23 #include <glib.h>
  24 #include <glib/gstdio.h>
  25 #include <libsigrok/libsigrok.h>
  26 #include "libsigrok-internal.h"
  27
  28 /** @cond PRIVATE */
  29 #define LOG_PREFIX "input"
  30 /** @endcond */
  31
  32 /** @cond PRIVATE */
  33 #define CHUNK_SIZE      (4 * 1024 * 1024)
  34 /** @endcond */
  35
  36 /**
  37  * @file
  38  *
  39  * Input module handling.
  40  */
  41
  42 /**
  43  * @defgroup grp_input Input modules
  44  *
  45  * Input file/data module handling.
  46  *
  47  * libsigrok can process acquisition data in several different ways.
  48  * Aside from acquiring data from a hardware device, it can also take it
  49  * from a file in various formats (binary, CSV, VCD, and so on).
  50  *
  51  * Like all libsigrok data handling, processing is done in a streaming
  52  * manner: input should be supplied a chunk at a time. This way anything
  53  * that processes data can do so in real time, without the user having
  54  * to wait for the whole thing to be finished.
  55  *
  56  * Every input module is "pluggable", meaning it's handled as being separate
  57  * from the main libsigrok, but linked in to it statically. To keep things
  58  * modular and separate like this, functions within an input module should be
  59  * declared static, with only the respective 'struct sr_input_module' being
  60  * exported for use into the wider libsigrok namespace.
  61  *
  62  * @{
  63  */
  64
  65 /** @cond PRIVATE */
  66 extern SR_PRIV struct sr_input_module input_chronovu_la8;
  67 extern SR_PRIV struct sr_input_module input_csv;
  68 extern SR_PRIV struct sr_input_module input_binary;
  69 extern SR_PRIV struct sr_input_module input_stf;
  70 extern SR_PRIV struct sr_input_module input_trace32_ad;
  71 extern SR_PRIV struct sr_input_module input_vcd;
  72 extern SR_PRIV struct sr_input_module input_wav;
  73 extern SR_PRIV struct sr_input_module input_raw_analog;
  74 extern SR_PRIV struct sr_input_module input_logicport;
  75 extern SR_PRIV struct sr_input_module input_saleae;
  76 extern SR_PRIV struct sr_input_module input_null;
  77 /** @endcond */
  78
  79 static const struct sr_input_module *input_module_list[] = {
  80         &input_binary,
  81         &input_chronovu_la8,
  82         &input_csv,
  83         &input_stf,
  84         &input_trace32_ad,
  85         &input_vcd,
  86         &input_wav,
  87         &input_raw_analog,
  88         &input_logicport,
  89         &input_saleae,
  90         &input_null,
  91         NULL,
  92 };
  93
  94 /**
  95  * Returns a NULL-terminated list of all available input modules.
  96  *
  97  * @since 0.4.0
  98  */
  99 SR_API const struct sr_input_module **sr_input_list(void)
 100 {
 101         return input_module_list;
 102 }
 103
 104 /**
 105  * Returns the specified input module's ID.
 106  *
 107  * @since 0.4.0
 108  */
 109 SR_API const char *sr_input_id_get(const struct sr_input_module *imod)
 110 {
 111         if (!imod) {
 112                 sr_err("Invalid input module NULL!");
 113                 return NULL;
 114         }
 115
 116         return imod->id;
 117 }
 118
 119 /**
 120  * Returns the specified input module's name.
 121  *
 122  * @since 0.4.0
 123  */
 124 SR_API const char *sr_input_name_get(const struct sr_input_module *imod)
 125 {
 126         if (!imod) {
 127                 sr_err("Invalid input module NULL!");
 128                 return NULL;
 129         }
 130
 131         return imod->name;
 132 }
 133
 134 /**
 135  * Returns the specified input module's description.
 136  *
 137  * @since 0.4.0
 138  */
 139 SR_API const char *sr_input_description_get(const struct sr_input_module *imod)
 140 {
 141         if (!imod) {
 142                 sr_err("Invalid input module NULL!");
 143                 return NULL;
 144         }
 145
 146         return imod->desc;
 147 }
 148
 149 /**
 150  * Returns the specified input module's file extensions typical for the file
 151  * format, as a NULL terminated array, or returns a NULL pointer if there is
 152  * no preferred extension.
 153  * @note these are a suggestions only.
 154  *
 155  * @since 0.4.0
 156  */
 157 SR_API const char *const *sr_input_extensions_get(
 158                 const struct sr_input_module *imod)
 159 {
 160         if (!imod) {
 161                 sr_err("Invalid input module NULL!");
 162                 return NULL;
 163         }
 164
 165         return imod->exts;
 166 }
 167
 168 /**
 169  * Return the input module with the specified ID, or NULL if no module
 170  * with that id is found.
 171  *
 172  * @since 0.4.0
 173  */
 174 SR_API const struct sr_input_module *sr_input_find(char *id)
 175 {
 176         int i;
 177
 178         for (i = 0; input_module_list[i]; i++) {
 179                 if (!strcmp(input_module_list[i]->id, id))
 180                         return input_module_list[i];
 181         }
 182
 183         return NULL;
 184 }
 185
 186 /**
 187  * Returns a NULL-terminated array of struct sr_option, or NULL if the
 188  * module takes no options.
 189  *
 190  * Each call to this function must be followed by a call to
 191  * sr_input_options_free().
 192  *
 193  * @since 0.4.0
 194  */
 195 SR_API const struct sr_option **sr_input_options_get(const struct sr_input_module *imod)
 196 {
 197         const struct sr_option *mod_opts, **opts;
 198         int size, i;
 199
 200         if (!imod || !imod->options)
 201                 return NULL;
 202
 203         mod_opts = imod->options();
 204
 205         for (size = 0; mod_opts[size].id; size++)
 206                 ;
 207         opts = g_malloc((size + 1) * sizeof(struct sr_option *));
 208
 209         for (i = 0; i < size; i++)
 210                 opts[i] = &mod_opts[i];
 211         opts[i] = NULL;
 212
 213         return opts;
 214 }
 215
 216 /**
 217  * After a call to sr_input_options_get(), this function cleans up all
 218  * resources returned by that call.
 219  *
 220  * @since 0.4.0
 221  */
 222 SR_API void sr_input_options_free(const struct sr_option **options)
 223 {
 224         int i;
 225
 226         if (!options)
 227                 return;
 228
 229         for (i = 0; options[i]; i++) {
 230                 if (options[i]->def) {
 231                         g_variant_unref(options[i]->def);
 232                         ((struct sr_option *)options[i])->def = NULL;
 233                 }
 234
 235                 if (options[i]->values) {
 236                         g_slist_free_full(options[i]->values, (GDestroyNotify)g_variant_unref);
 237                         ((struct sr_option *)options[i])->values = NULL;
 238                 }
 239         }
 240         g_free(options);
 241 }
 242
 243 /**
 244  * Create a new input instance using the specified input module.
 245  *
 246  * This function is used when a client wants to use a specific input
 247  * module to parse a stream. No effort is made to identify the format.
 248  *
 249  * @param imod The input module to use. Must not be NULL.
 250  * @param options GHashTable consisting of keys corresponding with
 251  * the module options @c id field. The values should be GVariant
 252  * pointers with sunk references, of the same GVariantType as the option's
 253  * default value.
 254  *
 255  * @since 0.4.0
 256  */
 257 SR_API struct sr_input *sr_input_new(const struct sr_input_module *imod,
 258                 GHashTable *options)
 259 {
 260         struct sr_input *in;
 261         const struct sr_option *mod_opts;
 262         const GVariantType *gvt;
 263         GHashTable *new_opts;
 264         GHashTableIter iter;
 265         gpointer key, value;
 266         int i;
 267
 268         in = g_malloc0(sizeof(struct sr_input));
 269         in->module = imod;
 270
 271         new_opts = g_hash_table_new_full(g_str_hash, g_str_equal, g_free,
 272                         (GDestroyNotify)g_variant_unref);
 273         if (imod->options) {
 274                 mod_opts = imod->options();
 275                 for (i = 0; mod_opts[i].id; i++) {
 276                         if (options && g_hash_table_lookup_extended(options,
 277                                         mod_opts[i].id, &key, &value)) {
 278                                 /* Option not given: insert the default value. */
 279                                 gvt = g_variant_get_type(mod_opts[i].def);
 280                                 if (!g_variant_is_of_type(value, gvt)) {
 281                                         sr_err("Invalid type for '%s' option.",
 282                                                 (char *)key);
 283                                         g_free(in);
 284                                         return NULL;
 285                                 }
 286                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 287                                                 g_variant_ref(value));
 288                         } else {
 289                                 /* Pass option along. */
 290                                 g_hash_table_insert(new_opts, g_strdup(mod_opts[i].id),
 291                                                 g_variant_ref(mod_opts[i].def));
 292                         }
 293                 }
 294
 295                 /* Make sure no invalid options were given. */
 296                 if (options) {
 297                         g_hash_table_iter_init(&iter, options);
 298                         while (g_hash_table_iter_next(&iter, &key, &value)) {
 299                                 if (!g_hash_table_lookup(new_opts, key)) {
 300                                         sr_err("Input module '%s' has no option '%s'",
 301                                                 imod->id, (char *)key);
 302                                         g_hash_table_destroy(new_opts);
 303                                         g_free(in);
 304                                         return NULL;
 305                                 }
 306                         }
 307                 }
 308         }
 309
 310         if (in->module->init && in->module->init(in, new_opts) != SR_OK) {
 311                 g_free(in);
 312                 in = NULL;
 313         } else {
 314                 in->buf = g_string_sized_new(128);
 315         }
 316
 317         if (new_opts)
 318                 g_hash_table_destroy(new_opts);
 319
 320         return in;
 321 }
 322
 323 /* Returns TRUE if all required meta items are available. */
 324 static gboolean check_required_metadata(const uint8_t *metadata, uint8_t *avail)
 325 {
 326         int m, a;
 327         uint8_t reqd;
 328
 329         for (m = 0; metadata[m]; m++) {
 330                 if (!(metadata[m] & SR_INPUT_META_REQUIRED))
 331                         continue;
 332                 reqd = metadata[m] & ~SR_INPUT_META_REQUIRED;
 333                 for (a = 0; avail[a]; a++) {
 334                         if (avail[a] == reqd)
 335                                 break;
 336                 }
 337                 if (!avail[a])
 338                         /* Found a required meta item that isn't available. */
 339                         return FALSE;
 340         }
 341
 342         return TRUE;
 343 }
 344
 345 /**
 346  * Try to find an input module that can parse the given buffer.
 347  *
 348  * The buffer must contain enough of the beginning of the file for
 349  * the input modules to find a match. This is format-dependent. When
 350  * magic strings get checked, 128 bytes normally could be enough. Note
 351  * that some formats try to parse larger header sections, and benefit
 352  * from seeing a larger scope.
 353  *
 354  * If an input module is found, an instance is created into *in.
 355  * Otherwise, *in contains NULL. When multiple input moduless claim
 356  * support for the format, the one with highest confidence takes
 357  * precedence. Applications will see at most one input module spec.
 358  *
 359  * If an instance is created, it has the given buffer used for scanning
 360  * already submitted to it, to be processed before more data is sent.
 361  * This allows a frontend to submit an initial chunk of a non-seekable
 362  * stream, such as stdin, without having to keep it around and submit
 363  * it again later.
 364  *
 365  */
 366 SR_API int sr_input_scan_buffer(GString *buf, const struct sr_input **in)
 367 {
 368         const struct sr_input_module *imod, *best_imod;
 369         GHashTable *meta;
 370         unsigned int m, i;
 371         unsigned int conf, best_conf;
 372         int ret;
 373         uint8_t mitem, avail_metadata[8];
 374
 375         /* No more metadata to be had from a buffer. */
 376         avail_metadata[0] = SR_INPUT_META_HEADER;
 377         avail_metadata[1] = 0;
 378
 379         *in = NULL;
 380         best_imod = NULL;
 381         best_conf = ~0;
 382         for (i = 0; input_module_list[i]; i++) {
 383                 imod = input_module_list[i];
 384                 if (!imod->metadata[0]) {
 385                         /* Module has no metadata for matching so will take
 386                          * any input. No point in letting it try to match. */
 387                         continue;
 388                 }
 389                 if (!check_required_metadata(imod->metadata, avail_metadata))
 390                         /* Cannot satisfy this module's requirements. */
 391                         continue;
 392
 393                 meta = g_hash_table_new(NULL, NULL);
 394                 for (m = 0; m < sizeof(imod->metadata); m++) {
 395                         mitem = imod->metadata[m] & ~SR_INPUT_META_REQUIRED;
 396                         if (mitem == SR_INPUT_META_HEADER)
 397                                 g_hash_table_insert(meta, GINT_TO_POINTER(mitem), buf);
 398                 }
 399                 if (g_hash_table_size(meta) == 0) {
 400                         /* No metadata for this module, so nothing to match. */
 401                         g_hash_table_destroy(meta);
 402                         continue;
 403                 }
 404                 sr_spew("Trying module %s.", imod->id);
 405                 ret = imod->format_match(meta, &conf);
 406                 g_hash_table_destroy(meta);
 407                 if (ret == SR_ERR_DATA) {
 408                         /* Module recognized this buffer, but cannot handle it. */
 409                         continue;
 410                 } else if (ret == SR_ERR) {
 411                         /* Module didn't recognize this buffer. */
 412                         continue;
 413                 } else if (ret != SR_OK) {
 414                         /* Can be SR_ERR_NA. */
 415                         continue;
 416                 }
 417
 418                 /* Found a matching module. */
 419                 sr_spew("Module %s matched, confidence %u.", imod->id, conf);
 420                 if (conf >= best_conf)
 421                         continue;
 422                 best_imod = imod;
 423                 best_conf = conf;
 424         }
 425
 426         if (best_imod) {
 427                 *in = sr_input_new(best_imod, NULL);
 428                 g_string_insert_len((*in)->buf, 0, buf->str, buf->len);
 429                 return SR_OK;
 430         }
 431
 432         return SR_ERR;
 433 }
 434
 435 /**
 436  * Try to find an input module that can parse the given file.
 437  *
 438  * If an input module is found, an instance is created into *in.
 439  * Otherwise, *in contains NULL. When multiple input moduless claim
 440  * support for the format, the one with highest confidence takes
 441  * precedence. Applications will see at most one input module spec.
 442  *
 443  */
 444 SR_API int sr_input_scan_file(const char *filename, const struct sr_input **in)
 445 {
 446         int64_t filesize;
 447         FILE *stream;
 448         const struct sr_input_module *imod, *best_imod;
 449         GHashTable *meta;
 450         GString *header;
 451         size_t count;
 452         unsigned int midx, i;
 453         unsigned int conf, best_conf;
 454         int ret;
 455         uint8_t avail_metadata[8];
 456
 457         *in = NULL;
 458
 459         if (!filename || !filename[0]) {
 460                 sr_err("Invalid filename.");
 461                 return SR_ERR_ARG;
 462         }
 463         stream = g_fopen(filename, "rb");
 464         if (!stream) {
 465                 sr_err("Failed to open %s: %s", filename, g_strerror(errno));
 466                 return SR_ERR;
 467         }
 468         filesize = sr_file_get_size(stream);
 469         if (filesize < 0) {
 470                 sr_err("Failed to get size of %s: %s",
 471                         filename, g_strerror(errno));
 472                 fclose(stream);
 473                 return SR_ERR;
 474         }
 475         header = g_string_sized_new(CHUNK_SIZE);
 476         count = fread(header->str, 1, header->allocated_len - 1, stream);
 477         if (count < 1 || ferror(stream)) {
 478                 sr_err("Failed to read %s: %s", filename, g_strerror(errno));
 479                 fclose(stream);
 480                 g_string_free(header, TRUE);
 481                 return SR_ERR;
 482         }
 483         fclose(stream);
 484         g_string_set_size(header, count);
 485
 486         meta = g_hash_table_new(NULL, NULL);
 487         g_hash_table_insert(meta, GINT_TO_POINTER(SR_INPUT_META_FILENAME),
 488                         (char *)filename);
 489         g_hash_table_insert(meta, GINT_TO_POINTER(SR_INPUT_META_FILESIZE),
 490                         GSIZE_TO_POINTER(MIN(filesize, G_MAXSSIZE)));
 491         g_hash_table_insert(meta, GINT_TO_POINTER(SR_INPUT_META_HEADER),
 492                         header);
 493         midx = 0;
 494         avail_metadata[midx++] = SR_INPUT_META_FILENAME;
 495         avail_metadata[midx++] = SR_INPUT_META_FILESIZE;
 496         avail_metadata[midx++] = SR_INPUT_META_HEADER;
 497         avail_metadata[midx] = 0;
 498         /* TODO: MIME type */
 499
 500         best_imod = NULL;
 501         best_conf = ~0;
 502         for (i = 0; input_module_list[i]; i++) {
 503                 imod = input_module_list[i];
 504                 if (!imod->metadata[0]) {
 505                         /* Module has no metadata for matching so will take
 506                          * any input. No point in letting it try to match. */
 507                         continue;
 508                 }
 509                 if (!check_required_metadata(imod->metadata, avail_metadata))
 510                         /* Cannot satisfy this module's requirements. */
 511                         continue;
 512
 513                 sr_dbg("Trying module %s.", imod->id);
 514
 515                 ret = imod->format_match(meta, &conf);
 516                 if (ret == SR_ERR) {
 517                         /* Module didn't recognize this buffer. */
 518                         continue;
 519                 } else if (ret != SR_OK) {
 520                         /* Module recognized this buffer, but cannot handle it. */
 521                         continue;
 522                 }
 523                 /* Found a matching module. */
 524                 sr_dbg("Module %s matched, confidence %u.", imod->id, conf);
 525                 if (conf >= best_conf)
 526                         continue;
 527                 best_imod = imod;
 528                 best_conf = conf;
 529         }
 530         g_hash_table_destroy(meta);
 531         g_string_free(header, TRUE);
 532
 533         if (best_imod) {
 534                 *in = sr_input_new(best_imod, NULL);
 535                 return SR_OK;
 536         }
 537
 538         return SR_ERR;
 539 }
 540
 541 /**
 542  * Return the input instance's module "class". This can be used to find out
 543  * which input module handles a specific input file. This is especially
 544  * useful when an application did not create the input stream by specifying
 545  * an input module, but instead some shortcut or convenience wrapper did.
 546  *
 547  * @since 0.6.0
 548  */
 549 SR_API const struct sr_input_module *sr_input_module_get(const struct sr_input *in)
 550 {
 551         if (!in)
 552                 return NULL;
 553
 554         return in->module;
 555 }
 556
 557 /**
 558  * Return the input instance's (virtual) device instance. This can be
 559  * used to find out the number of channels and other information.
 560  *
 561  * If the device instance has not yet been fully populated by the input
 562  * module, NULL is returned. This indicates the module needs more data
 563  * to identify the number of channels and so on.
 564  *
 565  * @since 0.4.0
 566  */
 567 SR_API struct sr_dev_inst *sr_input_dev_inst_get(const struct sr_input *in)
 568 {
 569         if (in->sdi_ready)
 570                 return in->sdi;
 571         else
 572                 return NULL;
 573 }
 574
 575 /**
 576  * Send data to the specified input instance.
 577  *
 578  * When an input module instance is created with sr_input_new(), this
 579  * function is used to feed data to the instance.
 580  *
 581  * As enough data gets fed into this function to completely populate
 582  * the device instance associated with this input instance, this is
 583  * guaranteed to return the moment it's ready. This gives the caller
 584  * the chance to examine the device instance, attach session callbacks
 585  * and so on.
 586  *
 587  * @since 0.4.0
 588  */
 589 SR_API int sr_input_send(const struct sr_input *in, GString *buf)
 590 {
 591         size_t len;
 592
 593         len = buf ? buf->len : 0;
 594         sr_spew("Sending %zu bytes to %s module.", len, in->module->id);
 595         return in->module->receive((struct sr_input *)in, buf);
 596 }
 597
 598 /**
 599  * Signal the input module no more data will come.
 600  *
 601  * This will cause the module to process any data it may have buffered.
 602  * The SR_DF_END packet will also typically be sent at this time.
 603  *
 604  * @since 0.4.0
 605  */
 606 SR_API int sr_input_end(const struct sr_input *in)
 607 {
 608         sr_spew("Calling end() on %s module.", in->module->id);
 609         return in->module->end((struct sr_input *)in);
 610 }
 611
 612 /**
 613  * Reset the input module's input handling structures.
 614  *
 615  * Causes the input module to reset its internal state so that we can re-send
 616  * the input data from the beginning without having to re-create the entire
 617  * input module.
 618  *
 619  * @since 0.5.0
 620  */
 621 SR_API int sr_input_reset(const struct sr_input *in_ro)
 622 {
 623         struct sr_input *in;
 624         int rc;
 625
 626         in = (struct sr_input *)in_ro;  /* "un-const" */
 627         if (!in || !in->module)
 628                 return SR_ERR_ARG;
 629
 630         /*
 631          * Run the optional input module's .reset() method. This shall
 632          * take care of the context (kept in the 'inc' variable).
 633          */
 634         if (in->module->reset) {
 635                 sr_spew("Resetting %s module.", in->module->id);
 636                 rc = in->module->reset(in);
 637         } else {
 638                 sr_spew("Tried to reset %s module but no reset handler found.",
 639                         in->module->id);
 640                 rc = SR_OK;
 641         }
 642
 643         /*
 644          * Handle input module status (kept in the 'in' variable) here
 645          * in common logic. This agrees with how input module's receive()
 646          * and end() routines "amend but never seed" the 'in' information.
 647          *
 648          * Void potentially accumulated receive() buffer content, and
 649          * clear the sdi_ready flag. This makes sure that subsequent
 650          * processing will scan the header again before sample data gets
 651          * interpreted, and stale content from previous calls won't affect
 652          * the result.
 653          *
 654          * This common logic does not harm when the input module implements
 655          * .reset() and contains identical assignments. In the absence of
 656          * an individual .reset() method, simple input modules can completely
 657          * rely on common code and keep working across resets.
 658          */
 659         if (in->buf)
 660                 g_string_truncate(in->buf, 0);
 661         in->sdi_ready = FALSE;
 662
 663         return rc;
 664 }
 665
 666 /**
 667  * Free the specified input instance and all associated resources.
 668  *
 669  * @since 0.4.0
 670  */
 671 SR_API void sr_input_free(const struct sr_input *in)
 672 {
 673         if (!in)
 674                 return;
 675
 676         /*
 677          * Run the input module's optional .cleanup() routine. This
 678          * takes care of the context (kept in the 'inc' variable).
 679          */
 680         if (in->module->cleanup)
 681                 in->module->cleanup((struct sr_input *)in);
 682
 683         /*
 684          * Common code releases the input module's state (kept in the
 685          * 'in' variable). Release the device instance, the receive()
 686          * buffer, the shallow 'in->priv' block which is 'inc' (after
 687          * .cleanup() released potentially nested resources under 'inc').
 688          */
 689         sr_dev_inst_free(in->sdi);
 690         if (in->buf->len > 64) {
 691                 /* That seems more than just some sub-unitsize leftover... */
 692                 sr_warn("Found %" G_GSIZE_FORMAT
 693                         " unprocessed bytes at free time.", in->buf->len);
 694         }
 695         g_string_free(in->buf, TRUE);
 696         g_free(in->priv);
 697         g_free((gpointer)in);
 698 }
 699
 700 /** @} */