Limerick(4) - Linter, Formatter, Logging and Editor



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:


Comments

Post a Comment

Popular posts from this blog

Limerick(6) - SpinalHDL Tutorial: the Simulation Flow of Hello World

Image
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 Verif...
Read more

Limerick(8) - Cocotb Tutorial: Introduction

Image
Hello everyone, welcome to the eighth episode of FPGA Limerick. In this episode, we will talk about the cocotb to make Python based test bench. And to show why we choose cocotb for verification, let’s visit other possible options: Overview 1. Verification, the old-fashioned way: Use Verilog/VHDL to make both testbench and DUT: As of today, a lot of companies still do things this way. However, because the Verilog/VHDL lacks the features offered by high level programming language, this method becomes very inflexible, verbose and unproductive. 2. Verification: HVL + HDL 3. Verification / Design with System Verilog Although System Verilog did a good job introducing high level programming language features, such as Object Oriented syntax, it is still considered too verbose and low level comparing to newer programming languages like Python. And thus comes the cocotb. Cocotb stands for Coroutine Cosimulation Testbench. It is a Python based verification framework. And practically it can be a g...
Read more

Limerick(9) - Cocotb Tutorial: Test Bench Structure

Image
Hello, everyone. Welcome to the nineth episode of FPGA limerick. In this episode, we will take a deep look into the test bench structure of cocotb. As we know, cocotb stands for Coroutine Cosimulation Testbench. So before we start, we might ask ourselves: What is coroutine? In multi-task scenario, coroutine can be viewed as a collaborative non-preemptive thread. The following shows two coroutines calling each other, with yield at every step. And the execution order will always be 1, 2, 3, 4, 5 In cocotb, the coroutine is marked by putting “async” in front of the function name. And the yield is done with “await” command. We will soon see the details when it comes to the test bench next. The Classic Way If you read the official document of cocotb, it uses Makefile to organize the test bench. And for each coroutine, it will be decorated @cocotb.test(), like the following example: @cocotb.test() async def test_xxx(dut):    … However, what we will recommend is something differe...
Read more