Merge pull request YosysHQ#5687 from YosysHQ/nella/pdr-doc

Update help text for rename -witness and write_aiger -ywmap

Author: KrystalDelusion

backends/aiger/aiger.cc

@@ -930,7 +930,9 @@ struct AigerBackend : public Backend {
 		log("        make indexes zero based, enable using map files with smt solvers.\n");
 		log("\n");
 		log("    -ywmap <filename>\n");
-		log("        write a map file for conversion to and from yosys witness traces.\n");
+		log("        write a map file for conversion to and from yosys witness traces,\n");
+		log("        also allows for mapping AIGER bad-state properties and invariant\n");
+		log("        constraints back to individual formal properties by name.\n");
 		log("\n");
 		log("    -I, -O, -B, -L\n");
 		log("        If the design contains no input/output/assert/flip-flop then create one\n");

docs/source/using_yosys/more_scripting/model_checking.rst

@@ -3,9 +3,9 @@ Symbolic model checking
 
 .. todo:: check text context
 
-.. note:: 
-    
-    While it is possible to perform model checking directly in Yosys, it 
+.. note::
+
+    While it is possible to perform model checking directly in Yosys, it
     is highly recommended to use SBY or EQY for formal hardware verification.
 
 Symbolic Model Checking (SMC) is used to formally prove that a circuit has (or
@@ -117,3 +117,32 @@ Result with fixed :file:`axis_master.v`:
 
     Solving problem with 159144 variables and 441626 clauses..
     SAT proof finished - no model found: SUCCESS!
+
+Witness framework and per-property tracking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When using AIGER-based formal verification flows (such as the ``abc`` engine in
+SBY), Yosys provides infrastructure for tracking individual formal
+properties through the verification pipeline.
+
+The `rename -witness` pass assigns public names to all cells that participate in
+the witness framework:
+
+- Witness signal cells: `$anyconst`, `$anyseq`, `$anyinit`,
+  `$allconst`, `$allseq`
+- Formal property cells: `$assert`, `$assume`, `$cover`, `$live`,
+  `$fair`, `$check`
+
+These public names allow downstream tools to refer to individual properties by
+their hierarchical path rather than by anonymous internal identifiers.
+
+The `write_aiger -ywmap` option generates a map file for conversion to and from
+Yosys witness traces, and also allows for mapping AIGER bad-state properties and
+invariant constraints back to individual formal properties by name. This enables
+features like per-property pass/fail reporting (e.g. ``abc pdr`` with
+``--keep-going`` mode).
+
+The `write_smt2` backend similarly uses the public witness names when emitting
+SMT2 comments. Cells whose ``hdlname`` attribute contains the ``_witness_``
+marker are treated as having private names for comment purposes, keeping solver
+output clean.

passes/cmds/rename.cc

@@ -254,18 +254,17 @@ struct RenamePass : public Pass {
 		log("\n");
 		log("    rename -enumerate [-pattern <pattern>] [selection]\n");
 		log("\n");
-		log("Assign short auto-generated names to all selected wires and cells with private\n");
-		log("names. The -pattern option can be used to set the pattern for the new names.\n");
-		log("The character %% in the pattern is replaced with a integer number. The default\n");
-		log("pattern is '_%%_'.\n");
+		log("Assigns auto-generated names to objects used in formal verification\n");
+		log("that do not have a public name. This applies to all formal property\n");
+		log("cells, $any*/$all* output wires, and their containing cells.\n");
 		log("\n");
 		log("\n");
 		log("    rename -witness\n");
 		log("\n");
-		log("Assigns auto-generated names to all $any*/$all* output wires and containing\n");
-		log("cells that do not have a public name. This ensures that, during formal\n");
-		log("verification, a solver-found trace can be fully specified using a public\n");
-		log("hierarchical names.\n");
+		log("Assigns auto-generated names to objects used in formal verification\n");
+		log("that do not have a public name. This applies to all formal property\n");
+		log("cells ($assert, $assume, $cover, $live, $fair, $check), $any*/$all*\n");
+		log("output wires, and their containing cells.\n");
 		log("\n");
 		log("\n");
 		log("    rename -hide [selection]\n");