Add some documentation for const eval and related topics

Author: oli-obk

src/SUMMARY.md

@@ -19,5 +19,6 @@
     - [MIR construction](./mir-construction.md)
     - [MIR borrowck](./mir-borrowck.md)
     - [MIR optimizations](./mir-optimizations.md)
+- [Constant evaluation](./const-eval.md)
 - [Generating LLVM IR](./trans.md)
 - [Glossary](./glossary.md)

src/const-eval.md

@@ -0,0 +1,32 @@
+# Constant Evaluation
+
+Constant evaluation is the process of computing values at compile time.
+Prominent examples are
+
+* Array length
+    * needs to be known to reserve stack or heap space
+* Enum variant discriminants
+    * needs to be known to prevent two variants from having the same discriminant
+* Patterns
+    * need to be known to check for overlapping patterns
+
+Additionally constant evaluation can be used to reduce the workload or binary
+size at runtime by precomputing complex operations at compiletime and only
+storing the result.
+
+Constant evaluation can be done by calling the `const_eval` query of `TyCtxt`.
+
+The `const_eval` query takes a [`ParamEnv`](./param_env.md) of environment in
+which the constant is evaluated (e.g. the function within which the constant is
+used) and a `GlobalId`. The `GlobalId` is made up of an
+`Instance` referring to a constant or static or of an
+`Instance` of a function and an index into the function's `Promoted` table.
+
+Constant evaluation returns a `Result` with either the error, or the simplest
+representation of the constant. "simplest" meaning if it is representable as an
+integer or fat pointer, it will directly yield the value (via `Value::ByVal` or
+`Value::ByValPair`), instead of referring to the [`miri`](./miri.md) virtual
+memory allocation (via `Value::ByRef`). This means that the `const_eval`
+function cannot be used to create miri-pointers to the evaluated constant or
+static. If you need that, you need to directly work with the functions in
+`src/librustc_mir/interpret/const_eval.rs`.

src/glossary.md

@@ -17,6 +17,7 @@ ICE                     |  internal compiler error. When the compiler crashes.
 ICH                     |  incremental compilation hash. ICHs are used as fingerprints for things such as HIR and crate metadata, to check if changes have been made. This is useful in incremental compilation to see if part of a crate has changed and should be recompiled.
 infcx                   |  the inference context (see `librustc/infer`)
 MIR                     |  the Mid-level IR that is created after type-checking for use by borrowck and trans ([see more](./mir.html))
+miri                    |  an interpreter for MIR used for constant evaluation ([see more](./miri.html))
 obligation              |  something that must be proven by the trait system ([see more](trait-resolution.html))
 local crate             |  the crate currently being compiled.
 node-id or NodeId       |  an index identifying a particular node in the AST or HIR; gradually being phased out and replaced with `HirId`.

src/miri.md

@@ -0,0 +1,47 @@
+# Miri
+
+Miri (**MIR** **I**nterpreter) is a virtual machine for executing MIR without
+compiling to machine code. It is usually invoked via `tcx.const_eval`.
+
+Its core datastructures can be found in `src/librustc/mir/interpret`. This is
+mainly the error enum and the `Value` and `PrimVal` types. A `Value` can be
+either `ByVal` (a single `PrimVal`), `ByValPair` (two `PrimVal`s, usually fat
+pointers or two element tuples) or `ByRef`, which is used for anything else and
+refers to a virtual allocation. These allocations can be accessed via the
+methods on `tcx.interpret_interner`.
+
+If you are expecting a numeric result, you can use `unwrap_u64` (panics on
+anything that can't be representad as a `u64`) or `to_raw_bits` which results
+in an `Option<u128>` yielding the `ByVal` if possible.
+
+## Miri allocations
+
+A miri allocation is either a byte sequence of the memory or an `Instance` in
+the case of function pointers. Byte sequences can additionally contain
+relocations that mark a group of bytes as a pointer to another allocation. The
+actual bytes at the relocation refer to the offset inside the other allocation.
+
+## Miri interpretation
+
+Although the main entry point to constant evaluation is the `tcx.const_eval`
+query, there are additional functions in `src/librustc_mir/interpret/const_eval`
+that allow accessing the fields of a `Value` (`ByRef` or otherwise). You should
+never have to access an `Allocation` directly except for translating it to the
+compilation target (atm just LLVM).
+
+### Details
+
+Miri starts by allocating a virtual stack frame for the current constant that
+is being evaluated. There's essentially no difference between a constant and a
+function with no arguments, except that constants do not allow local (named)
+variables at the time of writing this guide.
+
+A stack frame is defined by the `Frame` type in
+`src/librustc_mir/interpret/eval_context.rs` and contains all the local
+variables memory (`None` at the start of evaluation).
+
+Miri now calls the `step` method (in `src/librustc_mir/interpret/step.rs`) until
+it either returns an error or has no further statements to execute. Each
+statement will now initialize or modify the locals or the virtual memory
+referred to by a local. This might require evaluating other constants or
+statics, which just recursively invokes `tcx.const_eval`.

src/param_env.md

@@ -0,0 +1,17 @@
+# Parameter Environment
+
+When working with associated constants or generic types it is often relevant to
+have more information about the `Self` or generic parameters. Trait bounds and
+similar information is encoded in the `ParamEnv`. Often this is not enough
+information to obtain things like the type's `Layout`, but you can do all kinds
+of other checks on it (e.g. whether a type implements `Copy`) or you can
+evaluate an associated constant whose value does not depend on anything from the
+parameter environment.
+
+Although you can obtain a valid `ParamEnv` for any item via
+`tcx.param_env(def_id)`, this `ParamEnv` can be too generic for your use case.
+Using the `ParamEnv` from the surrounding context can allow you to evaluate more
+things.
+
+Another great thing about `ParamEnv` is that you can use it to eliminate the
+generic parameters from a `Ty` by calling `param_env.and(ty)`.

src/trait-resolution.md

@@ -433,7 +433,7 @@ before, and hence the cache lookup would succeed, yielding
 One subtle interaction is that the results of trait lookup will vary
 depending on what where clauses are in scope. Therefore, we actually
 have *two* caches, a local and a global cache. The local cache is
-attached to the `ParamEnv` and the global cache attached to the
+attached to the [`ParamEnv`](./param_env.md) and the global cache attached to the
 `tcx`. We use the local cache whenever the result might depend on the
 where clauses that are in scope. The determination of which cache to
 use is done by the method `pick_candidate_cache` in `select.rs`. At