mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-04-06 01:24:10 +00:00
Code Activity

cxxrtl: expose scope information in the C++ API.

Browse source 
This commit adds a `debug_scopes` container, which can collect metadata
about scopes in a design. Currently the only scope is that of a module.
A module scope can be represented either by a module and cell pair, or
a `$scopeinfo` cell in a flattened netlist. The metadata produced by
the C++ API is identical between these two cases, so flattening remains
transparent to a netlist with CXXRTL.

The existing `debug_items` method is deprecated. This isn't strictly
necessary, but the user experience is better if the path is provided
as e.g. `"top "` (as some VCD viewers make it awkward to select topmost
anonymous scope), and the upgrade flow encourages that, which should
reduce frustration later.

While the new `debug_items` method could still be broken in the future
as the C++ API permits, this seems unlikely since the debug information
can now capture all common netlist aspects and includes several
extension points (via `debug_item`, `debug_scope` types).

Also, naming of scope paths was normalized to `path` or `top_path`,
as applicable.
This commit is contained in:
Catherine 2024-02-13 17:43:53 +00:00
parent d903f47d41
commit 1a44645aef
5 changed files with 247 additions and 162 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

314
backends/cxxrtl/cxxrtl_backend.cc
View file

@ -25,6 +25,7 @@
#include "kernel/mem.h" #include "kernel/mem.h"
#include "kernel/log.h" #include "kernel/log.h"
#include "kernel/fmt.h" #include "kernel/fmt.h"
#include "kernel/scopeinfo.h"
USING_YOSYS_NAMESPACE USING_YOSYS_NAMESPACE
PRIVATE_NAMESPACE_BEGIN PRIVATE_NAMESPACE_BEGIN
@ -2311,11 +2312,14 @@ struct CxxrtlWorker {
dict<RTLIL::IdString, RTLIL::Const> attributes = object->attributes; dict<RTLIL::IdString, RTLIL::Const> attributes = object->attributes;
// Inherently necessary to get access to the object, so a waste of space to emit. // Inherently necessary to get access to the object, so a waste of space to emit.
attributes.erase(ID::hdlname); attributes.erase(ID::hdlname);
// Internal Yosys attribute that should be removed but isn't.
attributes.erase(ID::module_not_derived);
dump_metadata_map(attributes); dump_metadata_map(attributes);
} }
void dump_debug_info_method(RTLIL::Module *module) void dump_debug_info_method(RTLIL::Module *module)
{ {
size_t count_scopes = 0;
size_t count_public_wires = 0; size_t count_public_wires = 0;
size_t count_member_wires = 0; size_t count_member_wires = 0;
size_t count_undriven = 0; size_t count_undriven = 0;
@ -2328,153 +2332,188 @@ struct CxxrtlWorker {
size_t count_skipped_wires = 0; size_t count_skipped_wires = 0;
inc_indent(); inc_indent();
f << indent << "assert(path.empty() || path[path.size() - 1] == ' ');\n"; f << indent << "assert(path.empty() || path[path.size() - 1] == ' ');\n";
for (auto wire : module->wires()) { f << indent << "if (scopes) {\n";
const auto &debug_wire_type = debug_wire_types[wire]; inc_indent();
if (!wire->name.isPublic()) // The module is responsible for adding its own scope.
continue; f << indent << "scopes->add(path.empty() ? path : path.substr(0, path.size() - 1), ";
count_public_wires++; f << escape_cxx_string(get_hdl_name(module)) << ", ";
switch (debug_wire_type.type) { dump_debug_attrs(module);
case WireType::BUFFERED: f << ", std::move(cell_attrs));\n";
case WireType::MEMBER: { count_scopes++;
// Member wire // If there were any submodules that were flattened, the module is also responsible for adding them.
std::vector<std::string> flags; for (auto cell : module->cells()) {
if (cell->type != ID($scopeinfo)) continue;
if (wire->port_input && wire->port_output) if (cell->getParam(ID::TYPE).decode_string() == "module") {
flags.push_back("INOUT"); auto module_attrs = scopeinfo_attributes(cell, ScopeinfoAttrs::Module);
else if (wire->port_output) auto cell_attrs = scopeinfo_attributes(cell, ScopeinfoAttrs::Cell);
flags.push_back("OUTPUT"); cell_attrs.erase(ID::module_not_derived);
else if (wire->port_input) f << indent << "scopes->add(path + " << escape_cxx_string(get_hdl_name(cell)) << ", ";
flags.push_back("INPUT"); f << escape_cxx_string(cell->get_string_attribute(ID(module))) << ", ";
dump_metadata_map(module_attrs);
bool has_driven_sync = false; f << ", ";
bool has_driven_comb = false; dump_metadata_map(cell_attrs);
bool has_undriven = false;
if (!module->get_bool_attribute(ID(cxxrtl_blackbox))) {
for (auto bit : SigSpec(wire))
if (!bit_has_state.count(bit))
has_undriven = true;
else if (bit_has_state[bit])
has_driven_sync = true;
else
has_driven_comb = true;
} else if (wire->port_output) {
switch (cxxrtl_port_type(module, wire->name)) {
case CxxrtlPortType::SYNC:
has_driven_sync = true;
break;
case CxxrtlPortType::COMB:
has_driven_comb = true;
break;
case CxxrtlPortType::UNKNOWN:
has_driven_sync = has_driven_comb = true;
break;
}
} else {
has_undriven = true;
}
if (has_undriven)
flags.push_back("UNDRIVEN");
if (!has_driven_sync && !has_driven_comb && has_undriven)
count_undriven++;
if (has_driven_sync)
flags.push_back("DRIVEN_SYNC");
if (has_driven_sync && !has_driven_comb && !has_undriven)
count_driven_sync++;
if (has_driven_comb)
flags.push_back("DRIVEN_COMB");
if (!has_driven_sync && has_driven_comb && !has_undriven)
count_driven_comb++;
if (has_driven_sync + has_driven_comb + has_undriven > 1)
count_mixed_driver++;
f << indent << "items.add(path + " << escape_cxx_string(get_hdl_name(wire));
f << ", debug_item(" << mangle(wire) << ", " << wire->start_offset;
bool first = true;
for (auto flag : flags) {
if (first) {
first = false;
f << ", ";
} else {
f << "|";
}
f << "debug_item::" << flag;
}
f << "), ";
dump_debug_attrs(wire);
f << ");\n"; f << ");\n";
count_member_wires++; } else log_assert(false && "Unknown $scopeinfo type");
break; count_scopes++;
}
case WireType::ALIAS: {
// Alias of a member wire
const RTLIL::Wire *aliasee = debug_wire_type.sig_subst.as_wire();
f << indent << "items.add(path + " << escape_cxx_string(get_hdl_name(wire));
f << ", debug_item(";
// If the aliasee is an outline, then the alias must be an outline, too; otherwise downstream
// tooling has no way to find out about the outline.
if (debug_wire_types[aliasee].is_outline())
f << "debug_eval_outline";
else
f << "debug_alias()";
f << ", " << mangle(aliasee) << ", " << wire->start_offset << "), ";
dump_debug_attrs(aliasee);
f << ");\n";
count_alias_wires++;
break;
}
case WireType::CONST: {
// Wire tied to a constant
f << indent << "static const value<" << wire->width << "> const_" << mangle(wire) << " = ";
dump_const(debug_wire_type.sig_subst.as_const());
f << ";\n";
f << indent << "items.add(path + " << escape_cxx_string(get_hdl_name(wire));
f << ", debug_item(const_" << mangle(wire) << ", " << wire->start_offset << "), ";
dump_debug_attrs(wire);
f << ");\n";
count_const_wires++;
break;
}
case WireType::OUTLINE: {
// Localized or inlined, but rematerializable wire
f << indent << "items.add(path + " << escape_cxx_string(get_hdl_name(wire));
f << ", debug_item(debug_eval_outline, " << mangle(wire) << ", " << wire->start_offset << "), ";
dump_debug_attrs(wire);
f << ");\n";
count_inline_wires++;
break;
}
default: {
// Localized or inlined wire with no debug information
count_skipped_wires++;
break;
}
} }
} dec_indent();
if (!module->get_bool_attribute(ID(cxxrtl_blackbox))) { f << indent << "}\n";
for (auto &mem : mod_memories[module]) { f << indent << "if (items) {\n";
if (!mem.memid.isPublic()) inc_indent();
for (auto wire : module->wires()) {
const auto &debug_wire_type = debug_wire_types[wire];
if (!wire->name.isPublic())
continue; continue;
f << indent << "items.add(path + " << escape_cxx_string(mem.packed ? get_hdl_name(mem.cell) : get_hdl_name(mem.mem)); count_public_wires++;
f << ", debug_item(" << mangle(&mem) << ", "; switch (debug_wire_type.type) {
f << mem.start_offset << "), "; case WireType::BUFFERED:
if (mem.packed) { case WireType::MEMBER: {
dump_debug_attrs(mem.cell); // Member wire
} else { std::vector<std::string> flags;
dump_debug_attrs(mem.mem);
if (wire->port_input && wire->port_output)
flags.push_back("INOUT");
else if (wire->port_output)
flags.push_back("OUTPUT");
else if (wire->port_input)
flags.push_back("INPUT");
bool has_driven_sync = false;
bool has_driven_comb = false;
bool has_undriven = false;
if (!module->get_bool_attribute(ID(cxxrtl_blackbox))) {
for (auto bit : SigSpec(wire))
if (!bit_has_state.count(bit))
has_undriven = true;
else if (bit_has_state[bit])
has_driven_sync = true;
else
has_driven_comb = true;
} else if (wire->port_output) {
switch (cxxrtl_port_type(module, wire->name)) {
case CxxrtlPortType::SYNC:
has_driven_sync = true;
break;
case CxxrtlPortType::COMB:
has_driven_comb = true;
break;
case CxxrtlPortType::UNKNOWN:
has_driven_sync = has_driven_comb = true;
break;
}
} else {
has_undriven = true;
}
if (has_undriven)
flags.push_back("UNDRIVEN");
if (!has_driven_sync && !has_driven_comb && has_undriven)
count_undriven++;
if (has_driven_sync)
flags.push_back("DRIVEN_SYNC");
if (has_driven_sync && !has_driven_comb && !has_undriven)
count_driven_sync++;
if (has_driven_comb)
flags.push_back("DRIVEN_COMB");
if (!has_driven_sync && has_driven_comb && !has_undriven)
count_driven_comb++;
if (has_driven_sync + has_driven_comb + has_undriven > 1)
count_mixed_driver++;
f << indent << "items->add(path + " << escape_cxx_string(get_hdl_name(wire));
f << ", debug_item(" << mangle(wire) << ", " << wire->start_offset;
bool first = true;
for (auto flag : flags) {
if (first) {
first = false;
f << ", ";
} else {
f << "|";
}
f << "debug_item::" << flag;
}
f << "), ";
dump_debug_attrs(wire);
f << ");\n";
count_member_wires++;
break;
}
case WireType::ALIAS: {
// Alias of a member wire
const RTLIL::Wire *aliasee = debug_wire_type.sig_subst.as_wire();
f << indent << "items->add(path + " << escape_cxx_string(get_hdl_name(wire));
f << ", debug_item(";
// If the aliasee is an outline, then the alias must be an outline, too; otherwise downstream
// tooling has no way to find out about the outline.
if (debug_wire_types[aliasee].is_outline())
f << "debug_eval_outline";
else
f << "debug_alias()";
f << ", " << mangle(aliasee) << ", " << wire->start_offset << "), ";
dump_debug_attrs(aliasee);
f << ");\n";
count_alias_wires++;
break;
}
case WireType::CONST: {
// Wire tied to a constant
f << indent << "static const value<" << wire->width << "> const_" << mangle(wire) << " = ";
dump_const(debug_wire_type.sig_subst.as_const());
f << ";\n";
f << indent << "items->add(path + " << escape_cxx_string(get_hdl_name(wire));
f << ", debug_item(const_" << mangle(wire) << ", " << wire->start_offset << "), ";
dump_debug_attrs(wire);
f << ");\n";
count_const_wires++;
break;
}
case WireType::OUTLINE: {
// Localized or inlined, but rematerializable wire
f << indent << "items->add(path + " << escape_cxx_string(get_hdl_name(wire));
f << ", debug_item(debug_eval_outline, " << mangle(wire) << ", " << wire->start_offset << "), ";
dump_debug_attrs(wire);
f << ");\n";
count_inline_wires++;
break;
}
default: {
// Localized or inlined wire with no debug information
count_skipped_wires++;
break;
}
} }
f << ");\n";
} }
if (!module->get_bool_attribute(ID(cxxrtl_blackbox))) {
for (auto &mem : mod_memories[module]) {
if (!mem.memid.isPublic())
continue;
f << indent << "items->add(path + " << escape_cxx_string(mem.packed ? get_hdl_name(mem.cell) : get_hdl_name(mem.mem));
f << ", debug_item(" << mangle(&mem) << ", ";
f << mem.start_offset << "), ";
if (mem.packed) {
dump_debug_attrs(mem.cell);
} else {
dump_debug_attrs(mem.mem);
}
f << ");\n";
}
}
dec_indent();
f << indent << "}\n";
if (!module->get_bool_attribute(ID(cxxrtl_blackbox))) {
for (auto cell : module->cells()) { for (auto cell : module->cells()) {
if (is_internal_cell(cell->type)) if (is_internal_cell(cell->type))
continue; continue;
const char *access = is_cxxrtl_blackbox_cell(cell) ? "->" : "."; const char *access = is_cxxrtl_blackbox_cell(cell) ? "->" : ".";
f << indent << mangle(cell) << access << "debug_info(items, "; f << indent << mangle(cell) << access;
f << "path + " << escape_cxx_string(get_hdl_name(cell) + ' ') << ");\n"; f << "debug_info(items, scopes, path + " << escape_cxx_string(get_hdl_name(cell) + ' ') << ", ";
dump_debug_attrs(cell);
f << ");\n";
} }
} }
dec_indent(); dec_indent();
log_debug("Debug information statistics for module `%s':\n", log_id(module)); log_debug("Debug information statistics for module `%s':\n", log_id(module));
log_debug(" Scopes: %zu", count_scopes);
log_debug(" Public wires: %zu, of which:\n", count_public_wires); log_debug(" Public wires: %zu, of which:\n", count_public_wires);
log_debug(" Member wires: %zu, of which:\n", count_member_wires); log_debug(" Member wires: %zu, of which:\n", count_member_wires);
log_debug(" Undriven: %zu (incl. inputs)\n", count_undriven); log_debug(" Undriven: %zu (incl. inputs)\n", count_undriven);
@ -2522,7 +2561,8 @@ struct CxxrtlWorker {
f << indent << "}\n"; f << indent << "}\n";
if (debug_info) { if (debug_info) {
f << "\n"; f << "\n";
f << indent << "void debug_info(debug_items &items, std::string path = \"\") override {\n"; f << indent << "void debug_info(debug_items *items, debug_scopes *scopes, "
<< "std::string path, metadata_map &&cell_attrs = {}) override {\n";
dump_debug_info_method(module); dump_debug_info_method(module);
f << indent << "}\n"; f << indent << "}\n";
} }
@ -2631,7 +2671,8 @@ struct CxxrtlWorker {
} }
} }
f << "\n"; f << "\n";
f << indent << "void debug_info(debug_items &items, std::string path = \"\") override;\n"; f << indent << "void debug_info(debug_items *items, debug_scopes *scopes, "
<< "std::string path, metadata_map &&cell_attrs = {}) override;\n";
} }
dec_indent(); dec_indent();
f << indent << "}; // struct " << mangle(module) << "\n"; f << indent << "}; // struct " << mangle(module) << "\n";
@ -2659,7 +2700,8 @@ struct CxxrtlWorker {
} }
f << "\n"; f << "\n";
f << indent << "CXXRTL_EXTREMELY_COLD\n"; f << indent << "CXXRTL_EXTREMELY_COLD\n";
f << indent << "void " << mangle(module) << "::debug_info(debug_items &items, std::string path) {\n"; f << indent << "void " << mangle(module) << "::debug_info(debug_items *items, debug_scopes *scopes, "
<< "std::string path, metadata_map &&cell_attrs) {\n";
dump_debug_info_method(module); dump_debug_info_method(module);
f << indent << "}\n"; f << indent << "}\n";
} }

