Merge #284 284: Move `libtock_platform` and `libtock_runtime` out of `core/`. r=hudson-ayers a=jrvanwhy `libtock_platform` was originally built in `core/` because I intended to replace `libtock_core`'s modules one-by-one with replacements built on `libtock_platform`. However, this plan changed when we decided to build the new `libtock-rs` directly against Tock 2.0 rather than Tock 1.0, as that made `libtock_core` and `libtock_platform` fundamentally incompatible. Instead, these crates should be in the root of the repository. When we remove Tock 1.0 support from `libtock-rs`, we will remove the `core/` directory entirely. To make this change, I did: 1. `git mv core/platform .` 2. `git mv core/runtime .` 3. Remove `core/` from the crate paths in `./Cargo.toml` 4. Remove the `libtock_platform` dependency from `core/Cargo.toml` Co-authored-by: Johnathan Van Why <jrvanwhy@google.com>
diff --git a/doc/Overview.md b/doc/Overview.md new file mode 100644 index 0000000..c3145ae --- /dev/null +++ b/doc/Overview.md
@@ -0,0 +1,77 @@ +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` has a hard dependency on +`libtock_runtime`, and therefore cannot be used in a unit test environment. If +you want to unit test code that uses `libtock-rs`, you should depend on the +individual libraries rather than `libtock`. + +## 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 run `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