Hello, everyone. Welcome to the sixth episode of FPGA limerick. In this episode, we will take a close look at the simulation flow of SpinalHDL. And we will use the Hello World as an example for demonstration purpose.

Verification Methodology

Generally speaking, when it comes to digital circuits, there are two approaches for verification. 

1. Formal Verification

The formal verification is more like a math approach, because basically every digital circuit is nothing but a mapping from input to output, which mathematically fits the definition of Function. 

In that sense, the DUT is treated as a math function, whose property is described by SVA (System Verilog Assertion), as illustrated below:

As it is like a math approach, there is no need to prepare test vectors for input and output. And the formal verification tool will use analytic method to check the DUT against those SVAs, and to make sure those properties are satisfied in all conditions.

SpinalHDL also supports Formal Verification, which can be found in

https://spinalhdl.github.io/SpinalDoc-RTD/master/SpinalHDL/Formal%20verification/index.html

Because Formal Verification is an analytic method, no simulation is needed. We will just leave the rest of it to inquisitive viewers.

2. Functional Simulation

This is the main topic we will discuss today. And for functional simulation, there are also two approaches:

a) static approach, for which we will prepare the expected input/output before hand and make them as test vectors. After the simulation run, the simulation output is matched against the test vectors to verify the DUT, as illustrated below

b) dynamic approach, for which the input is randomized. And the simulation output is compared against a functional model to verify the DUT, as illustrated below:

In the figure above, the driver will generate the random inputs, and feed them to both the simulator and the functional model. And the monitor will capture the simulation outputs, and feed them into the checker to match against the functional model.

Simulation Flow for SpinalHDL 

For SpinalHDL, it can support multiple simulators as its backend. And the fastest one will be verilator.

As illustrated in the figure above, the DUT will be compiled into verilog and passed onto the verilator. The verilator will turn them into C++ code and use GCC to make a shared object. The test bench in scala, together with shared object, will finally produce the waveform dump. 

Currently the waveform dump can be in either VCD format or FST format. Comparing to VCD (a text format), the FST is a binary format and is a lot smaller than the VCD. So we would recommend using the FST format. Both VCD and FST can be viewed by GTKWave (https://gtkwave.sourceforge.net/)

Now let’s take a look at the test bench in Hello World example

The code can be checked out with

git clone --depth 1 --branch v1.2.3 https://github.com/PulseRain/FpgaLimerick.git

The test bench is under 

HelloWorld/test/spinal/NcoCounterSim.scala

First of all, please note that although SpinalHDL is built on top of Scala language, the test bench is 100% in vanilla Scala. In other words, the test bench is not in SpinalHDL at all. So when we try to get and compare the value from DUT, every data type originally in SpinalHDL has to be converted into Scala type. For example, the IO port could be “bits” in SpinalHDL. But when comparing it to the test vector, we need to use .toInt or .toLong to convert it to a data type understandable by vanilla Scala. Another example is the Boolean type. In SpinalHDL, the Boolean type is actually spelled as Bool, and the True/False literature is spelled with the first level as capital letter. But for vanilla scala language, the Boolean type is spelled as Boolean, with the true/false literature spelled in all small letter. So when we need to use .toBoolean to convert the Boolean type in SpinalHDL to the one in vanilla Scala.

Also, when we drive the DUT’s input ports, we also need to use data type from vanilla Scala. For the Boolean type, it means we should use “true/false” instead of “True/False”, and the syntax would be like

dut.io.srst #= false

Boilerplate Code for Test Bench

As we can see from the Hello World example, the Scala testbench is pretty much in boilerplate form. And we need the following method call:

.withConfig 

For the validation of the simulation, this SpinalConfig should match the one used by the DUT generation.

.withWave / .withFstWave / .withVcdWave

If waveform dump is needed, please use those methods to specify the dump format. As we will use verilator as our backend simulator, using .withFstWave is recommended.

.compile

Instantiate the DUT in this method

.doSim

Now this is the main body of the simulation, which we will elaborate next

Multithread Simulation

The Hello World example we use here demonstrates the static approach (test vector matching) for Functional Simulation. (And we will demonstrate the dynamic in later episodes when we talk about cocotb)

The main body of the simulation is contained in the .doSim method in the testbench. It basically has three threads:

*) clkThread

