From 52515a884dd9a2bd5f506ecfbb7e248349bdd422 Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Thu, 9 Jan 2025 10:07:54 -0800 Subject: [PATCH 1/4] [docs] Add Cookbook entry for Verilog case equality (IsX) --- docs/src/cookbooks/cookbook.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md index d8d3e2774e2..6cd941ff51e 100644 --- a/docs/src/cookbooks/cookbook.md +++ b/docs/src/cookbooks/cookbook.md @@ -897,6 +897,31 @@ compile(new TooWideOrNarrowUInt(8, 2)) compile(new TooWideOrNarrowUInt(8, 4)) ``` +## How can I use Verilog "case equality" operators in Chisel? + +Verilog has "case equality" (`===`) and inequality (`!==`) operators. +They are typically used to ignore unknown (`X`) values in assertions. + +Chisel does not support SystemVerilog `X` directly, but it is possible to check if a value is `X` with `chisel3.util.circt.isX`. +`isX` is commonly used to guard assertions against `X` which gives similar behavior to Verilog case equality. + +```scala mdoc:silent:reset +import chisel3._ +import chisel3.util.circt.IsX + +class XSafeAssert extends Module { + val in = IO(Input(UInt(8.W))) + + // Assert that in is never zero, but also guard against X + assert(IsX(in) || in =/= 0.U, "in should never equal 0") +} +``` + +```scala mdoc:invisible +// Hidden but will make sure this actually compiles +chisel3.docs.emitSystemVerilog(new XSafeAssert) +``` + ## Predictable Naming ### How do I get Chisel to name signals properly in blocks like when/withClockAndReset? From 0ca735294e6bda6aba32030458f54286b5579442 Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Thu, 9 Jan 2025 10:23:57 -0800 Subject: [PATCH 2/4] Update docs/src/cookbooks/cookbook.md --- docs/src/cookbooks/cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md index 6cd941ff51e..a33bfc92fa6 100644 --- a/docs/src/cookbooks/cookbook.md +++ b/docs/src/cookbooks/cookbook.md @@ -912,7 +912,7 @@ import chisel3.util.circt.IsX class XSafeAssert extends Module { val in = IO(Input(UInt(8.W))) - // Assert that in is never zero, but also guard against X + // Assert that in is never zero; also do not trigger assert in the presence of X. assert(IsX(in) || in =/= 0.U, "in should never equal 0") } ``` From a5774608304ca26f5a84b9b3b5bbc47596862a30 Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Thu, 9 Jan 2025 10:29:25 -0800 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Megan Wachs --- docs/src/cookbooks/cookbook.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md index a33bfc92fa6..b23c3ad60a1 100644 --- a/docs/src/cookbooks/cookbook.md +++ b/docs/src/cookbooks/cookbook.md @@ -909,7 +909,7 @@ Chisel does not support SystemVerilog `X` directly, but it is possible to check import chisel3._ import chisel3.util.circt.IsX -class XSafeAssert extends Module { +class AssertButAllowX extends Module { val in = IO(Input(UInt(8.W))) // Assert that in is never zero; also do not trigger assert in the presence of X. @@ -919,7 +919,7 @@ class XSafeAssert extends Module { ```scala mdoc:invisible // Hidden but will make sure this actually compiles -chisel3.docs.emitSystemVerilog(new XSafeAssert) +chisel3.docs.emitSystemVerilog(new AssertButAllowX) ``` ## Predictable Naming From 8efcd70a791c1fab2f89d37210c2565eede68eb2 Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Thu, 9 Jan 2025 10:42:29 -0800 Subject: [PATCH 4/4] Update docs/src/cookbooks/cookbook.md Co-authored-by: Tynan McAuley --- docs/src/cookbooks/cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md index b23c3ad60a1..20854b87b37 100644 --- a/docs/src/cookbooks/cookbook.md +++ b/docs/src/cookbooks/cookbook.md @@ -902,7 +902,7 @@ compile(new TooWideOrNarrowUInt(8, 4)) Verilog has "case equality" (`===`) and inequality (`!==`) operators. They are typically used to ignore unknown (`X`) values in assertions. -Chisel does not support SystemVerilog `X` directly, but it is possible to check if a value is `X` with `chisel3.util.circt.isX`. +Chisel does not support Verilog `X` directly, but it is possible to check if a value is `X` with `chisel3.util.circt.isX`. `isX` is commonly used to guard assertions against `X` which gives similar behavior to Verilog case equality. ```scala mdoc:silent:reset