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/wiki-deprecated/chisel3-vs-chisel2.md | 203 --------------------- docs/src/wiki-deprecated/experimental-features.md | 119 ------------ .../wiki-deprecated/upgrading-from-scala-2-11.md | 88 --------- 3 files changed, 410 deletions(-) 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/wiki-deprecated') 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