README.md: reporting multiple data races for the same access?

[model-checker.git] / README.md

diff --git a/README.md b/README.md
index a2458f43b755098a4644e1a8eda67ece24d1feb4..fa54aca1b964ba5e030c8a089793bdddc8e01029 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-CDSChecker Readme
-=================
+CDSChecker: A Model Checker for C11 and C++11 Atomics
+=====================================================
 
 Copyright © 2013 Regents of the University of California. All rights reserved.
 
@@ -37,7 +37,8 @@ Getting Started
 ---------------
 
 If you haven't done so already, you may download CDSChecker using
-[git](http://git-scm.com/):
+[git](http://git-scm.com/) (for those without git, snapshots can be found at the
+Gitweb URLs below):
 
       git clone git://demsky.eecs.uci.edu/model-checker.git
 
@@ -120,8 +121,15 @@ the benchmarks as follows:
 
 >     make benchmarks
 >     cd benchmarks
->     ./run.sh barrier/barrier -y -m 2     # runs barrier test with fairness/memory liveness
->     ./bench.sh                           # run all benchmarks and provide timing results
+>
+>     # run barrier test with fairness/memory liveness
+>     ./run.sh barrier/barrier -y -m 2
+>
+>     # Linux reader/write lock test with fairness/memory liveness
+>     ./run.sh linuxrwlocks/linuxrwlocks -y -m 2
+>
+>     # run all benchmarks and provide timing results
+>     ./bench.sh
 
 
 Running your own code
@@ -249,8 +257,8 @@ vector consists of the following values:
         CV[0] = 0, CV[1] = 7, CV[2] = 0, CV[3] = 10
 
 
-Other Notes
------------
+Other Notes and Pitfalls
+------------------------
 
 * Deadlock detection: CDSChecker can detect deadlocks. For instance, try the
   following test program.
@@ -270,6 +278,31 @@ Other Notes
   division by 0, for instance). In such programs, you might consider running
   CDSChecker with the `-u num` option.
 
+* Related to the previous point, CDSChecker may report more than one bug for a
+  particular candidate execution. This is because some bugs may not be
+  reportable until CDSChecker has explored more of the program, and in the
+  time between initial discovery and final assessment of the bug, CDSChecker may
+  discover another bug.
+
+* Data races may be reported as multiple bugs, one for each byte-address of the
+  data race in question. See, for example, this run:
+
+        $ ./run.sh test/releaseseq.o
+        ...
+        Bug report: 4 bugs detected
+          [BUG] Data race detected @ address 0x601078:
+            Access 1: write in thread  2 @ clock   4
+            Access 2:  read in thread  3 @ clock   9
+          [BUG] Data race detected @ address 0x601079:
+            Access 1: write in thread  2 @ clock   4
+            Access 2:  read in thread  3 @ clock   9
+          [BUG] Data race detected @ address 0x60107a:
+            Access 1: write in thread  2 @ clock   4
+            Access 2:  read in thread  3 @ clock   9
+          [BUG] Data race detected @ address 0x60107b:
+            Access 1: write in thread  2 @ clock   4
+            Access 2:  read in thread  3 @ clock   9
+
 
 See Also
 --------