Merge 789f0f18d5 into a4eb1e65ef

Readme pointing to Getting started from RTD

.gitignore

@@ -11,15 +11,21 @@ target
 lib_managed/
 src_managed/
 project/boot/
+project/project
 project/plugins/project/
 
 # Scala-IDE specific
 .scala_dependencies
 .worksheet
+.bloop
 
 .idea
 out
 
+# Metals
+.metals
+project/metals.sbt
+
 # Eclipse
 bin/
 .classpath

.mill-version

@@ -0,0 +1 @@
+0.9.8

.scalafmt.conf

@@ -0,0 +1,40 @@
+version = 3.6.0
+runner.dialect = scala212
+align.preset = some
+align.tokens."+" = [
+    {
+        code = "="
+        owners = [{
+            regex = "Defn\\.Val"
+        }]
+    }
+    {
+        code = ":="
+        owners = [{
+            regex = "Term\\.ApplyInfix"
+            parents = ["Term\\.Block|Template"]
+        }]
+    }
+    {
+        code = "#="
+        owners = [{
+            regex = "Term\\.ApplyInfix"
+            parents = ["Term\\.Block|Template"]
+        }]
+    }
+    {
+        code = "port"
+        owners = [{
+            regex = "Term\\.ApplyInfix"
+            parents = ["Defn\\.Val"]
+        }]
+    }
+    {
+        code = "->"
+        owners = [{
+            regex = "Term\\.ApplyInfix"
+        }]
+    }
+]
+docstrings.wrap = no
+docstrings.oneline = fold

.vscode/SpinalHDL.code-snippets

