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 +++++++++++ 3 files changed, 429 insertions(+) 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 (limited to 'docs/src/appendix') 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). + + -- cgit v1.2.3