@@ -277,22 +277,15 @@ Try running `cargo miri clean`.
277
277
Miri adds its own set of `-Z` flags, which are usually set via the `MIRIFLAGS`
278
278
environment variable. We first document the most relevant and most commonly used flags :
279
279
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`.
296
289
* `-Zmiri-disable-isolation` disables host isolation. As a consequence,
297
290
the program has access to host resources such as environment variables, file
298
291
systems, and randomness.
@@ -334,9 +327,6 @@ environment variable. We first document the most relevant and most commonly used
334
327
This will necessarily miss some bugs as those operations are not efficiently and accurately
335
328
implementable in a sanitizer, but it will only miss bugs that concern memory/pointers which is
336
329
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.
340
330
* `-Zmiri-report-progress` makes Miri print the current stacktrace every now and then, so you can
341
331
tell what it is doing when a program just keeps running. You can customize how frequently the
342
332
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
365
355
Some of these are **unsound**, which means they can lead
366
356
to Miri failing to detect cases of undefined behavior in a program.
367
357
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.
368
374
* `-Zmiri-disable-alignment-check` disables checking pointer alignment, so you
369
375
can focus on other failures, but it means Miri can miss bugs in your program.
370
376
Using this flag is **unsound**.
@@ -383,6 +389,10 @@ to Miri failing to detect cases of undefined behavior in a program.
383
389
this flag is **unsound**.
384
390
* `-Zmiri-disable-weak-memory-emulation` disables the emulation of some C++11 weak
385
391
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.
386
396
* `-Zmiri-native-lib=<path to a shared object file>` is an experimental flag for providing support
387
397
for calling native functions from inside the interpreter via FFI. The flag is supported only on
388
398
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.
412
422
without an explicit value), `none` means it never recurses, `scalar` means it only recurses for
413
423
types where we would also emit `noalias` annotations in the generated LLVM IR (types passed as
414
424
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.
415
429
* `-Zmiri-provenance-gc=<blocks>` configures how often the pointer provenance garbage collector runs.
416
430
The default is to search for and remove unreachable provenance once every `10000` basic blocks. Setting
417
431
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.
443
457
casts are not supported in this mode, but that may change in the future.
444
458
* `-Zmiri-force-page-size=<num>` overrides the default page size for an architecture, in multiples of 1k.
445
459
` 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`.
449
460
450
461
[function ABI] : https://doc.rust-lang.org/reference/items/functions.html#extern-function-qualifier
451
462
0 commit comments