12
backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.cc
View file

@ -35,19 +35,19 @@ cxxrtl_handle cxxrtl_create(cxxrtl_toplevel design) {
return cxxrtl_create_at(design, ""); return cxxrtl_create_at(design, "");
} }
cxxrtl_handle cxxrtl_create_at(cxxrtl_toplevel design, const char *root) { cxxrtl_handle cxxrtl_create_at(cxxrtl_toplevel design, const char *top_path_) {
std::string path = root; std::string top_path = top_path_;
if (!path.empty()) { if (!top_path.empty()) {
// module::debug_info() accepts either an empty path, or a path ending in space to simplify // 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 // 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. // would be a lot worse in the C API, so don't expose it here.
assert(path.back() != ' '); assert(top_path.back() != ' ');
path += ' '; top_path += ' ';
} }
cxxrtl_handle handle = new _cxxrtl_handle; cxxrtl_handle handle = new _cxxrtl_handle;
handle->module = std::move(design->module); handle->module = std::move(design->module);
handle->module->debug_info(handle->objects, path); handle->module->debug_info(handle->objects, top_path);
delete design; delete design;
return handle; return handle;
} }

4
backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.h
View file

@ -55,8 +55,8 @@ cxxrtl_handle cxxrtl_create(cxxrtl_toplevel design);
// Create a design handle at a given hierarchy position from a design toplevel. // 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 // This operation is similar to `cxxrtl_create`, except the full hierarchical name of every object
// is prepended with `root`. // is prepended with `top_path`.
cxxrtl_handle cxxrtl_create_at(cxxrtl_toplevel design, const char *root); cxxrtl_handle cxxrtl_create_at(cxxrtl_toplevel design, const char *top_path);
// Release all resources used by a design and its handle. // Release all resources used by a design and its handle.
void cxxrtl_destroy(cxxrtl_handle handle); void cxxrtl_destroy(cxxrtl_handle handle);

