Understand chisel language thoroughly 09. Chisel project construction, operation and testing (I) -- build and run chisel project with SBT

Chisel The project build 、 Run and test （ One ）—— use sbt structure Chisel Project and run

The last part introduces Chisel Basic grammar of , But except for the beginning of the tutorial Demo outside , We haven't started writing Chisel Code , This is a big taboo for learning programming languages . But fortunately, Chisel The basic grammar is not much , The eyes may master a big difference after going through it . But not always , So this part will talk about how to start our Chisel project .

How to start Chisel project

So build Chisel What do we need to know about the project ？

First , We need to know how to compile Chisel The program! ？ secondly , We need to know how to use Chisel Code generation Verilog The code comes from FPGA Go ahead ？ Moreover, we also need to know how to write tests to debug and verify whether our code is correct ？

Chisel Yes, it is Scala Written , So it supports building Scala The process of the project should be Chisel It also applies to projects . and Scala The last popular build tool is sbt, It is Scala interactive Build Tool Abbreviation . This sbt It can not only drive the compilation and testing process , Can also give Scala and Chisel Download the correct version of the Library , That is, it has the function of package management .

at present Chisel The popular project construction tool is sbt and mill, We use sbt Build our project .

About sbt and build.sbt The configuration file

Scala Kuzhong and Chisel and Chisel tester The relevant part is in the construction process from a Maven Downloaded from the warehouse , And these libraries are through build.sbt The file refers to .Chisel A typical project build.sbt The contents of the document are as follows ：

// See README.md for license details.

ThisBuild / scalaVersion     := "2.13.8"
ThisBuild / version          := "0.1.0"
ThisBuild / organization     := "com.github.github3rr0r"

val chiselVersion = "3.5.1"

lazy val root = (project in file("."))
  .settings(
    name := "OhMyChisel",
    libraryDependencies ++= Seq(
      "edu.berkeley.cs" %% "chisel3" % chiselVersion,
      "edu.berkeley.cs" %% "chiseltest" % "0.5.1" % "test"
    ),
    scalacOptions ++= Seq(
      "-language:reflectiveCalls",
      "-deprecation",
      "-feature",
      "-Xcheckinit",
      "-P:chiselplugin:genBundleElements",
    ),
    addCompilerPlugin("edu.berkeley.cs" % "chisel3-plugin" % chiselVersion cross CrossVersion.full),
  )

We can do it in build.sbt Configuration in file latest.release To specify the latest Chisel edition , But the disadvantage of this is that it will be online every time Maven Search again in the warehouse , If there is no networking, the construction will fail . So the best thing to do is build.sbt Specified in Chisel edition , Other Scala So is the library .

For example, the typical example given above build.sbt In file ,Scala The version is specified as "2.13.8",Chisel The version is specified as "3.5.1",chiseltest The version is specified as "0.5.1". The designated version not only avoids the embarrassment when there is no Internet , At the same time, it also maintains good project stability , For example, because Chisel Fast development , therefore API The incompatibility is Chisel It happens from time to time .

Chisel Project source code organization

sbt Inherited Maven Build source code organization conventions for automation tools , meanwhile Maven It's also open source Java The manager of the warehouse ,Chisel stay Maven The warehouse in the warehouse is here ：Maven Repository: edu.berkeley.cs » chisel3 (mvnrepository.com).

The following figure shows a typical Chisel Project source code organization ：

project The folder is the root directory of the project , You can also use other names , This root directory contains build.sbt, It may also include a for the build process Makefile file , And there could be README Document and LICENSE file .

In the project root directory src The folder contains all the source code , It's divided into main The folder and test Folder , The former contains all the hardware source code , The latter contains all the tester code .Chisel It's from Scala inherited ,Scala Again from Java Inherited the organizational structure of the source software package . package （Package） We can put our Chisel The code is organized into namespaces , Packages can also contain sub packages .

In the root directory of the project target The folder contains bytecode like files and other generated files , Usually we don't put our generated in this folder Verilog file , It's in the root directory generated Generate under folder Verilog file .

In order to be in Chisel The convenience of using namespaces in , We need to declare that we define a class under a package , For example, the following example is in mypack The package defines a Abc class ：

package mypack

import chisel3._

class Abc extends Module {
    
    val io = IO(new Bundle{
    })
}

It should be noted that , Here we import chisel3 Use this package Chisel Class in .

Now we want to in other contexts （ That is, different package namespaces ） Using modules Abc, Then we need to import mypack Components in the package ：

import mypack._

class AbcUser extends Module {
    
    val io = IO(new Bundle{
    })
    val abc = new Abc()
}

The underline in the above two pieces of code _ Represents a wildcard , It means that all classes in the package will be imported .

Or not from mypack Import all types , Instead, use the full name mypack.Abc To instruct mypack In bag Abc：

class AbcUser2 extends Module {
    
    val io = IO(new Bundle{
    })
    val abc = new mypack.Abc()
}

You can also import only Abc This class is used to create instances ：

import mypack.Abc

class AbcUser extends Module {
    
    val io = IO(new Bundle{
    })
    val abc = new Abc()
}

use sbt function Chisel project

A simple instruction can be used sbt Compile and run Chisel project ：

sbt run

This instruction will compile all from the source tree Chisel Code , And search for classes that contain main Method's object class , Or simply search directly from App The object of expansion . If multiple objects are found , That will list all eligible objects , We can choose one to execute . We can also directly specify the execution of an object , Pass it as a parameter to sbt that will do ：

sbt "runMain mypacket.MyObject"

sbt The default value is to search for main part , Instead of searching test part , This agreement also comes from Java and Scala To the . If you want to execute based on ChiselTest and ScalaTest Test of , Just run this code directly ：

sbt test

If we write a test , Not followed ChiselTest And contains a main function , But put it in the source code tree test Under the folder , We can do this ：

sbt "test:runMain mypacket.MyMainTest"

Conclusion

This article introduces sbt And how to use sbt structure 、 function Chisel project , It also introduces Chisel The source code organization structure of the project , It's almost ready for practice . But before we begin to practice, we still have two problems to solve , One is how to generate Verilog Code , The other is how to write tests 、 Run the test . Although this article also mentions the use of sbt Run the test , But I don't know how to write . Next , We will also have several articles , The previous article introduced Chisel How to generate Verilog Code and Chisel Tool flow for , How to write the following articles Chisel Four postures for testing and debugging .