uefi: Improve clarity of global_allocator

Add more comments and rename some variables.

Author: nicholasbishop

uefi/src/global_allocator.rs

@@ -52,38 +52,60 @@ pub fn exit_boot_services() {
 pub struct Allocator;
 
 unsafe impl GlobalAlloc for Allocator {
+    /// Allocate memory using [`BootServices::allocate_pool`]. The allocation is
+    /// of type [`MemoryType::LOADER_DATA`].
     unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
         let mem_ty = MemoryType::LOADER_DATA;
         let size = layout.size();
         let align = layout.align();
 
         if align > 8 {
-            // allocate more space for alignment
-            let ptr = if let Ok(ptr) = boot_services().as_ref().allocate_pool(mem_ty, size + align)
-            {
-                ptr
-            } else {
-                return ptr::null_mut();
-            };
-            // calculate align offset
-            let mut offset = ptr.align_offset(align);
+            // 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_services().as_ref().allocate_pool(mem_ty, size + align) {
+                    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;
             }
-            let return_ptr = ptr.add(offset);
-            // store allocated pointer before the struct
-            (return_ptr.cast::<*mut u8>()).sub(1).write(ptr);
-            return_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).
+            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_services()
                 .as_ref()
                 .allocate_pool(mem_ty, size)
                 .unwrap_or(ptr::null_mut())
         }
     }
 
+    /// Deallocate memory using [`BootServices::free_pool`].
     unsafe fn dealloc(&self, mut ptr: *mut u8, layout: Layout) {
         if layout.align() > 8 {
+            // Retrieve the pointer to the full allocation that was packed right
+            // before the aligned allocation in `alloc`.
             ptr = (ptr as *const *mut u8).sub(1).read();
         }
         boot_services().as_ref().free_pool(ptr).unwrap();