Skip to content

Commit f2dcad7

Browse files
committed
zephyr: alloc: Update documentation
Write some hopefully informative documentation on using the alloc feature within Zephyr. Signed-off-by: David Brown <[email protected]>
1 parent 767e201 commit f2dcad7

File tree

1 file changed

+47
-1
lines changed

1 file changed

+47
-1
lines changed

zephyr/src/alloc.rs

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,52 @@
11
//! A Rust global allocator that uses the stdlib allocator in Zephyr
2+
//!
3+
//! The zephyr runtime is divided into three crates:
4+
//! - [core](https://doc.rust-lang.org/stable/core/) is the the "dependency-free" foundation of the
5+
//! standard library. It is all of the parts of the standard library that have no dependencies
6+
//! outside of the language and the architecture itself.
7+
//! - [alloc](https://doc.rust-lang.org/stable/alloc/) provides the parts of the standard library
8+
//! that depend on memory allocation. This includes various types of smart pointers, atomically
9+
//! referenced counted pointers, and various collections. This depends on the platform providing
10+
//! an allocator.
11+
//! - [std](https://doc.rust-lang.org/stable/std/) is the rest of the standard library. It include
12+
//! both core and alloc, and then everthing else, including filesystem access, networking, etc. It
13+
//! is notable, however, that the Rust standard library is fairly minimal. A lot of functionality
14+
//! that other languages might include will be relegated to other crates, and the ecosystem and
15+
//! tooling around cargo make it as easy to use these as the standard library.
16+
//!
17+
//! For running application code on Zephyr, the core library (mostly) just works (the a caveat of a
18+
//! little work needed to use atomics on platforms Zephyr supports but don't have atomic
19+
//! instructions). The std library is somewhat explicitly _not_ supported. Although the intent is
20+
//! to provide much of the functionality from std, Zephyr is different enough from the conventional
21+
//! operating system std was built around that just porting it doesn't really give practical
22+
//! results. The result is either to complicated to make work, or too different from what is
23+
//! typically done on Zephyr. Supporting std could be a future project.
24+
//!
25+
//! This leaves alloc, which is mostly independent but is required to know about an allocator to
26+
//! use. This module provides an allocator for Rust that uses the underlying memory allocator
27+
//! configured into Zephyr.
28+
//!
29+
//! Because a given embedded application may or may not want memory allocation, this is controlled
30+
//! by the `CONFIG_RUST_ALLOC` Kconfig. When this config is enabled, the alloc crate becomes
31+
//! available to applications.
32+
//!
33+
//! Since alloc is typically used on Rust as a part of the std library, building in a no-std
34+
//! environment requires that it be access explicitly. Generally, alloc must be explicitly added
35+
//! to every module that needs it.
36+
//!
37+
//! ```
38+
//! extern crate alloc;
39+
//!
40+
//! use alloc::boxed::Box;
41+
//!
42+
//! let item = Box::new(5);
43+
//! printkln!("box value {}", item);
44+
//! ```
45+
//!
46+
//! The box holding the value 5 will be allocated by `Box::new`, and freed when the `item` goes out
47+
//! of scope.
248
3-
// This entire module is only use if CONFIG_RUST_ALLOC is enabled.
49+
// This entire module is only used if CONFIG_RUST_ALLOC is enabled.
450
extern crate alloc;
551

652
use core::alloc::{GlobalAlloc, Layout};

0 commit comments

Comments
 (0)