From a50c5a6fd08b727171d2cd61ea048f901b735129 Mon Sep 17 00:00:00 2001
From: bigsaltyfishes <bigsaltyfishes@gmail.com>
Date: Sat, 21 Sep 2024 22:44:05 +0800
Subject: [PATCH] doc: Improve documentation for buddy system heap order
 explanation

- Clarify that the real order of the buddy system is `ORDER - 1`.
- Treewide change of default `ORDER` to `33` to match the explanation.

Signed-off-by: bigsaltyfishes <bigsaltyfishes@gmail.com>
---
 benches/memory_allocator_benchmark.rs |  2 +-
 src/frame.rs                          | 12 ++++++------
 src/lib.rs                            | 12 +++++++++---
 3 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/benches/memory_allocator_benchmark.rs b/benches/memory_allocator_benchmark.rs
index 0055c10..9628469 100644
--- a/benches/memory_allocator_benchmark.rs
+++ b/benches/memory_allocator_benchmark.rs
@@ -138,7 +138,7 @@ pub fn thread_test() {
     }
 }
 
-const ORDER: usize = 32;
+const ORDER: usize = 33;
 const MACHINE_ALIGN: usize = core::mem::size_of::<usize>();
 /// for now 128M is needed
 /// TODO: reduce memory use
diff --git a/src/frame.rs b/src/frame.rs
index 8663c77..389d137 100644
--- a/src/frame.rs
+++ b/src/frame.rs
@@ -11,9 +11,9 @@ use spin::Mutex;
 
 /// A frame allocator that uses buddy system, requiring a global allocator.
 ///
-/// The max order of the allocator is specified via the const generic parameter `ORDER`. The frame
-/// allocator will only be able to allocate ranges of size up to 2<sup>ORDER</sup>, out of a total
-/// range of size at most 2<sup>ORDER + 1</sup> - 1.
+/// The max order of the allocator is determined by the const generic parameter `ORDER` (`MAX_ORDER = ORDER - 1`). 
+/// The frame allocator will only be able to allocate ranges of size up to 2<sup>MAX_ORDER</sup>, out of a total
+/// range of size at most 2<sup>MAX_ORDER + 1</sup> - 1.
 ///
 /// # Usage
 ///
@@ -29,7 +29,7 @@ use spin::Mutex;
 /// let num = frame.alloc(2);
 /// assert_eq!(num, Some(0));
 /// ```
-pub struct FrameAllocator<const ORDER: usize = 32> {
+pub struct FrameAllocator<const ORDER: usize = 33> {
     // buddy system with max order of ORDER
     free_list: [BTreeSet<usize>; ORDER],
 
@@ -175,7 +175,7 @@ impl<const ORDER: usize> FrameAllocator<ORDER> {
 /// Create a locked frame allocator and add frames to it:
 /// ```
 /// use buddy_system_allocator::*;
-/// let mut frame = LockedFrameAllocator::<32>::new();
+/// let mut frame = LockedFrameAllocator::<33>::new();
 /// assert!(frame.lock().alloc(1).is_none());
 ///
 /// frame.lock().add_frame(0, 3);
@@ -185,7 +185,7 @@ impl<const ORDER: usize> FrameAllocator<ORDER> {
 /// assert_eq!(num, Some(0));
 /// ```
 #[cfg(feature = "use_spin")]
-pub struct LockedFrameAllocator<const ORDER: usize = 32>(Mutex<FrameAllocator<ORDER>>);
+pub struct LockedFrameAllocator<const ORDER: usize = 33>(Mutex<FrameAllocator<ORDER>>);
 
 #[cfg(feature = "use_spin")]
 impl<const ORDER: usize> LockedFrameAllocator<ORDER> {
diff --git a/src/lib.rs b/src/lib.rs
index 1fd98e3..319b5b0 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -39,7 +39,10 @@ pub use frame::*;
 /// ```
 /// use buddy_system_allocator::*;
 /// # use core::mem::size_of;
-/// let mut heap = Heap::<32>::empty();
+/// // The order of the buddy system is `ORDER - 1`.
+/// // For example, to create a heap with a maximum block size of 2^32 bytes,
+/// // you should define the heap with `ORDER = 33`.
+/// let mut heap = Heap::<33>::empty();
 /// # let space: [usize; 100] = [0; 100];
 /// # let begin: usize = space.as_ptr() as usize;
 /// # let end: usize = begin + 100 * size_of::<usize>();
@@ -229,7 +232,10 @@ impl<const ORDER: usize> fmt::Debug for Heap<ORDER> {
 /// ```
 /// use buddy_system_allocator::*;
 /// # use core::mem::size_of;
-/// let mut heap = LockedHeap::<32>::new();
+/// // The order of the buddy system is `ORDER - 1`.
+/// // For example, to create a heap with a maximum block size of 2^32 bytes,
+/// // you should define the heap with `ORDER = 33`.
+/// let mut heap = LockedHeap::<33>::new();
 /// # let space: [usize; 100] = [0; 100];
 /// # let begin: usize = space.as_ptr() as usize;
 /// # let end: usize = begin + 100 * size_of::<usize>();
@@ -287,7 +293,7 @@ unsafe impl<const ORDER: usize> GlobalAlloc for LockedHeap<ORDER> {
 /// Create a locked heap:
 /// ```
 /// use buddy_system_allocator::*;
-/// let heap = LockedHeapWithRescue::new(|heap: &mut Heap<32>, layout: &core::alloc::Layout| {});
+/// let heap = LockedHeapWithRescue::new(|heap: &mut Heap<33>, layout: &core::alloc::Layout| {});
 /// ```
 ///
 /// Before oom, the allocator will try to call rescue function and try for one more time.