mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-05-12 02:04:44 +00:00
Code Activity

cxxrtl: reorganize runtime component files.

Browse source 
In preparation for substantial expansion of CXXRTL's runtime, this commit
reorganizes the files used by the implementation. Only minimal changes are
required in a consumer.

First, change:
  -I$(yosys-config --datdir)/include
to:
  -I$(yosys-config --datdir)/include/backends/cxxrtl/runtime

Second, change:
  #include <backends/cxxrtl/cxxrtl.h>
to:
  #include <cxxrtl/cxxrtl.h>
(and do the same for cxxrtl_vcd.h, etc.)
This commit is contained in:
Catherine 2023-11-28 12:09:47 +00:00
parent 3dd5262355
commit 62bbd086b1
10 changed files with 43 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

135
backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.cc Normal file
View file

@ -0,0 +1,135 @@
/*
* yosys -- Yosys Open SYnthesis Suite
*
* Copyright (C) 2020 whitequark <whitequark@whitequark.org>
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
*/
// This file is a part of the CXXRTL C API. It should be used together with `cxxrtl/capi/cxxrtl_capi.h`.
#include <cxxrtl/capi/cxxrtl_capi.h>
#include <cxxrtl/cxxrtl.h>
struct _cxxrtl_handle {
std::unique_ptr<cxxrtl::module> module;
cxxrtl::debug_items objects;
};
// Private function for use by other units of the C API.
const cxxrtl::debug_items &cxxrtl_debug_items_from_handle(cxxrtl_handle handle) {
return handle->objects;
}
cxxrtl_handle cxxrtl_create(cxxrtl_toplevel design) {
return cxxrtl_create_at(design, "");
}
cxxrtl_handle cxxrtl_create_at(cxxrtl_toplevel design, const char *root) {
std::string path = root;
if (!path.empty()) {
// module::debug_info() accepts either an empty path, or a path ending in space to simplify
// the logic in generated code. While this is sketchy at best to expose in the C++ API, this
// would be a lot worse in the C API, so don't expose it here.
assert(path.back() != ' ');
path += ' ';
}
cxxrtl_handle handle = new _cxxrtl_handle;
handle->module = std::move(design->module);
handle->module->debug_info(handle->objects, path);
delete design;
return handle;
}
void cxxrtl_destroy(cxxrtl_handle handle) {
delete handle;
}
void cxxrtl_reset(cxxrtl_handle handle) {
handle->module->reset();
}
int cxxrtl_eval(cxxrtl_handle handle) {
return handle->module->eval();
}
int cxxrtl_commit(cxxrtl_handle handle) {
return handle->module->commit();
}
size_t cxxrtl_step(cxxrtl_handle handle) {
return handle->module->step();
}
struct cxxrtl_object *cxxrtl_get_parts(cxxrtl_handle handle, const char *name, size_t *parts) {
auto it = handle->objects.table.find(name);
if (it == handle->objects.table.end())
return nullptr;
*parts = it->second.size();
return static_cast<cxxrtl_object*>(&it->second[0]);
}
void cxxrtl_enum(cxxrtl_handle handle, void *data,
void (*callback)(void *data, const char *name,
cxxrtl_object *object, size_t parts)) {
for (auto &it : handle->objects.table)
callback(data, it.first.c_str(), static_cast<cxxrtl_object*>(&it.second[0]), it.second.size());
}
void cxxrtl_outline_eval(cxxrtl_outline outline) {
outline->eval();
}
int cxxrtl_attr_type(cxxrtl_attr_set attrs_, const char *name) {
auto attrs = (cxxrtl::metadata_map*)attrs_;
if (!attrs->count(name))
return CXXRTL_ATTR_NONE;
switch (attrs->at(name).value_type) {
case cxxrtl::metadata::UINT:
return CXXRTL_ATTR_UNSIGNED_INT;
case cxxrtl::metadata::SINT:
return CXXRTL_ATTR_SIGNED_INT;
case cxxrtl::metadata::STRING:
return CXXRTL_ATTR_STRING;
case cxxrtl::metadata::DOUBLE:
return CXXRTL_ATTR_DOUBLE;
default:
// Present unsupported attribute type the same way as no attribute at all.
return CXXRTL_ATTR_NONE;
}
}
uint64_t cxxrtl_attr_get_unsigned_int(cxxrtl_attr_set attrs_, const char *name) {
auto &attrs = *(cxxrtl::metadata_map*)attrs_;
assert(attrs.count(name) && attrs.at(name).value_type == cxxrtl::metadata::UINT);
return attrs[name].as_uint();
}
int64_t cxxrtl_attr_get_signed_int(cxxrtl_attr_set attrs_, const char *name) {
auto &attrs = *(cxxrtl::metadata_map*)attrs_;
assert(attrs.count(name) && attrs.at(name).value_type == cxxrtl::metadata::SINT);
return attrs[name].as_sint();
}
const char *cxxrtl_attr_get_string(cxxrtl_attr_set attrs_, const char *name) {
auto &attrs = *(cxxrtl::metadata_map*)attrs_;
assert(attrs.count(name) && attrs.at(name).value_type == cxxrtl::metadata::STRING);
return attrs[name].as_string().c_str();
}
double cxxrtl_attr_get_double(cxxrtl_attr_set attrs_, const char *name) {
auto &attrs = *(cxxrtl::metadata_map*)attrs_;
assert(attrs.count(name) && attrs.at(name).value_type == cxxrtl::metadata::DOUBLE);
return attrs[name].as_double();
}

