From f1e37900170124254f3cf4599a45e7a485c17a91 Mon Sep 17 00:00:00 2001 From: Schuyler Eldridge Date: Wed, 7 Jul 2021 21:05:33 -0400 Subject: Update docs on dontTouch as optimization barrier (#2015) Change the Scaladoc for the dontTouch utility. Indicate that this is an _optimization barrier_ and not just a guarantee that the signal won't be removed. The optimization barrier interpretation is the current implementation in the Scala FIRRTL Compiler. Signed-off-by: Schuyler Eldridge Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>--- core/src/main/scala/chisel3/dontTouch.scala | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'core/src') diff --git a/core/src/main/scala/chisel3/dontTouch.scala b/core/src/main/scala/chisel3/dontTouch.scala index 0487a567..e679f1a4 100644 --- a/core/src/main/scala/chisel3/dontTouch.scala +++ b/core/src/main/scala/chisel3/dontTouch.scala @@ -5,7 +5,8 @@ package chisel3 import chisel3.experimental.{ChiselAnnotation, annotate, requireIsHardware} import firrtl.transforms.DontTouchAnnotation -/** Marks that a signal should not be removed by Chisel and Firrtl optimization passes +/** Marks that a signal is an optimization barrier to Chisel and the FIRRTL compiler. This has the effect of + * guaranteeing that a signal will not be removed. * * @example {{{ * class MyModule extends Module { @@ -21,9 +22,11 @@ import firrtl.transforms.DontTouchAnnotation * @note Calling this on [[Data]] creates an annotation that Chisel emits to a separate annotations * file. This file must be passed to FIRRTL independently of the `.fir` file. The execute methods * in [[chisel3.Driver]] will pass the annotations to FIRRTL automatically. + * @note Because this is an optimization barrier, constants will not be propagated through a signal marked as + * dontTouch. */ object dontTouch { - /** Marks a signal to be preserved in Chisel and Firrtl + /** Mark a signal as an optimization barrier to Chisel and FIRRTL. * * @note Requires the argument to be bound to hardware * @param data The signal to be marked -- cgit v1.2.3