From 9aba55e7452981058d069b3096544d45e730dba9 Mon Sep 17 00:00:00 2001 From: Richard Lin Date: Tue, 6 Dec 2016 17:16:40 -0800 Subject: utils scaladoc examples for BitPat through CircuitMath (#398) Add examples for utils, move examples from individual apply methods to class overview scaladoc--- src/main/scala/chisel3/util/BitPat.scala | 19 ++++++++--- src/main/scala/chisel3/util/Bitwise.scala | 46 +++++++++++++++++++++++---- src/main/scala/chisel3/util/Cat.scala | 13 +++++++- src/main/scala/chisel3/util/CircuitMath.scala | 17 ++++++---- 4 files changed, 77 insertions(+), 18 deletions(-) (limited to 'src/main') diff --git a/src/main/scala/chisel3/util/BitPat.scala b/src/main/scala/chisel3/util/BitPat.scala index 9c9909cd..add40f79 100644 --- a/src/main/scala/chisel3/util/BitPat.scala +++ b/src/main/scala/chisel3/util/BitPat.scala @@ -35,7 +35,7 @@ object BitPat { } /** Creates a [[BitPat]] literal from a string. - * + * * @param n the literal value as a string, in binary, prefixed with 'b' * @note legal characters are '0', '1', and '?', as well as '_' and white * space (which are ignored) @@ -45,7 +45,12 @@ object BitPat { new BitPat(bits, mask, width) } - /** Creates a [[BitPat]] of all don't cares of the specified bitwidth. */ + /** Creates a [[BitPat]] of all don't cares of the specified bitwidth. + * + * @example {{{ + * val myDontCare = BitPat.dontCare(4) // equivalent to BitPat("b????") + * }}} + */ def dontCare(width: Int): BitPat = BitPat("b" + ("?" * width)) @deprecated("Use BitPat.dontCare", "chisel3") @@ -73,10 +78,14 @@ object BitPat { } } -// TODO: Break out of Core? (this doesn't involve FIRRTL generation) /** Bit patterns are literals with masks, used to represent values with don't - * cares. Equality comparisons will ignore don't care bits (for example, - * BitPat(0b10?1) === 0b1001.asUInt and 0b1011.asUInt. + * care bits. Equality comparisons will ignore don't care bits. + * + * @example {{{ + * "b10101".U === BitPat("b101??") // evaluates to true.B + * "b10111".U === BitPat("b101??") // evaluates to true.B + * "b10001".U === BitPat("b101??") // evaluates to false.B + * }}} */ sealed class BitPat(val value: BigInt, val mask: BigInt, width: Int) { def getWidth: Int = width diff --git a/src/main/scala/chisel3/util/Bitwise.scala b/src/main/scala/chisel3/util/Bitwise.scala index 22326972..950fa65f 100644 --- a/src/main/scala/chisel3/util/Bitwise.scala +++ b/src/main/scala/chisel3/util/Bitwise.scala @@ -8,11 +8,21 @@ package chisel3.util import chisel3._ import chisel3.core.SeqUtils +/** Creates repetitions of each bit of the input in order. + * + * @example {{{ + * FillInterleaved(2, "b1 0 0 0".U) // equivalent to "b11 00 00 00".U + * FillInterleaved(2, "b1 0 0 1".U) // equivalent to "b11 00 00 11".U + * FillInterleaved(2, myUIntWire) // dynamic interleaved fill + * + * FillInterleaved(2, Seq(true.B, false.B, false.B, false.B)) // equivalent to "b11 00 00 00".U + * FillInterleaved(2, Seq(true.B, false.B, false.B, true.B)) // equivalent to "b11 00 00 11".U + * }}} + */ object FillInterleaved { /** Creates n repetitions of each bit of x in order. * * Output data-equivalent to in(size(in)-1) (n times) ## ... ## in(1) (n times) ## in(0) (n times) - * For example, FillInterleaved(2, "b1000") === UInt("b11 00 00 00") */ def apply(n: Int, in: UInt): UInt = apply(n, in.toBools) @@ -23,14 +33,31 @@ object FillInterleaved { def apply(n: Int, in: Seq[Bool]): UInt = Cat(in.map(Fill(n, _)).reverse) } -/** Returns the number of bits set (i.e value is 1) in the input signal. +/** Returns the number of bits set (value is 1 or true) in the input signal. + * + * @example {{{ + * PopCount(Seq(true.B, false.B, true.B, true.B)) // evaluates to 3.U + * PopCount(Seq(false.B, false.B, true.B, false.B)) // evaluates to 1.U + * + * PopCount("b1011".U) // evaluates to 3.U + * PopCount("b0010".U) // evaluates to 1.U + * PopCount(myUIntWire) // dynamic count + * }}} */ -object PopCount -{ +object PopCount { def apply(in: Iterable[Bool]): UInt = SeqUtils.count(in.toSeq) + def apply(in: Bits): UInt = apply((0 until in.getWidth).map(in(_))) } +/** Create repetitions of the input using a tree fanout topology. + * + * @example {{{ + * Fill(2, "b1000".U) // equivalent to "b1000 1000".U + * Fill(2, "b1001".U) // equivalent to "b1001 1001".U + * Fill(2, myUIntWire) // dynamic fill + * }}} + */ object Fill { /** Create n repetitions of x using a tree fanout topology. * @@ -53,6 +80,14 @@ object Fill { } } +/** Returns the input in bit-reversed order. Useful for little/big-endian conversion. + * + * @example {{{ + * Reverse("b1101".U) // equivalent to "b1011".U + * Reverse("b1101".U(8.W)) // equivalent to "b10110000".U + * Reverse(myUIntWire) // dynamic reverse + * }}} + */ object Reverse { private def doit(in: UInt, length: Int): UInt = { if (length == 1) { @@ -73,7 +108,6 @@ object Reverse { Cat(doit(in(half-1,0), half), doit(in(length-1,half), length-half)) } } - /** Returns the input in bit-reversed order. Useful for little/big-endian conversion. - */ + def apply(in: UInt): UInt = doit(in, in.getWidth) } diff --git a/src/main/scala/chisel3/util/Cat.scala b/src/main/scala/chisel3/util/Cat.scala index ba12a7d4..78801541 100644 --- a/src/main/scala/chisel3/util/Cat.scala +++ b/src/main/scala/chisel3/util/Cat.scala @@ -5,8 +5,19 @@ package chisel3.util import chisel3._ import chisel3.core.SeqUtils +/** Concatenates elements of the input, in order, together. + * + * @example {{{ + * Cat("b101".U, "b11".U) // equivalent to "b101 11".U + * Cat(myUIntWire0, myUIntWire1) + * + * Cat(Seq("b101".U, "b11".U)) // equivalent to "b101 11".U + * Cat(mySeqOfBits) + * }}} + */ object Cat { - /** Concatenates the argument data elements, in argument order, together. + /** Concatenates the argument data elements, in argument order, together. The first argument + * forms the most significant bits, while the last argument forms the least significant bits. */ def apply[T <: Bits](a: T, r: T*): UInt = apply(a :: r.toList) diff --git a/src/main/scala/chisel3/util/CircuitMath.scala b/src/main/scala/chisel3/util/CircuitMath.scala index a422b5fe..b5f491ef 100644 --- a/src/main/scala/chisel3/util/CircuitMath.scala +++ b/src/main/scala/chisel3/util/CircuitMath.scala @@ -7,10 +7,19 @@ package chisel3.util import chisel3._ +/** Returns the base-2 integer logarithm of an UInt. + * + * @note The result is truncated, so e.g. Log2(13.U) === 3.U + * + * @example {{{ + * Log2(8.U) // evaluates to 3.U + * Log2(13.U) // evaluates to 3.U (truncation) + * Log2(myUIntWire) + * }}} + * + */ object Log2 { /** Returns the base-2 integer logarithm of the least-significant `width` bits of an UInt. - * - * @note The result is truncated, so e.g. Log2(13.U) === 3.U */ def apply(x: Bits, width: Int): UInt = { if (width < 2) { @@ -28,10 +37,6 @@ object Log2 { } } - /** Returns the base-2 integer logarithm of an UInt. - * - * @note The result is truncated, so e.g. Log2(13.U) === 3.U - */ def apply(x: Bits): UInt = apply(x, x.getWidth) private def divideAndConquerThreshold = 4 -- cgit v1.2.3 From ad53161bbb9f67e16b88ca7a508a537f88d77e05 Mon Sep 17 00:00:00 2001 From: Chick Markley Date: Wed, 7 Dec 2016 10:31:23 -0800 Subject: Support for creating chisel annotations that are consumed by firrtl (#393) * Support for creating chisel annotations that are consumed by firrtl Update annotation serialization in Driver Add DiamondAnnotation Spec that illustrates how to do simple annotations frontEnd must have dependency on firrtl Add annotation method to Module Circuit has extra optional parameter that is Seq of Annotations In Builder add annotation buffer to DynamicContext to store annotations created in modules Added explicit types on naming api methods to avoid type confusion Because some names are not available until elaboration create intermediate ChiselAnnotation that gets turned into a firrtl Annotation after elaboration In execute pass firrtl text and annotation to firrtl are now passed in through optionManager, though intermediate file .fir and .anno files are still created for inspection and/or later use * Somehow missed ChiselAnnotation * fixes for Jack's review of PR --- src/main/scala/chisel3/Driver.scala | 12 ++++++++++++ src/main/scala/chisel3/package.scala | 3 +++ 2 files changed, 15 insertions(+) (limited to 'src/main') diff --git a/src/main/scala/chisel3/Driver.scala b/src/main/scala/chisel3/Driver.scala index ab51ad25..646702c3 100644 --- a/src/main/scala/chisel3/Driver.scala +++ b/src/main/scala/chisel3/Driver.scala @@ -6,10 +6,13 @@ import chisel3.internal.firrtl.Emitter import scala.sys.process._ import java.io._ +import net.jcazevedo.moultingyaml._ import internal.firrtl._ import firrtl._ +import _root_.firrtl.annotations.AnnotationYamlProtocol._ + /** * The Driver provides methods to invoke the chisel3 compiler and the firrtl compiler. * By default firrtl is automatically run after chisel. an [[ExecutionOptionsManager]] @@ -239,6 +242,15 @@ object Driver extends BackendCompilationUtilities { w.write(firrtlString) w.close() + val annotationFile = new File(optionsManager.getBuildFileName("anno")) + val af = new FileWriter(annotationFile) + af.write(circuit.annotations.toArray.toYaml.prettyPrint) + af.close() + + /* This passes the firrtl source and annotations directly to firrtl */ + optionsManager.firrtlOptions = optionsManager.firrtlOptions.copy( + firrtlSource = Some(firrtlString), annotations = circuit.annotations.toList) + val firrtlExecutionResult = if(chiselOptions.runFirrtlCompiler) { Some(firrtl.Driver.execute(optionsManager)) } diff --git a/src/main/scala/chisel3/package.scala b/src/main/scala/chisel3/package.scala index e4e64b89..25d3ec3a 100644 --- a/src/main/scala/chisel3/package.scala +++ b/src/main/scala/chisel3/package.scala @@ -32,6 +32,9 @@ package object chisel3 { // scalastyle:ignore package.object.name type Element = chisel3.core.Element type Bits = chisel3.core.Bits + type ChiselAnnotation = chisel3.core.ChiselAnnotation + val ChiselAnnotation = chisel3.core.ChiselAnnotation + // Some possible regex replacements for the literal specifier deprecation: // (note: these are not guaranteed to handle all edge cases! check all replacements!) // Bool\((true|false)\) -- cgit v1.2.3 From 72e6c884b3f66a379982e5b3efc01afc563275cd Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Wed, 14 Dec 2016 12:32:04 -0800 Subject: Change noenq in ReadyValid to use an uninitialized Wire instead of zero (#364) --- src/main/scala/chisel3/util/Decoupled.scala | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'src/main') diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala index fcda6943..4a97724a 100644 --- a/src/main/scala/chisel3/util/Decoupled.scala +++ b/src/main/scala/chisel3/util/Decoupled.scala @@ -37,12 +37,13 @@ object ReadyValidIO { dat } - /** Indicate no enqueue occurs. Valid is set to false, and all bits are set to zero. + /** Indicate no enqueue occurs. Valid is set to false, and bits are + * connected to an uninitialized wire */ def noenq(): Unit = { target.valid := false.B // We want the type from the following, not any existing binding. - target.bits := target.bits.cloneType.fromBits(0.asUInt) + target.bits := Wire(target.bits.cloneType) } /** Assert ready on this port and return the associated data bits. -- cgit v1.2.3 From 59a7c25d5c708305216532ec49c8120e59219f69 Mon Sep 17 00:00:00 2001 From: Chick Markley Date: Wed, 14 Dec 2016 15:31:31 -0800 Subject: Final steps for annotations getting from chisel to firrtl (#405) Pass transforms along with Annotations when calling firrtl compiler This introduces new requirement that firrtl.Transform subclasses (that are associated with an annotation) do not have parameters in their default constructor Add new test for NoDedup annotation that shows how to annotate a module instance--- src/main/scala/chisel3/Driver.scala | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'src/main') diff --git a/src/main/scala/chisel3/Driver.scala b/src/main/scala/chisel3/Driver.scala index 646702c3..40c94b54 100644 --- a/src/main/scala/chisel3/Driver.scala +++ b/src/main/scala/chisel3/Driver.scala @@ -247,9 +247,17 @@ object Driver extends BackendCompilationUtilities { af.write(circuit.annotations.toArray.toYaml.prettyPrint) af.close() + /* create custom transforms by finding the set of transform classes associated with annotations + * then instantiate them into actual transforms + */ + val transforms = circuit.annotations.map(_.transform).toSet.map { transformClass: Class[_ <: Transform] => + transformClass.newInstance() + } /* This passes the firrtl source and annotations directly to firrtl */ optionsManager.firrtlOptions = optionsManager.firrtlOptions.copy( - firrtlSource = Some(firrtlString), annotations = circuit.annotations.toList) + firrtlSource = Some(firrtlString), + annotations = circuit.annotations.toList, + customTransforms = transforms.toList) val firrtlExecutionResult = if(chiselOptions.runFirrtlCompiler) { Some(firrtl.Driver.execute(optionsManager)) -- cgit v1.2.3