376
backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.h Normal file
View file

@ -0,0 +1,376 @@
/*
* yosys -- Yosys Open SYnthesis Suite
*
* Copyright (C) 2020 whitequark <whitequark@whitequark.org>
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
*/
#ifndef CXXRTL_CAPI_H
#define CXXRTL_CAPI_H
// This file is a part of the CXXRTL C API. It should be used together with `cxxrtl_capi.cc`.
//
// The CXXRTL C API makes it possible to drive CXXRTL designs using C or any other language that
// supports the C ABI, for example, Python. It does not provide a way to implement black boxes.
#include <stddef.h>
#include <stdint.h>
#include <assert.h>
#ifdef __cplusplus
extern "C" {
#endif
// Opaque reference to a design toplevel.
//
// A design toplevel can only be used to create a design handle.
typedef struct _cxxrtl_toplevel *cxxrtl_toplevel;
// The constructor for a design toplevel is provided as a part of generated code for that design.
// Its prototype matches:
//
// cxxrtl_toplevel <design-name>_create();
// Opaque reference to a design handle.
//
// A design handle is required by all operations in the C API.
typedef struct _cxxrtl_handle *cxxrtl_handle;
// Create a design handle from a design toplevel.
//
// The `design` is consumed by this operation and cannot be used afterwards.
cxxrtl_handle cxxrtl_create(cxxrtl_toplevel design);
// Create a design handle at a given hierarchy position from a design toplevel.
//
// This operation is similar to `cxxrtl_create`, except the full hierarchical name of every object
// is prepended with `root`.
cxxrtl_handle cxxrtl_create_at(cxxrtl_toplevel design, const char *root);
// Release all resources used by a design and its handle.
void cxxrtl_destroy(cxxrtl_handle handle);
// Reinitialize the design, replacing the internal state with the reset values while preserving
// black boxes.
//
// This operation is essentially equivalent to a power-on reset. Values, wires, and memories are
// returned to their reset state while preserving the state of black boxes and keeping all of
// the interior pointers obtained with e.g. `cxxrtl_get` valid.
void cxxrtl_reset(cxxrtl_handle handle);
// Evaluate the design, propagating changes on inputs to the `next` value of internal state and
// output wires.
//
// Returns 1 if the design is known to immediately converge, 0 otherwise.
int cxxrtl_eval(cxxrtl_handle handle);
// Commit the design, replacing the `curr` value of internal state and output wires with the `next`
// value.
//
// Return 1 if any of the `curr` values were updated, 0 otherwise.
int cxxrtl_commit(cxxrtl_handle handle);
// Simulate the design to a fixed point.
//
// Returns the number of delta cycles.
size_t cxxrtl_step(cxxrtl_handle handle);
// Type of a simulated object.
//
// The type of a simulated object indicates the way it is stored and the operations that are legal
// to perform on it (i.e. won't crash the simulation). It says very little about object semantics,
// which is specified through flags.
enum cxxrtl_type {
// Values correspond to singly buffered netlist nodes, i.e. nodes driven exclusively by
// combinatorial cells, or toplevel input nodes.
//
// Values can be inspected via the `curr` pointer. If the `next` pointer is NULL, the value is
// driven by a constant and can never be modified. Otherwise, the value can be modified through
// the `next` pointer (which is equal to `curr` if not NULL). Note that changes to the bits
// driven by combinatorial cells will be ignored.
//
// Values always have depth 1.
CXXRTL_VALUE = 0,
// Wires correspond to doubly buffered netlist nodes, i.e. nodes driven, at least in part, by
// storage cells, or by combinatorial cells that are a part of a feedback path. They are also
// present in non-optimized builds.
//
// Wires can be inspected via the `curr` pointer and modified via the `next` pointer (which are
// distinct for wires). Note that changes to the bits driven by combinatorial cells will be
// ignored.
//
// Wires always have depth 1.
CXXRTL_WIRE = 1,
// Memories correspond to memory cells.
//
// Memories can be inspected and modified via the `curr` pointer. Due to a limitation of this
// API, memories cannot yet be modified in a guaranteed race-free way, and the `next` pointer is
// always NULL.
CXXRTL_MEMORY = 2,
// Aliases correspond to netlist nodes driven by another node such that their value is always
// exactly equal.
//
// Aliases can be inspected via the `curr` pointer. They cannot be modified, and the `next`
// pointer is always NULL.
CXXRTL_ALIAS = 3,
// Outlines correspond to netlist nodes that were optimized in a way that makes them inaccessible
// outside of a module's `eval()` function. At the highest debug information level, every inlined
// node has a corresponding outline object.
//
// Outlines can be inspected via the `curr` pointer and can never be modified; the `next` pointer
// is always NULL. Unlike all other objects, the bits of an outline object are meaningful only
// after a call to `cxxrtl_outline_eval` and until any subsequent modification to the netlist.
// Observing this requirement is the responsibility of the caller; it is not enforced.
//
// Outlines always correspond to combinatorial netlist nodes that are not ports.
CXXRTL_OUTLINE = 4,
// More object types may be added in the future, but the existing ones will never change.
};
// Flags of a simulated object.
//
// The flags of a simulated object indicate its role in the netlist:
// * The flags `CXXRTL_INPUT` and `CXXRTL_OUTPUT` designate module ports.
// * The flags `CXXRTL_DRIVEN_SYNC`, `CXXRTL_DRIVEN_COMB`, and `CXXRTL_UNDRIVEN` specify
// the semantics of node state. An object with several of these flags set has different bits
// follow different semantics.
enum cxxrtl_flag {
// Node is a module input port.
//
// This flag can be set on objects of type `CXXRTL_VALUE` and `CXXRTL_WIRE`. It may be combined
// with `CXXRTL_OUTPUT`, as well as other flags.
CXXRTL_INPUT = 1 << 0,
// Node is a module output port.
//
// This flag can be set on objects of type `CXXRTL_WIRE`. It may be combined with `CXXRTL_INPUT`,
// as well as other flags.
CXXRTL_OUTPUT = 1 << 1,
// Node is a module inout port.
//
// This flag can be set on objects of type `CXXRTL_WIRE`. It may be combined with other flags.
CXXRTL_INOUT = (CXXRTL_INPUT|CXXRTL_OUTPUT),
// Node has bits that are driven by a storage cell.
//
// This flag can be set on objects of type `CXXRTL_WIRE`. It may be combined with
// `CXXRTL_DRIVEN_COMB` and `CXXRTL_UNDRIVEN`, as well as other flags.
//
// This flag is set on wires that have bits connected directly to the output of a flip-flop or
// a latch, and hold its state. Many `CXXRTL_WIRE` objects may not have the `CXXRTL_DRIVEN_SYNC`
// flag set; for example, output ports and feedback wires generally won't. Writing to the `next`
// pointer of these wires updates stored state, and for designs without combinatorial loops,
// capturing the value from every of these wires through the `curr` pointer creates a complete
// snapshot of the design state.
CXXRTL_DRIVEN_SYNC = 1 << 2,
// Node has bits that are driven by a combinatorial cell or another node.
//
// This flag can be set on objects of type `CXXRTL_VALUE`, `CXXRTL_WIRE`, and `CXXRTL_OUTLINE`.
// It may be combined with `CXXRTL_DRIVEN_SYNC` and `CXXRTL_UNDRIVEN`, as well as other flags.
//
// This flag is set on objects that have bits connected to the output of a combinatorial cell,
// or directly to another node. For designs without combinatorial loops, writing to such bits
// through the `next` pointer (if it is not NULL) has no effect.
CXXRTL_DRIVEN_COMB = 1 << 3,
// Node has bits that are not driven.
//
// This flag can be set on objects of type `CXXRTL_VALUE` and `CXXRTL_WIRE`. It may be combined
// with `CXXRTL_DRIVEN_SYNC` and `CXXRTL_DRIVEN_COMB`, as well as other flags.
//
// This flag is set on objects that have bits not driven by an output of any cell or by another
// node, such as inputs and dangling wires.
CXXRTL_UNDRIVEN = 1 << 4,
// More object flags may be added in the future, but the existing ones will never change.
};
// Description of a simulated object.
//
// The `curr` and `next` arrays can be accessed directly to inspect and, if applicable, modify
// the bits stored in the object.
struct cxxrtl_object {
// Type of the object.
//
// All objects have the same memory layout determined by `width` and `depth`, but the type
// determines all other properties of the object.
uint32_t type; // actually `enum cxxrtl_type`
// Flags of the object.
uint32_t flags; // actually bit mask of `enum cxxrtl_flags`
// Width of the object in bits.
size_t width;
// Index of the least significant bit.
size_t lsb_at;
// Depth of the object. Only meaningful for memories; for other objects, always 1.
size_t depth;
// Index of the first word. Only meaningful for memories; for other objects, always 0;
size_t zero_at;
// Bits stored in the object, as 32-bit chunks, least significant bits first.
//
// The width is rounded up to a multiple of 32; the padding bits are always set to 0 by
// the simulation code, and must be always written as 0 when modified by user code.
// In memories, every element is stored contiguously. Therefore, the total number of chunks
// in any object is `((width + 31) / 32) * depth`.
//
// To allow the simulation to be partitioned into multiple independent units communicating
// through wires, the bits are double buffered. To avoid race conditions, user code should
// always read from `curr` and write to `next`. The `curr` pointer is always valid; for objects
// that cannot be modified, or cannot be modified in a race-free way, `next` is NULL.
uint32_t *curr;
uint32_t *next;
// Opaque reference to an outline. Only meaningful for outline objects.
//
// See the documentation of `cxxrtl_outline` for details. When creating a `cxxrtl_object`, set
// this field to NULL.
struct _cxxrtl_outline *outline;
// Opaque reference to an attribute set.
//
// See the documentation of `cxxrtl_attr_set` for details. When creating a `cxxrtl_object`, set
// this field to NULL.
//
// The lifetime of the pointers returned by `cxxrtl_attr_*` family of functions is the same as
// the lifetime of this structure.
struct _cxxrtl_attr_set *attrs;
// More description fields may be added in the future, but the existing ones will never change.
};
// Retrieve description of a simulated object.
//
// The `name` is the full hierarchical name of the object in the Yosys notation, where public names
// have a `\` prefix and hierarchy levels are separated by single spaces. For example, if
// the top-level module instantiates a module `foo`, which in turn contains a wire `bar`, the full
// hierarchical name is `\foo \bar`.
//
// The storage of a single abstract object may be split (usually with the `splitnets` pass) into
// many physical parts, all of which correspond to the same hierarchical name. To handle such cases,
// this function returns an array and writes its length to `parts`. The array is sorted by `lsb_at`.
//
// Returns the object parts if it was found, NULL otherwise. The returned parts are valid until
// the design is destroyed.
struct cxxrtl_object *cxxrtl_get_parts(cxxrtl_handle handle, const char *name, size_t *parts);
// Retrieve description of a single part simulated object.
//
// This function is a shortcut for the most common use of `cxxrtl_get_parts`. It asserts that,
// if the object exists, it consists of a single part. If assertions are disabled, it returns NULL
// for multi-part objects.
static inline struct cxxrtl_object *cxxrtl_get(cxxrtl_handle handle, const char *name) {
size_t parts = 0;
struct cxxrtl_object *object = cxxrtl_get_parts(handle, name, &parts);
assert(object == NULL || parts == 1);
if (object == NULL || parts == 1)
return object;
return NULL;
}
// Enumerate simulated objects.
//
// For every object in the simulation, `callback` is called with the provided `data`, the full
// hierarchical name of the object (see `cxxrtl_get` for details), and the object parts.
// The provided `name` and `object` values are valid until the design is destroyed.
void cxxrtl_enum(cxxrtl_handle handle, void *data,
void (*callback)(void *data, const char *name,
struct cxxrtl_object *object, size_t parts));
// Opaque reference to an outline.
//
// An outline is a group of outline objects that are evaluated simultaneously. The identity of
// an outline can be compared to determine whether any two objects belong to the same outline.
typedef struct _cxxrtl_outline *cxxrtl_outline;
// Evaluate an outline.
//
// After evaluating an outline, the bits of every outline object contained in it are consistent
// with the current state of the netlist. In general, any further modification to the netlist
// causes every outline object to become stale, after which the corresponding outline must be
// re-evaluated, otherwise the bits read from that object are meaningless.
void cxxrtl_outline_eval(cxxrtl_outline outline);
// Opaque reference to an attribute set.
//
// An attribute set is a map between attribute names (always strings) and values (which may have
// several different types). To find out the type of an attribute, use `cxxrtl_attr_type`, and
// to retrieve the value of an attribute, use `cxxrtl_attr_as_string`.
typedef struct _cxxrtl_attr_set *cxxrtl_attr_set;
// Type of an attribute.
enum cxxrtl_attr_type {
// Attribute is not present.
CXXRTL_ATTR_NONE = 0,
// Attribute has an unsigned integer value.
CXXRTL_ATTR_UNSIGNED_INT = 1,
// Attribute has an unsigned integer value.
CXXRTL_ATTR_SIGNED_INT = 2,
// Attribute has a string value.
CXXRTL_ATTR_STRING = 3,
// Attribute has a double precision floating point value.
CXXRTL_ATTR_DOUBLE = 4,
// More attribute types may be defined in the future, but the existing values will never change.
};
// Determine the presence and type of an attribute in an attribute set.
//
// This function returns one of the possible `cxxrtl_attr_type` values.
int cxxrtl_attr_type(cxxrtl_attr_set attrs, const char *name);
// Retrieve an unsigned integer valued attribute from an attribute set.
//
// This function asserts that `cxxrtl_attr_type(attrs, name) == CXXRTL_ATTR_UNSIGNED_INT`.
// If assertions are disabled, returns 0 if the attribute is missing or has an incorrect type.
uint64_t cxxrtl_attr_get_unsigned_int(cxxrtl_attr_set attrs, const char *name);
// Retrieve a signed integer valued attribute from an attribute set.
//
// This function asserts that `cxxrtl_attr_type(attrs, name) == CXXRTL_ATTR_SIGNED_INT`.
// If assertions are disabled, returns 0 if the attribute is missing or has an incorrect type.
int64_t cxxrtl_attr_get_signed_int(cxxrtl_attr_set attrs, const char *name);
// Retrieve a string valued attribute from an attribute set. The returned string is zero-terminated.
//
// This function asserts that `cxxrtl_attr_type(attrs, name) == CXXRTL_ATTR_STRING`. If assertions
// are disabled, returns NULL if the attribute is missing or has an incorrect type.
const char *cxxrtl_attr_get_string(cxxrtl_attr_set attrs, const char *name);
// Retrieve a double precision floating point valued attribute from an attribute set.
//
// This function asserts that `cxxrtl_attr_type(attrs, name) == CXXRTL_ATTR_DOUBLE`. If assertions
// are disabled, returns NULL if the attribute is missing or has an incorrect type.
double cxxrtl_attr_get_double(cxxrtl_attr_set attrs, const char *name);
#ifdef __cplusplus
}
#endif
#endif

