Add page about buddy_system_allocator.

Cargo.lock

@@ -11,6 +11,13 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "allocator-example"
+version = "0.1.0"
+dependencies = [
+ "buddy_system_allocator",
+]
+
 [[package]]
 name = "ammonia"
 version = "3.3.0"
@@ -84,6 +91,15 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "buddy_system_allocator"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43f9365b6b0c9e1663ca4ca9440c00eda46bc85a3407070be8b5e0d8d1f29629"
+dependencies = [
+ "spin",
+]
+
 [[package]]
 name = "bumpalo"
 version = "3.12.0"
@@ -1904,6 +1920,15 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "spin"
+version = "0.9.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5d6e0250b93c8427a177b849d144a96d5acc57006149479403d7861ab721e34"
+dependencies = [
+ "lock_api",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.0"

Cargo.toml

@@ -2,5 +2,6 @@
 members = [
   "i18n-helpers",
   "src/exercises",
+  "src/bare-metal/useful-crates/allocator-example",
   "src/bare-metal/useful-crates/zerocopy-example",
 ]

src/SUMMARY.md

@@ -270,7 +270,7 @@
 - [Useful crates](bare-metal/useful-crates.md)
   - [zerocopy](bare-metal/useful-crates/zerocopy.md)
   - [aarch64-paging](bare-metal/useful-crates/aarch64-paging.md)
-  - [buddy_system_allocator]()
+  - [buddy_system_allocator](bare-metal/useful-crates/buddy_system_allocator.md)
   - [tinyvec]()
   - [spin and once_cell]()
 - [Android]()

src/bare-metal/useful-crates/allocator-example/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "allocator-example"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+buddy_system_allocator = "0.9.0"

src/bare-metal/useful-crates/allocator-example/src/main.rs

@@ -0,0 +1,28 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// ANCHOR: main
+use buddy_system_allocator::FrameAllocator;
+use core::alloc::Layout;
+
+fn main() {
+    let mut allocator = FrameAllocator::<32>::new();
+    allocator.add_frame(0x200_0000, 0x400_0000);
+
+    let layout = Layout::from_size_align(0x100, 0x100).unwrap();
+    let bar = allocator
+        .alloc_aligned(layout)
+        .expect("Failed to allocate 0x100 byte MMIO region");
+    println!("Allocated 0x100 byte MMIO region at {:#x}", bar);
+}

src/bare-metal/useful-crates/buddy_system_allocator.md

@@ -0,0 +1,21 @@
+# `buddy_system_allocator`
+
+[`buddy_system_allocator`][1] is a third-party crate implementing a basic buddy system allocator.
+It can be used both for [`LockedHeap`][2] implementing [`GlobalAlloc`][3] so you can use the
+standard `alloc` crate (as we saw [before][4]), or for allocating other address space. For example,
+we might want to allocate MMIO space for PCI BARs:
+
+```rust,editable,compile_fail
+{{#include allocator-example/src/main.rs:main}}
+```
+
+<details>
+
+* PCI BARs always have alignment equal to their size.
+
+</details>
+
+[1]: https://crates.io/crates/buddy_system_allocator
+[2]: https://docs.rs/buddy_system_allocator/0.9.0/buddy_system_allocator/struct.LockedHeap.html
+[3]: https://doc.rust-lang.org/core/alloc/trait.GlobalAlloc.html
+[4]: ../alloc.md