b_asic.code_printer.vhdl¶
B-ASIC code generation module for VHDL.
vhdl_printer module¶
- class b_asic.code_printer.vhdl.vhdl_printer.VhdlPrinter(dt: DataType, vhdl_2008: bool = False)
Generate VHDL source files for an
Architecture.- Parameters:
- dt
DataType Data type configuration used for generated VHDL.
- vhdl_2008bool, default: False
Enable VHDL-2008 specific output where applicable.
- dt
- get_compile_order(arch: Architecture) list[str]
Return the file names for the VHDL code describing the provided architecture.
- Parameters:
- arch
Architecture instance used to determine the compile order of the generated VHDL files.
- print(arch: Architecture, *, path: str | Path = PosixPath('.'), vhdl_ls: bool = False, **kwargs) None
Write VHDL files for an
Architecture.- Parameters:
- arch
Architecture Architecture instance to generate code for.
- pathstr | Path, optional
Output directory. Defaults to the current directory.
- vhdl_lsbool, default
False Also write a
vhdl_ls.tomlconfiguration file for the VHDL Language Server alongside the generated VHDL files.- **kwargs
Optional VHDL code-generation settings. For info, see Notes.
- arch
Notes
Recognised keyword arguments, grouped by the component they affect:
Top-level / architecture
- io_registers
bool, defaultFalse Insert registers on all top-level I/O ports. Equivalent to setting both
input_registerandoutput_register.- input_register
bool, defaultFalse Insert registers on the top-level input ports only.
- output_register
bool, defaultFalse Insert registers on the top-level output ports only.
- multiplexer_control_registered
bool, defaultFalse Register multiplexer control signals in generated top-level.
- enable_pin
bool, defaultTrue Whether to include an enable pin on the top-level entity.
- interface
StreamInterface, optional Select synchronous I/O (default), AXI4-Stream, or Avalon-ST, FIFO sizing, clock mode, and whether the core may stall.
- stream_inputs, stream_outputs
dict, optional Map physical stream names to lists of input/output PE entity names. Scheduled transfers from grouped resources share one FIFO in schedule order. Unlisted resources get their own stream.
- centralize_control
bool, defaultTrue Generate a shared schedule-indexed control ROM in the top-level architecture instead of distributed control generation.
- pipeline_control
bool, defaultFalse Register all outputs of the centralized control ROM. Component control pipeline options must agree with this setting when supplied. This option requires centralized control.
Processing elements
- fp_backend
strordict[str,str] Floating-point IP backend to use. Pass a string to apply the same backend to every PE, or a
{entity_name: backend}dict to select on a per-PE basis.- pe_registers
dict[str,tuple[int,int]] Register split
(pre, post)inserted around the operator of a PE. Keys are either the PE entity name or the PE type name.- control_cycle
dict Clock cycle inside an operation at which each control signal becomes available.
- pipeline_pe_control
bool, defaultFalse Register PE control signals after generation.
Memories (RAM)
- output_sync
bool, defaultTrue Place output registers after memory read.
- external_schedule_counter
bool, defaultTrue Use an external schedule counter signal. Ignored when centralize_control is
Truesince no counter is needed.- std_logic_vector
bool, defaultFalse Use
std_logic_vectordata instead ofsigned/unsigned.- pipeline_mem_control
bool, defaultFalse Register memory control signals after generation.
External memory I/O
MemoryReadandMemoryWritegenerate one interface per memory name used by a PE. Names are sorted and numbered from zero; the generated PE comments record the mapping. Each interface has<pe>_memory_<index>_addressand<pe>_memory_<index>_enableoutputs, and data ports following the normal I/O naming convention. Address widths use the largest address on that interface, with a minimum of one bit. Enables are low during reset, disabled cycles, and cycles without an access. Read requests occur at operation start; data is expected at start plus read latency. The latency belongs to the external memory; no additional PE or top-level I/O registers are inserted in these interfaces.Memories (register-based)
- external_schedule_counter
bool, defaultTrue Use an external schedule counter signal.
- std_logic_vector
bool, defaultFalse Use
std_logic_vectordata.- pipeline_output_mux
bool, defaultFalse Register the output multiplexer select signal.
- pipeline_back_edge_mux
bool, defaultFalse Register the back-edge multiplexer select signal.
- print_vhdl_ls_toml(arch: Architecture, *, path: str | Path = PosixPath('.'), lib_name: str = 'lib') None
Write a
vhdl_ls.tomlconfiguration file for the VHDL Language Server.- Parameters:
- arch
Architecture Architecture instance used to determine the file list.
- pathstr | Path, optional
Output directory (same directory where VHDL files were written). Defaults to the current directory.
- lib_namestr, optional
Library name used in the toml file. Defaults to
"lib".
- arch
Streaming interfaces¶
Interface selection belongs to code generation. It does not change the SFG or its Input/Output operations. The default retains the fixed-interval synchronous ports. For example:
from b_asic.code_printer.vhdl.streaming import StreamInterface
printer.print(
architecture,
path="hdl",
interface=StreamInterface(
protocol="axi4_stream", # or "avalon_st", "synchronous"
clock_mode="asynchronous", # or "synchronous" (shared core clock)
fifo_depth=64,
startup_threshold=32,
stallable=True,
frame_length=1024,
),
stream_inputs={"samples": ["input0", "input1"]},
stream_outputs={"results": ["output0"]},
)
Group members are processing-element entity names, not operation names. Multiple operations already assigned to one input/output PE naturally share its stream. Grouping several PEs combines their transfers in increasing schedule order; each group must require at most one transfer per core cycle. The input stream must supply samples in that order; there is no stream-ID routing. Unlisted I/O PEs each receive a separate stream named after the PE.
Each stream has data, valid, ready, and TLAST/endofpacket ports. AXI names use
<stream>_tdata, _tvalid, _tready, and _tlast. Avalon names use
<stream>_data, _valid, _ready, and _endofpacket; Avalon ready
latency is zero. AXI data is padded to whole bytes with zero high bits; input
padding is ignored. Complex samples pack real bits below imaginary bits.
The sample widths follow the printer’s input/output data types.
Each group gets its own input or output FIFO. A shared-clock interface uses a
synchronous FIFO (any positive depth). Independent-clock interfaces add a
<stream>_clk port per stream and use Gray-coded pointers with two-stage
synchronizers; depth must be a power of two, at least four. The core always uses
clk. rst resets both sides, discards buffered data and framing state,
and clears errors. Assert reset across both clocks; release in the FIFO is
synchronized locally. Both clocks must run during reset recovery. Occupancy
flags in independent-clock mode include pointer synchronization delay. The
generated RAM uses show-ahead asynchronous reads; device-specific block RAM
inference is not guaranteed. Constrain Gray-pointer crossings with the target
tool’s bus-skew/max-delay constraints and mark clocks as asynchronous; the
generator supplies synchronizer attributes, but does not generate device timing
constraints.
The core waits until every input FIFO reaches startup_threshold. With
stallable=True, unavailable input samples or full output FIFOs disable the
entire core, including its schedule counter, memories, and enabled pipelines.
FIFO bus transfers continue during pauses, including when external en is
low. core_active indicates enabled core cycles. Custom arithmetic IP must
honor its enable for this mode to be safe. Optional top-level I/O registers
cannot be combined with streaming; the FIFOs provide the interface buffering.
With stallable=False, the core runs at fixed intervals after startup. Empty
input FIFOs at scheduled reads or full output FIFOs at scheduled writes latch
stream_error and stop further core execution until reset. Data from the
faulting cycle is invalid. Size the input threshold for a bounded source gap
and the output FIFO for the maximum downstream stall: no finite FIFO can
guarantee operation through an unlimited stall or sustained rate mismatch.
External en remains available for deliberate pauses; enable_pin=False
removes it while retaining internal startup/fault/stall control.
Input TLAST/EOP is stored in the FIFO word. <stream>_core_last is meaningful
when <stream>_core_valid is high, identifying the sample consumed on the next
core rising edge. These signals expose framing to surrounding logic; the
arithmetic SFG does not itself interpret packet metadata. Output framing counts
successful core-to-FIFO writes and marks every frame_length-th sample.
It stays aligned with data under backpressure. When frame_length=None, the
output frame marker is always low; variable input packet boundaries are not
automatically propagated through arithmetic transformations.
common module¶
Generation of common VHDL constructs.
- b_asic.code_printer.vhdl.common.alias_declaration(f: TextIO, name: str, signal_type: str, value: str | None = None, name_pad: int | None = None) None¶
- b_asic.code_printer.vhdl.common.asynchronous_read_memory(f: TextIO, clk: str, read_ports: set[tuple[str, str]], write_ports: set[tuple[str, str, str]], name: str | None = None, enable: str | None = None, use_to_integer: bool = True) None¶
Infer a VHDL memory with synchronous writes and asynchronous reads.
- Parameters:
- fTextIO
The TextIO to write the VHDL code onto.
- clkstr
Name of clock identifier to the synchronous memory.
- read_portsSet[Tuple[str,str]]
A set of strings used as identifiers for the read ports of the memory.
- write_portsSet[Tuple[str,str,str]]
A set of strings used as identifiers for the write ports of the memory.
- namestr, optional
An optional name for the memory process.
- enablestr, optional
An optional enable signal to gate the memory writes.
- use_to_integerbool, default: True
Wrap address signals in
to_integer(). Set to False when the address signal is already an integer type.
- b_asic.code_printer.vhdl.common.b_asic_preamble(f: TextIO) None¶
Write a standard B-ASIC VHDL preamble comment.
- Parameters:
- fTextIO
The file object to write the header to.
- b_asic.code_printer.vhdl.common.blank(f: TextIO) None¶
Write a blank line.
- Parameters:
- fTextIO
The file object to emit VHDL code to.
- b_asic.code_printer.vhdl.common.component_declaration(f: TextIO, entity_name: str, generics: list[str] | None = None, ports: list[str] | None = None, indent: int = 1) None¶
- b_asic.code_printer.vhdl.common.component_instantiation(f: TextIO, label: str, entity_name: str, generic_mappings: list[str] | None = None, port_mappings: list[str] | None = None, indent: int = 1) None¶
- b_asic.code_printer.vhdl.common.constant_declaration(f: TextIO, name: str, signal_type: str, value: Any, name_pad: int | None = None) None¶
Write a VHDL constant declaration with a name, a type and a value.
- Parameters:
- fTextIO
The TextIO object to write the constant declaration to.
- namestr
Signal name.
- signal_typestr
Signal type.
- valueanything convertible to str
Default value to the signal.
- name_padint, optional
An optional left padding value applied to the name.
- b_asic.code_printer.vhdl.common.entity_declaration(f: TextIO, entity_name: str, generics: list[str] | None = None, ports: list[str] | None = None, indent: int = 0) None¶
- b_asic.code_printer.vhdl.common.ieee_header(f: TextIO, std_logic_1164: bool = True, numeric_std: bool = True, fixed_pkg: bool = False) None¶
Write the standard IEEE VHDL use header.
This includes std_logic_1164 and numeric_std.
- Parameters:
- fTextIO
The TextIO object to write the IEEE header to.
- std_logic_1164bool, default: True
Include the std_logic_1164 header.
- numeric_stdbool, default: True
Include the numeric_std header.
- fixed_pkgbool, default: False
Include the fixed_pkg header.
- b_asic.code_printer.vhdl.common.is_valid_vhdl_identifier(identifier: str) bool¶
Test if identifier is a valid VHDL identifier, as specified by VHDL 2019.
An identifier is a valid VHDL identifier if it is not a VHDL reserved keyword and it is a valid basic identifier as specified by IEEE STD 1076-2019 (VHDL standard).
- Parameters:
- identifierstr
The identifier to test.
- Returns:
- bool
True if identifier is a valid VHDL identifier, False otherwise.
- b_asic.code_printer.vhdl.common.is_vhdl_reserved_keyword(identifier: str) bool¶
Test if identifier is a reserved VHDL keyword.
- Parameters:
- identifierstr
The identifier to test.
- Returns:
- bool
True if identifier is a reserved VHDL keyword, False otherwise.
- b_asic.code_printer.vhdl.common.process_epilogue(f: TextIO, sensitivity_list: str | None = None, indent: int = 1, name: str | None = None) None¶
Write the epilogue of a regular VHDL process.
- Parameters:
- fTextIO
The TextIO object to write the type declaration to.
- sensitivity_liststr, optional
Content of the process sensitivity list. Not needed when writing the epilogue.
- indentint, default: 1
Indentation level to use for this process.
- indentint, default: 1
Indentation level to use for this process.
- namestr, optional
An optional name of the ending process.
- b_asic.code_printer.vhdl.common.process_prologue(f: TextIO, sensitivity_list: str, indent: int = 1, name: str | None = None) None¶
Write the prologue of a regular VHDL process with a user provided sensitivity list.
This method should almost always be followed by a
process_epilogue().- Parameters:
- fTextIO
The TextIO object to write the type declaration to.
- sensitivity_liststr
Content of the process sensitivity list.
- indentint, default: 1
Indentation level to use for this process.
- namestr, optional
An optional name for the process.
- b_asic.code_printer.vhdl.common.signal_declaration(f: TextIO, name: str, signal_type: str, default_value: str | None = None, indent: int = 1, name_pad: int | None = None, vivado_ram_style: Literal['block', 'distributed', 'registers', 'ultra', 'mixed', 'auto'] | None = None, quartus_ram_style: Literal['M4K', 'M9K', 'M10K', 'M20K', 'M144K', 'MLAB', 'logic'] | None = None) None¶
Create a VHDL signal declaration.
The declaration looks like:
signal {name} : {type} [:= {default_value}];
- Parameters:
- fTextIO
The TextIO object to write the IEEE header to.
- namestr
Signal name.
- signal_typestr
Signal type.
- indentint, optional
Indentation level to use for this process.
- default_valuestr, optional
An optional default value to the signal.
- name_padint, optional
An optional left padding value applied to the name.
- vivado_ram_stylestr, optional
An optional Xilinx Vivado RAM style attribute to apply to this signal declaration. If set, exactly one of: “block”, “distributed”, “registers”, “ultra”, “mixed” or “auto”.
- quartus_ram_stylestr, optional
An optional Quartus Prime RAM style attribute to apply to this signal declaration. If set, exactly one of: “M4K”, “M9K”, “M10K”, “M20K”, “M144K”, “MLAB” or “logic”.
- b_asic.code_printer.vhdl.common.synchronous_memory(f: TextIO, clk: str, read_ports: set[tuple[str, str, str]], write_ports: set[tuple[str, str, str]], name: str | None = None) None¶
Infer a VHDL synchronous reads and writes.
- Parameters:
- fTextIO
The TextIO to write the VHDL code onto.
- clkstr
Name of clock identifier to the synchronous memory.
- read_portsSet[Tuple[str,str]]
A set of strings used as identifiers for the read ports of the memory.
- write_portsSet[Tuple[str,str,str]]
A set of strings used as identifiers for the write ports of the memory.
- namestr, optional
An optional name for the memory process.
- b_asic.code_printer.vhdl.common.synchronous_process(f: TextIO, clk: str, body: str, indent: int = 1, name: str | None = None) None¶
Write a regular VHDL synchronous process with a single clock.
The clock is the only item in the sensitivity list and is triggering a rising edge block by some body of VHDL code.
- Parameters:
- fTextIO
The TextIO to write the VHDL code onto.
- clkstr
Name of the clock.
- bodystr
Body of the if rising_edge(clk) then block.
- indentint, default: 1
Indentation level to use for this process.
- namestr, optional
An optional name for the process.
- b_asic.code_printer.vhdl.common.synchronous_process_epilogue(f: TextIO, clk: str | None = None, indent: int = 1, name: str | None = None) None¶
Write the epilogue of a regular VHDL synchronous process with a single clock.
The clock is the only item in the sensitivity list and is triggering a rising edge block by some body of VHDL code.
- Parameters:
- fTextIO
The TextIO to write the VHDL code onto.
- clkstr, optional
Name of the clock.
- indentint, default: 1
Indentation level to use for this process.
- namestr, optional
An optional name for the process.
- b_asic.code_printer.vhdl.common.synchronous_process_prologue(f: TextIO, clk: str = 'clk', indent: int = 1, name: str | None = None) None¶
Write the prologue of a regular VHDL synchronous process with a single clock object.
The clock is the only item in the sensitivity list and is triggering a rising edge block by some body of VHDL code.
This method is almost always followed by a
synchronous_process_epilogue().- Parameters:
- fTextIO
The TextIO to write the VHDL code onto.
- clkstr
Name of the clock.
- indentint, default: 1
Indentation level to use for this process.
- namestr, optional
An optional name for the process.
- b_asic.code_printer.vhdl.common.type_declaration(f: TextIO, name: str, alias: str) None¶
Write a VHDL type declaration with a name tied to an alias.
- Parameters:
- fTextIO
The TextIO object to write the type declaration to.
- namestr
Type name alias.
- aliasstr
The type to tie the new name to.
- b_asic.code_printer.vhdl.common.write(f: TextIO, indent_level: int, text: str, *, end: str = '\n', start: str | None = None) None¶
Write text to a VHDL file.
First,
f'{VHDL_TAB*indent_level}'is written to f as indentation. Immediately after the indentation, text is written to f. Finally, text is also written to f.- Parameters:
- fTextIO
The file object to emit VHDL code to.
- indent_levelint
Indentation level to use. Exactly
f'{VHDL_TAB*indent_level}'is written before the text is written.- textstr
The text to write to.
- endstr, default: ‘n’
Text to write exactly after text is written to f.
- startstr, optional
Text to write before both indentation and text.
- b_asic.code_printer.vhdl.common.write_lines(f: TextIO, lines: list[tuple[int, str] | tuple[int, str, str]]) None¶
Write provided lines to a VHDL file.
Each tuple
(int, str, [int])in the list lines is written to the TextIO object f using thevhdl.write()function.- Parameters:
- fTextIO
The file object to emit VHDL code to.
- lineslist of tuple (int,str) [1], or list of tuple (int,str,str) [2]
- [1]: The first
intof the tuple is used as indentation level for the line and the second
strof the tuple is the content of the line.- [2]: Same as [1], but the third
strof the tuple is passed to parameter end when calling
vhdl.write().
- [1]: The first
memory_storage module¶
Module for VHDL code generation of memory based storage.
- b_asic.code_printer.vhdl.memory_storage.architecture(f: TextIO, memory: Memory, dt: _VhdlDataType, *, output_sync: bool = True, external_schedule_counter: bool = True, std_logic_vector: bool = False, pipeline_control_signals: bool = False, external_control: bool = False) None¶
Generate the VHDL architecture for a memory-based storage architecture.
Settings should be sanitized when calling this function, e.g. from calling generate_memory_based_storage_vhdl from one of the memory classes.
- Parameters:
- fTextIO
File object (or other TextIO object) to write the architecture onto.
- memory
Memory Memory object to generate code for.
- dt
DataType Meta information of data signals.
- output_syncbool, default: True
Add registers to the output signal.
- external_schedule_counterbool, default: True
If True, schedule counter comes from external input port. If False, schedule counter is generated internally with synchronous reset.
- std_logic_vectorbool, default: False
If True, use std_logic_vector for data signals. If False, use dt.type_str.
- pipeline_control_signalsbool, default: False
If True, register the control signals.
- external_controlbool, default: False
Receive control signals from the enclosing architecture or generate them locally.
- b_asic.code_printer.vhdl.memory_storage.entity(f: TextIO, mem: Memory, dt: _VhdlDataType, external_schedule_counter: bool = True, std_logic_vector: bool = False, controls=(), external_control: bool = False) None¶
Generate entity for memory storage.
- Parameters:
- fTextIO
File object to write to.
- mem
Memory Memory object to generate entity for.
- dt
_VhdlDataType Data type information.
- external_schedule_counterbool, default: True
If True, schedule counter is an input port. If False, it’s generated internally.
- controlssequence
Control ports supplied by the enclosing architecture.
- external_controlbool, default: False
Receive control signals from the enclosing architecture or generate them internally.
- std_logic_vectorbool, default: False
If True, use std_logic_vector for data signals. If False, use dt.type_str.
processing_element module¶
Module for VHDL code generation of processing elements.
- b_asic.code_printer.vhdl.processing_element.architecture(f: TextIO, pe: ProcessingElement, dt: _VhdlDataType, core_code: tuple[str, str], register_split: tuple[int, int], control_cycle: dict[str, int] | None = None, pipeline_control_signals: bool = False, external_control: bool = False) None¶
- b_asic.code_printer.vhdl.processing_element.entity(f: TextIO, pe: ProcessingElement, dt: _VhdlDataType, controls=()) None¶
register_storage module¶
Module for VHDL code generation of register based storage.
- b_asic.code_printer.vhdl.register_storage.architecture(f: TextIO, forward_backward_table: _ForwardBackwardTable, memory: Memory, dt: _VhdlDataType, sync_rst: bool = False, async_rst: bool = False, std_logic_vector: bool = True, pipeline_output_mux: bool = False, pipeline_back_edge_mux: bool = False, external_control: bool = False) None¶
Generate architecture for register-based storage.
- Parameters:
- fTextIO
File object to write to.
- forward_backward_table
_ForwardBackwardTable Forward-backward allocation table.
- memory
Memory Memory object.
- dt
_VhdlDataType Data type information.
- sync_rstbool, default: False
Enable synchronous reset.
- async_rstbool, default: False
Enable asynchronous reset.
- std_logic_vectorbool, default: True
If True, use std_logic_vector for data signals. If False, use dt.type_str.
- pipeline_output_muxbool, default: False
If True, register the output multiplexer select signal, decoding it one clock cycle earlier to compensate for the added register stage.
- pipeline_back_edge_muxbool, default: False
If True, register the back-edge multiplexer select signal, decoding it one clock cycle earlier to compensate for the added register stage.
- external_controlbool, default: False
Receive control signals from the enclosing architecture or generate them locally.
- b_asic.code_printer.vhdl.register_storage.entity(f: TextIO, memory: Memory, dt: _VhdlDataType, std_logic_vector: bool = True, controls=(), external_control: bool = False) None¶
Generate entity for register-based storage.
- Parameters:
- fTextIO
File object to write to.
- memory
Memory Memory object to generate entity for.
- dt
_VhdlDataType Data type information.
- std_logic_vectorbool, default: True
If True, use std_logic_vector for data signals. If False, use dt.type_str.
- controlssequence
Control ports supplied by the enclosing architecture.
- external_controlbool, default: False
Receive control signals from the enclosing architecture or generate them internally.
test_bench module¶
Module for VHDL code generation of test benches.
- b_asic.code_printer.vhdl.test_bench.architecture(f: TextIO, arch: Architecture, dt: _VhdlDataType, enable_pin: bool = True) None¶
- b_asic.code_printer.vhdl.test_bench.entity(f: TextIO, arch: Architecture) None¶
top_level module¶
Module for VHDL code generation of top level designs.
- b_asic.code_printer.vhdl.top_level.architecture(f: TextIO, arch: Architecture, dt: _VhdlDataType, input_register: bool = False, output_register: bool = False, multiplexer_control_registered: bool = True, enable_pin: bool = True, controls: dict[str, list[Control]] | None = None, streams: list[Endpoint] | None = None) None¶
- b_asic.code_printer.vhdl.top_level.entity(f: TextIO, arch: Architecture, dt: _VhdlDataType, enable_pin: bool = True, streams: list[Endpoint] | None = None) None¶
util module¶
Utility functions for VHDL Printer.