add a reference TOC and fill it in a bit

Author: nikomatsakis

README.md

@@ -1,2 +1,31 @@
 # unsafe-code-guidelines
-Home for the Unsafe Code Guidelines effort.
+
+Home for the Unsafe Code Guidelines effort. The goal of the Unsafe
+Code Guidelines effort is to collaboratively produce a "reference
+guide" to write unsafe code. This guide should ultimately be a formal
+specification of what kinds of things unsafe code can and cannot do.
+However, we are not there yet.
+
+## The reference
+
+The primary document in this repo is the "Unsafe Code Guidelines
+Reference".  It is largely a work-in-progress right now. It serves as
+a kind of table of contents to the sorts of questions that are on our
+radar, as well as place to collect notes and summaries about those
+questions.
+
+Since we are not yet at the point where we can provide complete,
+definitive answers, the current goal for each section is to describe
+the "contours of the space". For example, we would try to specify what
+kinds of invariants **must** hold, as well as things that we expect to
+**never** be true. For other cases where there is disagreement, we
+will try to summarize the various options on the table -- you would do
+well in your unsafe code to steer clear of relying on those details.
+
+## How to participate
+
+The Unsafe Code Guidelines WG is in the process of being rebooted.  We
+expect to be holding regular meetings focused on particular topics.
+Stay tuned for more announcements. -- @nikomatsakis
+
+

reference/.gitignore

@@ -0,0 +1 @@
+book

reference/book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = ["Niko Matsakis"]
+multilingual = false
+src = "src"
+title = "Unsafe Code Guidelines Reference"

reference/src/SUMMARY.md

@@ -0,0 +1,17 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Areas of active discussion](./active_discussion.md)
+  - [Aliasing and memory model](./active_discussion/aliasing.md)
+  - [Cryptographic concerns](./active_discussion/crypto_concerns.md)
+    - [Keeping secrets](./active_discussion/crypto_concerns/keeping_secrets.md)
+    - [Constant time code](./active_discussion/crypto_concerns/constant_time_code.md)
+    - [Zeroing](./active_discussion/crypto_concerns/zeroing.md)
+  - [Data structure representation](./active_discussion/representation.md)
+  - [Stable addresses](./active_discussion/stable_addresses.md)
+  - [Storage liveness](./active_discussion/storage_liveness.md)
+  - [Uninhabited types like `!` and exhaustiveness](./active_discussion/uninhabited_types.md)
+  - [Unions](./active_discussion/unions.md)
+  - [Uninitialized memory](./active_discussion/uninitialized_memory.md)
+- [Optimizations](./optimizations.md)
+  - [Optimizing immutable memory](./optimizations/immutable_memory.md) 

reference/src/active_discussion.md

@@ -0,0 +1 @@
+# Areas of active discussion

reference/src/active_discussion/aliasing.md

@@ -0,0 +1,18 @@
+# Aliasing and memory model
+
+## Brief Summary
+
+Rust's borrow checker enforces some particular aliasing
+requirements. For example, an `&u32` reference is always guaranteed to
+be valid (dereferenceable) and immutable while it is in active
+use. Similarly, an `&mut` reference cannot alias any other active
+reference. It is less clear how those invariants translate to unsafe
+code that is using raw pointers.
+
+## See also
+
+- ACA model https://github.com/nikomatsakis/rust-memory-model/issues/26
+- Capability-based model https://github.com/nikomatsakis/rust-memory-model/issues/28
+- A formal C memory model supporting integer-pointer casts https://github.com/nikomatsakis/rust-memory-model/issues/30
+- Promising semantics for relaxed-memory concurrency https://github.com/nikomatsakis/rust-memory-model/issues/32
+- Tootsie Pop model https://github.com/nikomatsakis/rust-memory-model/issues/21

reference/src/active_discussion/crypto_concerns.md

@@ -0,0 +1,4 @@
+# Cryptographic concerns
+
+There are a number of concerns that arise when writing cryptographic
+code. This chapter summarizes some of them.

reference/src/active_discussion/crypto_concerns/constant_time_code.md

@@ -0,0 +1,5 @@
+# Constant time code
+
+It is often important to be able to turn off optimizations and
+guarantee that code executes in constant time to prevent side-channel
+attacks based on timing.

reference/src/active_discussion/crypto_concerns/keeping_secrets.md

@@ -0,0 +1,11 @@
+# Keeping secrets
+
+When storing cryptographic keys, crypto code wants to be sure that the
+compiler will not insert loads or stores that were not present in the
+source. Moreover, it wants to be able to zero memory and know that no
+bits from that memory "escape" into registers etc.
+
+## See also
+
+- https://internals.rust-lang.org/t/volatile-and-sensitive-memory/3188
+- https://github.com/nikomatsakis/rust-memory-model/issues/16

reference/src/active_discussion/representation.md

@@ -0,0 +1,13 @@
+# Data structure representation
+
+In general, Rust makes few guarantees about memory layout, unless you
+define your structs as `#[repr(rust)]`. But there are some things that
+we do guarantee. Let's write about them.
+
+TODO:
+
+- Find and link to the various RFCs
+- Enumerate things that we *might* in fact guarantee, even for non-C types:
+  - e.g., `&T` and `Option<&T>` are both pointer sized
+  - size of `extern fn` etc (at least on some platforms)?
+

reference/src/active_discussion/stable_addresses.md

@@ -0,0 +1,25 @@
+# Stable addresses
+
+Clearly, if you have a `&T` reference, the actual pointer address of
+that memory must remain valid while **that reference** is in active
+use. But how stable are the memory addresses of local variables in
+between borrows? Consider:
+
+```rust
+let x = 22;
+foo(&x);
+foo(&x);
+
+fn foo(y: &usize) { .. }
+```
+
+Is `foo` guaranteed to be given the same pointer each time? Note that
+safe code can observe the pointer value by doing `y as *const usize as
+usize`. If, however, the answer is no, that is helpful to the compiler
+since it can spill `x` only while it is borrowed but otherwise simply
+store `x` in a register.
+
+**Range of possible answers:**
+
+- local variables have stable addresses (de facto true today)
+- local variables have stable addresses while borrowed, but may change betwen borrows (would be nice)

reference/src/active_discussion/storage_liveness.md

@@ -0,0 +1,13 @@
+# Storage liveness
+
+If you move out from a variable, can you still use the underlying stack space?
+
+```rust
+{
+  let mut x: Vec<u32> = ....;
+  let p: *mut Vec<u32> = &mut x;
+  drop(x); // compiler can see `x` is uninitialized
+        
+  // what happens if you use `p` here?
+} // StorageDead(x)
+```

reference/src/active_discussion/uninhabited_types.md

@@ -0,0 +1,3 @@
+# Uninhabited types like `!` and exhaustiveness
+
+TBD

reference/src/active_discussion/uninitialized_memory.md

@@ -0,0 +1,3 @@
+# Uninitialized memory
+
+TBD

reference/src/active_discussion/unions.md

@@ -0,0 +1,3 @@
+# Unions
+
+TBD

reference/src/chapter_1.md

@@ -0,0 +1 @@
+# Chapter 1

reference/src/introduction.md

@@ -0,0 +1 @@
+# Introduction

reference/src/optimizations.md

@@ -0,0 +1 @@
+# Optimizations

reference/src/optimizations/immutable_memory.md

@@ -0,0 +1 @@
+# Optimizing immutable memory