### Heap Allocation Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Demonstrates how to allocate memory using `Heap::alloc()` and handle potential out-of-memory errors.

```Rust
use buddy_system_allocator::Heap;
use core::alloc::Layout;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];

unsafe {
    heap.init(buffer.as_ptr() as usize, buffer.len());
}

let layout = Layout::new::<u64>();
match heap.alloc(layout) {
    Ok(ptr) => {
        // Successfully allocated
        println!("Allocated at {:p}", ptr.as_ptr());
    }
    Err(()) => {
        // Allocation failed - out of memory
        println!("Out of memory!");
    }
}
```

--------------------------------

### Heap::init()

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Initializes the heap with a memory region of given size starting at `start`. Equivalent to `add_to_heap(start, start + size)`. This is an unsafe operation.

```APIDOC
## init()

### Description
Initializes the heap with a memory region of given size starting at `start`. Equivalent to `add_to_heap(start, start + size)`.

### Method
`unsafe fn init(&mut self, start: usize, size: usize)`

### Parameters
#### Path Parameters
- **start** (`usize`) - Required - Start address of the heap
- **size** (`usize`) - Required - Size in bytes of the heap region

### Return type
`()`

### Safety Requirements
- The caller must ensure the memory range `[start, start + size)` is valid and writable
- The range must not overlap with any previously added memory region
- The range must remain available for the lifetime of the heap

### Example
```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];
let start = buffer.as_ptr() as usize;

unsafe {
    heap.init(start, buffer.len());
}
```
```

--------------------------------

### LockedHeap Initialization and Allocation Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Demonstrates initializing a LockedHeap and performing memory allocation using its lock().

```rust
use buddy_system_allocator::LockedHeap;
use core::alloc::Layout;

let mut heap = LockedHeap::<33>::new();

unsafe {
    heap.lock().init(0x1000, 0x100000);
}

let layout = Layout::new::<u64>();
let result = heap.lock().alloc(layout);
```

--------------------------------

### Using LockedFrameAllocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Example demonstrating how to use LockedFrameAllocator by acquiring a lock to add frames and allocate them.

```rust
use buddy_system_allocator::LockedFrameAllocator;

let frame_alloc = LockedFrameAllocator::<33>::new();

{
    let mut alloc = frame_alloc.lock();
    alloc.add_frame(0, 1000);
    alloc.alloc(5);
}
```

--------------------------------

### Basic FrameAllocator Usage Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Demonstrates the fundamental usage of FrameAllocator, including adding frames, allocating, deallocating, and checking statistics.

```rust
use buddy_system_allocator::FrameAllocator;

fn main() {
    let mut frame_alloc = FrameAllocator::<33>::new();
    
    // Add frames 0-1000 to the allocator
    frame_alloc.add_frame(0, 1000);
    
    // Allocate 5 frames
    let frame1 = frame_alloc.alloc(5).expect("allocation failed");
    println!("Allocated frames at: {}", frame1);
    
    // Allocate 3 more frames
    let frame2 = frame_alloc.alloc(3).expect("allocation failed");
    println!("Allocated frames at: {}", frame2);
    
    // Deallocate the first range
    frame_alloc.dealloc(frame1, 5);
    
    // Statistics
    println!("Allocated: {}", frame_alloc.allocated);
    println!("Total: {}", frame_alloc.total);
}
```

--------------------------------

### Initialize Heap with a memory region

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Use `init` to initialize the heap with a memory region of a given size starting at a specific address. This is equivalent to calling `add_to_heap(start, start + size)`. Ensure the memory range is valid and writable.

```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];
let start = buffer.as_ptr() as usize;

unsafe {
    heap.init(start, buffer.len());
}
```

--------------------------------

### No-std Compatibility Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Demonstrates basic usage of the Heap allocator in a no_std environment. The 'alloc' crate is required only if the 'alloc' feature is used.

```Rust
#![no_std]

extern crate alloc;  // Required only if using alloc feature

use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();
```

--------------------------------

### Aligned Frame Allocation Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Illustrates allocating frames with specific alignment requirements using `FrameAllocator::alloc_aligned()` and handling potential failures.

```Rust
use buddy_system_allocator::FrameAllocator;
use core::alloc::Layout;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 10000);

let layout = Layout::from_size_align_unchecked(64, 64);
match frame_alloc.alloc_aligned(layout) {
    Some(frame) => println!("Aligned allocation at frame {}", frame),
    None => println!("No aligned frames available"),
}
```

--------------------------------

### Frame Allocation Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Shows how to allocate contiguous frames using `FrameAllocator::alloc()` and handle cases where no frames are available or insufficient frames remain.

```Rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 100);

// Allocate 5 frames
match frame_alloc.alloc(5) {
    Some(frame) => {
        println!("Allocated frames starting at {}", frame);
    }
    None => {
        println!("No frames available!");
    }
}

// Allocate when insufficient frames remain
match frame_alloc.alloc(100) {
    Some(frame) => println!("Allocated"),
    None => println!("Insufficient frames"),
}
```

--------------------------------

### Heap::add_to_heap() Panic Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Illustrates a panic condition in Heap::add_to_heap() where the start address is greater than the end address after alignment adjustments.