@@ -0,0 +1,190 @@
+{
+	"Import spinal.core": {
+		"scope": "scala",
+		"prefix": "importcore",
+		"body": ["import spinal.core._", ""]
+	},
+
+	"Import spinal.lib": {
+		"scope": "scala",
+		"prefix": "importlib",
+		"body": ["import spinal.lib.${1:_}", ""]
+	},
+
+	"Import spinal.core.sim": {
+		"scope": "scala",
+		"prefix": "importsim",
+		"body": ["import spinal.core.sim._", ""]
+	},
+
+	"New component": {
+		"scope": "scala",
+		"prefix": "component",
+		"body": [
+			"case class $1($2) extends Component {",
+			"  val io = new Bundle {",
+			"    $0",
+			"  }",
+			"",
+			"  ",
+			"}"
+		],
+	},
+
+	"Component to function": {
+		"scope": "scala",
+		"prefix": "fncomp",
+		"body": [
+			"object ${1/\\(.*//} {",
+			"  def apply($2: $3): $4 = {",
+			"    val ${1/([^(]*).*/${1:/camelcase}/} = $1($6)",
+			"    ${1/([^(]*).*/${1:/camelcase}/}.io.$2 := $2",
+			"    ${1/([^(]*).*/${1:/camelcase}/}.io.$5",
+			"  }",
+			"}"
+		],
+	},
+
+	"Component to function2": {
+		"scope": "scala",
+		"prefix": "fncomp2",
+		"body": [
+			"object ${1/\\(.*//} {",
+			"  def apply($2: $3, $4: $5): $6 = {",
+			"    val ${1/([^(]*).*/${1:/camelcase}/} = $1($8)",
+			"    ${1/([^(]*).*/${1:/camelcase}/}.io.$2 := $2",
+			"    ${1/([^(]*).*/${1:/camelcase}/}.io.$4 := $4",
+			"    ${1/([^(]*).*/${1:/camelcase}/}.io.$7",
+			"  }",
+			"}"
+		],
+	},
+
+	"New configurable component": {
+		"scope": "scala",
+		"prefix": "compcfg",
+		"body": [
+			"case class ${2:${1}Cfg} (",
+			"  $3",
+			")",
+			"",
+			"class $1(cfg: $2) extends Component {",
+			"  val io = new Bundle {",
+			"    $0",
+			"  }",
+			"",
+			"  ",
+			"}"
+		],
+	},
+
+	"New entity/architecture-like": {
+		"scope": "scala",
+		"prefix": "entarch",
+		"body": [
+			"abstract class $1$2 extends Component {",
+			"  val io = new Bundle {",
+			"    $0",
+			"  }",
+			"}",
+			"",
+			"class $1$3 extends $1$4 {",
+			"  ",
+			"}",
+		],
+	},
+
+	"New input": {
+		"scope": "scala",
+		"prefix": "pin",
+		"body": "val $1 = in port ",
+	},
+
+	"New output": {
+		"scope": "scala",
+		"prefix": "pout",
+		"body": "val $1 = out port ",
+	},
+
+	"New master port": {
+		"scope": "scala",
+		"prefix": "pmaster",
+		"body": "val $1 = master port ",
+	},
+
+	"New slave port": {
+		"scope": "scala",
+		"prefix": "pslave",
+		"body": "val $1 = slave port ",
+	},
+
+	"Bits": {
+		"scope": "scala",
+		"prefix": "nbits",
+		"body": "Bits($1 bits)",
+	},
+
+	"UInt": {
+		"scope": "scala",
+		"prefix": "nuint",
+		"body": "UInt($1 bits)",
+	},
+
+	"SInt": {
+		"scope": "scala",
+		"prefix": "nsint",
+		"body": "SInt($1 bits)",
+	},
+
+	"...ing flag": {
+		"scope": "scala",
+		"prefix": "doing",
+		"body": ["val ${2:${1}ing} = False", "def $1(): Unit = $2 := True", ""]
+	},
+
+	"...Flag flag": {
+		"scope": "scala",
+		"prefix": "flag",
+		"body": ["val ${2:${1}Flag} = False", "def $1(): Unit = $2 := True", ""]
+	},
+
+	"'def' function mux": {
+		"scope": "scala",
+		"prefix": "fnmux",
+		"body": ["$1 := $2", "def $3(): Unit = $1 := $0"]
+	},
+
+	"BlackBox wrapper": {
+		"scope": "scala",
+		"prefix": "blackboxwrapper",
+		"body": [
+			"class $1 extends Area {",
+			"  val io = new Bundle {",
+			"    ${0:// Direction-less Spinal ports}",
+			"  }",
+			"",
+			"  class $1 extends BlackBox {",
+			"    // Ports of the blackboxed item",
+			"  }",
+			"",
+			"  val bb = new $1",
+			"  bb.setPartialName(\"\")",
+			"",
+			"  // Connection logic",
+			"}"
+		]
+	},
+
+	"State machine": {
+		"scope": "scala",
+		"prefix": "fsm",
+		"body": [
+			"val $1 = new StateMachine {",
+			"  val $2, $3 = new State",
+			"  setEntry($2)",
+			"",
+			"  $0",
+			"}"
+		]
+	}
+}

README.md

@@ -1,108 +1,83 @@
-Spinal Base Project
-============
-This repository is a base SBT project added to help non Scala/SBT native people in their first steps.
+# SpinalHDL Base Project
 
-Just one important note, you need a java JDK >= 8
+This repository is a base project to help Spinal users set-up project without knowledge about Scala and SBT.
 
