William Wilberforce, a man who apparently had a thing for extremely long sentences, might have said something a bit similar about the end of slavery, but that's not the topic for today. Today's topic is the new FuseSoC release. We now live in a world of git snapshots (and less slavery than 1789), and I don't expect an increase in the number after the decimal point in the configure script matter to most people. Still, I think it's nice to do a stable release once in a while. It helps packagers (where are you by the way? I'm still waiting for someone to make a FuseSoC rpm or deb), and more importantly, I can take this as an opportunity to break things. This will be the first version where a part of CAPI1 gets deprecated. There are some other noteworthy changes since FuseSoC 1.3, and although I have summarized the changes in the NEWS file, and I recently wrote a post about the new IP-Xact support there are other changes that could be worth explaining in further detail. I do realize that this would not be needed if someone had written proper documentation (where are you by the way? I'm still waiting for someone to write the documentation for me), but no one has, so this will have to do for now.
Prominent features
File sets
Up until now, source code has been mainly verilog, with some support for C(++) for Verilator testbenches and VPI modules, together with a very limited support for VHDL in the Quartus backend flow. This part has been completely overhauled in this release, where filesets are introduced. Filesets is modeled on the IP-Xact filesets, and these will have a stronger connection in the future, as IP-Xact support is also introduced in this version. The verilog section will be deprecated at some point, so I suggest moving to filesets already. Here's a quick example on how to make the switch. The verilog section of the de0 nano system...[verilog] src_files = rtl/verilog/clkgen.v rtl/verilog/orpsoc_top.v backend/rtl/verilog/pll.v rtl/verilog/wb_intercon.v rtl/verilog/wb_intercon_dbg.v tb_private_src_files = bench/orpsoc_tb.v bench/uart_decoder.v include_files = rtl/verilog/include/or1200_defines.v rtl/verilog/include/orpsoc-defines.v rtl/verilog/wb_intercon.vh rtl/verilog/wb_intercon_dbg.vh sw/clear_r3_and_jump_to_0x100.vh sw/spi_uimage_loader.vh tb_include_files = bench/spi_image.vh bench/test-defines.v
...becomes...
[fileset rtl_files] files = rtl/verilog/clkgen.v rtl/verilog/orpsoc_top.v backend/rtl/verilog/pll.v rtl/verilog/wb_intercon.v rtl/verilog/wb_intercon_dbg.v file_type = verilogSource usage = sim synth [fileset tb_files] files = bench/orpsoc_tb.v bench/uart_decoder.v file_type = verilogSource usage = sim [fileset include_files] files = rtl/verilog/include/or1200_defines.v rtl/verilog/include/orpsoc-defines.v rtl/verilog/wb_intercon.vh rtl/verilog/wb_intercon_dbg.vh sw/clear_r3_and_jump_to_0x100.vh sw/spi_uimage_loader.vh file_type = verilogSource is_include_file = true usage = sim synth [fileset tb_include_files] files = bench/spi_image.vh bench/test-defines.v file_type = verilogSource is_include_file = true usage = sim
It's a few more lines, but the added flexibility outweighs the few extra bytes of ascii characters. It's now possible to set other file types, such as vhdlSource, or request specific language versions such as verilogSource-2001. The available file types are enumerated in the IP-Xact standard with some addtional ones allowed by FuseSoC (verilogSource-2005 and vhdlSource-2008 for now). The name of a fileset is not important, but the filesets are parsed in the order they appear in the .core file, so make sure that they are correctly ordered when dealing with languages where this is important.
The usage tag can be set to one or more items, and determines which tools that will use the fileset. These can be either a category (sim, synth) or a specific tool (verilator, quartus, modelsim...)
For languages that has a concept of libraries (VHDL, not verilog), the logical_name tag can be used to indicate library affiliation.
Another new feature is per-file attributes, which can be used to override the default value for the fileset. These attributes are placed inside square brackets at the end of the file. They are comma-separated and are either of the form attribute=value, or just attribute, to set boolean attributes. With per-file attributes, the above example can be changed to:
[fileset rtl_files] files = rtl/verilog/clkgen.v rtl/verilog/orpsoc_top.v backend/rtl/verilog/pll.v rtl/verilog/wb_intercon.v rtl/verilog/wb_intercon_dbg.v rtl/verilog/include/or1200_defines.v[is_include_file] rtl/verilog/include/orpsoc-defines.v[is_include_file] rtl/verilog/wb_intercon.vh[is_include_file] rtl/verilog/wb_intercon_dbg.vh[is_include_file] sw/clear_r3_and_jump_to_0x100.vh[is_include_file] sw/spi_uimage_loader.vh[is_include_file] file_type = verilogSource usage = sim synth [fileset tb_files] files = bench/orpsoc_tb.v bench/uart_decoder.v bench/spi_image.vh[is_include_file,file_type=verilogSource-2005] bench/test-defines.v[is_include_file] file_type = verilogSource usage = sim
Note that the file_type attribute for spi_image.vh was only added to show how multiple attributes can be set.
If there is an IP-Xact component file for the core, FuseSoC can parse that for the filesets instead. In that case, the above example will look like this
[main] component = de0_nano.xml
Yep, that's right. We can leave it all to IP-Xact. Except for when we need file types that aren't in the IP-Xact standard (again Verilog 2005 and VHDL 2008 are the primary cases here), and the usage will default to both sim and synth. Future versions of FuseSoC will allow overriding options in the IP-Xact files to handle these cases. The IP-Xact support is described in greater detail in an earlier post
Mixed-language support
With the new file set features in place, most of the simulators and synthesis tools now accept both verilog, systemVerilog and VHDL files simultaneously for mixed-language projects.
Compile-time parameter enhancements
Both build backends now support setting top-level verilog parameters at synthesis-time. This can be used for example to initialize a boot ROM with different contents, or setting a version tag at compile-time. Using the de0 nano example once again, the following can be added to the .core file to register a parameter
[parameter bootrom_file] datatype = file description = Boot ROM contents in Verilog hex format paramtype = vlogparam scope = public
To select a different boot ROM, run fusesoc build de0_nano --bootrom_file=/path/to/bootrom.vh
Slightly related are some enhancements to the simulator backends. Both verilator and XSIM now accepts parameters which are turned into plusargs, and all simulator backends now analyse the CLI arguments before building the simulator model to save some time.
Distutils and pypi
Apparently all the cool kids put their Python code on pypi, and it was suggested that I should do the same with FuseSoC. The easy way to do that is to replace autotools with a Python-based build system called distutils...or setuptools... which at some point gets used by pip... to create an egg or a wheel... which can be installed with pip.... or easy_install. I'm really not sure. Python packaging is a complete mess with around ten competing build systems. Try to Google it if you don't believe me. It's insane. I think this tweet pretty much sums it up.
So what are the benefits of this new Python-based build system. A small reduction in line count of the configuration files and the possibility to upload to pypi. It doesn't handle dependencies unfortunately, and there is no way to uninstall a package. How I love progress! The autotools-based build system is still there, until I figure out what to do.
That's all for now. I have already plenty of things lined up for the FuseSoC 1.5 release