```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();

// This panics if start address is greater than end address
unsafe {
    // heap.add_to_heap(0x2000, 0x1000);  // PANICS
    heap.add_to_heap(0x1000, 0x2000);   // OK
}
```

--------------------------------

### Global Allocator Setup and Usage

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Shows how to set up and use LockedHeap as a global allocator, including initialization and subsequent memory allocation.

```rust
use buddy_system_allocator::LockedHeap;

#[global_allocator]
static HEAP_ALLOCATOR: LockedHeap<33> = LockedHeap::new();

fn main() {
    // Unsafe initialization of the global allocator
    unsafe {
        HEAP_ALLOCATOR.lock().init(0x1000, 0x100000);
    }
    
    // Now can use Vec and other alloc types
    let vec = alloc::vec::vec![1, 2, 3];
}
```

--------------------------------

### Create a new empty LinkedList

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/linked-list.md

Initializes a new, empty linked list. Use this to start managing free blocks.

```rust
use buddy_system_allocator::linked_list::LinkedList;

let list = LinkedList::new();
assert!(list.is_empty());
```

--------------------------------

### FrameAllocator::add_frame() Panic Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Demonstrates a panic condition in FrameAllocator::add_frame() where the start frame is greater than the end frame.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();

// frame_alloc.add_frame(100, 50);  // PANICS
frame_alloc.add_frame(50, 100);     // OK
```

--------------------------------

### Immutable iteration example for LinkedList

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/linked-list.md

Demonstrates how to use the immutable iterator to traverse and inspect elements within the linked list.

```rust
use buddy_system_allocator::linked_list::LinkedList;

let mut list = LinkedList::new();
let mut nums = [0usize; 2];

unsafe {
    list.push(&mut nums[0] as *mut usize);
    list.push(&mut nums[1] as *mut usize);
}

for item in list.iter() {
    println!("Item pointer: {:p}", item);
}
```

--------------------------------

### Specific Frame Allocation Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Demonstrates allocating frames at a specific address using `FrameAllocator::alloc_at()` and handling errors related to misalignment, range unavailability, or unmanaged ranges.

```Rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 1000);

// Valid allocation: requesting 8 frames (next power of 2 >= 5)
// Rounded to 8, so start must be aligned to 8
match frame_alloc.alloc_at(16, 5) {
    Some(frame) => println!("Allocated at frame {}", frame),
    None => println!("Requested range unavailable or misaligned"),
}

// Invalid: misaligned start
match frame_alloc.alloc_at(17, 8) {
    Some(_) => println!("Allocated"),
    None => println!("Start address not aligned to block size"),
}

// Invalid: range already allocated
if let Some(_) = frame_alloc.alloc_at(100, 50) {
    // Frames already allocated
    match frame_alloc.alloc_at(100, 50) {
        Some(_) => println!("Allocated"),
        None => println!("Range already in use"),
    }
}
```

--------------------------------

### Global Allocator and Error Handler Setup

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

This snippet demonstrates how to configure the buddy system allocator as a global allocator and define a custom allocation error handler. The handler panics on allocation failure, as it must not return.

```rust
#![no_std]
extern crate alloc;

use buddy_system_allocator::LockedHeap;
use core::alloc::Layout;

#[global_allocator]
static ALLOCATOR: LockedHeap<33> = LockedHeap::new();

#[alloc_error_handler]
fn alloc_error_handler(layout: Layout) -> !
{
    panic!("Allocation failed for layout: {:?}", layout);
}

fn init_heap(start: usize, size: usize) {
    unsafe {
        ALLOCATOR.lock().init(start, size);
    }
}
```

--------------------------------

### Global Allocator Setup

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/README.md

Use this snippet to set up the LockedHeap as the global allocator in your Rust project. Ensure the `alloc` feature is enabled.

```rust
use buddy_system_allocator::LockedHeap;

#[global_allocator]
static HEAP_ALLOCATOR: LockedHeap<32> = LockedHeap::empty();
```

--------------------------------

### alloc_at()

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Attempts to allocate a specific range of frames. The count is rounded up to the next power of two, and the start must be aligned to this rounded size.

```APIDOC
## alloc_at()

### Description
Attempts to allocate a specific range of frames `[start, start + count)`. The `count` is rounded up to the next power of two, and `start` must be aligned to this rounded size (buddy system invariant).

### Parameters
#### Path Parameters
- **start** (usize) - Required - Desired starting frame number
- **count** (usize) - Required - Number of frames to allocate

### Return type
`Option<usize>`
- `Some(start)` - If the range was successfully allocated
- `None` - If the range is unavailable, misaligned, or not managed

### Example
```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 100);

// Try to allocate exactly frames [16, 24)
match frame_alloc.alloc_at(16, 8) {
    Some(frame) => {
        println!("Allocated frames at {}", frame);
    }
    None => {
        println!("Requested range unavailable or misaligned");
    }
}
```
```

--------------------------------

### FrameAllocator::dealloc() Correct Deallocation Example

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Shows the correct way to deallocate memory using FrameAllocator::dealloc(). The deallocated frame count must exactly match the original allocation count.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 1000);

// Allocate 8 frames (next power of 2 >= 5)
if let Some(frame) = frame_alloc.alloc(5) {
    // Must deallocate with exact same count
    frame_alloc.dealloc(frame, 5);  // Correct
    // frame_alloc.dealloc(frame, 8);  // WRONG - undefined behavior
}
```

