@@ -277,22 +277,15 @@ Try running `cargo miri clean`.
277277Miri adds its own set of `-Z` flags, which are usually set via the `MIRIFLAGS`
278278environment variable. We first document the most relevant and most commonly used flags :
279279
280- * `-Zmiri-address-reuse-rate=<rate>` changes the probability that a freed *non-stack* allocation
281- will be added to the pool for address reuse, and the probability that a new *non-stack* allocation
282- will be taken from the pool. Stack allocations never get added to or taken from the pool. The
283- default is `0.5`.
284- * `-Zmiri-address-reuse-cross-thread-rate=<rate>` changes the probability that an allocation which
285- attempts to reuse a previously freed block of memory will also consider blocks freed by *other
286- threads*. The default is `0.1`, which means by default, in 90% of the cases where an address reuse
287- attempt is made, only addresses from the same thread will be considered. Reusing an address from
288- another thread induces synchronization between those threads, which can mask data races and weak
289- memory bugs.
290- * `-Zmiri-compare-exchange-weak-failure-rate=<rate>` changes the failure rate of
291- ` compare_exchange_weak` operations. The default is `0.8` (so 4 out of 5 weak ops will fail).
292- You can change it to any value between `0.0` and `1.0`, where `1.0` means it
293- will always fail and `0.0` means it will never fail. Note that setting it to
294- ` 1.0` will likely cause hangs, since it means programs using
295- ` compare_exchange_weak` cannot make progress.
280+ * `-Zmiri-deterministic-concurrency` makes Miri's concurrency-related behavior fully deterministic.
281+ Strictly speaking, Miri is always fully deterministic when isolation is enabled (the default
282+ mode), but this determinism is achieved by using an RNG with a fixed seed. Seemingly harmless
283+ changes to the program, or just running it for a different target architecture, can thus lead to
284+ completely different program behavior down the line. This flag disables the use of an RNG for
285+ concurrency-related decisions. Therefore, Miri cannot find bugs that only occur under some
286+ specific circumstances, but Miri's behavior will also be more stable across versions and targets.
287+ This is equivalent to `-Zmiri-fixed-schedule -Zmiri-compare-exchange-weak-failure-rate=0.0
288+ -Zmiri-address-reuse-cross-thread-rate=0.0 -Zmiri-disable-weak-memory-emulation`.
296289* `-Zmiri-disable-isolation` disables host isolation. As a consequence,
297290 the program has access to host resources such as environment variables, file
298291 systems, and randomness.
@@ -334,9 +327,6 @@ environment variable. We first document the most relevant and most commonly used
334327 This will necessarily miss some bugs as those operations are not efficiently and accurately
335328 implementable in a sanitizer, but it will only miss bugs that concern memory/pointers which is
336329 subject to these operations.
337- * `-Zmiri-preemption-rate` configures the probability that at the end of a basic block, the active
338- thread will be preempted. The default is `0.01` (i.e., 1%). Setting this to `0` disables
339- preemption.
340330* `-Zmiri-report-progress` makes Miri print the current stacktrace every now and then, so you can
341331 tell what it is doing when a program just keeps running. You can customize how frequently the
342332 report is printed via `-Zmiri-report-progress=<blocks>`, which prints the report every N basic
@@ -365,6 +355,22 @@ The remaining flags are for advanced use only, and more likely to change or be r
365355Some of these are **unsound**, which means they can lead
366356to Miri failing to detect cases of undefined behavior in a program.
367357
358+ * `-Zmiri-address-reuse-rate=<rate>` changes the probability that a freed *non-stack* allocation
359+ will be added to the pool for address reuse, and the probability that a new *non-stack* allocation
360+ will be taken from the pool. Stack allocations never get added to or taken from the pool. The
361+ default is `0.5`.
362+ * `-Zmiri-address-reuse-cross-thread-rate=<rate>` changes the probability that an allocation which
363+ attempts to reuse a previously freed block of memory will also consider blocks freed by *other
364+ threads*. The default is `0.1`, which means by default, in 90% of the cases where an address reuse
365+ attempt is made, only addresses from the same thread will be considered. Reusing an address from
366+ another thread induces synchronization between those threads, which can mask data races and weak
367+ memory bugs.
368+ * `-Zmiri-compare-exchange-weak-failure-rate=<rate>` changes the failure rate of
369+ ` compare_exchange_weak` operations. The default is `0.8` (so 4 out of 5 weak ops will fail).
370+ You can change it to any value between `0.0` and `1.0`, where `1.0` means it
371+ will always fail and `0.0` means it will never fail. Note that setting it to
372+ ` 1.0` will likely cause hangs, since it means programs using
373+ ` compare_exchange_weak` cannot make progress.
368374* `-Zmiri-disable-alignment-check` disables checking pointer alignment, so you
369375 can focus on other failures, but it means Miri can miss bugs in your program.
370376 Using this flag is **unsound**.
@@ -383,6 +389,10 @@ to Miri failing to detect cases of undefined behavior in a program.
383389 this flag is **unsound**.
384390* `-Zmiri-disable-weak-memory-emulation` disables the emulation of some C++11 weak
385391 memory effects.
392+ * `-Zmiri-fixed-schedule` disables preemption (like `-Zmiri-preemption-rate=0.0`) and furthermore
393+ disables the randomization of the next thread to be picked, instead fixing a round-robin schedule.
394+ Note however that other aspects of Miri's concurrency behavior are still randomize; use
395+ ` -Zmiri-deterministic-concurrency` to disable them all.
386396* `-Zmiri-native-lib=<path to a shared object file>` is an experimental flag for providing support
387397 for calling native functions from inside the interpreter via FFI. The flag is supported only on
388398 Unix systems. Functions not provided by that file are still executed via the usual Miri shims.
@@ -412,6 +422,10 @@ to Miri failing to detect cases of undefined behavior in a program.
412422 without an explicit value), `none` means it never recurses, `scalar` means it only recurses for
413423 types where we would also emit `noalias` annotations in the generated LLVM IR (types passed as
414424 individual scalars or pairs of scalars). Setting this to `none` is **unsound**.
425+ * `-Zmiri-preemption-rate` configures the probability that at the end of a basic block, the active
426+ thread will be preempted. The default is `0.01` (i.e., 1%). Setting this to `0` disables
427+ preemption. Note that even without preemption, the schedule is still non-deterministic :
428+ if a thread blocks or yields, the next thread is chosen randomly.
415429* `-Zmiri-provenance-gc=<blocks>` configures how often the pointer provenance garbage collector runs.
416430 The default is to search for and remove unreachable provenance once every `10000` basic blocks. Setting
417431 this to `0` disables the garbage collector, which causes some programs to have explosive memory
@@ -443,9 +457,6 @@ to Miri failing to detect cases of undefined behavior in a program.
443457 casts are not supported in this mode, but that may change in the future.
444458* `-Zmiri-force-page-size=<num>` overrides the default page size for an architecture, in multiples of 1k.
445459 ` 4` is default for most targets. This value should always be a power of 2 and nonzero.
446- * `-Zmiri-unique-is-unique` performs additional aliasing checks for `core::ptr::Unique` to ensure
447- that it could theoretically be considered `noalias`. This flag is experimental and has
448- an effect only when used with `-Zmiri-tree-borrows`.
449460
450461[function ABI] : https://doc.rust-lang.org/reference/items/functions.html#extern-function-qualifier
451462
0 commit comments