From 435c99889dd9eced1d48e0ce367f60acff672854 Mon Sep 17 00:00:00 2001 From: ducky Date: Fri, 15 Feb 2019 17:03:39 -0800 Subject: [PATCH 1/5] Add Math docs --- src/main/scala/chisel3/util/Math.scala | 61 +++++++++++++++++++++++--- 1 file changed, 56 insertions(+), 5 deletions(-) diff --git a/src/main/scala/chisel3/util/Math.scala b/src/main/scala/chisel3/util/Math.scala index 0e1b36d5198..046930e37e2 100644 --- a/src/main/scala/chisel3/util/Math.scala +++ b/src/main/scala/chisel3/util/Math.scala @@ -8,7 +8,21 @@ package chisel3.util import chisel3._ import chisel3.internal.chiselRuntimeDeprecated -/** Compute the log2 rounded up with min value of 1 */ +/** Compute the log2 of a Scala integer, rounded up, with min value of 1. + * Useful for getting the number of bits needed to represent some number of states (in - 1), + * To get the number of bits needed to represent some number n, use log2Up(n + 1). + * with the minimum value preventing the creation of currently-unsupported zero-width wires. + * + * Note: prefer to use log2Ceil when in is known to be > 1 (where log2Ceil(in) > 0). + * This will be deprecated when zero-width wires is supported. + * + * @example {{{ + * log2Up(1) = 1 + * log2Up(2) = 1 + * log2Up(3) = 2 + * log2Up(4) = 2 + * }}} + */ object log2Up { // Do not deprecate until zero-width wires fully work: // https://github.com/freechipsproject/chisel3/issues/847 @@ -17,7 +31,20 @@ object log2Up { def apply(in: BigInt): Int = Chisel.log2Up(in) } -/** Compute the log2 rounded up */ +/** Compute the log2 of a Scala integer, rounded up. + * Useful for getting the number of bits needed to represent some number of states (in - 1). + * To get the number of bits needed to represent some number n, use log2Ceil(n + 1). + * + * Note: can return zero, and should not be used in cases where it may generate unsupported + * zero-width wires. + * + * @example {{{ + * log2Up(1) = 0 + * log2Up(2) = 1 + * log2Up(3) = 2 + * log2Up(4) = 2 + * }}} + */ object log2Ceil { def apply(in: BigInt): Int = { require(in > 0) @@ -26,7 +53,15 @@ object log2Ceil { def apply(in: Int): Int = apply(BigInt(in)) } -/** Compute the log2 rounded down with min value of 1 */ +/** Compute the log2 of a Scala integer, rounded down, with min value of 1. + * + * @example {{{ + * log2Down(1) = 1 + * log2Down(2) = 1 + * log2Down(3) = 1 + * log2Down(4) = 2 + * }}} + */ object log2Down { // Do not deprecate until zero-width wires fully work: // https://github.com/freechipsproject/chisel3/issues/847 @@ -35,13 +70,29 @@ object log2Down { def apply(in: BigInt): Int = Chisel.log2Down(in) } -/** Compute the log2 rounded down */ +/** Compute the log2 of a Scala integer, rounded down. + * + * @example {{{ + * log2Floor(1) = 0 + * log2Floor(2) = 1 + * log2Floor(3) = 1 + * log2Floor(4) = 2 + * }}} + */ object log2Floor { def apply(in: BigInt): Int = log2Ceil(in) - (if (isPow2(in)) 0 else 1) def apply(in: Int): Int = apply(BigInt(in)) } -/** Check if an Integer is a power of 2 */ +/** Returns whether a Scala integer is a power of two. + * + * @example {{{ + * isPow2(1) = true + * isPow2(2) = true + * isPow2(3) = false + * isPow2(4) = true + * }}} + */ object isPow2 { def apply(in: BigInt): Boolean = in > 0 && ((in & (in-1)) == 0) def apply(in: Int): Boolean = apply(BigInt(in)) From cf0d043ec47660cfbeafe4ae909a6985e12422ec Mon Sep 17 00:00:00 2001 From: ducky Date: Fri, 15 Feb 2019 17:06:26 -0800 Subject: [PATCH 2/5] Add use case for log2Floor --- src/main/scala/chisel3/util/Math.scala | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/main/scala/chisel3/util/Math.scala b/src/main/scala/chisel3/util/Math.scala index 046930e37e2..561c7888d2f 100644 --- a/src/main/scala/chisel3/util/Math.scala +++ b/src/main/scala/chisel3/util/Math.scala @@ -71,6 +71,8 @@ object log2Down { } /** Compute the log2 of a Scala integer, rounded down. + * + * Can be useful in computing the next-smallest power of two. * * @example {{{ * log2Floor(1) = 0 From 6840d24e91e4706a63ebf6039f885805b75b2675 Mon Sep 17 00:00:00 2001 From: ducky Date: Fri, 15 Feb 2019 18:56:42 -0800 Subject: [PATCH 3/5] MixedVec docs --- src/main/scala/chisel3/util/MixedVec.scala | 46 +++++++++++++--------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/src/main/scala/chisel3/util/MixedVec.scala b/src/main/scala/chisel3/util/MixedVec.scala index ec15e23abc0..80e224d3013 100644 --- a/src/main/scala/chisel3/util/MixedVec.scala +++ b/src/main/scala/chisel3/util/MixedVec.scala @@ -8,12 +8,20 @@ import chisel3.internal.naming.chiselName import scala.collection.immutable.ListMap +/** + * Create a MixedVec wire with default values as specified, and type of each element inferred from + * those default values. + * + * This is analogous to [[chisel3.core.VecInit]]. + * @return MixedVec with given values assigned + * + * @example {{{ + * MixedVecInit(Seq(100.U(8.W), 10000.U(16.W), 101.U(32.W))) + * }}} + */ object MixedVecInit { /** - * Construct a new wire with the given bound values. - * This is analogous to [[chisel3.core.VecInit]]. - * @param vals Values to create a MixedVec with and assign - * @return MixedVec with given values assigned + * Create a MixedVec wire from a Seq of values. */ def apply[T <: Data](vals: Seq[T]): MixedVec[T] = { // Create a wire of this type. @@ -26,39 +34,39 @@ object MixedVecInit { } /** - * Construct a new wire with the given bound values. - * This is analogous to [[chisel3.core.VecInit]]. - * @return MixedVec with given values assigned + * Create a MixedVec wire from a varargs list of values. */ def apply[T <: Data](val0: T, vals: T*): MixedVec[T] = apply(val0 +: vals.toSeq) } +/** + * Create a MixedVec type, given element types. Inputs must be Chisel types which have no value + * (not hardware types). + * + * @return MixedVec with the given types. + */ object MixedVec { /** - * Create a MixedVec from that holds the given types. - * @param eltsIn Element types. Must be Chisel types. - * @return MixedVec with the given types. + * Create a MixedVec type from a Seq of Chisel types. */ def apply[T <: Data](eltsIn: Seq[T]): MixedVec[T] = new MixedVec(eltsIn) /** - * Create a MixedVec from that holds the given types. - * The types passed to this constructor must be Chisel types. - * @return MixedVec with the given types. + * Create a MixedVec type from a varargs list of Chisel types. */ def apply[T <: Data](val0: T, vals: T*): MixedVec[T] = new MixedVec(val0 +: vals.toSeq) /** - * Create a new MixedVec from an unbound MixedVec type. - * @return MixedVec with the given types. + * Create a new MixedVec type from an unbound MixedVec type. */ def apply[T <: Data](mixedVec: MixedVec[T]): MixedVec[T] = new MixedVec(mixedVec.elts) /** - * Create a MixedVec from the type of the given Vec. - * For example, given a Vec(2, UInt(8.W)), this creates MixedVec(Seq.fill(2){UInt(8.W)}). - * @param vec Vec to use as template - * @return MixedVec analogous to the given Vec. + * Create a MixedVec type from the type of the given Vec. + * + * @example {{{ + * MixedVec(Vec(2, UInt(8.W))) = MixedVec(Seq.fill(2){UInt(8.W)}) + * }}} */ def apply[T <: Data](vec: Vec[T]): MixedVec[T] = { MixedVec(Seq.fill(vec.length)(vec.sample_element)) From 06d02b111a1a7909c0bd7ba2146b53a8b03f4611 Mon Sep 17 00:00:00 2001 From: ducky Date: Fri, 15 Feb 2019 19:03:35 -0800 Subject: [PATCH 4/5] fix lox2ceil --- src/main/scala/chisel3/util/Math.scala | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/main/scala/chisel3/util/Math.scala b/src/main/scala/chisel3/util/Math.scala index 561c7888d2f..f8b399bb3dc 100644 --- a/src/main/scala/chisel3/util/Math.scala +++ b/src/main/scala/chisel3/util/Math.scala @@ -39,10 +39,10 @@ object log2Up { * zero-width wires. * * @example {{{ - * log2Up(1) = 0 - * log2Up(2) = 1 - * log2Up(3) = 2 - * log2Up(4) = 2 + * log2Ceil(1) = 0 + * log2Ceil(2) = 1 + * log2Ceil(3) = 2 + * log2Ceil(4) = 2 * }}} */ object log2Ceil { From f1b2f50f925313d1a54a36459338ef3bc3f8a88b Mon Sep 17 00:00:00 2001 From: ducky Date: Tue, 26 Feb 2019 17:14:32 -0800 Subject: [PATCH 5/5] Examples technically executable --- src/main/scala/chisel3/util/Math.scala | 40 +++++++++++++------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/src/main/scala/chisel3/util/Math.scala b/src/main/scala/chisel3/util/Math.scala index f8b399bb3dc..f9278c7d6d6 100644 --- a/src/main/scala/chisel3/util/Math.scala +++ b/src/main/scala/chisel3/util/Math.scala @@ -17,10 +17,10 @@ import chisel3.internal.chiselRuntimeDeprecated * This will be deprecated when zero-width wires is supported. * * @example {{{ - * log2Up(1) = 1 - * log2Up(2) = 1 - * log2Up(3) = 2 - * log2Up(4) = 2 + * log2Up(1) // returns 1 + * log2Up(2) // returns 1 + * log2Up(3) // returns 2 + * log2Up(4) // returns 2 * }}} */ object log2Up { @@ -39,10 +39,10 @@ object log2Up { * zero-width wires. * * @example {{{ - * log2Ceil(1) = 0 - * log2Ceil(2) = 1 - * log2Ceil(3) = 2 - * log2Ceil(4) = 2 + * log2Ceil(1) // returns 0 + * log2Ceil(2) // returns 1 + * log2Ceil(3) // returns 2 + * log2Ceil(4) // returns 2 * }}} */ object log2Ceil { @@ -56,10 +56,10 @@ object log2Ceil { /** Compute the log2 of a Scala integer, rounded down, with min value of 1. * * @example {{{ - * log2Down(1) = 1 - * log2Down(2) = 1 - * log2Down(3) = 1 - * log2Down(4) = 2 + * log2Down(1) // returns 1 + * log2Down(2) // returns 1 + * log2Down(3) // returns 1 + * log2Down(4) // returns 2 * }}} */ object log2Down { @@ -75,10 +75,10 @@ object log2Down { * Can be useful in computing the next-smallest power of two. * * @example {{{ - * log2Floor(1) = 0 - * log2Floor(2) = 1 - * log2Floor(3) = 1 - * log2Floor(4) = 2 + * log2Floor(1) // returns 0 + * log2Floor(2) // returns 1 + * log2Floor(3) // returns 1 + * log2Floor(4) // returns 2 * }}} */ object log2Floor { @@ -89,10 +89,10 @@ object log2Floor { /** Returns whether a Scala integer is a power of two. * * @example {{{ - * isPow2(1) = true - * isPow2(2) = true - * isPow2(3) = false - * isPow2(4) = true + * isPow2(1) // returns true + * isPow2(2) // returns true + * isPow2(3) // returns false + * isPow2(4) // returns true * }}} */ object isPow2 {