--------------------------------

### Allocate Specific Frame Range

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Attempts to allocate a specific range of frames. The count is rounded up to the next power of two, and the start must be aligned to this size. Returns Some(start) on success, None if unavailable or misaligned.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 100);

// Try to allocate exactly frames [16, 24)
match frame_alloc.alloc_at(16, 8) {
    Some(frame) => {
        println!("Allocated frames at {}", frame);
    }
    None => {
        println!("Requested range unavailable or misaligned");
    }
}
```

--------------------------------

### Setup LockedHeap as Global Allocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Configures LockedHeap as the global allocator for a no_std environment. Includes a basic allocation error handler.

```rust
#![no_std]

extern crate alloc;

use buddy_system_allocator::LockedHeap;

#[global_allocator]
static HEAP_ALLOCATOR: LockedHeap<33> = LockedHeap::new();

#[alloc_error_handler]
fn alloc_error_handler(layout: core::alloc::Layout) -> !
{
    panic!("Allocation failed for layout: {:?}", layout);
}

fn init_allocator(heap_start: usize, heap_size: usize) {
    unsafe {
        HEAP_ALLOCATOR.lock().init(heap_start, heap_size);
    }
}
```

--------------------------------

### Heap::dealloc() Undefined Behavior Examples

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Demonstrates incorrect deallocation calls to Heap::dealloc() which lead to undefined behavior. Ensure ptr and layout match the original allocation.

```rust
use buddy_system_allocator::Heap;
use core::alloc::Layout;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];

unsafe {
    heap.init(buffer.as_ptr() as usize, buffer.len());
}

let layout = Layout::new::<u64>();
if let Ok(ptr) = heap.alloc(layout) {
    unsafe {
        // CORRECT: deallocate with same layout
        heap.dealloc(ptr, layout);
        
        // UNDEFINED BEHAVIOR: deallocate again
        // heap.dealloc(ptr, layout);
        
        // UNDEFINED BEHAVIOR: wrong layout
        // let wrong_layout = Layout::new::<u32>();
        // heap.dealloc(ptr, wrong_layout);
    }
}
```

--------------------------------

### Add Frame Ranges to FrameAllocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Shows how to add frame ranges to the FrameAllocator, either by specifying start and end frames or by using the Range type. Multiple ranges can be added.

```rust
use buddy_system_allocator::FrameAllocator;
use core::ops::Range;

let mut frame_alloc = FrameAllocator::<33>::new();

// Option 1: Add a frame range
frame_alloc.add_frame(0, 1000);  // Add frames [0, 1000)

// Option 2: Add using Range type
frame_alloc.insert(1000..2000);  // Add frames [1000, 2000)

// Option 3: Add multiple ranges
frame_alloc.add_frame(2000, 3000);
frame_alloc.add_frame(5000, 6000);
```

--------------------------------

### Rescue Function for Cache Clearing

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap-with-rescue.md

Demonstrates a rescue function that clears a hypothetical global cache when memory pressure is detected. This is an example of using the rescue mechanism for resource recycling and emergency memory recovery.

```rust
use buddy_system_allocator::{Heap, LockedHeapWithRescue};
use core::alloc::Layout;

// Hypothetical global cache
static GLOBAL_CACHE_SIZE: atomic::AtomicUsize = atomic::AtomicUsize::new(0);

fn rescue_with_cache_clear(heap: &mut Heap<33>, _layout: &Layout) {
    // Clear some cached data when needed
    GLOBAL_CACHE_SIZE.store(0, atomic::Ordering::Relaxed);
}

#[global_allocator]
static HEAP_ALLOCATOR: LockedHeapWithRescue<33> = LockedHeapWithRescue::new(rescue_with_cache_clear);
```

--------------------------------

### Get Total Heap Size

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Returns the total number of bytes available in the heap, which is the sum of all initialized memory regions. This provides an overview of the heap's capacity.

```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];

unsafe {
    heap.init(buffer.as_ptr() as usize, buffer.len());
}

println!("Total heap size: {}", heap.stats_total_bytes());
```

--------------------------------

### Heap Initialization

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/quick-start.md

Demonstrates the correct way to initialize a `Heap` before allocation. Allocating before initialization will result in an error.

```rust
// ❌ WRONG: Allocating before initialization
let mut heap = Heap::<33>::new();
heap.alloc(Layout::new::<u64>()); // Will fail (return Err)

// ✅ CORRECT: Initialize first
let mut heap = Heap::<33>::new();
unsafe {
    heap.init(0x1000, 0x100000);
}
heap.alloc(Layout::new::<u64>()); // Will succeed
```

--------------------------------

### Range Struct for Start and End

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/types.md

Represents a range of values with a `start` and `end` field. Used to specify a contiguous block of frames to be inserted into the `FrameAllocator`.

```rust
pub struct Range<T> {
    pub start: T,
    pub end: T,
}
```

--------------------------------

### Create and Use Layout

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/types.md

Demonstrates creating a Layout for a specific type and a custom size/alignment. The `Layout::new` function infers size and alignment from a type, while `from_size_align_unchecked` allows manual specification.

```rust
use core::alloc::Layout;

let layout = Layout::new::<u64>();
println!("Size: {}, Align: {}", layout.size(), layout.align());

