From 8fa46071c382b6fdecba86a9bab729526fa4fbe2 Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Thu, 4 Feb 2021 10:07:56 -0800 Subject: Minor docs improvements (#1774) * Fix some botched formatting (replace ```mdoc scala with ```scala mdoc) * Replace some unnecessary uses of triple backticks with single backticks * Move appendix docs from wiki-deprecated/ to appendix/ * This will require an update on the website as well * Update Bundle literal docs--- docs/src/appendix/chisel3-vs-chisel2.md | 203 +++++++++++++++++++++ docs/src/appendix/experimental-features.md | 138 ++++++++++++++ docs/src/appendix/upgrading-from-scala-2-11.md | 88 +++++++++ docs/src/explanations/blackboxes.md | 50 ++--- docs/src/explanations/bundles-and-vecs.md | 24 +-- docs/src/wiki-deprecated/chisel3-vs-chisel2.md | 203 --------------------- docs/src/wiki-deprecated/experimental-features.md | 119 ------------ .../wiki-deprecated/upgrading-from-scala-2-11.md | 88 --------- 8 files changed, 464 insertions(+), 449 deletions(-) create mode 100644 docs/src/appendix/chisel3-vs-chisel2.md create mode 100644 docs/src/appendix/experimental-features.md create mode 100644 docs/src/appendix/upgrading-from-scala-2-11.md delete mode 100644 docs/src/wiki-deprecated/chisel3-vs-chisel2.md delete mode 100644 docs/src/wiki-deprecated/experimental-features.md delete mode 100644 docs/src/wiki-deprecated/upgrading-from-scala-2-11.md (limited to 'docs/src') diff --git a/docs/src/appendix/chisel3-vs-chisel2.md b/docs/src/appendix/chisel3-vs-chisel2.md new file mode 100644 index 00000000..bfd20348 --- /dev/null +++ b/docs/src/appendix/chisel3-vs-chisel2.md @@ -0,0 +1,203 @@ +--- +layout: docs +title: "Chisel3 vs. Chisel2" +section: "chisel3" +--- + +# Chisel3 vs Chisel2 + +## Chisel2 Migration +For those moving from Chisel2, there were some backwards incompatible changes +and your RTL needs to be modified to work with Chisel3. The required +modifications are: + + - Wire declaration style: + ```scala + val wire = UInt(width = 15) + ``` + becomes (in Chisel3): + ```scala + val wire = Wire(UInt(15.W)) + ``` + + - I/O declaration style: + ```scala + val done = Bool(OUTPUT) + ``` + becomes (in Chisel3): + ```scala + val wire = Output(Bool()) + ``` + + - Sequential memories: + ```scala + val addr = Reg(UInt()) + val mem = Mem(UInt(8.W), 1024, seqRead = true) + val dout = when(enable) { mem(addr) } + ``` + becomes (in Chisel3): + ```scala + val addr = UInt() + val mem = SyncReadMem(1024, UInt(8.W)) + val dout = mem.read(addr, enable) + ``` + + Notice the address register is now internal to the SyncReadMem(), but the data + will still return on the subsequent cycle. + + - Generating Verilog with + ```scala + object Hello { + def main(args: Array[String]): Unit = { + chiselMain(Array("--backend", "v"), () => Module(new Hello())) + } + } + ``` + becomes (in Chisel3): + ```scala + object Hello { + def main(args: Array[String]): Unit = { + chisel3.Driver.execute(Array[String](), () => new Hello()) + } + } + ``` + + - Package changes: + - Chisel.log2Ceil -> chisel3.util.log2Ceil + - BitPat + - Decoupled is also in chisel3.util + +Please refer to the [Chisel3 compatibility section](https://github.com/ucb-bar/chisel#chisel3) +for instructions on preparing your Chisel2 designs for Chisel3. + +## Deprecated Usage +* `Vec(Reg)` should be replaced with `Reg(Vec)`, +* type-only vals (no associated data) must be wrapped in a `Wire()` if they will be the destination of a wiring operation (":=" or " < >"), +* masked bit patterns ('b??') should be created using BitPat(), not UInt() or Bits(), +* the `clone` method required for parameterized Bundles has been renamed `cloneType`, +* the con and alt inputs to a Mux must be type-compatible - both signed or both unsigned, +* bulk-connection to a node that has been procedurally assigned-to is illegal, +* `!=` is deprecated, use `=/=` instead, +* use `SyncReadMem(...)` instead of `Mem(..., seqRead)`, +* use `SyncReadMem(n:Int, out: => T)` instead of `SyncReadMem(out: => T, n:Int)`, +* use `SyncReadMem(...)` instead of `SeqMem(...)`, +* use `Mem(n:Int, t:T)` instead of `Mem(out:T, n:Int)`, +* use `Vec(n:Int, gen: => T)` instead of `Vec(gen: => T, n:Int)`, +* module io's must be wrapped in `IO()`. +* The methods `asInput`, `asOutput`, and `flip` should be replaced by the `Input()`, `Output()`, and `Flipped()` object apply methods. + +## Unsupported constructs +* `Mem(..., orderedWrites)` is no longer supported, +* masked writes are only supported for `Mem[Vec[_]]`, +* Chisel3 Vecs must all have the same type, unlike with Chisel2. Use `MixedVec` (see [Bundles and Vecs](../explanations/bundles-and-vecs)) for Vecs where the elements are of different types. +* connections between `UInt` and `SInt` are illegal. +* the `Node` class and object no longer exist (the class should have been private in Chisel2) +* `printf()` is defined in the Chisel object and produces simulation printf()'s. +To use the Scala `Predef.printf()`, you need to qualify it with `Predef`. +* in Chisel2, bulk-connects `<>` with unconnected source components do not update connections from the unconnected components. +** In Chisel3, bulk-connects strictly adhere to last connection semantics and unconnected OUTPUTs will be connected to INPUTs resulting in the assignment of random values to those inputs. +* In Chisel3, adding hardware inside `BlackBox` for simulation is no longer supported. (#289) +* `ChiselError` is gone + * Change `ChiselError.error("error msg")` to `throw new Error("error msg")` + * Change `ChiselError.info("info msg")` to `println("info msg")` +* In Chisel3, subword assignments are not supported. [Alternative constructions exist](https://github.com/freechipsproject/chisel3/wiki/Cookbook#how-do-i-do-subword-assignment-assign-to-some-bits-in-a-uint) in Chisel3. + +## Further changes +* The clock signal was renamed from `clk` to `clock` in Chisel3. +* Change `getWidth()` to `getWidth` + +## Packaging +Chisel3 is implemented as several packages. +The core DSL is differentiated from utility or library classes and objects, testers, and interpreters. +The prime components of the Chisel3 front end (the DSL and library objects) are: +* coreMacros - source locators provide Chisel line numbers for `firrtl` detected errors, +* chiselFrontend - main DSL components, +* chisel3 - compiler driver, interface packages, compatibility layer. + +Due to the wonders of `sbt`, you need only declare a dependency on the chisel3 package, and the others will be downloaded as required. + +The `firrtl` compiler is distributed as a separate package, and release versions will also be downloaded automatically as required. +If you choose to integrate the compiler into your own toolchain, or you're working with the development (master) branch of chisel3, you should clone the [firrtl](https://github.com/ucb-bar/firrtl) repo +and follow the instructions for installing the `firrtl` compiler. + +The testers in Chisel3 are distributed as a separate package. +If you intend to use them in your tests, you will either need to clone the [chisel-testers](https://github.com/ucb-bar/chisel-testers) repo +or declare a dependency on the published version of the package. +See the `build.sbt` file in either the [chisel-template](https://github.com/ucb-bar/chisel-template) or [chisel-tutorial](https://github.com/ucb-bar/chisel-tutorial) +repos for examples of the latter. + +## Simulation +Chisel2 was capable of directly generating a `C++` simulation from the Chisel code, or a harness for use with a `vcs` simulation. +Chisel3 relies on [verilator](http://www.veripool.org/wiki/verilator) to generate the `C++` simulation from the Verilog output of `firrtl`. +See the [Chisel3 README](https://github.com/ucb-bar/chisel3) for directions on installing `verilator`. + +## Compile Options and Front End Checks (Strict vs. NotStrict) +Chisel3 introduces a formal specification for hardware circuit graphs: FIRRTL, +and Chisel3 itself (the Scala library implementing the Chisel DSL), is a relatively thin front end that generates FIRRTL. +Since the `firrtl` parser needs to validate FIRRTL input, most of the checks that were performed in Chisel2 were eliminated +from the initial Chisel3 front end (the DRY principle). + +However, this does impact the ability to provide detailed messages for error conditions that could be detected in the Chisel3 +front end. The decision was made to optionally enable stricter error checking (for connections and the use of raw types versus +hardware objects), based on specific imports. +This allows designs to move from less strict front end checks (largely compatible with Chisel2), to stricter checking, +on a file by file basis, by adjusting specific import statements. + +```scala + import chisel3.core.ExplicitCompileOptions.Strict +``` + +enables stricter connection and usage checks, while + +```scala + import chisel3.core.ExplicitCompileOptions.NotStrict +``` + +defers these checks to the `firrtl` compiler. + +By default, the `Chisel` compatibility layer, invoked by: + +```scala + import Chisel._ +``` + +implicitly defines the compile options as `chisel3.core.ExplicitCompileOptions.NotStrict` + +whereas the Chisel3 package, invoked by: + +```scala + import chisel3._ +``` + +implicitly defines the compile options as `chisel3.core.ExplicitCompileOptions.Strict` + +Again, these implicit compile options definitions may be overridden by explicit imports. + +Currently, the specific error checks (found in [CompileOptions.scala](https://github.com/ucb-bar/chisel3/blob/master/chiselFrontend/src/main/scala/chisel3/core/CompileOptions.scala)) are: + +```scala + trait CompileOptions { + // Should Bundle connections require a strict match of fields. + // If true and the same fields aren't present in both source and sink, a MissingFieldException, + // MissingLeftFieldException, or MissingRightFieldException will be thrown. + val connectFieldsMustMatch: Boolean + // When creating an object that takes a type argument, the argument must be unbound (a pure type). + val declaredTypeMustBeUnbound: Boolean + // Module IOs should be wrapped in an IO() to define their bindings before the reset of the module is defined. + val requireIOWrap: Boolean + // If a connection operator fails, don't try the connection with the operands (source and sink) reversed. + val dontTryConnectionsSwapped: Boolean + // If connection directionality is not explicit, do not use heuristics to attempt to determine it. + val dontAssumeDirectionality: Boolean + // Issue a deprecation warning if Data.{flip, asInput,asOutput} is used + // instead of Flipped, Input, or Output. + val deprecateOldDirectionMethods: Boolean + // Check that referenced Data have actually been declared. + val checkSynthesizable: Boolean + } +``` + +`chisel3.core.ExplicitCompileOptions.Strict` sets all CompileOptions fields to true and +`chisel3.core.ExplicitCompileOptions.NotStrict` sets them all to false. +Clients are free to define their own settings for these options. +Examples may be found in the test [CompileOptionsSpec](https://github.com/ucb-bar/chisel3/blob/master/src/test/scala/chiselTests/CompileOptionsTest.scala) diff --git a/docs/src/appendix/experimental-features.md b/docs/src/appendix/experimental-features.md new file mode 100644 index 00000000..ba1a028d --- /dev/null +++ b/docs/src/appendix/experimental-features.md @@ -0,0 +1,138 @@ +--- +layout: docs +title: "Experimental Features" +section: "chisel3" +--- + +Chisel has a number of new features that are worth checking out. This page is an informal list of these features and projects. + +### FixedPoint +FixedPoint numbers are basic *Data* type along side of UInt, SInt, etc. Most common math and logic operations +are supported. Chisel allows both the width and binary point to be inferred by the Firrtl compiler which can simplify +circuit descriptions. See [FixedPointSpec](https://github.com/freechipsproject/chisel3/tree/master/src/test/scala/chiselTests/FixedPointSpec.scala) + +### Module Variants +The standard Chisel *Module* requires a `val io = IO(...)`, the experimental package introduces several +new ways of defining Modules +- BaseModule: no contents, instantiable +- BlackBox extends BaseModule +- UserDefinedModule extends BaseModule: this module can contain Chisel RTL. No default clock or reset lines. No default IO. - User should be able to specify non-io ports, ideally multiple of them. +- ImplicitModule extends UserModule: has clock, reset, and io, essentially current Chisel Module. +- RawModule: will be the user-facing version of UserDefinedModule +- Module: type-aliases to ImplicitModule, the user-facing version of ImplicitModule. + +### Bundle Literals + +Bundle literals can be constructed via an experimental import: + +```scala mdoc +import chisel3._ +import chisel3.experimental.BundleLiterals._ + +class MyBundle extends Bundle { + val a = UInt(8.W) + val b = Bool() +} + +class Example extends RawModule { + val out = IO(Output(new MyBundle)) + out := (new MyBundle).Lit(_.a -> 8.U, _.b -> true.B) +} +``` + +```scala mdoc:verilog +chisel3.stage.ChiselStage.emitVerilog(new Example) +``` + +Partial specification is allowed, defaulting any unconnected fields to 0 (regardless of type). + +```scala mdoc +class Example2 extends RawModule { + val out = IO(Output(new MyBundle)) + out := (new MyBundle).Lit(_.b -> true.B) +} +``` + +```scala mdoc:verilog +chisel3.stage.ChiselStage.emitVerilog(new Example2) +``` + +Bundle literals can also be nested arbitrarily. + +```scala mdoc +class ChildBundle extends Bundle { + val foo = UInt(8.W) +} + +class ParentBundle extends Bundle { + val a = UInt(8.W) + val b = new ChildBundle +} + +class Example3 extends RawModule { + val out = IO(Output(new ParentBundle)) + out := (new ParentBundle).Lit(_.a -> 123.U, _.b -> (new ChildBundle).Lit(_.foo -> 42.U)) +} +``` + +```scala mdoc:verilog +chisel3.stage.ChiselStage.emitVerilog(new Example3) +``` + +Vec literals are not yet supported. + +### Interval Type + +**Intervals** are a new experimental numeric type that comprises UInt, SInt and FixedPoint numbers. +It augments these types with range information, i.e. upper and lower numeric bounds. +This information can be used to exercise tighter programmatic control over the ultimate widths of +signals in the final circuit. The **Firrtl** compiler can infer this range information based on +operations and earlier values in the circuit. Intervals support all the ordinary bit and arithmetic operations +associated with UInt, SInt, and FixedPoint and adds the following methods for manipulating the range of +a **source** Interval with the IntervalRange of **target** Interval + +#### Clip -- Fit the value **source** into the IntervalRange of **target**, saturate if out of bounds +The clip method applied to an interval creates a new interval based on the argument to clip, +and constructs the necessary hardware so that the source Interval's value will be mapped into the new Interval. +Values that are outside the result range will be pegged to either maximum or minimum of result range as appropriate. + +> Generates necessary hardware to clip values, values greater than range are set to range.high, values lower than range are set to range min. + +#### Wrap -- Fit the value **source** into the IntervalRange of **target**, wrapping around if out of bounds +The wrap method applied to an interval creates a new interval based on the argument to wrap, +and constructs the necessary +hardware so that the source Interval's value will be mapped into the new Interval. +Values that are outside the result range will be wrapped until they fall within the result range. + +> Generates necessary hardware to wrap values, values greater than range are set to range.high, values lower than range are set to range min. + +> Does not handle out of range values that are less than half the minimum or greater than twice maximum + +#### Squeeze -- Fit the value **source** into the smallest IntervalRange based on source and target. +The squeeze method applied to an interval creates a new interval based on the argument to clip, the two ranges must overlap +behavior of squeeze with inputs outside of the produced range is undefined. + +> Generates no hardware, strictly a sizing operation + +##### Range combinations + +| Condition | A.clip(B) | A.wrap(B) | A.squeeze(B) | +| --------- | --------------- | --------------- | --------------- | +| A === B | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | +| A contains B | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | +| B contains A | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | +| A min < B min, A max in B | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | +| A min in B, A max > B max | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | +| A strictly less than B | error | error | error | +| A strictly greater than B | error | error | error | + + +#### Applying binary point operators to an Interval + +Consider a Interval with a binary point of 3: aaa.bbb + +| operation | after operation | binary point | lower | upper | meaning | +| --------- | --------------- | ------------ | ----- | ----- | ------- | +| setBinaryPoint(2) | aaa.bb | 2 | X | X | set the precision | +| shiftLeftBinaryPoint(2) | a.aabbb | 5 | X | X | increase the precision | +| shiftRighBinaryPoint(2) | aaaa.b | 1 | X | X | reduce the precision | diff --git a/docs/src/appendix/upgrading-from-scala-2-11.md b/docs/src/appendix/upgrading-from-scala-2-11.md new file mode 100644 index 00000000..26e2d252 --- /dev/null +++ b/docs/src/appendix/upgrading-from-scala-2-11.md @@ -0,0 +1,88 @@ +--- +layout: docs +title: "Upgrading From Scala 2.11" +section: "chisel3" +redirect_from: + - /chisel3/upgrading-from-scala-2-11.html +--- + + +```scala mdoc:invisible +import chisel3._ +``` + + +## Upgrading From Scala 2.11 to 2.12 + +As the latest (and probably last) release of Scala 2.11 (2.11.12) was released on 2 November 2017, the time has come to deprecate support for Scala 2.11. +Chisel 3.4 is the last version of Chisel that will support Scala 2.11, so users should upgrade to Scala 2.12 +This document is intended to help guide Chisel users through this process; both the "Why?" and the "How?". + +### Scala Versioning + + + +Scala versions have the following structure: `2.X.Y` where `X` is the _major version_ and `Y` is the _minor version_. +Note that while we keep the leading `2` constant, there is a project, [Dotty](https://dotty.epfl.ch/), that is slated to become Scala 3. + +Scala maintains both source and binary compatiblity between minor versions, but not between major versions. +Binary compatibility is defined at the level of the Java Byte Code (the `.class` or `.jar` files compiled from `.scala`). +This means that Scala projects that support multiple major versions of Scala must be compiled and published for each supported version. +When publishing artifacts to Maven repositories, this manifests as an appendix on the _Artifact ID_. +Taking Chisel v3.3.2 as an example, the "Artifact ID" is ["chisel3_2.12"](https://search.maven.org/artifact/edu.berkeley.cs/chisel3_2.12) +for Scala 2.12, and ["chisel3_2.11"](https://search.maven.org/artifact/edu.berkeley.cs/chisel3_2.11) for Scala 2.11. + +For more information, see the documentation on the Scala website: +* [Binary Compatibility of Scala Releases](https://docs.scala-lang.org/overviews/core/binary-compatibility-of-scala-releases.html) +* [Binary Compatibility for Library Authoers](https://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html) + + +### How to Upgrade + +For most users, this is as simple as changing the `scalaVersion` field in your `build.sbt`: +```scala +scalaVersion := "2.11.12" +``` +Becomes +```scala +scalaVersion := "2.12.12" +``` +Now, the next time you run SBT, it will be using the Scala 2.12 version of Chisel 3 (as well as any other dependencies you have). + +### Common Issues + +As mentioned in the [previous section](#scala-versioning), Scala does *not* maintain source compatibilty between major versions. +Put another way, sometimes they break things in backwards incompatible ways. +This section includes some common issues that Chisel users run into and how to fix them. + +For complete information about changes, please see the [release notes for Scala 2.12.0](https://www.scala-lang.org/news/2.12.0/). + +#### Value is not a member of chisel3.Bundle + +The most common problem for Chisel users upgrading from Scala 2.11 to 2.12 is a change in Scala type inference. +This usually occurs in the context of `io` `Bundles` in `Modules`, given: +```scala mdoc:silent +class Foo extends Module { + val io = IO(new Bundle { + val in = Input(Bool()) + val out = Output(Bool()) + }) + + io.out := ~io.in +} +``` +You may see an error that says somethign like "value out is not a member of chisel3.Bundle": +``` +[error] /workspace/src/main/scala/gcd/Foo.scala:9:6: value out is not a member of chisel3.Bundle +[error] io.out := ~io.in +[error] ^ +[error] /workspace/src/main/scala/gcd/Foo.scala:9:17: value in is not a member of chisel3.Bundle +[error] io.out := ~io.in +[error] ^ +[error] two errors found +``` +This can be worked around by adding `-Xsource:2.11` to your `scalacOptions`. +This is most commonly set in your `build.sbt`. +For an example, see the [chisel-template's build.sbt](https://github.com/freechipsproject/chisel-template/blob/11f6ca470120908d167cb8dc3241953eb31d0acb/build.sbt#L10). + + diff --git a/docs/src/explanations/blackboxes.md b/docs/src/explanations/blackboxes.md index a8d5fe03..4ecd1ea0 100644 --- a/docs/src/explanations/blackboxes.md +++ b/docs/src/explanations/blackboxes.md @@ -9,7 +9,7 @@ for hardware constructs that cannot be described in Chisel and for connecting to Modules defined as a `BlackBox` will be instantiated in the generated Verilog, but no code will be generated to define the behavior of module. -Unlike Module, `BlackBox` has no implicit clock and reset. +Unlike Module, `BlackBox` has no implicit clock and reset. `BlackBox`'s clock and reset ports must be explicitly declared and connected to input signals. Ports declared in the IO Bundle will be generated with the requested name (ie. no preceding `io_`). @@ -34,7 +34,7 @@ class IBUFDS extends BlackBox(Map("DIFF_TERM" -> "TRUE", } class Top extends Module { - val io = IO(new Bundle{}) + val io = IO(new Bundle {}) val ibufds = Module(new IBUFDS) // connecting one of IBUFDS's input clock ports to Top's clock signal ibufds.io.I := clock @@ -52,12 +52,14 @@ IBUFDS #(.DIFF_TERM("TRUE"), .IOSTANDARD("DEFAULT")) ibufds ( ``` ### Providing Implementations for Blackboxes + Chisel provides the following ways of delivering the code underlying the blackbox. Consider the following blackbox that adds two real numbers together. The numbers are represented in chisel3 as 64-bit unsigned integers. + ```scala mdoc:silent:reset import chisel3._ class BlackBoxRealAdd extends BlackBox { - val io = IO(new Bundle() { + val io = IO(new Bundle { val in1 = Input(UInt(64.W)) val in2 = Input(UInt(64.W)) val out = Output(UInt(64.W)) @@ -66,6 +68,7 @@ class BlackBoxRealAdd extends BlackBox { ``` The implementation is described by the following verilog + ```verilog module BlackBoxRealAdd( input [63:0] in1, @@ -73,39 +76,43 @@ module BlackBoxRealAdd( output reg [63:0] out ); always @* begin - out <= $realtobits($bitstoreal(in1) + $bitstoreal(in2)); + out <= $realtobits($bitstoreal(in1) + $bitstoreal(in2)); end endmodule ``` ### Blackboxes with Verilog in a Resource File -In order to deliver the verilog snippet above to the backend simulator, chisel3 provides the following tools based on the chisel/firrtl [annotation system](../explanations/annotations). Add the trait ```HasBlackBoxResource``` to the declaration, and then call a function in the body to say where the system can find the verilog. The Module now looks like -```mdoc scala:silent:reset + +In order to deliver the verilog snippet above to the backend simulator, chisel3 provides the following tools based on the chisel/firrtl [annotation system](../explanations/annotations). Add the trait `HasBlackBoxResource` to the declaration, and then call a function in the body to say where the system can find the verilog. The Module now looks like + +```scala mdoc:silent:reset +import chisel3._ +import chisel3.util.HasBlackBoxResource + class BlackBoxRealAdd extends BlackBox with HasBlackBoxResource { - val io = IO(new Bundle() { + val io = IO(new Bundle { val in1 = Input(UInt(64.W)) val in2 = Input(UInt(64.W)) val out = Output(UInt(64.W)) }) - setResource("/real_math.v") + addResource("/real_math.v") } ``` -The verilog snippet above gets put into a resource file names ```real_math.v```. What is a resource file? It comes from + +The verilog snippet above gets put into a resource file names `real_math.v`. What is a resource file? It comes from a java convention of keeping files in a project that are automatically included in library distributions. In a typical chisel3 project, see [chisel-template](https://github.com/ucb-bar/chisel-template), this would be a directory in the - source hierarchy -``` -src/main/resources/real_math.v -``` + source hierarchy: `src/main/resources/real_math.v`. ### Blackboxes with In-line Verilog -It is also possible to place this verilog directly in the scala source. Instead of ```HasBlackBoxResource``` use - ```HasBlackBoxInline``` and instead of ```setResource``` use ```setInline```. The code will look like this. +It is also possible to place this verilog directly in the scala source. Instead of `HasBlackBoxResource` use + `HasBlackBoxInline` and instead of `setResource` use `setInline`. The code will look like this. + ```scala mdoc:silent:reset import chisel3._ import chisel3.util.HasBlackBoxInline class BlackBoxRealAdd extends BlackBox with HasBlackBoxInline { - val io = IO(new Bundle() { + val io = IO(new Bundle { val in1 = Input(UInt(64.W)) val in2 = Input(UInt(64.W)) val out = Output(UInt(64.W)) @@ -123,15 +130,16 @@ class BlackBoxRealAdd extends BlackBox with HasBlackBoxInline { """.stripMargin) } ``` -This technique will copy the inline verilog into the target directory under the name ```BlackBoxRealAdd.v``` + +This technique will copy the inline verilog into the target directory under the name `BlackBoxRealAdd.v` ### Under the Hood This mechanism of delivering verilog content to the testing backends is implemented via chisel/firrtl annotations. The -two methods, inline and resource, are two kinds of annotations that are created via the ```setInline``` and -```setResource``` methods calls. Those annotations are passed through to the chisel-testers which in turn passes them +two methods, inline and resource, are two kinds of annotations that are created via the `setInline` and +`setResource` methods calls. Those annotations are passed through to the chisel-testers which in turn passes them on to firrtl. The default firrtl verilog compilers have a pass that detects the annotations and moves the files or inline test into the build directory. For each unique file added, the transform adds a line to a file -black_box_verilog_files.f, this file is added to the command line constructed for verilator or vcs to inform them where +`black_box_verilog_files.f`, this file is added to the command line constructed for verilator or vcs to inform them where to look. The [dsptools project](https://github.com/ucb-bar/dsptools) is a good example of using this feature to build a real number simulation tester based on black boxes. @@ -144,4 +152,4 @@ construct scala implementations of the black boxes. The scala implementation co passed down to the interpreter by the execution harness. The interpreter is a scala simulation tester. Once again the dsptools project uses this mechanism and is a good place to look at it. > It is planned that the BlackBoxFactory will be replaced by integration with the annotation based blackbox methods ->stuff soon. +> stuff soon. diff --git a/docs/src/explanations/bundles-and-vecs.md b/docs/src/explanations/bundles-and-vecs.md index dcac31cd..bac9393a 100644 --- a/docs/src/explanations/bundles-and-vecs.md +++ b/docs/src/explanations/bundles-and-vecs.md @@ -3,14 +3,12 @@ layout: docs title: "Bundles and Vecs" section: "chisel3" --- -``` - -``` `Bundle` and `Vec` are classes that allow the user to expand the set of Chisel datatypes with aggregates of other types. Bundles group together several named fields of potentially different types into a coherent unit, much like a `struct` in C. Users define their own bundles by defining a class as a subclass of `Bundle`. + ```scala mdoc:silent import chisel3._ class MyFloat extends Bundle { @@ -25,24 +23,12 @@ class ModuleWithFloatWire extends RawModule { } ``` -> Currently, there is no way to create a bundle literal like ```8.U``` for ```UInt```s. Therefore, in order to create ->literals for bundles, we must declare a [[wire|Combinational-Circuits#wires]] of that bundle type, and then assign ->values to it. We are working on a way to declare bundle literals without requiring the creation of a Wire node and ->assigning to it. +You can create literal Bundles using the experimental [Bundle Literals](../appendix/experimental-features#bundle-literals) feature. -```scala mdoc:silent -class ModuleWithFloatConstant extends RawModule { - // Floating point constant. - val floatConst = Wire(new MyFloat) - floatConst.sign := true.B - floatConst.exponent := 10.U - floatConst.significand := 128.U -} -``` - -A Scala convention is to capitalize the name of new classes and we suggest you follow that convention in Chisel too. +Scala convention is to name classes using UpperCamelCase, and we suggest you follow that convention in your Chisel code. Vecs create an indexable vector of elements, and are constructed as follows: + ```scala mdoc:silent class ModuleWithVec extends RawModule { // Vector of 5 23-bit signed integers. @@ -63,6 +49,7 @@ superclass, `Data`. Every object that ultimately inherits from Bundles and Vecs can be arbitrarily nested to build complex data structures: + ```scala mdoc:silent class BigBundle extends Bundle { // Vector of 5 23-bit signed integers. @@ -152,6 +139,7 @@ Note that in the vast majority of cases, **this is not required** as Chisel can automatically. Here is an example of a parametrized bundle (`ExampleBundle`) that features a custom `cloneType`. + ```scala mdoc:silent class ExampleBundle(a: Int, b: Int) extends Bundle { val foo = UInt(a.W) diff --git a/docs/src/wiki-deprecated/chisel3-vs-chisel2.md b/docs/src/wiki-deprecated/chisel3-vs-chisel2.md deleted file mode 100644 index bfd20348..00000000 --- a/docs/src/wiki-deprecated/chisel3-vs-chisel2.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -layout: docs -title: "Chisel3 vs. Chisel2" -section: "chisel3" ---- - -# Chisel3 vs Chisel2 - -## Chisel2 Migration -For those moving from Chisel2, there were some backwards incompatible changes -and your RTL needs to be modified to work with Chisel3. The required -modifications are: - - - Wire declaration style: - ```scala - val wire = UInt(width = 15) - ``` - becomes (in Chisel3): - ```scala - val wire = Wire(UInt(15.W)) - ``` - - - I/O declaration style: - ```scala - val done = Bool(OUTPUT) - ``` - becomes (in Chisel3): - ```scala - val wire = Output(Bool()) - ``` - - - Sequential memories: - ```scala - val addr = Reg(UInt()) - val mem = Mem(UInt(8.W), 1024, seqRead = true) - val dout = when(enable) { mem(addr) } - ``` - becomes (in Chisel3): - ```scala - val addr = UInt() - val mem = SyncReadMem(1024, UInt(8.W)) - val dout = mem.read(addr, enable) - ``` - - Notice the address register is now internal to the SyncReadMem(), but the data - will still return on the subsequent cycle. - - - Generating Verilog with - ```scala - object Hello { - def main(args: Array[String]): Unit = { - chiselMain(Array("--backend", "v"), () => Module(new Hello())) - } - } - ``` - becomes (in Chisel3): - ```scala - object Hello { - def main(args: Array[String]): Unit = { - chisel3.Driver.execute(Array[String](), () => new Hello()) - } - } - ``` - - - Package changes: - - Chisel.log2Ceil -> chisel3.util.log2Ceil - - BitPat - - Decoupled is also in chisel3.util - -Please refer to the [Chisel3 compatibility section](https://github.com/ucb-bar/chisel#chisel3) -for instructions on preparing your Chisel2 designs for Chisel3. - -## Deprecated Usage -* `Vec(Reg)` should be replaced with `Reg(Vec)`, -* type-only vals (no associated data) must be wrapped in a `Wire()` if they will be the destination of a wiring operation (":=" or " < >"), -* masked bit patterns ('b??') should be created using BitPat(), not UInt() or Bits(), -* the `clone` method required for parameterized Bundles has been renamed `cloneType`, -* the con and alt inputs to a Mux must be type-compatible - both signed or both unsigned, -* bulk-connection to a node that has been procedurally assigned-to is illegal, -* `!=` is deprecated, use `=/=` instead, -* use `SyncReadMem(...)` instead of `Mem(..., seqRead)`, -* use `SyncReadMem(n:Int, out: => T)` instead of `SyncReadMem(out: => T, n:Int)`, -* use `SyncReadMem(...)` instead of `SeqMem(...)`, -* use `Mem(n:Int, t:T)` instead of `Mem(out:T, n:Int)`, -* use `Vec(n:Int, gen: => T)` instead of `Vec(gen: => T, n:Int)`, -* module io's must be wrapped in `IO()`. -* The methods `asInput`, `asOutput`, and `flip` should be replaced by the `Input()`, `Output()`, and `Flipped()` object apply methods. - -## Unsupported constructs -* `Mem(..., orderedWrites)` is no longer supported, -* masked writes are only supported for `Mem[Vec[_]]`, -* Chisel3 Vecs must all have the same type, unlike with Chisel2. Use `MixedVec` (see [Bundles and Vecs](../explanations/bundles-and-vecs)) for Vecs where the elements are of different types. -* connections between `UInt` and `SInt` are illegal. -* the `Node` class and object no longer exist (the class should have been private in Chisel2) -* `printf()` is defined in the Chisel object and produces simulation printf()'s. -To use the Scala `Predef.printf()`, you need to qualify it with `Predef`. -* in Chisel2, bulk-connects `<>` with unconnected source components do not update connections from the unconnected components. -** In Chisel3, bulk-connects strictly adhere to last connection semantics and unconnected OUTPUTs will be connected to INPUTs resulting in the assignment of random values to those inputs. -* In Chisel3, adding hardware inside `BlackBox` for simulation is no longer supported. (#289) -* `ChiselError` is gone - * Change `ChiselError.error("error msg")` to `throw new Error("error msg")` - * Change `ChiselError.info("info msg")` to `println("info msg")` -* In Chisel3, subword assignments are not supported. [Alternative constructions exist](https://github.com/freechipsproject/chisel3/wiki/Cookbook#how-do-i-do-subword-assignment-assign-to-some-bits-in-a-uint) in Chisel3. - -## Further changes -* The clock signal was renamed from `clk` to `clock` in Chisel3. -* Change `getWidth()` to `getWidth` - -## Packaging -Chisel3 is implemented as several packages. -The core DSL is differentiated from utility or library classes and objects, testers, and interpreters. -The prime components of the Chisel3 front end (the DSL and library objects) are: -* coreMacros - source locators provide Chisel line numbers for `firrtl` detected errors, -* chiselFrontend - main DSL components, -* chisel3 - compiler driver, interface packages, compatibility layer. - -Due to the wonders of `sbt`, you need only declare a dependency on the chisel3 package, and the others will be downloaded as required. - -The `firrtl` compiler is distributed as a separate package, and release versions will also be downloaded automatically as required. -If you choose to integrate the compiler into your own toolchain, or you're working with the development (master) branch of chisel3, you should clone the [firrtl](https://github.com/ucb-bar/firrtl) repo -and follow the instructions for installing the `firrtl` compiler. - -The testers in Chisel3 are distributed as a separate package. -If you intend to use them in your tests, you will either need to clone the [chisel-testers](https://github.com/ucb-bar/chisel-testers) repo -or declare a dependency on the published version of the package. -See the `build.sbt` file in either the [chisel-template](https://github.com/ucb-bar/chisel-template) or [chisel-tutorial](https://github.com/ucb-bar/chisel-tutorial) -repos for examples of the latter. - -## Simulation -Chisel2 was capable of directly generating a `C++` simulation from the Chisel code, or a harness for use with a `vcs` simulation. -Chisel3 relies on [verilator](http://www.veripool.org/wiki/verilator) to generate the `C++` simulation from the Verilog output of `firrtl`. -See the [Chisel3 README](https://github.com/ucb-bar/chisel3) for directions on installing `verilator`. - -## Compile Options and Front End Checks (Strict vs. NotStrict) -Chisel3 introduces a formal specification for hardware circuit graphs: FIRRTL, -and Chisel3 itself (the Scala library implementing the Chisel DSL), is a relatively thin front end that generates FIRRTL. -Since the `firrtl` parser needs to validate FIRRTL input, most of the checks that were performed in Chisel2 were eliminated -from the initial Chisel3 front end (the DRY principle). - -However, this does impact the ability to provide detailed messages for error conditions that could be detected in the Chisel3 -front end. The decision was made to optionally enable stricter error checking (for connections and the use of raw types versus -hardware objects), based on specific imports. -This allows designs to move from less strict front end checks (largely compatible with Chisel2), to stricter checking, -on a file by file basis, by adjusting specific import statements. - -```scala - import chisel3.core.ExplicitCompileOptions.Strict -``` - -enables stricter connection and usage checks, while - -```scala - import chisel3.core.ExplicitCompileOptions.NotStrict -``` - -defers these checks to the `firrtl` compiler. - -By default, the `Chisel` compatibility layer, invoked by: - -```scala - import Chisel._ -``` - -implicitly defines the compile options as `chisel3.core.ExplicitCompileOptions.NotStrict` - -whereas the Chisel3 package, invoked by: - -```scala - import chisel3._ -``` - -implicitly defines the compile options as `chisel3.core.ExplicitCompileOptions.Strict` - -Again, these implicit compile options definitions may be overridden by explicit imports. - -Currently, the specific error checks (found in [CompileOptions.scala](https://github.com/ucb-bar/chisel3/blob/master/chiselFrontend/src/main/scala/chisel3/core/CompileOptions.scala)) are: - -```scala - trait CompileOptions { - // Should Bundle connections require a strict match of fields. - // If true and the same fields aren't present in both source and sink, a MissingFieldException, - // MissingLeftFieldException, or MissingRightFieldException will be thrown. - val connectFieldsMustMatch: Boolean - // When creating an object that takes a type argument, the argument must be unbound (a pure type). - val declaredTypeMustBeUnbound: Boolean - // Module IOs should be wrapped in an IO() to define their bindings before the reset of the module is defined. - val requireIOWrap: Boolean - // If a connection operator fails, don't try the connection with the operands (source and sink) reversed. - val dontTryConnectionsSwapped: Boolean - // If connection directionality is not explicit, do not use heuristics to attempt to determine it. - val dontAssumeDirectionality: Boolean - // Issue a deprecation warning if Data.{flip, asInput,asOutput} is used - // instead of Flipped, Input, or Output. - val deprecateOldDirectionMethods: Boolean - // Check that referenced Data have actually been declared. - val checkSynthesizable: Boolean - } -``` - -`chisel3.core.ExplicitCompileOptions.Strict` sets all CompileOptions fields to true and -`chisel3.core.ExplicitCompileOptions.NotStrict` sets them all to false. -Clients are free to define their own settings for these options. -Examples may be found in the test [CompileOptionsSpec](https://github.com/ucb-bar/chisel3/blob/master/src/test/scala/chiselTests/CompileOptionsTest.scala) diff --git a/docs/src/wiki-deprecated/experimental-features.md b/docs/src/wiki-deprecated/experimental-features.md deleted file mode 100644 index d36b2946..00000000 --- a/docs/src/wiki-deprecated/experimental-features.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -layout: docs -title: "Experimental Features" -section: "chisel3" ---- - -Chisel has a number of new features that are worth checking out. This page is an informal list of these features and projects. - -### FixedPoint -FixedPoint numbers are basic *Data* type along side of UInt, SInt, etc. Most common math and logic operations -are supported. Chisel allows both the width and binary point to be inferred by the Firrtl compiler which can simplify -circuit descriptions. See [FixedPointSpec](https://github.com/freechipsproject/chisel3/tree/master/src/test/scala/chiselTests/FixedPointSpec.scala) - -### Module Variants -The standard Chisel *Module* requires a ```val io = IO(...)```, the experimental package introduces several -new ways of defining Modules -- BaseModule: no contents, instantiable -- BlackBox extends BaseModule -- UserDefinedModule extends BaseModule: this module can contain Chisel RTL. No default clock or reset lines. No default IO. - User should be able to specify non-io ports, ideally multiple of them. -- ImplicitModule extends UserModule: has clock, reset, and io, essentially current Chisel Module. -- RawModule: will be the user-facing version of UserDefinedModule -- Module: type-aliases to ImplicitModule, the user-facing version of ImplicitModule. - -### Bundle Literals - -Chisel 3.2 introduces an experimental mechanism for Bundle literals in #820, but this feature is largely incomplete and not ready for user code yet. The following is provided as documentation for library writers who want to take a stab at using this mechanism for their library's bundles. - -```mdoc scala -class MyBundle extends Bundle { - val a = UInt(8.W) - val b = Bool() - - // Bundle literal constructor code, which will be auto-generated using macro annotations in - // the future. - import chisel3.core.BundleLitBinding - import chisel3.internal.firrtl.{ULit, Width} - - // Full bundle literal constructor - def Lit(aVal: UInt, bVal: Bool): MyBundle = { - val clone = cloneType - clone.selfBind(BundleLitBinding(Map( - clone.a -> litArgOfBits(aVal), - clone.b -> litArgOfBits(bVal) - ))) - clone - } - - // Partial bundle literal constructor - def Lit(aVal: UInt): MyBundle = { - val clone = cloneType - clone.selfBind(BundleLitBinding(Map( - clone.a -> litArgOfBits(aVal) - ))) - clone - } -} -``` - -Example usage: - -```scala -val outsideBundleLit = (new MyBundle).Lit(42.U, true.B) -``` - -### Interval Type - -**Intervals** are a new experimental numeric type that comprises UInt, SInt and FixedPoint numbers. -It augments these types with range information, i.e. upper and lower numeric bounds. -This information can be used to exercise tighter programmatic control over the ultimate widths of -signals in the final circuit. The **Firrtl** compiler can infer this range information based on -operations and earlier values in the circuit. Intervals support all the ordinary bit and arithmetic operations -associated with UInt, SInt, and FixedPoint and adds the following methods for manipulating the range of -a **source** Interval with the IntervalRange of **target** Interval - -#### Clip -- Fit the value **source** into the IntervalRange of **target**, saturate if out of bounds -The clip method applied to an interval creates a new interval based on the argument to clip, -and constructs the necessary hardware so that the source Interval's value will be mapped into the new Interval. -Values that are outside the result range will be pegged to either maximum or minimum of result range as appropriate. - -> Generates necessary hardware to clip values, values greater than range are set to range.high, values lower than range are set to range min. - -#### Wrap -- Fit the value **source** into the IntervalRange of **target**, wrapping around if out of bounds -The wrap method applied to an interval creates a new interval based on the argument to wrap, -and constructs the necessary -hardware so that the source Interval's value will be mapped into the new Interval. -Values that are outside the result range will be wrapped until they fall within the result range. - -> Generates necessary hardware to wrap values, values greater than range are set to range.high, values lower than range are set to range min. - -> Does not handle out of range values that are less than half the minimum or greater than twice maximum - -#### Squeeze -- Fit the value **source** into the smallest IntervalRange based on source and target. -The squeeze method applied to an interval creates a new interval based on the argument to clip, the two ranges must overlap -behavior of squeeze with inputs outside of the produced range is undefined. - -> Generates no hardware, strictly a sizing operation - -##### Range combinations - -| Condition | A.clip(B) | A.wrap(B) | A.squeeze(B) | -| --------- | --------------- | --------------- | --------------- | -| A === B | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | -| A contains B | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | -| B contains A | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | -| A min < B min, A max in B | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | -| A min in B, A max > B max | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | max(Alo, Blo), min(Ahi, Bhi) | -| A strictly less than B | error | error | error | -| A strictly greater than B | error | error | error | - - -#### Applying binary point operators to an Interval - -Consider a Interval with a binary point of 3: aaa.bbb - -| operation | after operation | binary point | lower | upper | meaning | -| --------- | --------------- | ------------ | ----- | ----- | ------- | -| setBinaryPoint(2) | aaa.bb | 2 | X | X | set the precision | -| shiftLeftBinaryPoint(2) | a.aabbb | 5 | X | X | increase the precision | -| shiftRighBinaryPoint(2) | aaaa.b | 1 | X | X | reduce the precision | diff --git a/docs/src/wiki-deprecated/upgrading-from-scala-2-11.md b/docs/src/wiki-deprecated/upgrading-from-scala-2-11.md deleted file mode 100644 index 26e2d252..00000000 --- a/docs/src/wiki-deprecated/upgrading-from-scala-2-11.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -layout: docs -title: "Upgrading From Scala 2.11" -section: "chisel3" -redirect_from: - - /chisel3/upgrading-from-scala-2-11.html ---- - - -```scala mdoc:invisible -import chisel3._ -``` - - -## Upgrading From Scala 2.11 to 2.12 - -As the latest (and probably last) release of Scala 2.11 (2.11.12) was released on 2 November 2017, the time has come to deprecate support for Scala 2.11. -Chisel 3.4 is the last version of Chisel that will support Scala 2.11, so users should upgrade to Scala 2.12 -This document is intended to help guide Chisel users through this process; both the "Why?" and the "How?". - -### Scala Versioning - - - -Scala versions have the following structure: `2.X.Y` where `X` is the _major version_ and `Y` is the _minor version_. -Note that while we keep the leading `2` constant, there is a project, [Dotty](https://dotty.epfl.ch/), that is slated to become Scala 3. - -Scala maintains both source and binary compatiblity between minor versions, but not between major versions. -Binary compatibility is defined at the level of the Java Byte Code (the `.class` or `.jar` files compiled from `.scala`). -This means that Scala projects that support multiple major versions of Scala must be compiled and published for each supported version. -When publishing artifacts to Maven repositories, this manifests as an appendix on the _Artifact ID_. -Taking Chisel v3.3.2 as an example, the "Artifact ID" is ["chisel3_2.12"](https://search.maven.org/artifact/edu.berkeley.cs/chisel3_2.12) -for Scala 2.12, and ["chisel3_2.11"](https://search.maven.org/artifact/edu.berkeley.cs/chisel3_2.11) for Scala 2.11. - -For more information, see the documentation on the Scala website: -* [Binary Compatibility of Scala Releases](https://docs.scala-lang.org/overviews/core/binary-compatibility-of-scala-releases.html) -* [Binary Compatibility for Library Authoers](https://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html) - - -### How to Upgrade - -For most users, this is as simple as changing the `scalaVersion` field in your `build.sbt`: -```scala -scalaVersion := "2.11.12" -``` -Becomes -```scala -scalaVersion := "2.12.12" -``` -Now, the next time you run SBT, it will be using the Scala 2.12 version of Chisel 3 (as well as any other dependencies you have). - -### Common Issues - -As mentioned in the [previous section](#scala-versioning), Scala does *not* maintain source compatibilty between major versions. -Put another way, sometimes they break things in backwards incompatible ways. -This section includes some common issues that Chisel users run into and how to fix them. - -For complete information about changes, please see the [release notes for Scala 2.12.0](https://www.scala-lang.org/news/2.12.0/). - -#### Value is not a member of chisel3.Bundle - -The most common problem for Chisel users upgrading from Scala 2.11 to 2.12 is a change in Scala type inference. -This usually occurs in the context of `io` `Bundles` in `Modules`, given: -```scala mdoc:silent -class Foo extends Module { - val io = IO(new Bundle { - val in = Input(Bool()) - val out = Output(Bool()) - }) - - io.out := ~io.in -} -``` -You may see an error that says somethign like "value out is not a member of chisel3.Bundle": -``` -[error] /workspace/src/main/scala/gcd/Foo.scala:9:6: value out is not a member of chisel3.Bundle -[error] io.out := ~io.in -[error] ^ -[error] /workspace/src/main/scala/gcd/Foo.scala:9:17: value in is not a member of chisel3.Bundle -[error] io.out := ~io.in -[error] ^ -[error] two errors found -``` -This can be worked around by adding `-Xsource:2.11` to your `scalacOptions`. -This is most commonly set in your `build.sbt`. -For an example, see the [chisel-template's build.sbt](https://github.com/freechipsproject/chisel-template/blob/11f6ca470120908d167cb8dc3241953eb31d0acb/build.sbt#L10). - - -- cgit v1.2.3