83
backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi_vcd.cc Normal file
View file

@ -0,0 +1,83 @@
/*
* yosys -- Yosys Open SYnthesis Suite
*
* Copyright (C) 2020 whitequark <whitequark@whitequark.org>
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
*/
// This file is a part of the CXXRTL C API. It should be used together with `cxxrtl/capi/cxxrtl_capi_vcd.h`.
#include <cxxrtl/capi/cxxrtl_capi_vcd.h>
#include <cxxrtl/cxxrtl_vcd.h>
extern const cxxrtl::debug_items &cxxrtl_debug_items_from_handle(cxxrtl_handle handle);
struct _cxxrtl_vcd {
cxxrtl::vcd_writer writer;
bool flush = false;
};
cxxrtl_vcd cxxrtl_vcd_create() {
return new _cxxrtl_vcd;
}
void cxxrtl_vcd_destroy(cxxrtl_vcd vcd) {
delete vcd;
}
void cxxrtl_vcd_timescale(cxxrtl_vcd vcd, int number, const char *unit) {
vcd->writer.timescale(number, unit);
}
void cxxrtl_vcd_add(cxxrtl_vcd vcd, const char *name, cxxrtl_object *object) {
// Note the copy. We don't know whether `object` came from a design (in which case it is
// an instance of `debug_item`), or from user code (in which case it is an instance of
// `cxxrtl_object`), so casting the pointer wouldn't be safe.
vcd->writer.add(name, cxxrtl::debug_item(*object));
}
void cxxrtl_vcd_add_from(cxxrtl_vcd vcd, cxxrtl_handle handle) {
vcd->writer.add(cxxrtl_debug_items_from_handle(handle));
}
void cxxrtl_vcd_add_from_if(cxxrtl_vcd vcd, cxxrtl_handle handle, void *data,
int (*filter)(void *data, const char *name,
const cxxrtl_object *object)) {
vcd->writer.add(cxxrtl_debug_items_from_handle(handle),
[=](const std::string &name, const cxxrtl::debug_item &item) {
return filter(data, name.c_str(), static_cast<const cxxrtl_object*>(&item));
});
}
void cxxrtl_vcd_add_from_without_memories(cxxrtl_vcd vcd, cxxrtl_handle handle) {
vcd->writer.add_without_memories(cxxrtl_debug_items_from_handle(handle));
}
void cxxrtl_vcd_sample(cxxrtl_vcd vcd, uint64_t time) {
if (vcd->flush) {
vcd->writer.buffer.clear();
vcd->flush = false;
}
vcd->writer.sample(time);
}
void cxxrtl_vcd_read(cxxrtl_vcd vcd, const char **data, size_t *size) {
if (vcd->flush) {
vcd->writer.buffer.clear();
vcd->flush = false;
}
*data = vcd->writer.buffer.c_str();
*size = vcd->writer.buffer.size();
vcd->flush = true;
}

