1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
//! The allocator seam: `rusty_alloc` as the family's global allocator.
//!
//! Every deliverable in Janus declares its global allocator through this
//! crate and never names `rusty_alloc` itself. That is the house rule, and it
//! buys one thing: the exact pin, the profile and the startup shape are
//! decided here once instead of in every firmware and every CLI.
//!
//! **A library must never declare a global allocator.** A program may define
//! exactly one, so a library that declares it forces the choice on every
//! consumer and makes two such libraries impossible to link together. This
//! crate does not declare one either — it hands out the type and the region,
//! and the deliverable's own `main.rs` does the declaring.
//!
//! # A hosted deliverable
//!
//! ```ignore
//! #[global_allocator]
//! static ALLOC: rusty_esp_alloc::Alloc = rusty_esp_alloc::Alloc;
//! ```
//!
//! # A firmware
//!
//! A chip has no operating system to ask for memory: it has a region the
//! linker gave it. [`Region`] is that region, handed over once at startup.
//!
//! ```ignore
//! #[global_allocator]
//! static ALLOC: rusty_esp_alloc::Alloc = rusty_esp_alloc::Alloc;
//! static HEAP: rusty_esp_alloc::Region<{ 96 * 1024 }> = rusty_esp_alloc::Region::new();
//!
//! # fn main() {
//! HEAP.give().expect("the heap is given once");
//! # }
//! ```
//!
//! # Which allocator a firmware should actually use
//!
//! Not this one, necessarily, and the honest answer is in rusty_alloc's own
//! README: on a XIAO ESP32-S3 it is **2.0x to 3.7x faster** than `esp-alloc`
//! per allocate/free pair, and it needs **68 KiB where `esp-alloc` needs 8**,
//! because a size-class page allocator's floor is `classes touched x page
//! size` rather than `bytes live`. That is structural, not a missing
//! optimisation.
//!
//! So: reach for this when a firmware **churns** — allocates and frees
//! repeatedly at varied sizes, which is what fragments a free list — and has
//! the RAM. Reach for `esp-alloc` when the budget is tight. A firmware that
//! allocates a handful of buffers at startup and never allocates again gains
//! nothing here and pays the whole floor, and several of ours are exactly
//! that shape.
//!
//! The reason to adopt it anyway, where the RAM allows, is the safety
//! posture rather than the speed: **a double free aborts** instead of putting
//! one block on a free list twice and handing identical memory to two owners.
//! Treat that abort as a bug to fix, never a check to disable.
//!
//! # The single-thread invariant a firmware must assert
//!
//! rusty_alloc'''s `no_std` profile assumes **one thread**: its cell'''s `Sync`,
//! the fixed backend'''s constant thread id and spin lock, and the split
//! 64-bit atomics in its options all depend on it. The crate will not build
//! without the caller saying so, which is the right way round -- it refuses
//! rather than assuming.
//!
//! A firmware opts in through its own `.cargo/config.toml`:
//!
//! ```toml
//! [build]
//! rustflags = ["--cfg", "ra_single_threaded"]
//! ```
//!
//! **Only assert that if it is true.** On an ESP32-S3 it holds for a Track B
//! firmware that runs `esp_hal::main` on one core and never starts the app
//! core. It stops holding the moment a second core is started **or an
//! interrupt handler allocates** -- an interrupt is another context even on
//! one core. A firmware that needs either wants `esp-alloc`, or rusty_alloc
//! with the `std` profile if a target ever offers one.
// The region is a `static` whose bytes are handed out as `&'static mut` once.
// There is no safe way to express that, and the whole point of this crate is
// that the unsafe lives here rather than in every firmware.
/// The global allocator type. A deliverable writes
/// `#[global_allocator] static A: Alloc = Alloc;` and nothing else.
pub use RustyAlloc as Alloc;
/// The pinned allocator version, so a firmware can print what it is running
/// rather than what its manifest said.
pub use VERSION;
/// What can go wrong handing over a region.
///
/// The three backend refusals are kept apart because they have three
/// different fixes, which is the distinction rusty_alloc 2.0.1 added after
/// this seam collapsed them into one and had to guess.
/// A chip's heap: `N` bytes of static storage, handed to the allocator once.
///
/// Only exists where there is no operating system to allocate from. On a
/// hosted target the allocator asks the OS and a deliverable declares
/// [`Alloc`] with no region at all.
///
/// `N` is the whole budget, and rusty_alloc's floor is set by how many size
/// classes the program touches rather than how many bytes it holds — see this
/// module's note on which allocator to use. Below about 68 KiB on an ESP32-S3
/// a real workload starts being refused, so a firmware that cannot spare that
/// should stay on `esp-alloc`.
/// The heap region, re-exported from the allocator rather than built here.
///
/// This seam carried its own container until 2.0.4 shipped one. Both of this
/// crate's attempts at it were wrong in ways the allocator's own type is not,
/// and both were found on the board rather than in review:
///
/// 1. A plain `[u8; N]` has alignment 1, so the linker placed it anywhere and
/// a region sized to exactly `good_region_size` served one segment fewer
/// than its size implied -- a startup panic (2026-09-09).
/// 2. Adding `#[repr(align(65536))]` fixed that and cost **60,952 bytes of
/// stack**, because the old sizing rule was `k * SEGMENT_SIZE + FIXED_PAGE`
/// and aligning a size that is not a whole number of segments rounds it up
/// to the next one. `free=0` was verified and the section table was not,
/// which is the exact check this crate's own `.stack` identity exists to
/// force.
///
/// `prim::fixed::Region` is aligned by construction, checks at compile time
/// that `N` is whole segments, asserts `size_of::<Region<N>>() == N` so it
/// cannot be padded, and returns the usable bytes from `give`. There is no
/// version of this worth maintaining separately.
pub use Region;
/// The largest region no bigger than `budget` that the 64 KiB granule strands
/// nothing of, and the smallest region serving at least `usable` bytes.
///
/// Re-exported from 2.0.3, which added them after this consumer measured a
/// 220 KiB region losing 24,576 bytes to the granule -- three times the
/// allocator's whole code cost at the time. A firmware should size its heap
/// with one of these rather than a round number.
pub use ;
/// What the allocator has done with the region: `(used, free, total)` bytes.
///
/// The counterpart to `esp_alloc::HEAP.stats()`, and the reason a firmware can
/// report its own footprint after a swap instead of guessing. A fixed-region
/// allocator that cannot say how much of its region is out is unmeasurable on
/// exactly the deployment it exists for.