patina 21.1.1

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
115
116

//! Macro definitions for the UEFI SDK.
//!
//! ## License
//!
//! Copyright (C) Microsoft Corporation.
//!
//! SPDX-License-Identifier: Apache-2.0
//!

/// Converts a size in bytes to the number of UEFI pages required.
///
/// Takes a size in bytes and calculates the number of UEFI pages needed to accommodate that size.
///
/// # Parameters
///
/// - `$size`: The size in bytes that needs to be converted to UEFI pages.
///
/// # Returns
///
/// The number of UEFI pages required to accommodate the given size.
///
/// # Example
///
/// ```rust
/// use patina::base::UEFI_PAGE_SIZE;
/// use patina::uefi_size_to_pages;
///
/// let size_in_bytes = UEFI_PAGE_SIZE * 3;
/// let pages = uefi_size_to_pages!(size_in_bytes);
/// assert_eq!(pages, 3);
/// ```
///
/// In this example, 3 UEFI pages are required.
#[macro_export]
macro_rules! uefi_size_to_pages {
    ($size:expr) => {
        (($size) + patina::base::UEFI_PAGE_MASK) / patina::base::UEFI_PAGE_SIZE
    };
}

/// Converts a number of UEFI pages to the corresponding size in bytes.
///
/// This macro calculates the total size in bytes by multiplying the given number of UEFI pages
/// by the size of a UEFI page (`UEFI_PAGE_SIZE`).
///
/// # Parameters
///
/// - `$pages`: The number of UEFI pages to be converted to bytes.
///
/// # Returns
///
/// The total size in bytes corresponding to the given number of UEFI pages.
///
/// # Example
///
/// ```rust
/// use patina::base::UEFI_PAGE_SIZE;
/// use patina::uefi_pages_to_size;
///
/// let pages = 3;
/// let size_in_bytes = uefi_pages_to_size!(pages);
/// assert_eq!(size_in_bytes, 3 * UEFI_PAGE_SIZE);
/// ```
///
/// In this example, 3 UEFI pages returns the expected size in bytes.
#[macro_export]
macro_rules! uefi_pages_to_size {
    ($pages:expr) => {
        ($pages) * $crate::base::UEFI_PAGE_SIZE
    };
}

/// Logs an error message and fires a [`debug_assert!`]`(false)` with the same message.
///
/// In debug builds, this will panic after logging. In release builds, only the [`log::error!`] is emitted.
///
/// # Parameters
///
/// - `$($arg)*`: Format string and arguments, passed directly to [`log::error!`] and [`debug_assert!`].
///
/// # Example
///
/// ```rust ignore
/// use patina::log_debug_assert;
///
/// log_debug_assert!("unexpected state: value was {}", value);
/// ```
#[macro_export]
macro_rules! log_debug_assert {
    ($($arg:tt)*) => {{
        log::error!($($arg)*);
        debug_assert!(false, $($arg)*);
    }};
}

/// Macro definitions for working with PCI devices.
pub mod pci {
    /// Constructs a PCI library address from the given bus, device, function, and register values.
    ///
    /// # Arguments
    ///
    /// * `bus` - The PCI bus number (8 bits).
    /// * `device` - The PCI device number (5 bits).
    /// * `function` - The PCI function number (3 bits).
    /// * `register` - The PCI register offset (12 bits).
    ///
    /// # Returns
    ///
    /// A `u32` value representing the PCI library address.
    #[macro_export]
    macro_rules! pci_address {
        ($bus:expr, $device:expr, $function:expr, $register:expr) => {
            (($register & 0xfff) | (($function & 0x07) << 12) | (($device & 0x1f) << 15) | (($bus & 0xff) << 20)) as u32
        };
    }
}