Copy section to docs on runtime services.

doc/rust.md

@@ -3100,6 +3100,94 @@ let s = recv(p);
 
 # Runtime services, linkage and debugging
 
+
+The Rust _runtime_ is a relatively compact collection of C and Rust code
+that provides fundamental services and datatypes to all Rust tasks at
+run-time. It is smaller and simpler than many modern language runtimes. It is
+tightly integrated into the language's execution model of memory, tasks,
+communication and logging.
+
+
+### Memory allocation
+
+The runtime memory-management system is based on a _service-provider
+interface_, through which the runtime requests blocks of memory from its
+environment and releases them back to its environment when they are no longer
+in use. The default implementation of the service-provider interface consists
+of the C runtime functions `malloc` and `free`.
+
+The runtime memory-management system in turn supplies Rust tasks with
+facilities for allocating, extending and releasing stacks, as well as
+allocating and freeing boxed values.
+
+
+### Built in types
+
+The runtime provides C and Rust code to assist with various built-in types,
+such as vectors, strings, and the low level communication system (ports,
+channels, tasks).
+
+Support for other built-in types such as simple types, tuples, records, and
+tags is open-coded by the Rust compiler.
+
+
+
+### Task scheduling and communication
+
+The runtime provides code to manage inter-task communication.  This includes
+the system of task-lifecycle state transitions depending on the contents of
+queues, as well as code to copy values between queues and their recipients and
+to serialize values for transmission over operating-system inter-process
+communication facilities.
+
+
+### Logging system
+
+The runtime contains a system for directing [logging
+expressions](#log-expressions) to a logging console and/or internal logging
+buffers. Logging expressions can be enabled per module.
+
+Logging output is enabled by setting the `RUST_LOG` environment variable.
+`RUST_LOG` accepts a logging specification that is a comma-separated list of
+paths. For each module containing log expressions, if `RUST_LOG` contains the
+path to that module or a parent of that module, then its logs will be output
+to the console. The path to an module consists of the crate name, any parent
+modules, then the module itself, all separated by double colons (`::`).
+
+As an example, to see all the logs generated by the compiler, you would set
+`RUST_LOG` to `rustc`, which is the crate name (as specified in its `link`
+[attribute](#attributes)). To narrow down the logs to just crate resolution,
+you would set it to `rustc::metadata::creader`.
+
+Note that when compiling either `.rs` or `.rc` files that don't specifiy a
+crate name the crate is given a default name that matches the source file,
+with the extension removed. In that case, to turn on logging for a program
+compiled from, e.g. `helloworld.rs`, `RUST_LOG` should be set to `helloworld`.
+
+As a convenience, the logging spec can also be set to a special psuedo-crate,
+`::help`. In this case, when the application starts, the runtime will
+simply output a list of loaded modules containing log expressions, then exit.
+
+The Rust runtime itself generates logging information. The runtime's logs are
+generated for a number of artificial modules in the `::rt` psuedo-crate,
+and can be enabled just like the logs for any standard module. The full list
+of runtime logging modules follows.
+
+* `::rt::mem` Memory management
+* `::rt::comm` Messaging and task communication
+* `::rt::task` Task management
+* `::rt::dom` Task scheduling
+* `::rt::trace` Unused
+* `::rt::cache` Type descriptor cache
+* `::rt::upcall` Compiler-generated runtime calls
+* `::rt::timer` The scheduler timer
+* `::rt::gc` Garbage collection
+* `::rt::stdlib` Functions used directly by the standard library
+* `::rt::kern` The runtime kernel
+* `::rt::backtrace` Unused
+* `::rt::callback` Unused
+
+
 # Appendix: Rationales and design tradeoffs
 
 *TODO*.