Merge pull request #2485 from whitequark/cxxrtl-cell-input-buffering

[yosys.git] / backends / cxxrtl / cxxrtl_capi.h

diff --git a/backends/cxxrtl/cxxrtl_capi.h b/backends/cxxrtl/cxxrtl_capi.h
index d2e9787dd4d1adeda79122519728f121a387b004..d67c58f94d1f64087bb72a7050179a706c2cf14a 100644 (file)
--- a/backends/cxxrtl/cxxrtl_capi.h
+++ b/backends/cxxrtl/cxxrtl_capi.h
@@ -52,9 +52,23 @@ typedef struct _cxxrtl_handle *cxxrtl_handle;
 // 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.
 //
@@ -73,6 +87,10 @@ int cxxrtl_commit(cxxrtl_handle handle);
 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.
@@ -86,7 +104,8 @@ enum cxxrtl_type {
        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.
+       // 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
@@ -113,6 +132,12 @@ enum cxxrtl_type {
 };
 
 // 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.
        //
@@ -131,6 +156,38 @@ enum cxxrtl_flag {
        // 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` and `CXXRTL_WIRE`. 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.
 };