*) measure

*) compare

And they are forked when they are created, and then joined afterwards. For more complicated designs, more than one compare thread could be launched to match multiple test vectors.

The measure thread is not typical in the verification. It is just included in the Hello World as a way to sanity check the verification.

The clkThread is used to initialized the test, and keep track of the start/end of the test with accurate clock count.

To View the Wave

After the simulation, if the waveform is dumped, we can use GTKWave to view the wave. On Windows, the GTKWave can be installed in MSYS2. Please open MSYS2 MINGW64, and type in 

pacman -S mingw-w64-x86_64-gtkwave

And then open a command prompt and type in “gtkwave” to launch the waveviewer. For the Hello World example, the wave dump (.fst or .vcd) can be found as .simWorkspace/NcoCounter/test.fst

Posted by FPGA Limerick at March 19, 2023 |  0 Comments

 

Hello, everyone! Welcome to the fifth episode of FPGA limerick. In this episode, we will take a close look at the “Hello World” example for SpinalHDL. And based on that, we will also demonstrate the basic design flow for SpinalHDL.

As mentioned in previous episodes, the Hello World can be checked out like

git clone --depth 1 --branch v1.1.4 https://github.com/PulseRain/FpgaLimerick.git

 

The folder structure of Hello World

And for a fresh checkout, it has the following files:

*) Files at the top level

                build.sbt: configuration file for SBG

                .scalafix.conf: configuration file for scalafix (linter)

                scalastyle-config.xml: configuration file for scalastyle (linter)

                .scalafmt.conf: configuration file for scalafmt (formatter)

 

*) Folder:

                src/spinal: project source for SpinalHDL

                src/main/resources/log4j2.xml: configuration file for log4j2

                test/spinal: test bench in SpinalHDL

                test/cocotb: test bench using cocotb

                project: additional configuration files for SBT

 

And the HelloWorld can also serve as a template for other projects. You can find a script called “make_new_prj.sh” under the scripts folder. And it can be used to create a new project folder using HelloWorld as the template. (Please run it under WSL.)

 

The design flow of SpinalHDL

 

As illustrated above, the general design flow for SpinalHDL is to:
1. Setup the Parameters of the SpinalHDL top module
2. Feed the source code into SpinalConfig
3. Generate the output in Verilog, System Verilog or VHDL

And now let's take a close look to the HelloWorld example to see how the flow works.

The background of the HelloWorld Example: NCO Counter

The HelloWorld is actually an example of NCO Counter. NCO stands for Numerically Controlled Oscillator. It tries to output a new clock (an enable pulse train actually) from on a base clock. The frequency of the output clock and the frequency of the base clock are predefined by parameters.

And mathematically, we need to do the following:
1.    Find the GCD of the base clock and the output clock
2.    Use the GCD to simplify the ratio between output clock and the base clock, i.e:

3.    Once we get the simplified ratio of n over m, we can set the NCO counter like the following:
  a)    Set the counter value to be zero (The initial phase)
  b)    For every base clock cycle, counter = (counter + n) mod m
  c)    Generate a pulse (output clock) every time the counter rolls over m

 

The code structure of the SpinalHDL module

Now let’s take a look at the code structure of the HelloWorld Example:
 

1.    package

To following the naming convention of JAVA package, the package name is often the reverse form of a URL. But you are also free to choose other name formats as you see fit. For example, in our FpgaLimerick repo, all the common code is placed in a package called “common”

2.    import

This is like the include section for Verilog or C++. And you can use scalafix to find and remove the unused imports.

3.    case class extends Component

This is similar to the “module” in Verilog. The SpinalHDL coding convention recommends using “case class” instead of “class” in scala.

4.    The parameters of the module. Here we use the convention for parameters as all capital letter with G_ prefix. (G stands for generics, a reminiscent from VHDL)

5.    A bundle for port list

6.    The main body of the design (combinatorial logic and sequential logic)

7.    And a companion object that contains the main function, which will generate the verilog / system verilog / VHDL based on the configuration.

