2 * yosys -- Yosys Open SYnthesis Suite
4 * Copyright (C) 2020 whitequark <whitequark@whitequark.org>
6 * Permission to use, copy, modify, and/or distribute this software for any
7 * purpose with or without fee is hereby granted.
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.
19 #ifndef CXXRTL_VCD_CAPI_H
20 #define CXXRTL_VCD_CAPI_H
22 // This file is a part of the CXXRTL C API. It should be used together with `cxxrtl_vcd_capi.cc`.
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.
30 #include <backends/cxxrtl/cxxrtl_capi.h>
36 // Opaque reference to a VCD writer.
37 typedef struct _cxxrtl_vcd
*cxxrtl_vcd
;
39 // Create a VCD writer.
40 cxxrtl_vcd
cxxrtl_vcd_create();
42 // Release all resources used by a VCD writer.
43 void cxxrtl_vcd_destroy(cxxrtl_vcd vcd
);
47 // The `number` must be 1, 10, or 100, and the `unit` must be one of `"s"`, `"ms"`, `"us"`, `"ns"`,
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
);
53 // Schedule a specific CXXRTL object to be sampled.
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
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
);
63 // Schedule all CXXRTL objects in a simulation.
65 // The design `handle` must outlive the VCD writer.
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
);
70 // Schedule CXXRTL objects in a simulation that match a given predicate.
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.
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
));
81 // Schedule all CXXRTL objects in a simulation except for memories.
83 // The design `handle` must outlive the VCD writer.
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
);
88 // Sample all scheduled objects.
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
);
95 // Retrieve buffered VCD data.
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
);