-On debian : 
+
+## If it is your are learning SpinalHDL
+
+You can follow the tutorial on the [Getting Started](https://spinalhdl.github.io/SpinalDoc-RTD/master/SpinalHDL/Getting%20Started/index.html) page.
+
+More specifically:
+
+* instructions to install tools can be found on the [Install and setup](https://spinalhdl.github.io/SpinalDoc-RTD/master/SpinalHDL/Getting%20Started/Install%20and%20setup.html#install-and-setup) page
+* instructions to get this repository locally are available in the [Create a SpinalHDL project](https://spinalhdl.github.io/SpinalDoc-RTD/master/SpinalHDL/Getting%20Started/Install%20and%20setup.html#create-a-spinalhdl-project) section.
+
+
+### TL;DR Things have arleady been set up in my environment, how do I run things to try SpinalHDL?
+
+Once in the `SpinalTemplateSbt` directory, when tools are installed, the commands below can be run to use `sbt`.
 
 ```sh
-sudo add-apt-repository -y ppa:openjdk-r/ppa
-sudo apt-get update
-sudo apt-get install openjdk-8-jdk -y
+// To generate the Verilog from the example
+sbt "runMain projectname.MyTopLevelVerilog"
 
-#To set the default java
-sudo update-alternatives --config java
-sudo update-alternatives --config javac
+// To generate the VHDL from the example
+sbt "runMain projectname.MyTopLevelVhdl"
+
+// To run the testbench
+sbt "runMain projectname.MyTopLevelSim"
 ```
 
-## Basics, without any IDE
+* The example hardware description is into `hw/spinal/projectname/MyTopLevel.scala`
+* The testbench is into `hw/spinal/projectname/MyTopLevelSim.scala`
 
-You need to install SBT
+When you really start working with SpinalHDL, it is recommended (both for comfort and efficiency) to use an IDE, see the [Getting started](https://spinalhdl.github.io/SpinalDoc-RTD/master/SpinalHDL/Getting%20Started/index.html).
+
+
+## If you want to create a new project from this template
+
+### Change project name
+
+You might want to change the project name, which is currently `projectname`. To do so (let's say your actual project name is `myproject`; it must be all lowercase with no separators):
+
+* Update `build.sbt` and/or `build.sc` by replacing `projectname` by the name of your project `myproject` (1 occurrence in each file). The better is to replace in both (it will always work), but in some contexts you can keep only one of these two files:
+    * If you are sure all people only use `sbt`, you can replace only in `build.sbt` and remove `build.sc`
+    * If you are sure all people only use `mill`, you can replace only in `build.sc` and remove `build.sbt`
+    * Replace in both files for open-source project.
+* Put all your scala files into `hw/spinal/myproject/` (remove the unused `hw/spinal/projectname/` folder)
+* Start all your scala files with `package myproject`
+
+
+### Change project structure
+
+You can change the project structure as you want. The only restrictions (from Scala environment) are (let's say your actual project name is `myproject`):
+
+* you must have a `myproject` folder and files in it must start with `package myproject`
+* if you have a file in a subfolder `myproject/somepackage/MyElement.scala` it must start with `package myproject.somepackage`.
+* `sbt` and `mill` must be run right in the folder containing their configurations (recommended to not move these files)
+
+Once the project structure is modified, update configurations:
+
+* In `build.sbt` and/or `build.sc` (see above) replace `/ "hw" / "spinal"` by the new path to the folder containing the `myproject` folder.
+* In the spinal configuration file (if you kept it, by default it is in `projectname/Config.scala`) change the path in `targetDirectory = "hw/gen"` to the directory where you want generated files to be written. If you don't use a config or if it doesn't contain this element, generated files will be written in the root directory.
+
+
+### Update this README
+
+Of course you can replace/modify this file to help people with your own project!
+
+
+## Mill Support (Experimental)
+
+The [Mill build tool](https://com-lihaoyi.github.io/mill) can be installed and used instead of `sbt`.
 
 ```sh
-echo "deb https://dl.bintray.com/sbt/debian /" | sudo tee -a /etc/apt/sources.list.d/sbt.list
-sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 2EE0EA64E40A89B84B2DF73499E82A75642AC823
-sudo apt-get update
-sudo apt-get install sbt
+// To generate the Verilog from the example
+mill projectname.runMain projectname.MyTopLevelVerilog
+
+// To generate the VHDL from the example
+mill projectname.runMain projectname.MyTopLevelVhdl
+
+// To run the testbench
+mill projectname.runMain projectname.MyTopLevelSim
 ```
-
-If you want to run the scala written testbench, you have to be on linux and have Verilator installed (a recent version) :
-
-```sh
-sudo apt-get install git make autoconf g++ flex bison -y  # First time prerequisites
-git clone http://git.veripool.org/git/verilator   # Only first time
-unsetenv VERILATOR_ROOT  # For csh; ignore error if on bash
-unset VERILATOR_ROOT  # For bash
-cd verilator
-git pull        # Make sure we're up-to-date
-git checkout verilator_3_916
-autoconf        # Create ./configure script
-./configure
-make -j$(nproc)
-sudo make install
-cd ..
-echo "DONE"
-
-```
-
-Clone or download this repository.
-
-```sh
-git clone https://github.com/SpinalHDL/SpinalTemplateSbt.git
-```
-
-Open a terminal in the root of it and run "sbt run". At the first execution, the process could take some seconds
-
-```sh
-cd SpinalTemplateSbt
-
-//If you want to generate the Verilog of your design
-sbt "runMain mylib.MyTopLevelVerilog"
-
-//If you want to generate the VHDL of your design
-sbt "runMain mylib.MyTopLevelVhdl"
-
-//If you want to run the scala written testbench
-sbt "runMain mylib.MyTopLevelSim"
-```
-
-The top level spinal code is defined into src\main\scala\mylib
-
-## Basics, with Intellij IDEA and its scala plugin
-
-You need to install :
-
-- Java JDK 8
-- SBT
-- Intellij IDEA (the free Community Edition is good enough)
-- Intellij IDEA Scala plugin (when you run Intellij IDEA the first time, he will ask you about it)
-
-And do the following :
-
-- Clone or download this repository.
-- In Intellij IDEA, "import project" with the root of this repository, Import project from external model SBT
-- In addition maybe you need to specify some path like JDK to Intellij
-- In the project (Intellij project GUI), go in src/main/scala/mylib/MyTopLevel.scala, right click on MyTopLevelVerilog, "Run MyTopLevelVerilog"
-
-Normally, this must generate an MyTopLevel.v output files.
-
-## Basics, with Eclipse and its scala plugin
-
-You need to install :
-
-- Java JDK
-- Scala
-- SBT
-- Eclipse (tested with Mars.2 - 4.5.2)
-- [scala plugin](http://scala-ide.org/) (tested with 4.4.1)
-
-And do the following :
-
-- Clone or download this repository.
-- Run ```sbt eclipse``` in the ```SpinalTemplateSbt``` directory.
-- Import the eclipse project from eclipse.
-- In the project (eclipse project GUI), right click on src/main/scala/mylib/MyTopLevel.scala, right click on MyTopLevelVerilog, and select run it
-
-Normally, this must generate output file ```MyTopLevel.v```.
-

build.sbt

@@ -1,13 +1,17 @@
-name := "SpinalTemplateSbt"
-version := "1.0"
-scalaVersion := "2.11.12"
-val spinalVersion = "1.4.0"
+ThisBuild / version := "1.0"
+ThisBuild / scalaVersion := "2.12.16"
+ThisBuild / organization := "org.example"
 
-libraryDependencies ++= Seq(
-  "com.github.spinalhdl" % "spinalhdl-core_2.11" % spinalVersion,
-  "com.github.spinalhdl" % "spinalhdl-lib_2.11" % spinalVersion,
-  compilerPlugin("com.github.spinalhdl" % "spinalhdl-idsl-plugin_2.11" % spinalVersion)
-)
+val spinalVersion = "1.8.1"
+val spinalCore = "com.github.spinalhdl" %% "spinalhdl-core" % spinalVersion
+val spinalLib = "com.github.spinalhdl" %% "spinalhdl-lib" % spinalVersion
+val spinalIdslPlugin = compilerPlugin("com.github.spinalhdl" %% "spinalhdl-idsl-plugin" % spinalVersion)
+
+lazy val projectname = (project in file("."))
+  .settings(
+    Compile / scalaSource := baseDirectory.value / "hw" / "spinal",
+    Test / scalaSource := baseDirectory.value / "tb" / "spinal",
+    libraryDependencies ++= Seq(spinalCore, spinalLib, spinalIdslPlugin)
+  )
 
 fork := true
-EclipseKeys.withSource := true

build.sc

@@ -0,0 +1,17 @@
+import mill._, scalalib._
+
+val spinalVersion = "1.8.0"
+
+object projectname extends SbtModule {
+  def scalaVersion = "2.12.16"
+  override def millSourcePath = os.pwd
+  def sources = T.sources(
+    millSourcePath / "hw" / "spinal",
+    millSourcePath / "tb" / "spinal"
+  )
+  def ivyDeps = Agg(
+    ivy"com.github.spinalhdl::spinalhdl-core:$spinalVersion",
+    ivy"com.github.spinalhdl::spinalhdl-lib:$spinalVersion"
+  )
+  def scalacPluginIvyDeps = Agg(ivy"com.github.spinalhdl::spinalhdl-idsl-plugin:$spinalVersion")
+}

hw/gen/.gitignore

@@ -0,0 +1 @@
+*

hw/spinal/projectname/Config.scala

@@ -0,0 +1,16 @@
+package projectname
+
+import spinal.core._
+import spinal.core.sim._
+
+object Config {
+  def spinal = SpinalConfig(
+    targetDirectory = "hw/gen",
+    defaultConfigForClockDomains = ClockDomainConfig(
+      resetActiveLevel = HIGH
+    ),
+    onlyStdLogicVectorAtTopLevelIo = true
+  )
+
+  def sim = SimConfig.withConfig(spinal).withFstWave
+}

hw/spinal/projectname/MyTopLevel.scala

@@ -0,0 +1,30 @@
+package projectname
+
+import spinal.core._
+
+// Hardware definition
+case class MyTopLevel() extends Component {
+  val io = new Bundle {
+    val cond0 = in  Bool()
+    val cond1 = in  Bool()
+    val flag  = out Bool()
+    val state = out UInt(8 bits)
+  }
+
+  val counter = Reg(UInt(8 bits)) init 0
+
+  when(io.cond0) {
+    counter := counter + 1
+  }
+
+  io.state := counter
+  io.flag := (counter === 0) | io.cond1
+}
+
+object MyTopLevelVerilog extends App {
+  Config.spinal.generateVerilog(MyTopLevel())
+}
+
+object MyTopLevelVhdl extends App {
+  Config.spinal.generateVhdl(MyTopLevel())
+}

project/build.properties

@@ -1 +1 @@
-sbt.version=1.3.3
+sbt.version=1.6.0

project/plugins.sbt

@@ -1,4 +1 @@
-addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "5.2.4")
-
-addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.14.10")
-
+addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.4.6")

src/main/scala/mylib/MyTopLevel.scala

@@ -1,67 +0,0 @@
-/*
- * SpinalHDL
- * Copyright (c) Dolu, All rights reserved.
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 3.0 of the License, or (at your option) any later version.
- *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this library.
- */
-
-package mylib
-
-import spinal.core._
-import spinal.lib._
-
-import scala.util.Random
-
-//Hardware definition
-class MyTopLevel extends Component {
-  val io = new Bundle {
-    val cond0 = in  Bool
-    val cond1 = in  Bool
-    val flag  = out Bool
-    val state = out UInt(8 bits)
-  }
-  val counter = Reg(UInt(8 bits)) init(0)
-
-  when(io.cond0){
-    counter := counter + 1
-  }
-
-  io.state := counter
-  io.flag  := (counter === 0) | io.cond1
-}
-
-//Generate the MyTopLevel's Verilog
-object MyTopLevelVerilog {
-  def main(args: Array[String]) {
-    SpinalVerilog(new MyTopLevel)
-  }
-}
-
-//Generate the MyTopLevel's VHDL
-object MyTopLevelVhdl {
-  def main(args: Array[String]) {
-    SpinalVhdl(new MyTopLevel)
-  }
-}
-
-
-//Define a custom SpinalHDL configuration with synchronous reset instead of the default asynchronous one. This configuration can be resued everywhere
-object MySpinalConfig extends SpinalConfig(defaultConfigForClockDomains = ClockDomainConfig(resetKind = SYNC))
-
-//Generate the MyTopLevel's Verilog using the above custom configuration.
-object MyTopLevelVerilogWithCustomConfig {
-  def main(args: Array[String]) {
-    MySpinalConfig.generateVerilog(new MyTopLevel)
-  }
-}

src/main/scala/mylib/MyTopLevelSim.scala

@@ -1,38 +0,0 @@
-package mylib
-
-import spinal.core._
-import spinal.sim._
-import spinal.core.sim._
-
-import scala.util.Random
-
-
-//MyTopLevel's testbench
-object MyTopLevelSim {
-  def main(args: Array[String]) {
-    SimConfig.withWave.doSim(new MyTopLevel){dut =>
-      //Fork a process to generate the reset and the clock on the dut
-      dut.clockDomain.forkStimulus(period = 10)
-
-      var modelState = 0
-      for(idx <- 0 to 99){
-        //Drive the dut inputs with random values
-        dut.io.cond0 #= Random.nextBoolean()
-        dut.io.cond1 #= Random.nextBoolean()
-
-        //Wait a rising edge on the clock
-        dut.clockDomain.waitRisingEdge()
-
-        //Check that the dut values match with the reference model ones
-        val modelFlag = modelState == 0 || dut.io.cond1.toBoolean
-        assert(dut.io.state.toInt == modelState)
-        assert(dut.io.flag.toBoolean == modelFlag)
-
-        //Update the reference model value
-        if(dut.io.cond0.toBoolean) {
-          modelState = (modelState + 1) & 0xFF
-        }
-      }
-    }
-  }
-}

tb/spinal/projectname/MyTopLevelFormal.scala

@@ -0,0 +1,24 @@
+package projectname
+
+import spinal.core._
+import spinal.core.formal._
+
+// You need SymbiYosys to be installed.
+// See https://spinalhdl.github.io/SpinalDoc-RTD/master/SpinalHDL/Formal%20verification/index.html#installing-requirements
+object MyTopLevelFormal extends App {
+  FormalConfig
+    .withBMC(10)
+    .doVerify(new Component {
+      val dut = FormalDut(MyTopLevel())
+
+      // Ensure the formal test start with a reset
+      assumeInitial(clockDomain.isResetActive)
+
+      // Provide some stimulus
+      anyseq(dut.io.cond0)
+      anyseq(dut.io.cond1)
+
+      // Check the state initial value and increment
+      assert(dut.io.state === past(dut.io.state + U(dut.io.cond0)).init(0))
+    })
+}

tb/spinal/projectname/MyTopLevelSim.scala

@@ -0,0 +1,31 @@
+package projectname
+
+import spinal.core._
+import spinal.core.sim._
+
+object MyTopLevelSim extends App {
+  Config.sim.compile(MyTopLevel()).doSim { dut =>
+    // Fork a process to generate the reset and the clock on the dut
+    dut.clockDomain.forkStimulus(period = 10)
+
+    var modelState = 0
+    for (idx <- 0 to 99) {
+      // Drive the dut inputs with random values
+      dut.io.cond0.randomize()
+      dut.io.cond1.randomize()
+
+      // Wait a rising edge on the clock
+      dut.clockDomain.waitRisingEdge()
+
+      // Check that the dut values match with the reference model ones
+      val modelFlag = modelState == 0 || dut.io.cond1.toBoolean
+      assert(dut.io.state.toInt == modelState)
+      assert(dut.io.flag.toBoolean == modelFlag)
+
+      // Update the reference model value
+      if (dut.io.cond0.toBoolean) {
+        modelState = (modelState + 1) & 0xff
+      }
+    }
+  }
+}