Now, comparing to verilog, it is a cinch for SpinalHDL to get GCD value, as SpinalHDL is based on a high level programming language scala. If we want to do the same implementation in verilog, we have to jump through a lot of hoops to get the GCD value, as verilog’s system functions are very primitive and do not cover GCD directly. Even if you can find a way to calculate the GCD with verilog’s system functions, I bet the code would be bulky and messy.

Configuration and Code Generation

The Hello World uses the MainConfig to generate the code. The MainConfig can be found in common/MainConfig.scala, which is derived from SpinalConfig (in Spinal.scala from spinalhdl-core)

And in the MainConfig, the targetDirectory to be “gen”, and it sets the async reset to be active low.

Summary

From the Hello World example, it shows that the SpinalHDL is much more powerful and flexible for design parameterization.

Posted by FPGA Limerick at March 11, 2023 |  0 Comments

Hello, everyone. Welcome to the fourth episode of FPGA limerick. In this episode, we will talk about the linter, formatter, logging and editor for SpinalHDL. However, as we all know, the concepts like linter, formatter etc. are universal. They are not only confined to SpinalHDL. So we will expand the scope to other languages when it is necessary.

Linter for C/C++

Maybe we can start with a more popular language like C/C++. An often-used linter for C/C++ is clang-tidy. On Ubuntu, (which is the Linux distro we choose for WSL), it can be installed like

sudo apt install clang-tidy

And you can use the following to check a C/C++ source file:

clang-tidy -checks=* file_name.cpp

And you can use the following inline comment to ignore a certain warning, like

// NOLINT(cppcoreguidelines-avoid-magic-numbers, readability-magic-numbers)

Or simply just

// NOLINT

 

Formatter for C/C++

An often-used formatter for C/C++ is clang-formatter, which can be installed on Ubuntu like

sudo apt install clang-format

And you can format your code in place by:

clang-format -i -style="{BasedOnStyle: Google, SortIncludes: false}" file_name.cpp

Here we choose to follow Google C++ Style Guide, and to disable the sorting of the include order (The sorting of the include order might cause compiling error.)

Linter for Python

An often-used one is pylint

sudo apt install pylint

 

Linter for Verilog / SystemVerilog

Option 1: verible

Can be downloaded from https://github.com/chipsalliance/verible/releases

verible-verilog-lint file_name.sv

 

Option 2: verilator_bin

After installing verilator

verilator_bin --lint-only file_name.sv

 

Formatter for Verilog / SystemVerilog

