clarify what is UB

src/what-unsafe-does.md

@@ -16,18 +16,41 @@ to your program. You definitely *should not* invoke Undefined Behavior.
 Unlike C, Undefined Behavior is pretty limited in scope in Rust. All the core
 language cares about is preventing the following things:
 
-* Dereferencing null, dangling, or unaligned pointers
-* Reading [uninitialized memory][]
+* Dereferencing (using the `*` operator on) dangling, or unaligned pointers, or
+  wide pointers with invalid metadata (see below)
 * Breaking the [pointer aliasing rules][]
-* Producing invalid primitive values:
-    * dangling/null references
-    * null `fn` pointers
+* Unwinding into another language
+* Causing a [data race][race]
+* Executing code compiled with target features that the current thread of execution does
+  not support (see [`target_feature`][])
+* Producing invalid primitive values (either alone or as a field of a compound
+  type such as `enum`/`struct`/array/tuple):
     * a `bool` that isn't 0 or 1
     * an undefined `enum` discriminant
+    * null `fn` pointers
     * a `char` outside the ranges [0x0, 0xD7FF] and [0xE000, 0x10FFFF]
-    * A non-utf8 `str`
-* Unwinding into another language
-* Causing a [data race][race]
+    * a `!` (all values are invalid for this type)
+    * dangling/unaligned references, references that do themselves point to
+      invalid values, or wide references (to a dynamically sized type) with
+      invalid metadata
+        * slice metadata is invalid if the slice has a total size larger than
+          `isize::MAX` bytes in memory
+        * `dyn Trait` metadata is invalid if it is not a pointer to a vtable for
+          `Trait` that matches the actual dynamic trait the reference points to
+    * a non-utf8 `str`
+    * an integer (`i*`/`u*`), floating point value (`f*`), or raw pointer read from
+      [uninitialized memory][]
+    * an invalid library type with custom invalid values, such as a `NonNull` or
+      the `NonZero` family of types, that is 0
+
+"Producing" a value happens any time a value is assigned, passed to a
+function/primitive operation or returned from a function/primitive operation.
+
+A reference/pointer is "dangling" if it is null or not all of the bytes it
+points to are part of the same allocation (so in particular they all have to be
+part of *some* allocation). The span of bytes it points to is determined by the
+pointer value and the size of the pointee type. As a consequence, if the span is
+empty, "dangling" is the same as "non-null".
 
 That's it. That's all the causes of Undefined Behavior baked into Rust. Of
 course, unsafe functions and traits are free to declare arbitrary other
@@ -58,3 +81,4 @@ these problems are considered impractical to categorically prevent.
 [pointer aliasing rules]: references.html
 [uninitialized memory]: uninitialized.html
 [race]: races.html
+[`target_feature`]: ../reference/attributes/codegen.html#the-target_feature-attribute