let layout2 = Layout::from_size_align_unchecked(256, 64);
```

--------------------------------

### Add memory range to Heap

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Use `add_to_heap` to add a memory range `[start, end)` to the heap. The range is automatically split into buddy system blocks. Ensure the memory range is valid, writable, and does not overlap with other regions. The start address will be aligned and the end address aligned down.

```rust
use buddy_system_allocator::Heap;
use core::mem::size_of;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];
let start = buffer.as_ptr() as usize;
let end = start + buffer.len();

unsafe {
    heap.add_to_heap(start, end);
}
```

--------------------------------

### Configure Heap and Frame Allocators with ORDER

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Demonstrates how to instantiate Heap and FrameAllocator types with different ORDER generic parameters to control maximum allocation size and total addressable range.

```Rust
use buddy_system_allocator::{Heap, FrameAllocator, LockedHeap};

// Small, embedded system allocator
let small_heap = Heap::<17>::new();

// Standard allocator for OS kernels
let kernel_heap = Heap::<33>::new();

// Large server system
let large_heap = Heap::<48>::new();

// Frame allocator with default ORDER=33
let frames_default = FrameAllocator::new();

// Frame allocator with custom ORDER
let frames_custom = FrameAllocator::<64>::new();
```

--------------------------------

### Allocate Memory with NonNull Pointer

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/types.md

Shows how to initialize a heap, allocate memory using a Layout, and obtain a `NonNull<u8>` pointer. Demonstrates dereferencing the pointer after converting it to a mutable raw pointer.

```rust
use core::ptr::NonNull;
use buddy_system_allocator::Heap;
use core::alloc::Layout;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];

unsafe {
    heap.init(buffer.as_ptr() as usize, buffer.len());
}

let layout = Layout::new::<u32>();
if let Ok(ptr) = heap.alloc(layout) {
    // ptr is NonNull<u8>
    let raw = ptr.as_ptr();  // Convert to *mut u8
    unsafe {
        *raw = 42;
    }
}
```

--------------------------------

### Allocate Frames and Handle Option

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/types.md

Shows how to add frames to a `FrameAllocator` and then attempt to allocate a number of frames. The `match` statement handles the `Option<usize>` returned, distinguishing between successful allocation and unavailability of frames.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 1000);

match frame_alloc.alloc(5) {
    Some(frame) => println!("Allocated at frame {}", frame),
    None => println!("No frames available"),
}
```

--------------------------------

### Direct Imports for Buddy System Allocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Import specific types directly for clarity and to avoid namespace pollution. This is the recommended approach.

```rust
use buddy_system_allocator::Heap;
use buddy_system_allocator::LockedHeap;
use buddy_system_allocator::LockedHeapWithRescue;
use buddy_system_allocator::FrameAllocator;
use buddy_system_allocator::LockedFrameAllocator;
use buddy_system_allocator::linked_list::LinkedList;
```

--------------------------------

### Get Total Managed Frame Count

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Retrieves the total number of frames managed by the allocator. This field represents the overall capacity.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 100);

println!("Total frames: {}", frame_alloc.total);
```

--------------------------------

### Heap::add_to_heap()

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Adds a memory range `[start, end)` to the heap. The range is automatically split into buddy system blocks. This is an unsafe operation.

```APIDOC
## add_to_heap()

### Description
Adds a memory range `[start, end)` to the heap. The range is automatically split into buddy system blocks.

### Method
`unsafe fn add_to_heap(&mut self, start: usize, end: usize)`

### Parameters
#### Path Parameters
- **start** (`usize`) - Required - Start address (will be aligned to `size_of::<usize>()`)
- **end** (`usize`) - Required - End address (exclusive, will be aligned down)

### Return type
`()`

### Safety Requirements
- The caller must ensure the memory range `[start, end)` is valid and writable
- The range must not overlap with any previously added memory region
- The range must not be managed by any other allocator
- The range must remain available for the lifetime of the heap

### Example
```rust
use buddy_system_allocator::Heap;
use core::mem::size_of;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];
let start = buffer.as_ptr() as usize;
let end = start + buffer.len();

unsafe {
    heap.add_to_heap(start, end);
}
```
```

--------------------------------

### Initialize and Use Frame Allocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Creates a `FrameAllocator` instance and adds a range of frames. It then attempts to allocate a specified number of frames.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::new();
frame_alloc.add_frame(0, 1000);
let frame = frame_alloc.alloc(5).expect("allocation failed");
```

--------------------------------

### Cargo.toml: Default Buddy System Allocator Configuration

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Includes both 'alloc' and 'use_spin' features for the buddy_system_allocator crate.

```toml
[dependencies]
buddy_system_allocator = "0.13"
```

--------------------------------

### Cargo.toml: Minimal Buddy System Allocator Configuration

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Configures the buddy_system_allocator crate with no features enabled, providing only Heap<ORDER> and its related functionality.

```toml
[dependencies]
buddy_system_allocator = { version = "0.13", default-features = false }
```

--------------------------------

### Initialize and Use LockedFrameAllocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Demonstrates how to create a thread-safe frame allocator, add frames, and allocate a frame. Requires the 'alloc' and 'use_spin' features.

