From 4ef37d9411cf78545e6babd09c9a578b9947513a Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Mon, 25 Oct 2021 19:53:29 -0400 Subject: [PATCH] Commentary --- docs/guide/exe_verilator.rst | 40 +++++++++++++++++------------------- docs/guide/extensions.rst | 7 +++---- 2 files changed, 22 insertions(+), 25 deletions(-) diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index 8ed959e21..7e38489e5 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -158,28 +158,26 @@ Summary: .. option:: --clk - Sometimes it is quite difficult for Verilator to distinguish clock - signals from other data signals. Occasionally the clock signals can end - up in the checking list of signals which determines if further - evaluation is needed. This will heavily degrade the performance of a - Verilated model. - With :vlopt:`--clk`, the specified signal-name is taken as a root clock - into the model, then Verilator will mark the signal as clocker and - propagate the clocker attribute automatically to other signals derived - from that. In this way, Verilator will try to avoid taking the clocker - signal into checking list. + into the model; Verilator will mark the signal as clocker and + propagate the clocker attribute automatically to other signals downstream in + that clock tree. - Note signal-name is specified by the RTL hierarchy path. For example, - v.foo.bar. If the signal is the input to top-module, the directly the - signal name. If you find it difficult to find the exact name, try to use - a :option:`/*verilator&32;clocker*/` metacomment in RTL file to mark the + The provided signal-name is specified using a RTL hierarchy path. For + example, v.foo.bar. If the signal is the input to top-module, then + directly provide the signal name. Alternatively, use a + :option:`/*verilator&32;clocker*/` metacomment in RTL file to mark the signal directly. - If clock signals are assigned to vectors and then later used - individually, Verilator will attempt to decompose the vector and connect - the single-bit clock signals directly. This should be transparent to - the user. + If clock signals are assigned to vectors and then later used as + individual bits, Verilator will attempt to decompose the vector and + connect the single-bit clock signals. + + The clocker attribute is useful in cases where Verilator does not + properly distinguish clock signals from other data signals. Using + clocker will cause the signal indicated to be considered a clock, and + remove it from the combinatorial logic reevaluation checking code. This + may greatly improve performance. .. option:: --make @@ -1506,9 +1504,9 @@ The grammar of configuration commands is as follows: .. option:: no_clocker -module "" [-function ""] -var "" - Indicate the signal is used as clock or not. This information is used by - Verilator to mark the signal as clocker and propagate the clocker - attribute automatically to derived signals. See :vlopt:`--clk`. + Indicates that the signal is used as clock or not. This information is + used by Verilator to mark the signal and any derrived signals as + clocker. See :vlopt:`--clk`. Same as :option:`/*verilator&32;clocker*/` metacomment. diff --git a/docs/guide/extensions.rst b/docs/guide/extensions.rst index c82c89adb..6e2d26495 100644 --- a/docs/guide/extensions.rst +++ b/docs/guide/extensions.rst @@ -176,10 +176,9 @@ or "`ifdef`"'s may break other tools. .. option:: /*verilator&32;no_clocker*/ - Used after a signal declaration to indicate the signal is used as clock - or not. This information is used by Verilator to mark the signal as - clocker and propagate the clocker attribute automatically to derived - signals. See :vlopt:`--clk`. + Specifies that the signal is used as clock or not. This information is + used by Verilator to mark the signal and any derrived signals as + clocker. See :vlopt:`--clk`. Same as :option:`clocker` and :option:`no_clocker` in configuration files.