107
backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi_vcd.h Normal file
View file

@ -0,0 +1,107 @@
/*
* yosys -- Yosys Open SYnthesis Suite
*
* Copyright (C) 2020 whitequark <whitequark@whitequark.org>
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
*/
#ifndef CXXRTL_CAPI_VCD_H
#define CXXRTL_CAPI_VCD_H
// This file is a part of the CXXRTL C API. It should be used together with `cxxrtl_vcd_capi.cc`.
//
// The CXXRTL C API for VCD writing makes it possible to insert virtual probes into designs and
// dump waveforms to Value Change Dump files.
#include <stddef.h>
#include <stdint.h>
#include <cxxrtl/capi/cxxrtl_capi.h>
#ifdef __cplusplus
extern "C" {
#endif
// Opaque reference to a VCD writer.
typedef struct _cxxrtl_vcd *cxxrtl_vcd;
// Create a VCD writer.
cxxrtl_vcd cxxrtl_vcd_create();
// Release all resources used by a VCD writer.
void cxxrtl_vcd_destroy(cxxrtl_vcd vcd);
// Set VCD timescale.
//
// The `number` must be 1, 10, or 100, and the `unit` must be one of `"s"`, `"ms"`, `"us"`, `"ns"`,
// `"ps"`, or `"fs"`.
//
// Timescale can only be set before the first call to `cxxrtl_vcd_sample`.
void cxxrtl_vcd_timescale(cxxrtl_vcd vcd, int number, const char *unit);
// Schedule a specific CXXRTL object to be sampled.
//
// The `name` is a full hierarchical name as described for `cxxrtl_get`; it does not need to match
// the original name of `object`, if any. The `object` must outlive the VCD writer, but there are
// no other requirements; if desired, it can be provided by user code, rather than come from
// a design.
//
// Objects can only be scheduled before the first call to `cxxrtl_vcd_sample`.
void cxxrtl_vcd_add(cxxrtl_vcd vcd, const char *name, struct cxxrtl_object *object);
// Schedule all CXXRTL objects in a simulation.
//
// The design `handle` must outlive the VCD writer.
//
// Objects can only be scheduled before the first call to `cxxrtl_vcd_sample`.
void cxxrtl_vcd_add_from(cxxrtl_vcd vcd, cxxrtl_handle handle);
// Schedule CXXRTL objects in a simulation that match a given predicate.
//
// For every object in the simulation, `filter` is called with the provided `data`, the full
// hierarchical name of the object (see `cxxrtl_get` for details), and the object description.
// The object will be sampled if the predicate returns a non-zero value.
//
// Objects can only be scheduled before the first call to `cxxrtl_vcd_sample`.
void cxxrtl_vcd_add_from_if(cxxrtl_vcd vcd, cxxrtl_handle handle, void *data,
int (*filter)(void *data, const char *name,
const struct cxxrtl_object *object));
// Schedule all CXXRTL objects in a simulation except for memories.
//
// The design `handle` must outlive the VCD writer.
//
// Objects can only be scheduled before the first call to `cxxrtl_vcd_sample`.
void cxxrtl_vcd_add_from_without_memories(cxxrtl_vcd vcd, cxxrtl_handle handle);
// Sample all scheduled objects.
//
// First, `time` is written to the internal buffer. Second, the values of every signal changed since
// the previous call to `cxxrtl_vcd_sample` (all values if this is the first call) are written to
// the internal buffer. The contents of the buffer can be retrieved with `cxxrtl_vcd_read`.
void cxxrtl_vcd_sample(cxxrtl_vcd vcd, uint64_t time);
// Retrieve buffered VCD data.
//
// The pointer to the start of the next chunk of VCD data is assigned to `*data`, and the length
// of that chunk is assigned to `*size`. The pointer to the data is valid until the next call to
// `cxxrtl_vcd_sample` or `cxxrtl_vcd_read`. Once all of the buffered data has been retrieved,
// this function will always return zero sized chunks.
void cxxrtl_vcd_read(cxxrtl_vcd vcd, const char **data, size_t *size);
#ifdef __cplusplus
}
#endif
#endif

