[RFC] CDC library

[sequencer]

Type of issue: feature request

Impact: API addition (no impact on existing code)

Development Phase: proposal

For a PnR friendly RTL, I think we should start to consider how to add Clock-domain-checking library.
Here are my simple ideas to this problem.

for registers in the circuit, they have 4 types:

1. under a clock
2. under a clock and correspond synchronous reset
3. under a clock and full asynchronous reset
4. under a clock and asynchronous reset synchronous deassertion reset.
   RTL of "full asynchronous" and "asynchronous reset synchronous deassertion" are same:
   https://scastie.scala-lang.org/6HKMD9YbSxGeZxP0oroEtw

However a synchronizer should be implemented like this.
https://scastie.scala-lang.org/gAUzcR5iQXSCXVXwGgEATA

These two asynchronous reset have two types of reset, but a same chisel type.

Basically, my idea is annotate clock and reset and let FIRRTL transform to resolve and check them.
I wanna RFC for some comments on what to annotate, and what to check.
Here are something I can come up with:

1. annotate clock frequency.
2. annotate clock - synchronous reset relationship
3. annotate reset generation IO or Module.
4. annotate asynchronous type.
5. annotate false path(from register to register?)
6. annotate safe cross clock domain Module.(AsyncQueue, RationalQueue etc.)
7. check register under different clock are not crossing.
8. check register under same clock - synchronous reset pair are not crossing to other clock - synchronous reset pair.
9. check asynchronous resets are from a reset generation IO without passing any combinational path.

Output should be a set of annotations and can have a vendor specific Transform to generate SDC files.

[mwachs5]

I like this idea. One concern I have about approaches I have heard in the past is if we derive the CDC from the FIRRTL directly (like, "this register is synchronous to this clock"), that is basically exactly what the SDC lint checks will do, therefore your lint checks dont actually check anything anymore. You really want a human in the loop saying something about their design intent, then a check that the hardware actually does that.

Haven't read through your proposal in detail, just noting one solution I would not prefer.

[ekiwi]

You probably also want:
10. the clock domain of any toplevel input signal (or if it is asynchronous)

[ekiwi]

@sequencer, when we want to do clock domain analysis - in my opinion - the biggest problem are special cases where clocks or resets are cast to something else. Could you try and see if the asClock or asAsyncReset primops are used anywhere in your company's code base? Having some use cases would help us decide how to deal with them when trying to extract the clock domains.

[colinschmidt]

@azidar made something related to these issues a long time ago to make the "designer inspection" part simpler.
It wasn't perfect but it did help catch a few issues at the time.

https://github.com/chipsalliance/firrtl/tree/master/src/main/scala/firrtl/passes/clocklist

[sequencer]

I like this idea. One concern I have about approaches I have heard in the past is if we derive the CDC from the FIRRTL directly (like, "this register is synchronous to this clock"), that is basically exactly what the SDC lint checks will do, therefore your lint checks dont actually check anything anymore.

Yes, clock tree analysis will be executed during synthesis flow. checking CDC error is redundant, but annotate relationship for different clock/reset the target.

You really want a human in the loop saying something about their design intent, then a check that the hardware actually does that.

Yes, what I really wanna do is: try to gather "what will a human say during this loop", abstract them to APIs, annotate to target Data.
Chisel only handle synchronous circuit, and SDC for synchronous circuit won't be too much, I think we only need to gather the clock and reset relationship.

[sequencer]

in my opinion - the biggest problem are special cases where clocks or resets are cast to something else. Could you try and see if the asClock or asAsyncReset primops are used anywhere in your company's code base?

Yes, that's what I really care about, I discussed with some experienced PnR engineers, they said there will always be some ClockGen and ResetGen Module to do commutation on clock/reset signal, rather than directly pull a Clock signal, cast them to Bool, do some combinational logic, and cast back to Clock, they are forbidden to do this. So I think if our Clock cast and Reset cast have a bad design for PnR guys?

[sequencer]

10. the clock domain of any toplevel input signal (or if it is asynchronous)

In my understanding, annotating a clock anywhere inside the circuit will propagate the metadata to whole clock tree. So maybe no need to annotate toplevel input signal, aka, the source of clock tree. We just need to annotate a clock node inside the clock tree and let CircuitAnalysis transform automatically spread the metadata.

[sequencer]

@ azidar made something related to these issues a long time ago to make the "designer inspection" part simpler.
It wasn't perfect but it did help catch a few issues at the time.

That's a good start point to do this! We already have CircuitGraph and ConnectionGraph to do connection analysis, I think the rest of thing is try to understand the real need, design API, and work on the transform, the most hard part are perfectly done by Adam ;p

[ekiwi]

Yes, that's what I really care about, I discussed with some experienced PnR engineers, they said there will always be some ClockGen and ResetGen Module to do commutation on clock/reset signal, rather than directly pull a Clock signal, cast them to Bool, do some combinational logic, and cast back to Clock, they are forbidden to do this.

Could you build the firrtl of some of your designs and grep for asClock or asAsyncReset?
I am just wondering if people are using these today, or if all the clock and reset generators are written in Verilog.

[ekiwi]

In my understanding, annotating a clock anywhere inside the circuit will propagate the metadata to whole clock tree. So maybe no need to annotate toplevel input signal, aka, the source of clock tree. We just need to annotate a clock node inside the clock tree and let CircuitAnalysis transform automatically spread the metadata.

The reason I suggested to annotate the clock domain of the inputs is to check whether there is a clock domain crossing of a data signal. If you think about a circuit in firrtl, we can easily determine the clock domain of any signal that comes from a register since it will be the same as the register's. However, for input to the top level module (and also for outputs of BlackBoxes) we do not know the clock domain and thus it needs to be annotated in order to do CDC checking.

[sequencer]

However, for input to the top level module (and also for outputs of BlackBoxes) we do not know the clock domain and thus it needs to be annotated in order to do CDC checking.

Yes, I got it, that's what we need to annotate too!