70
backends/cxxrtl/runtime/cxxrtl/cxxrtl.h
View file

@ -1331,14 +1331,15 @@ struct debug_items {
std::map<std::string, std::vector<debug_item>> table; std::map<std::string, std::vector<debug_item>> table;
std::map<std::string, std::unique_ptr<debug_attrs>> attrs_table; std::map<std::string, std::unique_ptr<debug_attrs>> attrs_table;
void add(const std::string &name, debug_item &&item, metadata_map &&item_attrs = {}) { void add(const std::string &path, debug_item &&item, metadata_map &&item_attrs = {}) {
std::unique_ptr<debug_attrs> &attrs = attrs_table[name]; assert((path.empty() || path[path.size() - 1] != ' ') && path.find(" ") == std::string::npos);
std::unique_ptr<debug_attrs> &attrs = attrs_table[path];
if (attrs.get() == nullptr) if (attrs.get() == nullptr)
attrs = std::unique_ptr<debug_attrs>(new debug_attrs); attrs = std::unique_ptr<debug_attrs>(new debug_attrs);
for (auto attr : item_attrs) for (auto attr : item_attrs)
attrs->map.insert(attr); attrs->map.insert(attr);
item.attrs = attrs.get(); item.attrs = attrs.get();
std::vector<debug_item> &parts = table[name]; std::vector<debug_item> &parts = table[path];
parts.emplace_back(item); parts.emplace_back(item);
std::sort(parts.begin(), parts.end(), std::sort(parts.begin(), parts.end(),
[](const debug_item &a, const debug_item &b) { [](const debug_item &a, const debug_item &b) {
@ -1346,25 +1347,58 @@ struct debug_items {
}); });
} }
size_t count(const std::string &name) const { size_t count(const std::string &path) const {
if (table.count(name) == 0) if (table.count(path) == 0)
return 0; return 0;
return table.at(name).size(); return table.at(path).size();
} }
const std::vector<debug_item> &at(const std::string &name) const { const std::vector<debug_item> &at(const std::string &path) const {
return table.at(name); return table.at(path);
} }
// Like `at()`, but operates only on single-part debug items. // Like `at()`, but operates only on single-part debug items.
const debug_item &operator [](const std::string &name) const { const debug_item &operator [](const std::string &path) const {
const std::vector<debug_item> &parts = table.at(name); const std::vector<debug_item> &parts = table.at(path);
assert(parts.size() == 1); assert(parts.size() == 1);
return parts.at(0); return parts.at(0);
} }
const metadata_map &attrs(const std::string &name) const { bool is_memory(const std::string &path) const {
return attrs_table.at(name)->map; return at(path).at(0).type == debug_item::MEMORY;
}
const metadata_map &attrs(const std::string &path) const {
return attrs_table.at(path)->map;
}
};
// Only `module` scopes are defined. The type is implicit, since Yosys does not currently support
// any other scope types.
struct debug_scope {
std::string module_name;
std::unique_ptr<debug_attrs> module_attrs;
std::unique_ptr<debug_attrs> cell_attrs;
};
struct debug_scopes {
std::map<std::string, debug_scope> table;
void add(const std::string &path, const std::string &module_name, metadata_map &&module_attrs, metadata_map &&cell_attrs) {
assert((path.empty() || path[path.size() - 1] != ' ') && path.find(" ") == std::string::npos);
assert(table.count(path) == 0);
debug_scope &scope = table[path];
scope.module_name = module_name;
scope.module_attrs = std::unique_ptr<debug_attrs>(new debug_attrs { module_attrs });
scope.cell_attrs = std::unique_ptr<debug_attrs>(new debug_attrs { cell_attrs });
}
size_t contains(const std::string &path) const {
return table.count(path);
}
const debug_scope &operator [](const std::string &path) const {
return table.at(path);
} }
}; };
@ -1412,8 +1446,16 @@ struct module {
return deltas; return deltas;
} }
virtual void debug_info(debug_items &items, std::string path = "") { virtual void debug_info(debug_items *items, debug_scopes *scopes, std::string path, metadata_map &&cell_attrs = {}) {
(void)items, (void)path; (void)items, (void)scopes, (void)path, (void)cell_attrs;
}
// Compatibility method.
#if __has_attribute(deprecated)
__attribute__((deprecated("Use `debug_info(path, &items, /*scopes=*/nullptr);` instead. (`path` could be \"top \".)")))
#endif
void debug_info(debug_items &items, std::string path) {
debug_info(&items, /*scopes=*/nullptr, path);
} }
}; };

9
backends/cxxrtl/runtime/cxxrtl/cxxrtl_replay.h
View file

@ -491,9 +491,9 @@ public:
template<typename ...Args> template<typename ...Args>
recorder(Args &&...args) : writer(std::forward<Args>(args)...) {} recorder(Args &&...args) : writer(std::forward<Args>(args)...) {}
void start(module &module) { void start(module &module, std::string top_path = "") {
debug_items items; debug_items items;
module.debug_info(items); module.debug_info(&items, /*scopes=*/nullptr, top_path);
start(items); start(items);
} }
@ -621,9 +621,10 @@ public:
template<typename ...Args> template<typename ...Args>
player(Args &&...args) : reader(std::forward<Args>(args)...) {} player(Args &&...args) : reader(std::forward<Args>(args)...) {}
void start(module &module) { // The `top_path` must match the one given to the recorder.
void start(module &module, std::string top_path = "") {
debug_items items; debug_items items;
module.debug_info(items); module.debug_info(&items, /*scopes=*/nullptr, top_path);
start(items); start(items);
} }