uefi: allocator: improve documentation and switch to match {}

The refactoring to a match {} block simplifies the following
improvements.

Author: phip1611

uefi/src/allocator.rs

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! This module implements Rust's global allocator interface using UEFI's memory allocation functions.
+//! This module [`Allocator`], which uses UEFI boot services to allocate memory.
 //!
-//! If the `global_allocator` feature is enabled, the [`Allocator`] will be used
+//! By implementing the [`GlobalAlloc`] trait, this type can be designated as the
+//! global allocator using the `#[global_allocator]` attribute. If the
+//! `global_allocator` crate feature is enabled, the [`Allocator`] will be used
 //! as the global Rust allocator.
 //!
 //! This allocator can only be used while boot services are active. If boot
@@ -44,7 +46,8 @@ fn get_memory_type() -> MemoryType {
 
 /// Allocator which uses the UEFI pool allocation functions.
 ///
-/// Only valid for as long as the UEFI boot services are available.
+/// The allocator can only be used as long as the UEFI boot services are
+/// available and have not been exited.
 #[derive(Debug)]
 pub struct Allocator;
 
@@ -63,45 +66,50 @@ unsafe impl GlobalAlloc for Allocator {
         let align = layout.align();
         let memory_type = get_memory_type();
 
-        if align > 8 {
-            // The requested alignment is greater than 8, but `allocate_pool` is
-            // only guaranteed to provide eight-byte alignment. Allocate extra
-            // space so that we can return an appropriately-aligned pointer
-            // within the allocation.
-            let full_alloc_ptr = if let Ok(ptr) = boot::allocate_pool(memory_type, size + align) {
-                ptr.as_ptr()
-            } else {
-                return ptr::null_mut();
-            };
-
-            // Calculate the offset needed to get an aligned pointer within the
-            // full allocation. If that offset is zero, increase it to `align`
-            // so that we still have space to store the extra pointer described
-            // below.
-            let mut offset = full_alloc_ptr.align_offset(align);
-            if offset == 0 {
-                offset = align;
+        match align {
+            0..=8 /* UEFI default alignment */ => {
+                // The requested alignment is less than or equal to eight, and
+                // `allocate_pool` always provides eight-byte alignment, so we can
+                // use `allocate_pool` directly.
+                boot::allocate_pool(memory_type, size)
+                    .map(|ptr| ptr.as_ptr())
+                    .unwrap_or(ptr::null_mut())
             }
+            9.. => {
+                // The requested alignment is greater than 8, but `allocate_pool` is
+                // only guaranteed to provide eight-byte alignment. Allocate extra
+                // space so that we can return an appropriately-aligned pointer
+                // within the allocation.
+                let full_alloc_ptr = boot::allocate_pool(memory_type, size + align);
+                let full_alloc_ptr = if let Ok(ptr) = full_alloc_ptr
+                {
+                    ptr.as_ptr()
+                } else {
+                    return ptr::null_mut();
+                };
+
+                // Calculate the offset needed to get an aligned pointer within the
+                // full allocation. If that offset is zero, increase it to `align`
+                // so that we still have space to store the extra pointer described
+                // below.
+                let mut offset = full_alloc_ptr.align_offset(align);
+                if offset == 0 {
+                    offset = align;
+                }
 
-            // Before returning the aligned allocation, store a pointer to the
-            // full unaligned allocation in the bytes just before the aligned
-            // allocation. We know we have at least eight bytes there due to
-            // adding `align` to the memory allocation size. We also know the
-            // write is appropriately aligned for a `*mut u8` pointer because
-            // `align_ptr` is aligned, and alignments are always powers of two
-            // (as enforced by the `Layout` type).
-            unsafe {
-                let aligned_ptr = full_alloc_ptr.add(offset);
-                (aligned_ptr.cast::<*mut u8>()).sub(1).write(full_alloc_ptr);
-                aligned_ptr
+                // Before returning the aligned allocation, store a pointer to the
+                // full unaligned allocation in the bytes just before the aligned
+                // allocation. We know we have at least eight bytes there due to
+                // adding `align` to the memory allocation size. We also know the
+                // write is appropriately aligned for a `*mut u8` pointer because
+                // `align_ptr` is aligned, and alignments are always powers of two
+                // (as enforced by the `Layout` type).
+                unsafe {
+                    let aligned_ptr = full_alloc_ptr.add(offset);
+                    (aligned_ptr.cast::<*mut u8>()).sub(1).write(full_alloc_ptr);
+                    aligned_ptr
+                }
             }
-        } else {
-            // The requested alignment is less than or equal to eight, and
-            // `allocate_pool` always provides eight-byte alignment, so we can
-            // use `allocate_pool` directly.
-            boot::allocate_pool(memory_type, size)
-                .map(|ptr| ptr.as_ptr())
-                .unwrap_or(ptr::null_mut())
         }
     }