Release notes

Release history and changelog for the tsfpga project. We follow the semantic versioning scheme MAJOR.MINOR.PATCH:

MAJOR is bumped when incompatible API changes are made.
MINOR is bumped when functionality is added in a backward-compatible manner.
PATCH is bumped when backward-compatible bug fixes are made.

Unreleased (YYYY-MM-DD)

Changes since previous release

Updates in example simulation script.

13.0.0 (14 october 2024)

Changes since previous release

Bug fixes

Adapt netlist build time reporting to work with VUnit > 4.7.0 also (#87).

Breaking changes

Remove super().__init__(**kwargs) call from BaseModule.__init__(). Users that depend on base class initialization must now make these calls explicitly. See #112 for background.

12.3.6 (27 august 2024)

Changes since previous release

Fixes

Update example scripts to utilize features in latest hdl-registers.

12.3.5 (9 july 2024)

Changes since previous release

Peg required VUnit version to <= 4.7.0 due to #87.

12.3.4 (9 july 2024)

Changes since previous release

Added

Abort Vivado build if synthesis or implementation CDC timing report contains any critical violation.
Find VHDL simulation subset that depends on generated register artifacts in GitSimulationSubset.

Accidentally breaking change

Call super().__init__(**kwargs) in BaseModule.__init__(). See #112.

12.3.3 (14 may 2024)

Changes since previous release

Added

Add modules_folder argument to get_modules().

12.3.2 (29 april 2024)

Changes since previous release

Added

Add to_binary_nibble_string(), to_hex_string(), to_hex_byte_string() functions. Renames internal function to_binary_string() argument int_value to value.

Fixes

Improve Verilog and SystemVerilog support in Vivado project creation.
Fix create_directory() behavior when path already exists as a file.
Fix potential Vivado build crash when implementation explore is used.

Internal changes

Rework HdlFile type indication using enumeration HdlFile.Type.

12.3.1 (8 march 2024)

Changes since previous release

Fixes

Remove nonsense assertion in path_relative_to().

12.3.0 (5 february 2024)

Changes since previous release

Added

Add support for generating VHDL simulation register field check package ( VhdlSimulationCheckPackageGenerator ) from hdl-registers before simulation and build. Requires hdl-registers version 5.1.0 or greater.

12.2.1 (29 january 2024)

Changes since previous release

Update example simulation and FPGA build scripts.

12.2.0 (25 january 2024)

Changes since previous release

Added

Generate further register VHDL artifacts
- record package ( VhdlRecordPackageGenerator ),
- AXI-Lite register file wrapper ( VhdlAxiLiteWrapperGenerator ),
- simulation read/write package ( VhdlSimulationReadWritePackageGenerator ),
- simulation wait until package ( VhdlSimulationWaitUntilPackageGenerator )
from hdl-registers before simulation and build. Requires hdl-registers version 5.0.0 or greater.

12.1.2 (14 november 2023)

Changes since previous release

Fixes

Peg required hdl-registers version ahead of a major API change in that project.

12.1.0 (6 november 2023)

Changes since previous release

Added

Add support for parallel implementation explore runs.
Include bit file in generated Xilinx shell archive (.xsa) file.

Fixes

Fix Vivado simlib compilation on Windows.
Abort if creation of IP core simulation project fails.

12.0.4 (18 august 2023)

Changes since previous release

Bug fixes

Fix so that string generics work in Vivado 2023.1 as well.

12.0.3 (25 april 2023)

Changes since previous release

Fixes

Compile Vivado simlib library-by-library with GHDL instead of file-by-file. Reduces compile time from 7 minutes to 5 seconds.
Make the error message for bad generic value type a little more helpful.
Add assertions that some VivadoProject arguments are the correct type.

12.0.2 (6 march 2023)

Changes since previous release

Changes

Update documentation.

12.0.1 (2 march 2023)

Changes since previous release

Changes

Update project slogan on PyPI to fit within 98 characters.

12.0.0 (2 march 2023)

Changes since previous release

Added

Add set_random_seed argument to BaseModule.add_vunit_config().
Add table with netlist build resource utilization to Sphinx documentation in ModuleDocumentation.
Add --from-impl support to VivadoProject.build() and example build_fpga.py.
Add create_ghdl_ls_configuration() function to generate a configuration file (hdl-prj.json) for the ghdl-ls language server.
Add support for string and bit vector generics in VivadoProject using the types StringGenericValue and BitVectorGenericValue.
Add check that fails Vivado build unless all bus skew constraints are met after implementation.
Fail Vivado build if any messages with severity ERROR have been reported after synthesis or implementation.

Breaking changes

Remove bundling of hdl-modules with PyPI release. This also removes the constants/functions tsfpga.HDL_MODULES_LOCATION, tsfpga.HDL_MODULES_TAG, tsfpga.HDL_MODULES_SHA and tsfpga.module.get_hdl_modules().
Remove support for formal flow. It’s still a bit too experimental for us to support.
Add mandatory heading_character_2 argument to ModuleDocumentation.get_submodule_rst().

Bug fixes

Fix bug where multiple build projects filters that match the same project would crash the build.
Fix bug where Vivado build could crash when there was an ILA in the design in a very specific scenario.

11.0.0 (25 october 2021)

Changes since previous release

Breaking changes

Split out the tsfpga/registers/ folder into the standalone hdl-registers project (https://hdl-registers.com, https://github.com/hdl-registers/hdl-registers). This moves all python modules from the tsfpga.registers package to a new package called hdl_registers. The PyPI package tsfpga has a dependency on hdl-registers, so if you install tsfpga via pip the change is transparent. If you use tsfpga from a repo checkout, you will also need to check out the hdl-registers repo.

10.0.0 (20 october 2021)

Changes since previous release

Breaking changes

Split out the modules/ folder into the standalone hdl-modules project (https://hdl-modules.com, https://github.com/hdl-modules/hdl-modules). The modules are still bundled with each PyPI release of tsfpga.

9.0.0 (19 october 2021)

Changes since previous release

Added

Add common.handshake_master, common.handshake_slave, common.axi_stream_master and common.axi_stream_slave VHDL BMFs.
Add common.keep_remover and common.strobe_on_last VHDL entities.
Add “peek read” mode to fifo.fifo.
Add ModuleDocumentation class for generating Sphinx RST documentation of a module.

Bug fixes

Fix bug where common.width_conversion would set output_last on the wrong beat when downsizing.
Fix bug in reg_file.reg_operations_pkg.read_modify_reg_bit.

Changes

Update so that reg_file.axi_lite_reg_file asserts reg_was_read[i] the exact same cycle as the AXI-Lite R transaction occurs (used to be cycle after).

Breaking changes

Add common.width_conversion generic enable_last with default value false (used to be implied value true).
Move example scripts from examples to tsfpga/examples. This renames the corresponding python package from examples to tsfpga.examples.

8.0.1 (15 july 2021)

Changes since previous release

Fixed

Fix issues with dependency on GitPython in setup.py

8.0.0 (6 july 2021)

Changes since previous release

Added

Add resync.resync_slv_level_coherent VHDL entity.
Add VivadoIpCoreProject class which is the default vivado_project_class for VivadoIpCores.__init__(). If you use a custom class it is a good idea to inherit from this new class instead of VivadoProject.
Add IpCoreFile class to represent IP core files, which adds the possibility of parameterizing IP core creation.

Fixed

Fix bug where Vivado build-time generics dictionary was not copied, which could result in incorrect generic values for parallel builds.

Breaking changes

Rename all VHDL files/entities/types/constants with prefix axil_ to have prefix axi_lite_. This is done in order to be more descriptive, and to be consistent with axi_stream components. A search/replace axil_ -> axi_lite_ on all VHDL in your FPGA project should be able to adapt for this.
Always call BaseModule.registers_hook() from BaseModule.registers(), even when TOML file does not exists. This means that self._registers might be None when entering BaseModule.registers_hook().
Add mandatory generic enable_input_register to resync.resync_level and resync.resync_slv_level VHDL entities. See resync_level.vhd file header for details.
Rework testbench helper procedures in reg_file.reg_operations_pkg completely.
1. Rename bits/bits argument to bit_index/bit_indexes.
2. Rename expected argument to value.
3. Add mandatory value/values argument to check_reg_equal_bit/check_reg_equal_bits.
4. Add optional other_bits_value argument to check_reg_equal_bit/check_reg_equal_bits to control what value the non-designated bits are expected to be (default is zero).
5. Add mandatory value/values argument to wait_until_reg_equals_bit/wait_until_reg_equals_bits.
6. Add optional other_bits_value argument to wait_until_reg_equals_bit/wait_until_reg_equals_bits to control what value the non-designated bits are expected to be (default is don’t care).
7. Add mandatory value/values argument to write_reg_bit/write_reg_bits.
8. Add optional other_bits_value argument to write_reg_bit/write_reg_bits to control what value is assigned to non-designated bits (default is zero).
9. Add read_modify_write_reg_bit/read_modify_write_reg_bits which performs a read-modify-write where the designated bits are updated.

7.0.0 (17 may 2021)

Changes since previous release

Added

Add support for bit vector fields in register code generator.
Add possibility of setting a description for register arrays.
Add hdl_registers.register_list.RegisterList.create_python_class,
hdl_registers.register_list.RegisterList.get_register_array() and hdl_registers.register_list.RegisterList.get_register_index() methods.
Add optional vivado_project_class argument to VivadoIpCores constructor.
Add axi.axi_stream_pkg VHDL package and axi.axi_stream_fifo VHDL entity.
Add common.periodic_pulser VHDL entity.
Add support for byte strobe and unaligned burst length in common.width_conversion.
Add support for checking maximum logic level in netlist builds via the MaximumLogicLevel class and the build_result_checkers argument to VivadoNetlistProject.__init__().

Breaking changes

Re-work the format for register definition TOML files.
- Rename register property bits to bit.
- Move default_value property from register to be a property on each register field (bits, bit vectors).
Rename generated register C header bit definitions to have _SHIFT and _MASK suffix. This is to be consistent with the naming for bit vector fields.
Remove #pragma pack(push, 1) and #pragma pack(pop) from register C header.
The methods hdl_registers.register_list.RegisterList.get_register(), hdl_registers.register_list.RegisterList.get_constant(), hdl_registers.register_array.RegisterArray.get_register(), hdl_registers.register.Register.get_field(), will now raise exception if nothing matches, instead of returning None.
Move the classes LessThan, EqualTo, TotalLuts, LogicLuts, LutRams, Srls, Ffs, Ramb36, Ramb18 and DspBlocks from tsfpga.vivado.size_checker to tsfpga.vivado.build_result_checker.
Rename VivadoNetlistProject.__init__() argument result_size_checkers to build_result_checkers.

Changes

Switch to using python package tomlkit instead of toml for parsing register TOML files.

Fixed

Fix bug in synchronous FIFO when drop_packet is asserted in same cycle as write_last.

6.0.0 (24 march 2021)

Changes since previous release

Added

Add fifo.fifo_wrapper VHDL entity.
Add drop_packet support to synchronous and asynchronous FIFOs.
Add check for pulse width timing violations after implementation in Vivado build system.
Check clock interaction after implementation as well in Vivado build system.
Add common.clock_counter VHDL entity.
Add bfm.axi_read_slave, bfm.axi_write_slave, bfm.axil_read_slave and bfm.axil_write_slave VHDL entities.

Breaking changes

Rename fifo.afifo to fifo.asynchronous_fifo.
Rename vivado.project.VivadoNetlistProject constructor argument analyze_clock_interaction to analyze_synthesis_timing.
Remove tsfpga.vivado.size_checker.Dsp48Blocks in favor of .vivado.size_checker.DspBlocks.
Add a pipelining step to improve timing of axi.axi_read_throttle and axi.axi_write_throttle. This introduces three new generics that must be set.
Change bfm.axi_slave and bfm.axil_slave interfaces to require two axi_slave_t generics: axi_read_slave and axi_write_slave.
Break axi.axi_simple_crossbar into axi.axi_simple_read_crossbar and axi.axi_simple_write_crossbar.
Break axi.axil_simple_crossbar into axi.axil_simple_read_crossbar and axi.axil_simple_write_crossbar.

Changes

Update timing of fifo.fifo port read_ready to get lower fanout and shorter critical path. The change implies an increased latency from a read transaction until write_ready is raised.

5.0.0 (15 february 2021)

Changes since previous release

Added

Add optional clk_in port to resync.resync_level which enables a more deterministic latency constraint.
Add support for HTML paragraph breaks in register/bit descriptions. Consecutive newlines will be converted to paragraph breaks.
Add support for parallel builds of FPGA projects using the BuildProjectList class.
Add support for register constants in TOML file.
Add axi.axi_read_throttle and axi.axi_write_throttle VHDL entities.
Add BaseModule.pre_build() hook function.
Add time saving mechanism to only re-create the register VHDL package when necessary.
Add common.debounce VHDL entity.
Add reg_was_read port to reg_file.axil_reg_file.
Add VivadoProject.pre_create() hook function.
Allow Vivado project source files to contain spaces.
Add .BaseModule.get_formal_files method used to select what files are included in a formal project.
Add files_include and files_avoid arguments to BaseModule.get_synthesis_files(), BaseModule.get_simulation_files() and .BaseModule.get_formal_files.
Add full_throughput and allow_poor_input_ready_timing generics to common.handshake_pipeline.

Breaking changes

Rename resync.resync_on_signal to resync.resync_level_on_signal and resync.resync_slv_on_signal to resync.resync_slv_level_on_signal. This is more descriptive and follows the naming of the other resync blocks.
The generated register HTML page no longer supports markdown flavor of using underscores to annotate. Instead use **double asterisks for bold** and *single asterisks for emphasis*. This change is done to make it easier to refer to other registers/constants/signals who very often have underscores in their name.
Rename axi.axi_interconnect to axi.axi_simple_crossbar and axi.axil_interconnect to axi.axil_simple_crossbar. This naming is factual (it is a crossbar, not an interconnect) and more descriptive.
Rename RegisterList.create_html_table() to hdl_registers.register_list.RegisterList.create_html_register_table. Add hdl_registers.register_list.RegisterList.create_html_constant_table.
Deprecate BaseModule.setup_simulations() in favor of BaseModule.setup_vunit().
Rework BuildProjectList class completely. See the class documentation, the minimal usage example and the build_fpga.py example in the repo.
Change VivadoProject to catch non-zero exit code exception if Vivado call fails. If VivadoProject.create() or VivadoProject.open() fail they will return False. If VivadoProject.build() fails, the returned build_result.BuildResult object will have success set to False.
Rename <module>_reg_was_written_t to <module>_reg_was_accessed_t in generated register VHDL package.
Add mandatory generic width to resync.resync_slv_level and resync.resync_slv_level_on_signal.
Rename BaseModule.add_config to BaseModule.add_vunit_config().
Rename types_pkg.swap_bytes to types_pkg.swap_byte_order.
Remove VivadoIpCores.vivado_project_sources_directory in favor of VivadoIpCores.project_directory.
Change tsfpga.create_vhdl_ls_config.create_configuration() argument ip_core_vivado_project_sources_directory to be ip_core_vivado_project_directory.

Changes

Add TCL sources before adding modules in VivadoTcl.
The tsfpga.module.get_modules() method now returns a ModuleList object instead of a raw list.

4.0.1 (25 august 2020)

Changes since previous release

Changed

Add missing files to PyPI release.

4.0.0 (21 august 2020)

Changes since previous release

Added

Add automatic size checkers for netlist builds: Build result checkers.
Add resync.resync_cycles VHDL entity.

Breaking changes

Change address types (in axi.axi_pkg, axi.axil_pkg and common.addr_pkg) to be unsigned rather than std_logic_vector. Do the same for AXI id, addr, len and size.
Change register definition file from JSON (regs_<name>.json) to TOML (regs_<name>.toml).
Build result, as returned by VivadoProject.build(), is now a build_result.BuildResult object instead of a dict.
The hooks VivadoProject.pre_build() and VivadoProject.post_build() must now return True upon success.
Rename common.types_pkg.natural_vector to natural_vec_t and common.types_pkg.positive_vector to positive_vec_t.
Move Vivado-related Python code from tsfpga package to sub-package tsfpga.vivado. The Python modules are renamed accordingly:
- tsfpga.vivado_utills -> tsfpga.vivado.common
- tsfpga.vivado_ip_cores -> tsfpga.vivado.ip_cores
- tsfpga.vivado_project -> tsfpga.vivado.project
- tsfpga.vivado_simlib -> tsfpga.vivado.simlib
- tsfpga.vivado_simlib_commercial -> tsfpga.vivado.simlib_commercial
- tsfpga.vivado_simlib_ghdl -> tsfpga.vivado.simlib_ghdl
- tsfpga.vivado_tcl -> tsfpga.vivado.tcl
- tsfpga.utilization_parser -> tsfpga.vivado.utilization_parser

3.0.0 (25 june 2020)

Changes since previous release

Added

Add last flag and packet mode to asynchronous FIFO.
Add AXI FIFOs and CDCs.
Add class for Vivado netlist builds.
Add axi.axil_pipeline VHDL entity.

Fixes

Fix issues where VivadoIpCores would re-compile when not necessary.

Breaking changes

Lower axi.axi_pkg.axi_id_sz from 32 to 24.
Remove default values from AXI conversion functions in axi_pkg and axil_pkg. The addr_width, data_width and id_width always have to be specified.
Change ram_type generic of FIFOs and FIFO wrappers to be of type common.attribute_pkg.ram_style_t instead of string.

2.0.0 (20 may 2020)

Changes since previous release

Added

Add support for register arrays in register code generation.
Add support for default values in register code generation.
Add BaseModule.registers_hook() to make it more convenient to manipulate register information from Python.
Add last flag and packet mode to synchronous FIFO.
Add common.handshake_splitter VHDL entity.

Fixes

Fix synchronous FIFO signal almost_empty being de-asserted too early when almost_empty_level is zero.
Area optimize the synchronous and asynchronous FIFOs.

Breaking changes

Change meaning of almost_empty FIFO signal to be “‘1’ if there are almost_empty_level or fewer words available to read”. Used to be “fewer than almost_empty_level”.
Change register json definition file name from <name>_regs.json to regs_<name>.json.
default_registers passed to BaseModule shall now be a list of hdl_registers.register.Register, instead of a dict.
Remove generated register constant <name>_regs_zero. Instead add <name>_regs_init with default values.
FPGA build projects shall now be set up with BaseModule.get_build_projects() using module_<name>.py rather than with project_<name>.py. See documentation.
Rename FpgaProjectList to BuildProjectList to get a consistent naming.
Constructor argument to BuildProjectList shall now be a list of modules rather than a list of modules folders.
Interface of resync_counter now uses unsigned vectors rather than integer s.

Internal changes

Refactor register handling to use only one class hdl_registers.register_list.RegisterList.

1.0.1 (29 february 2020)

Changes since previous release

Added

Include pylintrc and pycodestylerc in release.

1.0.0 (29 february 2020)

Changes since previous release

Added

Add run_index argument to VivadoProject.__init__() and VivadoProject.build().
Add VivadoProject.open() method.
Add VHDL AXI-Lite interconnect.

Breaking changes

Refactor to use pathlib.Path instead of strings to represent file system paths. All paths supplied to tsfpga must now be pathlib.Path objects.
Rename HdlFile.filename to HdlFile.path.
Adjust axi.axi_to_axil to not allow more than one outstanding transaction.
Rename FPGAProjectList to FpgaProjectList.
axi.axil_mux now responds with DECERR if no slave matches, instead of timing out.
Update interface to vivado simlib API with a factory class. See here.