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.
22 // This file is a part of the CXXRTL C API. It should be used together with `cxxrtl_capi.cc`.
24 // The CXXRTL C API makes it possible to drive CXXRTL designs using C or any other language that
25 // supports the C ABI, for example, Python. It does not provide a way to implement black boxes.
34 // Opaque reference to a design toplevel.
36 // A design toplevel can only be used to create a design handle.
37 typedef struct _cxxrtl_toplevel
*cxxrtl_toplevel
;
39 // The constructor for a design toplevel is provided as a part of generated code for that design.
40 // Its prototype matches:
42 // cxxrtl_toplevel <design-name>_create();
44 // Opaque reference to a design handle.
46 // A design handle is required by all operations in the C API.
47 typedef struct _cxxrtl_handle
*cxxrtl_handle
;
49 // Create a design handle from a design toplevel.
51 // The `design` is consumed by this operation and cannot be used afterwards.
52 cxxrtl_handle
cxxrtl_create(cxxrtl_toplevel design
);
54 // Release all resources used by a design and its handle.
55 void cxxrtl_destroy(cxxrtl_handle handle
);
57 // Simulate the design to a fixed point.
59 // Returns the number of delta cycles.
60 size_t cxxrtl_step(cxxrtl_handle handle
);
62 // Type of a simulated object.
64 // Values correspond to singly buffered netlist nodes, i.e. nodes driven exclusively by
65 // combinatorial cells, or toplevel input nodes.
67 // Values can be inspected via the `curr` pointer. If the `next` pointer is NULL, the value is
68 // driven by a constant and can never be modified. Otherwise, the value can be modified through
69 // the `next` pointer (which is equal to `curr` if not NULL). Note that changes to the bits
70 // driven by combinatorial cells will be ignored.
72 // Values always have depth 1.
75 // Wires correspond to doubly buffered netlist nodes, i.e. nodes driven, at least in part, by
76 // storage cells, or by combinatorial cells that are a part of a feedback path.
78 // Wires can be inspected via the `curr` pointer and modified via the `next` pointer (which are
79 // distinct for wires). Note that changes to the bits driven by combinatorial cells will be
82 // Wires always have depth 1.
85 // Memories correspond to memory cells.
87 // Memories can be inspected and modified via the `curr` pointer. Due to a limitation of this
88 // API, memories cannot yet be modified in a guaranteed race-free way, and the `next` pointer is
92 // Aliases correspond to netlist nodes driven by another node such that their value is always
93 // exactly equal, or driven by a constant value.
95 // Aliases can be inspected via the `curr` pointer. They cannot be modified, and the `next`
96 // pointer is always NULL.
99 // More object types may be added in the future, but the existing ones will never change.
102 // Description of a simulated object.
104 // The `data` array can be accessed directly to inspect and, if applicable, modify the bits
105 // stored in the object.
106 struct cxxrtl_object
{
107 // Type of the object.
109 // All objects have the same memory layout determined by `width` and `depth`, but the type
110 // determines all other properties of the object.
111 uint32_t type
; // actually `enum cxxrtl_type`
113 // Width of the object in bits.
116 // Depth of the object. Only meaningful for memories; for other objects, always 1.
119 // Bits stored in the object, as 32-bit chunks, least significant bits first.
121 // The width is rounded up to a multiple of 32; the padding bits are always set to 0 by
122 // the simulation code, and must be always written as 0 when modified by user code.
123 // In memories, every element is stored contiguously. Therefore, the total number of chunks
124 // in any object is `((width + 31) / 32) * depth`.
126 // To allow the simulation to be partitioned into multiple independent units communicating
127 // through wires, the bits are double buffered. To avoid race conditions, user code should
128 // always read from `curr` and write to `next`. The `curr` pointer is always valid; for objects
129 // that cannot be modified, or cannot be modified in a race-free way, `next` is NULL.
133 // More description fields may be added in the future, but the existing ones will never change.
136 // Retrieve description of a simulated object.
138 // The `name` is the full hierarchical name of the object in the Yosys notation, where public names
139 // have a `\` prefix and hierarchy levels are separated by single spaces. For example, if
140 // the top-level module instantiates a module `foo`, which in turn contains a wire `bar`, the full
141 // hierarchical name is `\foo \bar`.
143 // Returns the object if it was found, NULL otherwise. The returned value is valid until the design
145 struct cxxrtl_object
*cxxrtl_get(cxxrtl_handle handle
, const char *name
);
147 // Enumerate simulated objects.
149 // For every object in the simulation, `callback` is called with the provided `data`, the full
150 // hierarchical name of the object (see `cxxrtl_get` for details), and the object description.
151 // The provided `name` and `object` values are valid until the design is destroyed.
152 void cxxrtl_enum(cxxrtl_handle handle
, void *data
,
153 void (*callback
)(void *data
, const char *name
, struct cxxrtl_object
*object
));