VeriSnip 0.0.3

A small example package

VeriSnip-Overview

VeriSnip (VS) is a project designed to bring the power of Verilog scripting to the open‑source hardware community. This tool simplifies the generation of Verilog modules or snippets by seamlessly integrating with other programs. The generated files can be easily included in any Verilog project. The motivation behind this work is so that creating hardware modules is a process of creating a template file written in Verilog and letting your programs/scripts generate the hardware. These scripts are included in your Verilog template file using Verilog snippets.

With VeriSnip, the process of calling programs or scripts responsible for generating Verilog files is streamlined. After file generation, VeriSnip neatly organizes all Hardware Description Languages (HDL) and TestBench files under the build directory.

Learn more about how VeriSnip works here.

Index

1. How to use VeriSnip (vs_build.py)
2. vs_colours.py
3. MyLibrary
4. Opening Issues
5. Contributing
6. Development Environment
7. Credits

How to use VeriSnip (aka, vs_build)

The vs_build script serves as the cornerstone of the VeriSnip tool‑chain, encompassing core functions essential for project compilation. This script orchestrates the creation of the build directory, housing Verilog modules and headers crucial for the project's hardware implementation. The code residing under the ./build directory represents the compiled output ready for simulation and FPGA synthesis.

Run vs_build.py

vs_build must receive at least one argument. To show the help page:

Usage: python vs_build.py --help

Create a build directory containing all the compiled hardware:

Usage: python vs_build.py <main_module> --TestBench <testbench_name> --Boards <board_modules> <main_module> -> This is the name of the main RTL design. --TestBench <testbench_name> (optional) -> by default vs_build looks for a TestBench file with the name <main_module>_tb. --Boards <board_modules> (optional) -> by default vs_build looks for NO board RTL design top module. Multiple boards can be passed in a single argument (example, "Board1 Board2 Board3"). --quiet (optional) -> suppresses INFO prints. --debug (optional) -> enables DEBUG prints.

Clean the contents generated by vs_build:

Usage: python vs_build.py --clean all all (optional) -> By default "--clean" only removes the "build" directory, with "all" it also removes the "hardware/generated" directory.

Example of calling vs_build: python3 ./*vs_build* top_module --TestBench top_module_tb --Boards "top_module_ecp5" or ./*vs_build* --help

Using Verilog Snippets (.vs)

Users need to include the corresponding .vs file in their Verilog modules to enable VeriSnip to search for or generate a Verilog Snippet. For example:

module example (
  `include "example_ios.vs" // VS_NO_GENERATE
);
  `include "example_contents.vs" /*
    Argument passed to the program/script that generates example_contents.vs
  */
endmodule

In the above example, VeriSnip scans for a program or script whose name resembles the Verilog Snippet name (excluding the file extension).
The statement include "example_contents.vs" corresponds to a program or script named either example.* or example_contents.*, where * represents any supported file extension.

Since include "example_ios.vs" is followed by VS_NO_GENERATE, VeriSnip will ignore this file and will not attempt to generate it.
The file can be generated later by another include statement if necessary.

For another example, refer to the MyReg module.
You can run vs_build myreg to execute a small build with VeriSnip.

Note: Avoid including a file on the first line of a Verilog source file, as this is not supported.
Instead, use the beginning of the file to provide a brief introduction or description of its contents.

Creating a Compatible Program/Script for Verilog Snippet Generation

Users have the flexibility to create custom programs or scripts for generating ".vs" files or Verilog modules, or they can utilize existing ones. It's crucial to note that all scripts responsible for generating Verilog code, whether modules or ".vs" files, are independent of "vs_build." "vs_build" exclusively calls these scripts without importing them into the project.

Supported File Extensions and Corresponding Languages: Currently, VeriSnip supports programs and scripts with the following file extensions:

• ".py" for Python
• ".sh" for Bash
• ".lua" for Lua
• ".scala" for Scala
• ".rb" for Ruby
• ".pl" for Perl
• ".vt" for Verilog Template (a custom extension)

The Verilog Template extension (".vt") is specific to VeriSnip. If you compile a program that generates a Verilog module or snippet, you can use the ".vt" extension to enable VeriSnip to locate it.

