Add an Overview doc. Overview gives a high-level view of the crates in the Tock 2.0 libtock-rs. Not all of these crates have been merged into this repository yet, but all of them are a work in progress.
diff --git a/doc/Overview.md b/doc/Overview.md new file mode 100644 index 0000000..0c6952b --- /dev/null +++ b/doc/Overview.md
@@ -0,0 +1,81 @@ +Overview +====== + +Note: This describes the layout of the Tock 2.0 `libtock-rs` crates, not the +Tock 1.0 crates. Not all of the Tock 2.0 crates have been merged into this +repository yet. + +This document gives an overview of the crates in this repository, and is +intended to be useful to `libtock-rs` newcomers. + +## `libtock` + +Note: `libtock` is currently called `libtock2`, as `libtock` is already a Tock +1.0 crate. + +`libtock` provides the default `libtock-rs` experience. It re-exports all of the +drivers `libtock-rs` provides, and provides usable defaults for panic handling +and memory allocation. It should be easy to build a Tock application that only +has one direct dependency: `libtock`. + +In order to be easy to use, `libtock` lacks some functionality that the other +`libtock-rs` crates provide. In particular, you should depend on the other +crates directly if you want any of the following: + +* The ability to unit test your code. +* The ability to customize panic handling. +* The ability to run without dynamic memory allocation or with an alternative + memory allocator. + +## Naming convention note + +Although these crates have yet to be uploaded to crates.io, they likely will be +uploaded in the future. Therefore, to avoid name collisions, most crates in this +repository have a name that begins with `libtock`. Crates that are only intended +for internal use (e.g. `syscall_tests`, which tests code internal to +`libtock_platform`) do not have the `libtock_` prefix. + +The directory names of `libtock_` crates do not contain the `libtock_` prefix. + +## Core abstractions: `libtock_platform` + +In order to unit test `libtock-rs` code, we need a way to run `libtock-rs` on +our development machines (and in CI). Ironically, that means most crates in +`libtock-rs` are platform independent. `libtock_platform` provides the tools +that allow code to run in both a unit test environment and in real Tock apps. It +consists primarily of the `Syscalls` trait and supporting machinery. + +## Syscall implementations: `libtock_runtime` and `libtock_unittest` + +In order to `libtock-rs` code, you need a `libtock_platform::Syscalls` +implementation. Multiple implementations exist that work in different +environments: + +* `libtock_runtime` provides a syscall interface that uses a real Tock kernel. + This is the crate to use in Tock process binaries. +* `libtock_unittest` provides a fake kernel for use in unit tests. + +In addition, `libtock_runtime` provides the linker script and Rust runtime +needed to start a Tock process binary. `libtock_unittest` relies on `std` to +provide a runtime. + +## Panic handler crates + +Each Rust binary must have exactly one panic handler (note that `std` provides a +panic handler for binaries that depend on it). The following crates provide a +`#[panic_handler]` implementation for Tock process binaries: + +* `libtock_panic_debug` provides useful diagnostics in the event of a panic, at + the expense of code size. This is the panic handler used by `libtock`. + +## Driver crates + +Driver crates provide interfaces to specific Tock APIs: + +| Crate | Tock API | +|-------------------------|-----------------| +|`libtock_console` |[Console] | +|`libtock_low_level_debug`|[Low-Level Debug]| + +[Console]: https://github.com/tock/tock/blob/master/doc/syscalls/00001_console.md +[Low-Level Debug]: https://github.com/tock/tock/blob/master/doc/syscalls/00008_low_level_debug.md