uefi 0.37.0

This crate makes it easy to develop Rust software that leverages safe, convenient, and performant abstractions for UEFI functionality.
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
115
116
117
118

// SPDX-License-Identifier: MIT OR Apache-2.0

//! Protocol with utility functions for working with device paths.

use super::{DevicePath, DevicePathNode, PoolDevicePath};
use crate::mem::PoolAllocation;
use core::ptr::NonNull;
use uefi_macros::unsafe_protocol;
use uefi_raw::Status;
use uefi_raw::protocol::device_path::DevicePathUtilitiesProtocol;

/// Protocol with utility functions for working with device paths.
#[derive(Debug)]
#[repr(transparent)]
#[unsafe_protocol(DevicePathUtilitiesProtocol::GUID)]
pub struct DevicePathUtilities(DevicePathUtilitiesProtocol);

impl DevicePathUtilities {
    /// Retrieves the size of the specified device path in bytes, including the
    /// end-of-device-path node.
    ///
    /// # Arguments
    /// - `device_path`: A reference to the [`DevicePath`] whose size is to be determined.
    ///
    /// # Returns
    /// The size of the specified device path in bytes.
    #[must_use]
    pub fn get_size(&self, device_path: &DevicePath) -> usize {
        unsafe { (self.0.get_device_path_size)(device_path.as_ffi_ptr().cast()) }
    }

    /// Create a new device path by cloning the given `path` into newly allocated memory.
    ///
    /// # Arguments
    /// - `path`: A reference to the device path to clone.
    ///
    /// # Returns
    /// A [`PoolDevicePath`] instance created by cloning the given `path`.
    pub fn duplicate_path(&self, path: &DevicePath) -> crate::Result<PoolDevicePath> {
        unsafe {
            let ptr = (self.0.duplicate_device_path)(path.as_ffi_ptr().cast());
            NonNull::new(ptr.cast_mut())
                .map(|p| PoolDevicePath(PoolAllocation::new(p.cast())))
                .ok_or_else(|| Status::OUT_OF_RESOURCES.into())
        }
    }

    /// Creates a new device path by appending the second device path to the first.
    ///
    /// # Arguments
    /// - `path0`: A reference to the base device path.
    /// - `path1`: A reference to the device path to append.
    ///
    /// # Returns
    /// A [`PoolDevicePath`] instance containing the newly created device path,
    /// or an error if memory could not be allocated.
    pub fn append_path(
        &self,
        path0: &DevicePath,
        path1: &DevicePath,
    ) -> crate::Result<PoolDevicePath> {
        unsafe {
            let ptr =
                (self.0.append_device_path)(path0.as_ffi_ptr().cast(), path1.as_ffi_ptr().cast());
            NonNull::new(ptr.cast_mut())
                .map(|p| PoolDevicePath(PoolAllocation::new(p.cast())))
                .ok_or_else(|| Status::OUT_OF_RESOURCES.into())
        }
    }

    /// Creates a new device path by appending a device node to the base device path.
    ///
    /// # Arguments
    /// - `basepath`: A reference to the base device path.
    /// - `node`: A reference to the device node to append.
    ///
    /// # Returns
    /// A [`PoolDevicePath`] instance containing the newly created device path,
    /// or an error if memory could not be allocated.
    pub fn append_node(
        &self,
        basepath: &DevicePath,
        node: &DevicePathNode,
    ) -> crate::Result<PoolDevicePath> {
        unsafe {
            let ptr =
                (self.0.append_device_node)(basepath.as_ffi_ptr().cast(), node.as_ffi_ptr().cast());
            NonNull::new(ptr.cast_mut())
                .map(|p| PoolDevicePath(PoolAllocation::new(p.cast())))
                .ok_or_else(|| Status::OUT_OF_RESOURCES.into())
        }
    }

    /// Creates a new device path by appending the specified device path instance to the base path.
    ///
    /// # Arguments
    /// - `basepath`: A reference to the base device path.
    /// - `instance`: A reference to the device path instance to append.
    ///
    /// # Returns
    /// A [`PoolDevicePath`] instance containing the newly created device path,
    /// or an error if memory could not be allocated.
    pub fn append_instance(
        &self,
        basepath: &DevicePath,
        instance: &DevicePath,
    ) -> crate::Result<PoolDevicePath> {
        unsafe {
            let ptr = (self.0.append_device_path_instance)(
                basepath.as_ffi_ptr().cast(),
                instance.as_ffi_ptr().cast(),
            );
            NonNull::new(ptr.cast_mut())
                .map(|p| PoolDevicePath(PoolAllocation::new(p.cast())))
                .ok_or_else(|| Status::OUT_OF_RESOURCES.into())
        }
    }
}