When vs_build calls another program (see example here), it passes a variable number of arguments. Nevertheless, it always follows the same order. Therefore, take into consideration the following arguments and their order when developing your program or script:

• Path to the program or script being called
• Difference between the ".vs" filename and the program/script name. It corresponds to the suffix of the program/script name
• Comment written after the "`include"
• File where the include is being called from, therefore the file where the "`include" is written
• vs_build received arguments (excluding its own name)

Code structure

vs_build code is distinctly divided into three stages.

• in 1st stage the function find_vs_scripts_and_verilog() finds all existing verilog modules, headers, snippets and scripts under the current directory.
• the 2nd stage is where it finds the verilog modules and snippets needed by the core. If a verilog module or a snippet does not exist it will try to generate them. The generated snippets should be stored under the ./rtl/generated directory. The function called for this stage is verilog_fetch().
• during the 3rd stage all verilog snippet files included are substituted for its content. Those files are then stored under the ./build directory.

2nd stage - details

• When calling scripts to generate ".vs" priority is always given to scripts with the full name of the file. If there is no script corresponding to the ".vs" name look for a script that corresponds only to the initial part of the name. Example:

  • in include "io_modules.vs" look for VTio.py or io.py if io_modules.py does not exist.

• When calling scripts that generate modules the script should have the name of the module.

• "vs_build" only calls the scripts if they are newer than the files already existent.

• When there are two or more scripts with the same name a warning should be printed and the script with the closest directory path should be used.

• All files and scripts should only be looked for from the base directory of the project, unless specified otherwise in a custom script.

3rd stage - details

• all files which are generated should have a copy in the "aux" directory
• "vs_build" substitutes the ".vs" and copies the modules needed to the build directory, after finding or generating all modules and ".vs" files.

vs_colours

This script defines the colors that should be used when printing error, warning or successful messages. It defines the print_coloured() function and some variables that allow to modify the text printed to the console.

MyLibrary

The "MyLibrary" directory contains hardware Verilog modules, snippets and scripts that might be commonly reused.

Scripts

This section of the README contains information about the scripts present under the ./library/scripts directory. Read more about each script in the README.md on the scripts directory.

Opening an Issue

Welcome to our issue reporting system! We appreciate your contribution to the project by reporting any issues you encounter. Your feedback helps us make this project even better.

How to Open an Issue

When opening an issue, please follow this format:

Issue Title: A concise and descriptive title for the issue.

Hello Tag the developers you think might be able to help,

Issue Description:

Provide a detailed description of the issue you encountered. Include information about your environment, steps to reproduce the issue, and any error messages. The more details you provide, the easier it is for us to understand and address the problem.

Solution Reference (Optional):

If you have a solution in mind, you're welcome to present it and provide a detailed explanation of why you believe it will work. If possible, include references to supporting pages or documentation that back your proposed solution. This can help us better understand your perspective and expedite the resolution process.

Suggested Changes (Optional):

If you have ideas for changes that might solve the issue, propose them here. Be clear and concise in your suggestions.

Additional Question (Optional):

If you have questions directly or indirectly related to the issue, feel free to ask them in this section.

Tag developers by using @username to get their attention.

We appreciate your help in improving this project!

Contributing

All contributions to this project are warmly welcomed.

Contributions in the form of automatically generated Verilog scripts should be placed within the hardware/scripts directory. Additionally, contributors are required to create a corresponding section in the README when adding a script. This section should detail the generated core and provide instructions on the script's usage. It is important that the section structure aligns with the structures of other script sections.

Development Environment

To utilize vs_build, all that's necessary is Python3 and support for the scripting languages in which your scripts are written.

Credits

This project idea came to me while I was working at IObundle. IObundle was developing a similar open-source tool called python-setup. The two projects are fundamentally different. Therefore I decided to create this project from 0 instead of contributing the ideas and tools directly to IObundle's python-setup.

Where the two projects are similar is both are being developed to generate automatic verilog.

Where they mainly differ is on the way the verilog is generated. The IObundle python-setup project aims to generate all the verilog core using a python framework. VeriSnip aims to substitute the .vs files present on the verilog code, generating the .vs code as needed. There may also exist scripts that generate .v modules.