From 492a8f7b67da0f84ea60852566e83d3b02567709 Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Wed, 23 Sep 2026 08:16:51 -0400 Subject: [PATCH] Commentary --- AGENTS.md | 6 +++--- docs/guide/exe_verilator.rst | 4 ++-- docs/guide/simulating.rst | 2 +- docs/internals.rst | 13 ++----------- 4 files changed, 8 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6679847a6..a9dae0e89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,7 +72,7 @@ top-of-file comment. - Build in the source tree: `autoconf && ./configure && make -j8`. Configure with `--enable-ccwarn` so a new compiler warning stops the build. - Run one test from the repository root: `test_regress/t/t_.py`. -- Run the full regression with `make test`. The complete suite requires +- Run the full regression tests with `make test`. The complete suite requires configuring with `--enable-longtests` (works on every OS, including macOS). ______________________________________________________________________ @@ -93,8 +93,8 @@ ______________________________________________________________________ - [ ] Ran `make format` (clang-format), `make cppcheck`, and `make lint-py`; self-reviewed the diff for leftover debug code, stale comments, and copy-paste errors. -- [ ] Ran the full regression on at least one OS before submitting. Partial runs - are fine during development, but the submitted PR is expected to pass every +- [ ] Ran the full regression tests on at least one OS before submitting. Partial + runs are fine during development, but the submitted PR is expected to pass every test. - [ ] Validated the code changes against recommendations in the AGENTS.md files. - [ ] Did not edit `docs/CONTRIBUTORS` (humans only) or `Changes` (maintainer diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index a8f819c17..fd5867354 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -2272,7 +2272,7 @@ Summary: If using `--x-assign unique`, use the :vlopt:`+verilator+rand+reset+2 <+verilator+rand+reset+\>` runtime option, and seed the runtime random number generator such that - each regression run gets a different randomization sequence with + each regression test run gets a different randomization sequence with :vlopt:`+verilator+seed+\`. You'll probably also want to print any seeds selected, and code to enable rerunning with that same seed, so you can reproduce bugs. @@ -2301,7 +2301,7 @@ Summary: If using `--x-initial unique`, use the :vlopt:`+verilator+rand+reset+2 <+verilator+rand+reset+\>` runtime option, and seed the runtime random number generator such that - each regression run gets a different randomization sequence with + each regression test run gets a different randomization sequence with :vlopt:`+verilator+seed+\`. You'll probably also want to print any seeds selected, and code to enable rerunning with that same seed, so you can reproduce bugs. diff --git a/docs/guide/simulating.rst b/docs/guide/simulating.rst index 94da900fb..c6d1975bb 100644 --- a/docs/guide/simulating.rst +++ b/docs/guide/simulating.rst @@ -153,7 +153,7 @@ experience depends on the use case, and some experimentation can pay dividends. For a speedy debug cycle during development, especially on large designs where C++ compilation speed can dominate, consider using lower optimization to get to an executable faster. For throughput-oriented use -cases, for example, regressions, it is usually worth spending extra +cases, for example, regression testing, it is usually worth spending extra compilation time to reduce total CPU time. If you will be running many simulations on a single model, you can diff --git a/docs/internals.rst b/docs/internals.rst index 9267abae5..4c9fea037 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -1031,15 +1031,6 @@ Profile-guided optimization make this a bit better, by adjusting mtask scheduling, but this does not yet guide the packing into mtasks. -Performance Regression -++++++++++++++++++++++ - -It would be nice if we had a regression of large designs, with some -diversity of design styles, to test on both single- and multithreaded -modes. This would help to avoid performance regressions, and also to -evaluate the optimizations while minimizing the impact of parasitic noise. - - Per-Instance Classes ++++++++++++++++++++ @@ -1645,7 +1636,7 @@ There are some traps to avoid when running regression tests Hat/Fedora/Centos offer *perl-Pod-Perldoc*', while Debian/Ubuntu/Linux Mint offer \`perl-doc'. -- Running regression may exhaust resources on some Linux systems, +- Running regression tests may exhaust resources on some Linux systems, particularly file handles and user processes. Increase these to respectively 16,384 and 4,096. The method of doing this is system-dependent, but on Fedora Linux it would require editing the @@ -2422,7 +2413,7 @@ driver.py Non-Scenario Arguments .. option:: --quiet Suppress all output except for failures and progress messages every 15 - seconds. Intended for use only in automated regressions. See also + seconds. Intended for use only in automated regression testing. See also ``--rerun``, and ``--verbose`` which is not the opposite of ``--quiet``. .. option:: --rerun