From 627ecc454f4a5bc9fccaf07d84fee54342c7ca8c Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Tue, 11 Sep 2018 18:35:51 +0200 Subject: [PATCH] Add addtional details to the no_std section * information about the stdlib runtime * details about the no_std attribute itself * a more detailed summary * a table for comparision of supported and unsupported features of std vs. no_std environments --- src/intro/no-std.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/src/intro/no-std.md b/src/intro/no-std.md index a167c4d..a501c1a 100644 --- a/src/intro/no-std.md +++ b/src/intro/no-std.md @@ -19,15 +19,33 @@ special HW or I/Os. Overall it feels like coding in a special-purpose PC environ In a bare metal environment there will be no high level OS running and hosting our code. This means there will be no primitives, which means there's also no standard library by default. By marking our code with `no_std` we indicate that our code is capable of running in such an environment. -This means the rust [stdlib](https://doc.rust-lang.org/std/) and dynamic memory allocation can't be used by such code. +This means the rust [libstd](https://doc.rust-lang.org/std/) and dynamic memory allocation can't be used by such code. However, such code can use [libcore](https://doc.rust-lang.org/core/), which can easily be made available in any kind of environment by providing just a few symbols (for details see [libcore](https://doc.rust-lang.org/core/)). -## Summary -What implications does `no_std` Rust Environment have on the code: +### The libstd Runtime +As mentioned before using [libstd](https://doc.rust-lang.org/std/) requires some sort of system integration, but this is not only because +[libstd](https://doc.rust-lang.org/std/) is just providing a common way of accessing OS abstractions, it also provides a runtime. +This runtime, among other things, takes care of setting up stack overflow protection, processing command line arguments, +and spawning the main thread before a program's main function is invoked. This runtime also won't be available in a `no_std` environment. -* No Standard Library -* No Dynamic Memory allocation +## Summary +`#![no_std]` is a crate-level attribute that indicates that the crate will link to the core-crate instead of the std-crate. +The [libcore](https://doc.rust-lang.org/core/) crate in turn is a platform-agnostic subset of the std crate, that makes no assumptions about the system the program will run on. +As such, it provides APIs for language primitives like floats, strings and slices, as well as APIs that expose processor features +like atomic operations and SIMD instructions. However it lacks APIs for anything that involves platform integration. +Because of these properties no\_std and [libcore](https://doc.rust-lang.org/core/) code can be used for any kind of bootstrapping (stage 0) code like bootloaders, firmware or kernels. + +### Overview + +| feature | no\_std | std | +|-----------------------------------------------------------|--------|-----| +| heap (dynamic memory) | ✘ | ✓ | +| stack overflow protection | ✘ | ✓ | +| runs init code before main | ✘ | ✓ | +| libstd available | ✘ | ✓ | +| libcore available | ✓ | ✓ | +| writing firmware, kernel, or bootloader code | ✓ | ✘ | ## See also * [FAQ](https://www.rust-lang.org/en-US/faq.html#does-rust-work-without-the-standard-library)