```rust
use buddy_system_allocator::LockedFrameAllocator;

let frame_alloc = LockedFrameAllocator::new();
frame_alloc.lock().add_frame(0, 1000);
let frame = frame_alloc.lock().alloc(5);
```

--------------------------------

### Get Current Allocated Frame Count

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Retrieves the number of frames currently allocated. This field tracks allocated frames, excluding internal metadata.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 100);
frame_alloc.alloc(5);

println!("Allocated frames: {}", frame_alloc.allocated);
```

--------------------------------

### FrameAllocator::alloc()

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Allocates a specified number of contiguous frames. The actual size allocated is rounded up to the nearest power of two. Returns the starting frame number if successful.

```APIDOC
## FrameAllocator::alloc()

### Description
Allocates `count` contiguous frames and returns the first frame number. The actual allocation size is rounded up to the next power of two.

### Method
`alloc(&mut self, count: usize) -> Option<usize>`

### Parameters
#### Path Parameters
- **count** (usize) - Required - Number of frames to allocate

### Return type
`Option<usize>`
- `Some(frame_num)` - First frame of the allocated range
- `None` - Allocation failed (not enough contiguous frames available)

### Example
```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 100);

match frame_alloc.alloc(5) {
    Some(frame_num) => {
        println!("Allocated frames starting at: {}", frame_num);
        // Actual allocation size is 8 frames (next power of 2 >= 5)
    }
    None => {
        println!("Allocation failed");
    }
}
```
```

--------------------------------

### FrameAllocator::insert()

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Adds a range of frames to the allocator using a `Range<usize>` type. This is functionally equivalent to calling `add_frame` with the range's start and end values.

```APIDOC
## FrameAllocator::insert()

### Description
Adds a range of frames to the allocator using a Range type. Equivalent to `add_frame(range.start, range.end)`.

### Method
`insert(&mut self, range: Range<usize>)`

### Parameters
#### Path Parameters
- **range** (Range<usize>) - Required - Frame number range `[start, end)`

### Return type
`()`

### Example
```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.insert(0..100);
// Equivalent to add_frame(0, 100)
```
```

--------------------------------

### Initialize Generic Heap Allocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Instantiates and initializes a generic buddy system heap allocator. Ensure the memory region is valid and properly aligned before calling `init`.

```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();
unsafe {
    heap.init(0x1000, 0x100000);
}
```

--------------------------------

### Setup LockedHeapWithRescue as Global Allocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Sets up LockedHeapWithRescue as the global allocator, providing a custom rescue function to handle allocation failures. The rescue function can be used for cleanup.

```rust
#![no_std]

extern crate alloc;

use buddy_system_allocator::{Heap, LockedHeapWithRescue};
use core::alloc::Layout;

fn rescue_fn(heap: &mut Heap<33>, layout: &Layout) {
    // Clean up caches or deallocate non-critical data
    println!("Rescue called for layout: {:?}", layout);
}

#[global_allocator]
static HEAP_ALLOCATOR: LockedHeapWithRescue<33> = LockedHeapWithRescue::new(rescue_fn);

fn init_allocator(heap_start: usize, heap_size: usize) {
    unsafe {
        HEAP_ALLOCATOR.lock().init(heap_start, heap_size);
    }
}
```

--------------------------------

### Heap Allocation Handling Patterns

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Illustrates common patterns for handling `Result` from `Heap::alloc()`, including `if let` and `map_or`.

```Rust
if let Ok(ptr) = heap.alloc(layout) {
    // Use pointer
} else {
    // Handle allocation failure
}

// Or with map_or:
let ptr = heap.alloc(layout)
    .map_or(core::ptr::null_mut(), |p| p.as_ptr());
```

--------------------------------

### Frame Allocation Handling Patterns

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Demonstrates various ways to handle `Option<usize>` returned by `FrameAllocator::alloc()`, such as `if let`, `unwrap_or`, and `map`.

```Rust
if let Some(frame) = frame_alloc.alloc(count) {
    // Use frame
} else {
    // Handle allocation failure
}

// Or with unwrap_or:
let frame = frame_alloc.alloc(count).unwrap_or(0);

// Or with map:
frame_alloc.alloc(count).map(|f| {
    println!("Allocated at frame {}", f);
});
```

--------------------------------

### Create a new Heap instance

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Use `Heap::new()` to create an empty heap. The ORDER constant determines the maximum allocation size (2^(ORDER-1) bytes).

```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();
// Maximum block size is 2^32 bytes (ORDER - 1 = 32)
```

--------------------------------

### Define Heap Allocator Sizes with ORDER

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/types.md

Demonstrates how to create heap allocators with different maximum allocation sizes using the ORDER const generic parameter. The maximum allocatable size is determined by 2^(ORDER-1).

```rust
use buddy_system_allocator::{Heap, FrameAllocator, LockedHeap};

// Small allocator: max 2^16 bytes = 64 KB
let small_heap = Heap::<17>::new();

// Medium allocator: max 2^20 bytes = 1 MB  
let medium_heap = Heap::<21>::new();

// Large allocator: max 2^32 bytes = 4 GB
let large_heap = Heap::<33>::new();