1850
backends/cxxrtl/runtime/cxxrtl/cxxrtl.h Normal file
View file

File diff suppressed because it is too large Load diff

275
backends/cxxrtl/runtime/cxxrtl/cxxrtl_vcd.h Normal file
View file

@ -0,0 +1,275 @@
/*
* yosys -- Yosys Open SYnthesis Suite
*
* Copyright (C) 2020 whitequark <whitequark@whitequark.org>
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
*/
#ifndef CXXRTL_VCD_H
#define CXXRTL_VCD_H
#include <cxxrtl/cxxrtl.h>
namespace cxxrtl {
class vcd_writer {
struct variable {
size_t ident;
size_t width;
chunk_t *curr;
size_t cache_offset;
debug_outline *outline;
bool *outline_warm;
};
std::vector<std::string> current_scope;
std::map<debug_outline*, bool> outlines;
std::vector<variable> variables;
std::vector<chunk_t> cache;
std::map<chunk_t*, size_t> aliases;
bool streaming = false;
void emit_timescale(unsigned number, const std::string &unit) {
assert(!streaming);
assert(number == 1 || number == 10 || number == 100);
assert(unit == "s" || unit == "ms" || unit == "us" ||
unit == "ns" || unit == "ps" || unit == "fs");
buffer += "$timescale " + std::to_string(number) + " " + unit + " $end\n";
}
void emit_scope(const std::vector<std::string> &scope) {
assert(!streaming);
while (current_scope.size() > scope.size() ||
(current_scope.size() > 0 &&
current_scope[current_scope.size() - 1] != scope[current_scope.size() - 1])) {
buffer += "$upscope $end\n";
current_scope.pop_back();
}
while (current_scope.size() < scope.size()) {
buffer += "$scope module " + scope[current_scope.size()] + " $end\n";
current_scope.push_back(scope[current_scope.size()]);
}
}
void emit_ident(size_t ident) {
do {
buffer += '!' + ident % 94; // "base94"
ident /= 94;
} while (ident != 0);
}
void emit_name(const std::string &name) {
for (char c : name) {
if (c == ':') {
// Due to a bug, GTKWave cannot parse a colon in the variable name, causing the VCD file
// to be unreadable. It cannot be escaped either, so replace it with the sideways colon.
buffer += "..";
} else {
buffer += c;
}
}
}
void emit_var(const variable &var, const std::string &type, const std::string &name,
size_t lsb_at, bool multipart) {
assert(!streaming);
buffer += "$var " + type + " " + std::to_string(var.width) + " ";
emit_ident(var.ident);
buffer += " ";
emit_name(name);
if (multipart || name.back() == ']' || lsb_at != 0) {
if (var.width == 1)
buffer += " [" + std::to_string(lsb_at) + "]";
else
buffer += " [" + std::to_string(lsb_at + var.width - 1) + ":" + std::to_string(lsb_at) + "]";
}
buffer += " $end\n";
}
void emit_enddefinitions() {
assert(!streaming);
buffer += "$enddefinitions $end\n";
streaming = true;
}
void emit_time(uint64_t timestamp) {
assert(streaming);
buffer += "#" + std::to_string(timestamp) + "\n";
}
void emit_scalar(const variable &var) {
assert(streaming);
assert(var.width == 1);
buffer += (*var.curr ? '1' : '0');
emit_ident(var.ident);
buffer += '\n';
}
void emit_vector(const variable &var) {
assert(streaming);
buffer += 'b';
for (size_t bit = var.width - 1; bit != (size_t)-1; bit--) {
bool bit_curr = var.curr[bit / (8 * sizeof(chunk_t))] & (1 << (bit % (8 * sizeof(chunk_t))));
buffer += (bit_curr ? '1' : '0');
}
buffer += ' ';
emit_ident(var.ident);
buffer += '\n';
}
void reset_outlines() {
for (auto &outline_it : outlines)
outline_it.second = /*warm=*/(outline_it.first == nullptr);
}
variable &register_variable(size_t width, chunk_t *curr, bool constant = false, debug_outline *outline = nullptr) {
if (aliases.count(curr)) {
return variables[aliases[curr]];
} else {
auto outline_it = outlines.emplace(outline, /*warm=*/(outline == nullptr)).first;
const size_t chunks = (width + (sizeof(chunk_t) * 8 - 1)) / (sizeof(chunk_t) * 8);
aliases[curr] = variables.size();
if (constant) {
variables.emplace_back(variable { variables.size(), width, curr, (size_t)-1, outline_it->first, &outline_it->second });
} else {
variables.emplace_back(variable { variables.size(), width, curr, cache.size(), outline_it->first, &outline_it->second });
cache.insert(cache.end(), &curr[0], &curr[chunks]);
}
return variables.back();
}
}
bool test_variable(const variable &var) {
if (var.cache_offset == (size_t)-1)
return false; // constant
if (!*var.outline_warm) {
var.outline->eval();
*var.outline_warm = true;
}
const size_t chunks = (var.width + (sizeof(chunk_t) * 8 - 1)) / (sizeof(chunk_t) * 8);
if (std::equal(&var.curr[0], &var.curr[chunks], &cache[var.cache_offset])) {
return false;
} else {
std::copy(&var.curr[0], &var.curr[chunks], &cache[var.cache_offset]);
return true;
}
}
static std::vector<std::string> split_hierarchy(const std::string &hier_name) {
std::vector<std::string> hierarchy;
size_t prev = 0;
while (true) {
size_t curr = hier_name.find_first_of(' ', prev);
if (curr == std::string::npos) {
hierarchy.push_back(hier_name.substr(prev));
break;
} else {
hierarchy.push_back(hier_name.substr(prev, curr - prev));
prev = curr + 1;
}
}
return hierarchy;
}
public:
std::string buffer;
void timescale(unsigned number, const std::string &unit) {
emit_timescale(number, unit);
}
void add(const std::string &hier_name, const debug_item &item, bool multipart = false) {
std::vector<std::string> scope = split_hierarchy(hier_name);
std::string name = scope.back();
scope.pop_back();
emit_scope(scope);
switch (item.type) {
// Not the best naming but oh well...
case debug_item::VALUE:
emit_var(register_variable(item.width, item.curr, /*constant=*/item.next == nullptr),
"wire", name, item.lsb_at, multipart);
break;
case debug_item::WIRE:
emit_var(register_variable(item.width, item.curr),
"reg", name, item.lsb_at, multipart);
break;
case debug_item::MEMORY: {
const size_t stride = (item.width + (sizeof(chunk_t) * 8 - 1)) / (sizeof(chunk_t) * 8);
for (size_t index = 0; index < item.depth; index++) {
chunk_t *nth_curr = &item.curr[stride * index];
std::string nth_name = name + '[' + std::to_string(index) + ']';
emit_var(register_variable(item.width, nth_curr),
"reg", nth_name, item.lsb_at, multipart);
}
break;
}
case debug_item::ALIAS:
// Like VALUE, but, even though `item.next == nullptr` always holds, the underlying value
// can actually change, and must be tracked. In most cases the VCD identifier will be
// unified with the aliased reg, but we should handle the case where only the alias is
// added to the VCD writer, too.
emit_var(register_variable(item.width, item.curr),
"wire", name, item.lsb_at, multipart);
break;
case debug_item::OUTLINE:
emit_var(register_variable(item.width, item.curr, /*constant=*/false, item.outline),
"wire", name, item.lsb_at, multipart);
break;
}
}
template<class Filter>
void add(const debug_items &items, const Filter &filter) {
// `debug_items` is a map, so the items are already sorted in an order optimal for emitting
// VCD scope sections.
for (auto &it : items.table)
for (auto &part : it.second)
if (filter(it.first, part))
add(it.first, part, it.second.size() > 1);
}
void add(const debug_items &items) {
this->add(items, [](const std::string &, const debug_item &) {
return true;
});
}
void add_without_memories(const debug_items &items) {
this->add(items, [](const std::string &, const debug_item &item) {
return item.type != debug_item::MEMORY;
});
}
void sample(uint64_t timestamp) {
bool first_sample = !streaming;
if (first_sample) {
emit_scope({});
emit_enddefinitions();
}
reset_outlines();
emit_time(timestamp);
for (auto var : variables)
if (test_variable(var) || first_sample) {
if (var.width == 1)
emit_scalar(var);
else
emit_vector(var);
}
}
};
}
#endif