Auto merge of #1699 - m-ou-se:panic-format, r=RalfJung

[rust.git] / README.md

diff --git a/README.md b/README.md
index 578ca0251c5e4c15d9b34df4453444159a9c398e..ae70c80d5f0a1e3b5d72757c6447043760b61c04 100644 (file)
--- a/README.md
+++ b/README.md
@@ -20,11 +20,18 @@ for example:
   or an invalid enum discriminant)
 * **Experimental**: Violations of the [Stacked Borrows] rules governing aliasing
   for reference types
+* **Experimental**: Data races (but no weak memory effects)
 
 On top of that, Miri will also tell you about memory leaks: when there is memory
 still allocated at the end of the execution, and that memory is not reachable
 from a global `static`, Miri will raise an error.
 
+You can use Miri to emulate programs on other targets, e.g. to ensure that
+byte-level data manipulation works correctly both on little-endian and
+big-endian systems. See
+[cross-interpretation](#cross-interpretation-running-for-different-targets)
+below.
+
 Miri has already discovered some [real-world bugs](#bugs-found-by-miri).  If you
 found a bug with Miri, we'd appreciate if you tell us and we'll add it to the
 list!
@@ -43,16 +50,15 @@ in your program, and cannot run all programs:
   still run fine in Miri -- but might break (including causing UB) on different
   compiler versions or different platforms.
 * Program execution is non-deterministic when it depends, for example, on where
-  exactly in memory allocations end up. Miri tests one of many possible
-  executions of your program. If your code is sensitive to allocation base
-  addresses or other non-deterministic data, try running Miri with different
-  values for `-Zmiri-seed` to test different executions.
+  exactly in memory allocations end up, or on the exact interleaving of
+  concurrent threads. Miri tests one of many possible executions of your
+  program. You can alleviate this to some extent by running Miri with different
+  values for `-Zmiri-seed`, but that will still by far not explore all possible
+  executions.
 * Miri runs the program as a platform-independent interpreter, so the program
   has no access to most platform-specific APIs or FFI. A few APIs have been
   implemented (such as printing to stdout) but most have not: for example, Miri
   currently does not support SIMD or networking.
-* Miri currently does not check for data-races and most other concurrency-related
-  issues.
 
 [rust]: https://www.rust-lang.org/
 [mir]: https://github.com/rust-lang/rfcs/blob/master/text/1211-mir.md
@@ -189,9 +195,15 @@ up the sysroot.  If you are using `miri` (the Miri driver) directly, see the
 Miri adds its own set of `-Z` flags, which are usually set via the `MIRIFLAGS`
 environment variable:
 
+* `-Zmiri-compare-exchange-weak-failure-rate=<rate>` changes the failure rate of
+  `compare_exchange_weak` operations. The default is `0.8` (so 4 out of 5 weak ops will fail).
+  You can change it to any value between `0.0` and `1.0`, where `1.0` means it
+  will always fail and `0.0` means it will never fail.
 * `-Zmiri-disable-alignment-check` disables checking pointer alignment, so you
   can focus on other failures, but it means Miri can miss bugs in your program.
   Using this flag is **unsound**.
+* `-Zmiri-disable-data-race-detector` disables checking for data races.  Using
+  this flag is **unsound**.
 * `-Zmiri-disable-stacked-borrows` disables checking the experimental
   [Stacked Borrows] aliasing rules.  This can make Miri run faster, but it also
   means no aliasing violations will be detected.  Using this flag is **unsound**
@@ -242,8 +254,7 @@ environment variable:
   help identify latent aliasing issues in code that Miri accepts by default. You
   can recognize false positives by "<untagged>" occurring in the message -- this
   indicates a pointer that was cast from an integer, so Miri was unable to track
-  this pointer. Make sure to use a non-Windows target with this flag, as the
-  Windows runtime makes use of integer-pointer casts.
+  this pointer.
 
 Some native rustc `-Z` flags are also very relevant for Miri:
 
@@ -281,6 +292,8 @@ different Miri binaries, and as such worth documenting:
   directory after loading all the source files, but before commencing
   interpretation. This is useful if the interpreted program wants a different
   working directory at run-time than at build-time.
+* `MIRI_VERBOSE` when set to any value tells the various `cargo-miri` phases to
+  perform verbose logging.
   
 [testing-miri]: CONTRIBUTING.md#testing-the-miri-driver
 
@@ -345,9 +358,9 @@ If you want to contribute to Miri, great!  Please check out our
 [contribution guide](CONTRIBUTING.md).
 
 For help with running Miri, you can open an issue here on
-GitHub or contact us (`oli-obk` and `RalfJ`) on the [Rust Zulip].
+GitHub or use the [Miri stream on the Rust Zulip][zulip].
 
-[Rust Zulip]: https://rust-lang.zulipchat.com
+[zulip]: https://rust-lang.zulipchat.com/#narrow/stream/269128-miri
 
 ## History