// Extra large frame allocator: max 2^63 frames
let huge_frame_alloc = FrameAllocator::<64>::new();
```

--------------------------------

### Cargo Configuration for 'alloc' Feature

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Shows how to configure the 'alloc' feature in Cargo.toml. This feature enables FrameAllocator and LockedFrameAllocator types and requires a global allocator.

```toml
[dependencies]
buddy_system_allocator = "0.13"  # alloc enabled by default
buddy_system_allocator = { version = "0.13", features = ["alloc"] }  # Explicit
buddy_system_allocator = { version = "0.13", default-features = false, features = ["alloc"] }  # Only alloc
```

--------------------------------

### Insert Frame Range using Range Type

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Adds a range of frames to the allocator using a Range type. This is equivalent to calling add_frame with the range's start and end values.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.insert(0..100);
// Equivalent to add_frame(0, 100)
```

--------------------------------

### Cargo Configuration for 'use_spin' Feature

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Shows how to configure the 'use_spin' feature in Cargo.toml. This feature enables locked allocator types and depends on the 'spin' crate.

```toml
[dependencies]
buddy_system_allocator = "0.13"  # use_spin enabled by default
buddy_system_allocator = { version = "0.13", features = ["use_spin"] }  # Explicit
buddy_system_allocator = { version = "0.13", default-features = false, features = ["use_spin"] }  # Only use_spin
```

--------------------------------

### Add Frame Range to Allocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/frame-allocator.md

Adds a range of frame numbers to the allocator, making them available for allocation. The range is automatically split into buddy system blocks. Panics if start > end.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.add_frame(0, 100);
// Now 100 frames are available for allocation
```

--------------------------------

### Heap Allocation Result Handling

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/README.md

Demonstrates how to handle the Result returned by heap allocation. Use the Ok variant for successful allocations and the Err variant to handle out-of-memory conditions.

```rust
match heap.alloc(layout) {
    Ok(ptr) => { /* use ptr */ } 
    Err(()) => { /* out of memory */ }
}
```

--------------------------------

### Get User-Requested Bytes Allocated

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Returns the total number of bytes requested by allocations, not the actual rounded-up size. This is useful for tracking memory usage from the perspective of the user's requests.

```rust
use buddy_system_allocator::Heap;
use core::alloc::Layout;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];

unsafe {
    heap.init(buffer.as_ptr() as usize, buffer.len());
}

let layout = Layout::new::<u32>();
heap.alloc(layout).ok();

println!("User-allocated bytes: {}", heap.stats_alloc_user());
```

--------------------------------

### Get Actual Allocated Bytes (Rounded)

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Returns the actual number of bytes allocated, including buddy system rounding to the nearest power of two. This reflects the true memory footprint on the heap.

```rust
use buddy_system_allocator::Heap;
use core::alloc::Layout;

let mut heap = Heap::<33>::new();
let mut buffer = [0u8; 4096];

unsafe {
    heap.init(buffer.as_ptr() as usize, buffer.len());
}

let layout = Layout::new::<u32>();
heap.alloc(layout).ok();

println!("Actual allocated bytes: {}", heap.stats_alloc_actual());
```

--------------------------------

### Wildcard Import for Buddy System Allocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Import all items from the crate into the current scope. This is generally not recommended as it can lead to namespace conflicts and make code harder to understand.

```rust
use buddy_system_allocator::*;
```

--------------------------------

### FrameAllocator Allocation with Expect for Panicking

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Demonstrates using `expect` on FrameAllocator allocation results. This will panic with a custom message if the allocation fails.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::new();
frame_alloc.add_frame(0, 10000);

let frame = frame_alloc.alloc(5)
    .expect("Critical: frame allocation failed");
```

--------------------------------

### Heap Allocation with Direct Match Error Handling

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/error-handling.md

Demonstrates handling Heap allocation results using a `match` statement. This pattern is suitable when specific actions are needed for both success and failure.

```rust
use buddy_system_allocator::Heap;
use core::alloc::Layout;

let mut heap = Heap::<33>::new();

let layout = Layout::new::<u32>();
match heap.alloc(layout) {
    Ok(ptr) => {
        // Use allocated memory
        unsafe { *(ptr.as_ptr() as *mut u32) = 42; }
    }
    Err(()) => {
        // Handle OOM
        panic!("Failed to allocate memory");
    }
}
```

--------------------------------

### Get Pointer from Linked List Node

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/linked-list.md

Demonstrates retrieving the pointer stored in a linked list node using `ListNode::value()` without removing the node. Requires unsafe block for initial list population.

```rust
use buddy_system_allocator::linked_list::LinkedList;

let mut list = LinkedList::new();
let mut data = 0usize;

unsafe {
    list.push(&mut data as *mut usize);
}

for node in list.iter_mut() {
    let ptr = node.value();
    println!("Value at: {:p}", ptr);
}
```

--------------------------------

### Access Heap Methods via Deref

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap-with-rescue.md

LockedHeapWithRescue dereferences to the inner spin::Mutex<Heap<ORDER>>, allowing access to heap methods through the .lock() call. This example demonstrates initializing the heap and performing an allocation after acquiring the lock.

```rust
use buddy_system_allocator::LockedHeapWithRescue;
use core::alloc::Layout;

fn rescue_fn(heap: &mut buddy_system_allocator::Heap<33>, layout: &Layout) {}

let heap = LockedHeapWithRescue::<33>::new(rescue_fn);

unsafe {
    heap.lock().init(0x1000, 0x100000);
}

let layout = Layout::new::<u64>();
let result = heap.lock().alloc(layout);
```

