From 56319e016b80df3db592d6af2a2d6de5fac47f53 Mon Sep 17 00:00:00 2001
From: Andrew Walbran <qwandor@google.com>
Date: Thu, 16 Mar 2023 18:07:58 +0000
Subject: [PATCH] Add page about buddy_system_allocator.

---
 Cargo.lock                                    | 25 +++++++++++++++++
 Cargo.toml                                    |  1 +
 src/SUMMARY.md                                |  2 +-
 .../allocator-example/Cargo.toml              |  7 +++++
 .../allocator-example/src/main.rs             | 28 +++++++++++++++++++
 .../useful-crates/buddy_system_allocator.md   | 21 ++++++++++++++
 6 files changed, 83 insertions(+), 1 deletion(-)
 create mode 100644 src/bare-metal/useful-crates/allocator-example/Cargo.toml
 create mode 100644 src/bare-metal/useful-crates/allocator-example/src/main.rs
 create mode 100644 src/bare-metal/useful-crates/buddy_system_allocator.md

diff --git a/Cargo.lock b/Cargo.lock
index e575671d..1e7de05d 100644
--- a/Cargo.lock
+++ b/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"
diff --git a/Cargo.toml b/Cargo.toml
index e011c207..12d3f650 100644
--- a/Cargo.toml
+++ b/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",
 ]
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 7e54c8dc..42e16bb5 100644
--- a/src/SUMMARY.md
+++ b/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]()
diff --git a/src/bare-metal/useful-crates/allocator-example/Cargo.toml b/src/bare-metal/useful-crates/allocator-example/Cargo.toml
new file mode 100644
index 00000000..5a85cc23
--- /dev/null
+++ b/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"
diff --git a/src/bare-metal/useful-crates/allocator-example/src/main.rs b/src/bare-metal/useful-crates/allocator-example/src/main.rs
new file mode 100644
index 00000000..73f36bed
--- /dev/null
+++ b/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);
+}
diff --git a/src/bare-metal/useful-crates/buddy_system_allocator.md b/src/bare-metal/useful-crates/buddy_system_allocator.md
new file mode 100644
index 00000000..194b1860
--- /dev/null
+++ b/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