patina 21.1.0

Common types and functionality used in UEFI development.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

//! This module provides a Box type whose lifetime is tied to the UEFI Boot Services.
//!
//! ## License
//!
//! Copyright (c) Microsoft Corporation.
//!
//! SPDX-License-Identifier: Apache-2.0
//!
use alloc::slice;
use core::{
    mem,
    ops::{Deref, DerefMut},
    ptr,
};

use super::BootServices;
use crate::efi_types::EfiMemoryType;

/// A boxed type to wrap a [BootServices] implementation
#[derive(Debug)]
pub struct BootServicesBox<'a, T: ?Sized, B: BootServices + ?Sized> {
    ptr: *mut T,
    boot_services: &'a B,
}

impl<'a, T, B: BootServices> BootServicesBox<'a, T, B> {
    /// Create a new BootServicesBox containing the provided value
    pub fn new(value: T, memory_type: EfiMemoryType, boot_services: &'a B) -> Self {
        let size = mem::size_of_val(&value);
        let ptr = boot_services.allocate_pool(memory_type, size).unwrap() as *mut T;
        // SAFETY: ptr was just allocated with the exact size needed for T.
        // The pointer is valid and uninitialized, making ptr::write safe.
        unsafe { ptr::write(ptr, value) };
        Self { boot_services, ptr }
    }

    /// Create a BootServicesBox from the provided raw pointer
    ///
    /// # Safety
    /// ptr must be valid, and must be legal to call boot_services::free_pool(ptr). The easiest way to guarantee this
    /// is to only use from_raw on pointers created by BootServicesBox::into_raw* functions.
    pub unsafe fn from_raw(ptr: *mut T, boot_services: &'a B) -> Self {
        Self { boot_services, ptr }
    }

    /// Consumes the `BootServicesBox`, returning a raw pointer to the underlying data.
    pub fn into_raw(self) -> *const T {
        self.ptr as *const T
    }

    /// Consumes the `BootServicesBox`, returning a mutable raw pointer to the underlying data.
    pub fn into_raw_mut(self) -> *mut T {
        self.ptr
    }

    /// Leaks the box, such that the memory will not be freed even if all references to it are dropped.
    pub fn leak(self) -> &'a mut T {
        // SAFETY: ptr is valid for T as it was allocated by allocate_pool and initialized by ptr::write
        // in new(). The returned reference has lifetime 'a, bounded by the BootServices reference.
        let leak = unsafe { self.ptr.as_mut() }.unwrap();
        mem::forget(self);
        leak
    }
}

impl<'a, T, B: BootServices> BootServicesBox<'a, [T], B> {
    /// Create a boot services box from raw pointer and length.
    ///
    /// # Safety
    ///
    /// Caller must ensure that the pointer and len are correct and that rust pointer invariants (e.g. no aliasing) are respected.
    pub unsafe fn from_raw_parts_mut(ptr: *mut T, len: usize, boot_services: &'a B) -> Self {
        // SAFETY: The caller guarantees that ptr and len are valid and that slice invariants are upheld.
        let ptr = unsafe { slice::from_raw_parts_mut(ptr, len) };
        Self { boot_services, ptr }
    }
}

impl<T: ?Sized, B: BootServices + ?Sized> Drop for BootServicesBox<'_, T, B> {
    fn drop(&mut self) {
        let _ = self.boot_services.free_pool(self.ptr as *mut u8);
    }
}

impl<T: ?Sized, B: BootServices> Deref for BootServicesBox<'_, T, B> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        // SAFETY: ptr is valid and properly initialized. It was created by allocate_pool and
        // initialized by ptr::write, or created through from_raw with a caller safety contract.
        unsafe { self.ptr.as_ref() }.unwrap()
    }
}

impl<T: ?Sized, B: BootServices> DerefMut for BootServicesBox<'_, T, B> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        // SAFETY: ptr is valid and properly initialized. It was created by allocate_pool and
        // initialized by ptr::write, or created through from_raw with a caller safety contract.
        // Exclusive access is ensured by &mut self.
        unsafe { self.ptr.as_mut() }.unwrap()
    }
}

impl<T: ?Sized, B: BootServices> AsRef<T> for BootServicesBox<'_, T, B> {
    fn as_ref(&self) -> &T {
        self.deref()
    }
}

impl<T: ?Sized, B: BootServices> AsMut<T> for BootServicesBox<'_, T, B> {
    fn as_mut(&mut self) -> &mut T {
        self.deref_mut()
    }
}