cxxrtl: fix misleading example, caution about race conditions.

Fixes #1944.

diff --git a/backends/cxxrtl/cxxrtl.cc b/backends/cxxrtl/cxxrtl.cc
index d6b901aa0832ae2ce658e3367c1fd186a62b06e4..8f7f9d7a3101fb94c75ea3e82f23dc63adf40402 100644 (file)
--- a/backends/cxxrtl/cxxrtl.cc
+++ b/backends/cxxrtl/cxxrtl.cc
@@ -1640,21 +1640,30 @@ struct CxxrtlBackend : public Backend {
                log("\n");
                log("    write_cxxrtl [options] [filename]\n");
                log("\n");
-               log("Write C++ code for simulating the design. The generated code requires a driver;\n");
-               log("the following simple driver is provided as an example:\n");
+               log("Write C++ code for simulating the design. The generated code requires a driver\n");
+               log("that instantiates the design, toggles its clock, and interacts with its ports.\n");
+               log("\n");
+               log("The following driver may be used as an example for a design with a single clock\n");
+               log("driving rising edge triggered flip-flops:\n");
                log("\n");
                log("    #include \"top.cc\"\n");
                log("\n");
                log("    int main() {\n");
                log("      cxxrtl_design::p_top top;\n");
+               log("      top.step();\n");
                log("      while (1) {\n");
-               log("        top.p_clk.next = value<1> {1u};\n");
-               log("        top.step();\n");
+               log("        /* user logic */\n");
                log("        top.p_clk.next = value<1> {0u};\n");
                log("        top.step();\n");
+               log("        top.p_clk.next = value<1> {1u};\n");
+               log("        top.step();\n");
                log("      }\n");
                log("    }\n");
                log("\n");
+               log("Note that CXXRTL simulations, just like the hardware they are simulating, are\n");
+               log("subject to race conditions. If, in then example above, the user logic would run\n");
+               log("simultaneously with the rising edge of the clock, the design would malfunction.\n");
+               log("\n");
                log("The following options are supported by this backend:\n");
                log("\n");
                log("    -header\n");