Add a set of CDC Linting rules

[chili-chips-ba]

For starters, we could check the scenarios that mainstream commercial tools address:

• https://www.realintent.com/clock-domain-crossing-meridian-cdc
• https://www.synopsys.com/verification/static-and-formal-verification/spyglass/spyglass-cdc.html

There is also this open-source project that can be taken for reference:

• https://github.com/BerkeleyLab/Bedrock/blob/master/build-tools/cdc_snitch.md

Verilator CDC Request
Yosys CDC Request
Slang CDC Request

[ajeethakv]

Thanks for the interest. I browsed through some of the links you've provided. I don't see a crisp set of rules that can be lint-checked. CDC verification is ofcourse a wider problem involving multitude of techniques and looks like that cdc_snitch is a good start. What exactly do you have in mind for source code level Verilog/SV (or even VHDL) lint checks w.r.t CDC?

[ajeethakv]

Here are some basic conceptual rules. I am looking for more concrete ones to implement via PySlint.

CDC Lint Rules

1. Clock Domain Identification:

• Rule: Ensure all clock domains are explicitly identified.
• Description: Clearly label and document all clock domains used in the design. Use consistent naming conventions for signals and modules to indicate their clock domains (e.g., clk_a, clk_b).

2. Synchronous Resets:

• Rule: Use synchronous resets for all registers.
• Description: Ensure that all resets are synchronous to the respective clock domains they control. Asynchronous resets should be avoided unless absolutely necessary, and should be de-asserted synchronously.

3. Single-Bit Signal Synchronization:

• Rule: Synchronize single-bit signals crossing clock domains using multi-stage flip-flop synchronizers.
• Description: Use at least two flip-flops in series to synchronize single-bit signals crossing clock domains to avoid metastability.

4. Multi-Bit Signal Handling:

• Rule: Use CDC-safe structures for multi-bit signal transfers.
• Description: Employ methods like FIFOs, dual-port RAMs, or handshaking protocols to safely transfer multi-bit data across clock domains.

5. FIFO Usage:

• Rule: Use asynchronous FIFOs for data transfer between different clock domains.
• Description: Asynchronous FIFOs should be implemented with proper full and empty flag synchronization to manage data safely between clock domains.

6. Handshake Protocols:

• Rule: Implement handshake protocols for control signal transfers.
• Description: Use handshaking mechanisms (e.g., request-acknowledge) for transferring control signals across clock domains to ensure data integrity.

7. Avoid Combinational Logic Between Clock Domains:

• Rule: Do not use combinational logic to connect signals between different clock domains.
• Description: Ensure that signals crossing clock domains are registered and do not pass through combinational logic to prevent glitches and metastability.

8. Metastability Handling:

• Rule: Design for metastability tolerance.
• Description: Ensure that the design can tolerate metastability by allowing sufficient settling time and using proper synchronizers.

[chili-chips-ba]

... you may also want to take a look at this @obruendl repo with descriptions of common CDC scenarios and library modules for handling them:

• https://github.com/open-logic/open-logic/blob/2.0.0/doc/base/clock_crossing_principles.md
• https://github.com/open-logic/open-logic/blob/2.0.0/doc/base/olo_base_cc_bits.md
• https://github.com/open-logic/open-logic/blob/2.0.0/doc/base/olo_base_cc_pulse.md
• https://github.com/open-logic/open-logic/blob/2.0.0/doc/base/olo_base_cc_reset.md
• https://github.com/open-logic/open-logic/blob/2.0.0/doc/base/olo_base_cc_simple.md
• https://github.com/open-logic/open-logic/blob/2.0.0/doc/base/olo_base_cc_status.md
• https://github.com/open-logic/open-logic/blob/2.0.0/doc/base/olo_base_cc_xn2n.md
• https://github.com/open-logic/open-logic/blob/2.0.0/doc/base/olo_base_cc_n2xn.md

[chili-chips-ba]

@ajeethakv any progress on this track?

We're hot to trying it on our Wireguard-FPGA project...