Integrate PR 12649's race detector directly in the testsuite machinery

[platform/upstream/binutils.git] / gdb / testsuite / README

diff --git a/gdb/testsuite/README b/gdb/testsuite/README
index 466993d..9a5059a 100644 (file)
--- a/gdb/testsuite/README
+++ b/gdb/testsuite/README
@@ -176,6 +176,47 @@ Example:
 If not using GNU make then the value is passed directly to runtest.
 If not specified, all tests are run.
 
+READ1
+
+This make (not runtest) variable is used to specify whether the
+testsuite preloads the read1.so library into expect.  Any non-empty
+value means true.  See "Race detection" below.
+
+Race detection
+**************
+
+The testsuite includes a mechanism that helps detect test races.
+
+For example, say the program running under expect outputs "abcd", and
+a test does something like this:
+
+  expect {
+    "a.*c" {
+    }
+    "b" {
+    }
+    "a" {
+    }
+  }
+
+Which case happens to match depends on what expect manages to read
+into its internal buffer in one go.  If it manages to read three bytes
+or more, then the first case matches.  If it manages to read two
+bytes, then the second case matches.  If it manages to read only one
+byte, then the third case matches.
+
+To help detect these cases, the race detection mechanism preloads a
+library into expect that forces the `read' system call to always
+return at most 1 byte.
+
+To enable this, either pass a non-empty value in the READ1 make
+variable, or use the check-read1 make target instead of check.
+
+Examples:
+
+       make -j10 check-read1 TESTS="*/paginate-*.exp"
+       make -j10 check READ1="1"
+
 Testsuite Configuration
 ***********************