backends/cxxrtl/cxxrtl_vcd_capi.h

   1 /*
   2  *  yosys -- Yosys Open SYnthesis Suite
   3  *
   4  *  Copyright (C) 2020  whitequark <whitequark@whitequark.org>
   5  *
   6  *  Permission to use, copy, modify, and/or distribute this software for any
   7  *  purpose with or without fee is hereby granted.
   8  *
   9  *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10  *  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11  *  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12  *  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13  *  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14  *  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15  *  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16  *
  17  */
  18
  19 #ifndef CXXRTL_VCD_CAPI_H
  20 #define CXXRTL_VCD_CAPI_H
  21
  22 // This file is a part of the CXXRTL C API. It should be used together with `cxxrtl_vcd_capi.cc`.
  23 //
  24 // The CXXRTL C API for VCD writing makes it possible to insert virtual probes into designs and
  25 // dump waveforms to Value Change Dump files.
  26
  27 #include <stddef.h>
  28 #include <stdint.h>
  29
  30 #include <backends/cxxrtl/cxxrtl_capi.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 // Opaque reference to a VCD writer.
  37 typedef struct _cxxrtl_vcd *cxxrtl_vcd;
  38
  39 // Create a VCD writer.
  40 cxxrtl_vcd cxxrtl_vcd_create();
  41
  42 // Release all resources used by a VCD writer.
  43 void cxxrtl_vcd_destroy(cxxrtl_vcd vcd);
  44
  45 // Set VCD timescale.
  46 //
  47 // The `number` must be 1, 10, or 100, and the `unit` must be one of `"s"`, `"ms"`, `"us"`, `"ns"`,
  48 // `"ps"`, or `"fs"`.
  49 //
  50 // Timescale can only be set before the first call to `cxxrtl_vcd_sample`.
  51 void cxxrtl_vcd_timescale(cxxrtl_vcd vcd, int number, const char *unit);
  52
  53 // Schedule a specific CXXRTL object to be sampled.
  54 //
  55 // The `name` is a full hierarchical name as described for `cxxrtl_get`; it does not need to match
  56 // the original name of `object`, if any. The `object` must outlive the VCD writer, but there are
  57 // no other requirements; if desired, it can be provided by user code, rather than come from
  58 // a design.
  59 //
  60 // Objects can only be scheduled before the first call to `cxxrtl_vcd_sample`.
  61 void cxxrtl_vcd_add(cxxrtl_vcd vcd, const char *name, struct cxxrtl_object *object);
  62
  63 // Schedule all CXXRTL objects in a simulation.
  64 //
  65 // The design `handle` must outlive the VCD writer.
  66 //
  67 // Objects can only be scheduled before the first call to `cxxrtl_vcd_sample`.
  68 void cxxrtl_vcd_add_from(cxxrtl_vcd vcd, cxxrtl_handle handle);
  69
  70 // Schedule CXXRTL objects in a simulation that match a given predicate.
  71 //
  72 // For every object in the simulation, `filter` is called with the provided `data`, the full
  73 // hierarchical name of the object (see `cxxrtl_get` for details), and the object description.
  74 // The object will be sampled if the predicate returns a non-zero value.
  75 //
  76 // Objects can only be scheduled before the first call to `cxxrtl_vcd_sample`.
  77 void cxxrtl_vcd_add_from_if(cxxrtl_vcd vcd, cxxrtl_handle handle, void *data,
  78                             int (*filter)(void *data, const char *name,
  79                                           const struct cxxrtl_object *object));
  80
  81 // Schedule all CXXRTL objects in a simulation except for memories.
  82 //
  83 // The design `handle` must outlive the VCD writer.
  84 //
  85 // Objects can only be scheduled before the first call to `cxxrtl_vcd_sample`.
  86 void cxxrtl_vcd_add_from_without_memories(cxxrtl_vcd vcd, cxxrtl_handle handle);
  87
  88 // Sample all scheduled objects.
  89 //
  90 // First, `time` is written to the internal buffer. Second, the values of every signal changed since
  91 // the previous call to `cxxrtl_vcd_sample` (all values if this is the first call) are written to
  92 // the internal buffer. The contents of the buffer can be retrieved with `cxxrtl_vcd_read`.
  93 void cxxrtl_vcd_sample(cxxrtl_vcd vcd, uint64_t time);
  94
  95 // Retrieve buffered VCD data.
  96 //
  97 // The pointer to the start of the next chunk of VCD data is assigned to `*data`, and the length
  98 // of that chunk is assigned to `*size`. The pointer to the data is valid until the next call to
  99 // `cxxrtl_vcd_sample` or `cxxrtl_vcd_read`. Once all of the buffered data has been retrieved,
 100 // this function will always return zero sized chunks.
 101 void cxxrtl_vcd_read(cxxrtl_vcd vcd, const char **data, size_t *size);
 102
 103 #ifdef __cplusplus
 104 }
 105 #endif
 106
 107 #endif