verible (download from https://github.com/chipsalliance/verible/releases )

format in place

verible-verilog-format --inplace file_name.sv

 

Linter and Logging for SpinalHDL

 

Now let’s get to the main part of this episode: SpinalHDL (or Scala)

The style is mostly based on

Official Scala Style Guide:

https://docs.scala-lang.org/style/

SpinalHDL Coding Convention

https://spinalhdl.github.io/SpinalDoc-RTD/dev/SpinalHDL/Getting%20Started/Scala%20Guide/coding_conventions.html

 

If you check out the Hello World example (v1.1.2 tag) from our GitHub repo

git clone --depth --branch v1.1.3 https://github.com/PulseRain/FpgaLimerick.git

cd FpgaLimerick

cd HelloWorld

You will see three configuration files (next to the build.sbt) for the linter/formatter:

.scalafix.conf: Configuration file for scalafix ( https://scalacenter.github.io/scalafix/)

scalastyle-config.xml: Configuration file for scalastyle ( http://www.scalastyle.org/)

(And scalastyle can also be enabled in IntelliJ Editor, which we will discuss later.)

.scalafmt.conf: Configuration for scalafmt ( https://scalameta.org/scalafmt/ )

(code formatter for scala, which is integrated with IntelliJ.)

 

Now let’s see how we can use those linter and formatter in SBT command line:

In FpgaLimerick/HelloWorld

And interactive like the following

C:\GitHub\FpgaLimerick\HelloWorld>sbt

[info] welcome to sbt 1.8.2 (Oracle Corporation Java 19.0.2)

[info] loading settings for project helloworld-build from plugins.sbt ...

[info] loading project definition from C:\GitHub\FpgaLimerick\HelloWorld\project

[info] loading settings for project helloworld from build.sbt ...

[info] set current project to helloworld (in build file:/C:/GitHub/FpgaLimerick/HelloWorld/)

[info] sbt server started at local:sbt-server-e926ab8ee3957332f208

[info] started sbt server

sbt:helloworld> scalastyle

[info] scalastyle using config C:\GitHub\FpgaLimerick\HelloWorld\scalastyle-config.xml

[info] scalastyle Processed 4 file(s)

[info] scalastyle Found 0 errors

[info] scalastyle Found 0 warnings

[info] scalastyle Found 0 infos

[info] scalastyle Finished in 5 ms

[success] created output: C:\GitHub\FpgaLimerick\HelloWorld\target

[success] Total time: 0 s, completed Mar 5, 2023, 4:50:35 AM

sbt:helloworld> scalafix -check

[info] Running scalafix on 4 Scala sources

[success] Total time: 6 s, completed Mar 5, 2023, 4:50:56 AM

sbt:helloworld>

 

For now, everything looks clean. Now if we open the

HelloWorld/src/spinal/NcoCounter.scala

Now change the line #88 from logger.info to println

And if we run “scalastyle” again, we will see the following:

sbt:helloworld> scalastyle

[info] scalastyle using config C:\GitHub\FpgaLimerick\HelloWorld\scalastyle-config.xml

[warn] C:\GitHub\FpgaLimerick\HelloWorld\src\spinal\NcoCounter.scala:88:4: Regular expression matched 'println'

[warn] C:\GitHub\FpgaLimerick\HelloWorld\src\spinal\NcoCounter.scala:88:4: Regular expression matched 'println'

[info] scalastyle Processed 4 file(s)

[info] scalastyle Found 0 errors

[info] scalastyle Found 2 warnings

[info] scalastyle Found 0 infos

[info] scalastyle Finished in 5 ms

[success] created output: C:\GitHub\FpgaLimerick\HelloWorld\target

[warn] warnings exist

[success] Total time: 0 s, completed Mar 5, 2023, 5:03:10 AM

sbt:helloworld>

 

Here the println gets a warning, because println is deemed as a bad way for logging, as explained in https://www.baeldung.com/scala/apache-log4j

For that, we have setup the build.sbt for log4j2, and put the configuration file in

HelloWorld/src/main/resources/log4j2.xml

Currently the log4j2 is setup to be at INFO level, and it will output to both stdout and log file. The log files can be found under the logs folder.

 

Formatter and Editor for SpinalHDL

We didn’t demo the scalafmt early for the SBT command line, as we think it is better to use the scalafmt together with the editor. As for the editor of SpinalHDL, it is best to use IntelliJ IDEA.

 The IntelliJ IDEA can be downloaded from

https://www.jetbrains.com/idea/download/download-thanks.html?platform=windows&code=IIC

And after installation, please also install the Scala Plugin, as illustrated below

Then, the Hello World project can be opened as SBT project.

And for the first time, in Menu 

File/Project Structure … /SDK needs to be setup for the JDK, as shown below

And the JVM for SBT can be setup in Menu

File/Settings … /Build, Execution, Deployment /Build Tools / sbt, Choose JRE on the right hand side:

As for the scalafmt, the formatter can be setup in Menu

File / Settings… /Editor/Code Style/Scala

Set the Formatter as scalafmt, and Click the “Reformat on Save”

Now, we can launch the sbt shell (at the bottom of the IntelliJ IDEA), and type in run to run the Hello World (choose 2 to test the verilator simulation)

To use scalastyle and exclude the test folder, please right click the test/spinal folder and mark directory as test sources root

Then in Menu

File / Settings…/Editor/Inspections/Scala/Code Style/Scala Style Inspection

And setup like the following:

Posted by FPGA Limerick at March 05, 2023 |  0 Comments

*) Legal Disclaimer
*) Introduction

*) GitHub Repo
*) YouTube
*) SpinalHDL
*) cocotb

*) FCC Wireless
*) ARRL
*) PAPA System
*) EARS