--------------------------------

### Heap<const ORDER: usize>

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

A generic buddy system allocator for arbitrary memory blocks. This is the core allocator type, suitable for various memory sizes based on the ORDER parameter.

```APIDOC
## Heap<const ORDER: usize>

### Description
A generic buddy system allocator for arbitrary memory blocks. This is the core allocator type.

### Methods
- `new()` / `empty()` - Constructor
- `init()` / `add_to_heap()` - Add memory regions
- `alloc()` - Allocate memory
- `dealloc()` - Deallocate memory
- `stats_alloc_user()` - User-requested bytes
- `stats_alloc_actual()` - Actual allocated bytes
- `stats_total_bytes()` - Total heap size

### Parameters
#### Associated Type
- `ORDER` (usize) - Specifies the maximum order of blocks the allocator can manage. Common values include 17 (64 KB), 33 (4 GB), and 48 (256 TB).

### Request Example
```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();
unsafe {
    heap.init(0x1000, 0x100000);
}
```
```

--------------------------------

### Frame Allocation Option Handling

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/README.md

Illustrates handling the Option returned by frame allocation. Use the Some variant for successful frame allocations and None when no frames are available.

```rust
match frames.alloc(count) {
    Some(frame) => { /* use frame */ } 
    None => { /* no frames available */ }
}
```

--------------------------------

### LockedHeap::new

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Creates a new empty locked heap. This is a constructor for the LockedHeap.

```APIDOC
## LockedHeap::new

### Description
Creates a new empty locked heap. This is a constructor for the LockedHeap.

### Method
`pub const fn new() -> Self`

### Parameters
Constructor takes no parameters

### Return type:
`LockedHeap<ORDER>`

### Example:
```rust
use buddy_system_allocator::LockedHeap;
use core::mem::size_of;

#[global_allocator]
static HEAP_ALLOCATOR: LockedHeap<33> = LockedHeap::new();

fn main() {
    unsafe {
        HEAP_ALLOCATOR.lock().init(0x1000, 0x100000);
    }
}
```
```

--------------------------------

### Add Memory Ranges to Heap

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Demonstrates how to add contiguous memory ranges or initialize the heap with a specific size. This can be called multiple times to add disjointed ranges.

```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();

unsafe {
    // Option 1: Add a contiguous memory range
    heap.add_to_heap(0x1000, 0x100000);  // Add [0x1000, 0x100000)
    
    // Option 2: Initialize with size
    heap.init(0x1000, 0xFF000);  // Same as above
    
    // Option 3: Add multiple ranges (can be called multiple times)
    heap.add_to_heap(0x200000, 0x300000);
    heap.add_to_heap(0x400000, 0x500000);
}
```

--------------------------------

### Create Empty Linked List with Default Trait

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/linked-list.md

Illustrates creating an empty `LinkedList` using the `Default` trait implementation. This is a convenient way to initialize an empty list.

```rust
use buddy_system_allocator::linked_list::LinkedList;

let list: LinkedList = Default::default();
assert!(list.is_empty());
```

--------------------------------

### FrameAllocator<const ORDER: usize = 33>

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Allocates contiguous ranges of frames (e.g., physical pages) using the buddy system algorithm. This allocator requires a global allocator to be set up.

```APIDOC
## FrameAllocator<const ORDER: usize = 33>

### Description
Allocates contiguous ranges of frames (e.g., physical pages) using buddy system. Requires a global allocator.

### Methods
- `new()` - Constructor
- `add_frame()` / `insert()` - Add frame ranges
- `alloc()` - Allocate frame range
- `alloc_aligned()` - Allocate with alignment
- `alloc_at()` - Allocate at specific frame
- `dealloc()` - Deallocate frame range
- `dealloc_aligned()` - Deallocate aligned range

### Parameters
#### Associated Type
- `ORDER` (usize) - Specifies the maximum order of frames the allocator can manage. Defaults to 33 (2^32 max frames).

### Statistics
- `allocated` - Currently allocated frames
- `total` - Total available frames

### Features
- `alloc` (enabled by default)

### Request Example
```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::new();
frame_alloc.add_frame(0, 1000);
let frame = frame_alloc.alloc(5).expect("allocation failed");
```
```

--------------------------------

### Frame Allocation with Error Handling

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Demonstrates allocating frames using FrameAllocator and handling the case where no frames are available. The error condition is represented by None.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::new();
// ... add frames ...

match frame_alloc.alloc(5) {
    Some(frame) => { /* use frame */ } 
    None => { /* handle no frames available */ }
}
```

--------------------------------

### Heap Allocation with Error Handling

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Shows how to allocate memory using Heap and handle potential out-of-memory errors. The error condition is represented by Err(()).

```rust
use buddy_system_allocator::Heap;
use core::alloc::Layout;

let mut heap = Heap::<33>::new();
// ... initialize ...

let layout = Layout::new::<u64>();
match heap.alloc(layout) {
    Ok(ptr) => { /* use ptr */ } 
    Err(()) => { /* handle OOM */ }
}
```

--------------------------------

### Cargo.toml: Custom Feature Selection for Buddy System Allocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Enables the 'use_spin' feature for the buddy_system_allocator crate, providing LockedHeap but not FrameAllocator.

```toml
[dependencies]
buddy_system_allocator = { version = "0.13", default-features = false, features = ["use_spin"] }
```

--------------------------------

### LinkedList::new()

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/linked-list.md

Creates a new, empty linked list. This constructor takes no parameters.

```APIDOC
## LinkedList::new()

### Description
Creates a new empty linked list.

### Method
`new()`

### Parameters
This constructor takes no parameters.

### Return type
`LinkedList`

### Example
```rust
use buddy_system_allocator::linked_list::LinkedList;

let list = LinkedList::new();
assert!(list.is_empty());
```
```

--------------------------------

### Insert Frames using Range

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/types.md

Demonstrates inserting a range of frames into the `FrameAllocator`. The range `0..1000` includes frames from 0 up to (but not including) 1000.

```rust
use buddy_system_allocator::FrameAllocator;

let mut frame_alloc = FrameAllocator::<33>::new();
frame_alloc.insert(0..1000);  // Add frames 0-999
```

--------------------------------

### Create an empty Heap instance (alias)

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Use `Heap::empty()` as an alias for `Heap::new()` to create an empty heap. The ORDER constant defines the maximum allocation size.

```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::empty();
```

--------------------------------

### Heap Deallocation with Matching Layout

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/quick-start.md

Ensures correct deallocation by using the same `Layout` used for allocation. Mismatched layouts lead to undefined behavior.

```rust
// ❌ WRONG: Using different layout
let layout1 = Layout::new::<u32>();
let ptr = heap.alloc(layout1).ok();
let layout2 = Layout::new::<u64>();
unsafe {
    heap.dealloc(ptr.unwrap(), layout2); // Wrong!
}

// ✅ CORRECT: Use same layout
let layout = Layout::new::<u32>();
if let Ok(ptr) = heap.alloc(layout) {
    unsafe {
        heap.dealloc(ptr, layout);
    }
}
```

--------------------------------

### Buddy System Allocator Feature Selection

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/quick-start.md

Configure specific features for the buddy_system_allocator crate in Cargo.toml to tailor its functionality, such as minimal builds or specific allocator types.

```toml
# Default (recommended): includes both alloc and use_spin
buddy_system_allocator = "0.13"

# Minimal: only Heap type, no thread-safe wrappers or FrameAllocator
buddy_system_allocator = { version = "0.13", default-features = false }

# Only heap allocators with locks (no FrameAllocator)
buddy_system_allocator = { version = "0.13", default-features = false, features = ["use_spin"] }

# Only frame allocators (no locked heap)
buddy_system_allocator = { version = "0.13", default-features = false, features = ["alloc"] }
```

--------------------------------

### Add Multiple Memory Regions to Heap

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Demonstrates how to add multiple, potentially non-contiguous memory regions to a Heap allocator. This allows for flexible memory management.

```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();

unsafe {
    heap.add_to_heap(0x1000_0000, 0x1000_0000 + 0x1000000);
    heap.add_to_heap(0x2000_0000, 0x2000_0000 + 0x1000000);
    heap.add_to_heap(0x3000_0000, 0x3000_0000 + 0x1000000);
}
```

--------------------------------

### Heap::new()

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/api-reference/heap.md

Creates a new empty heap with no memory regions allocated. The ORDER constant determines the maximum allocation size.

```APIDOC
## Heap<ORDER>::new()

### Description
Creates a new empty heap with no memory regions allocated. The ORDER constant parameter determines the maximum allocation size: the buddy system has a maximum order of `ORDER - 1`, allowing allocations up to 2^(ORDER-1) bytes.

### Method
`new()`

### Parameters
This constructor takes no parameters.

### Return type
`Heap<ORDER>`

### Example
```rust
use buddy_system_allocator::Heap;

let mut heap = Heap::<33>::new();
// Maximum block size is 2^32 bytes (ORDER - 1 = 32)
```
```

--------------------------------

### Set Up LockedHeap as Global Allocator

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/module-index.md

Configures LockedHeap as the global allocator for a no_std environment. Requires initialization of the heap with a memory region.

```rust
#![no_std]
extern crate alloc;

use buddy_system_allocator::LockedHeap;

#[global_allocator]
static ALLOCATOR: LockedHeap<33> = LockedHeap::new();

fn init_heap(start: usize, size: usize) {
    unsafe { ALLOCATOR.lock().init(start, size); }
}
```

--------------------------------

### FrameAllocator Frame Range Addition

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/quick-start.md

Illustrates the correct way to add frames to `FrameAllocator`. The frame range must be in ascending order; reversed ranges will cause a panic.

```rust
// ❌ WRONG: Reversed range
let mut frames = FrameAllocator::new();
frames.add_frame(1000, 0); // Panics!

// ✅ CORRECT: Ascending range
let mut frames = FrameAllocator::new();
frames.add_frame(0, 1000); // OK
```

--------------------------------

### Build Configuration: Rust Edition

Source: https://github.com/rcore-os/buddy_system_allocator/blob/master/_autodocs/configuration.md

Specifies the Rust edition for the project, targeting the latest stable features.

```toml
[package]
edition = "2024"
```