Merge pull request #151 from rust-osdev/dev3

multiboot2: more tag name streamlining

Author: phip1611

multiboot2/Changelog.md

@@ -22,6 +22,10 @@
 - **BREAKING** Renamed `ImageLoadPhysAddr` to `ImageLoadPhysAddrTag`
 - **BREAKING** Renamed `EFIImageHandle32` to `EFIImageHandle32Tag`
 - **BREAKING** Renamed `EFIImageHandle64` to `EFIImageHandle64Tag`
+- **BREAKING** Renamed `EFISdt32` to `EFISdt32Tag`
+- **BREAKING** Renamed `EFISdt64` to `EFISdt64Tag`
+- **BREAKING** Renamed `EFIBootServicesNotExited` to `EFIBootServicesNotExitedTag`
+- added `BootInformation::efi_bs_not_exited_tag`
 
 ## 0.15.1 (2023-03-18)
 - **BREAKING** `MemoryMapTag::all_memory_areas()` was renamed to `memory_areas`

multiboot2/src/builder/information.rs

@@ -2,9 +2,9 @@
 use crate::builder::traits::StructAsBytes;
 use crate::{
     BasicMemoryInfoTag, BootInformationInner, BootLoaderNameTag, CommandLineTag,
-    EFIBootServicesNotExited, EFIImageHandle32Tag, EFIImageHandle64Tag, EFIMemoryMapTag, EFISdt32,
-    EFISdt64, ElfSectionsTag, EndTag, FramebufferTag, ImageLoadPhysAddrTag, MemoryMapTag,
-    ModuleTag, RsdpV1Tag, RsdpV2Tag, SmbiosTag,
+    EFIBootServicesNotExitedTag, EFIImageHandle32Tag, EFIImageHandle64Tag, EFIMemoryMapTag,
+    EFISdt32Tag, EFISdt64Tag, ElfSectionsTag, EndTag, FramebufferTag, ImageLoadPhysAddrTag,
+    MemoryMapTag, ModuleTag, RsdpV1Tag, RsdpV2Tag, SmbiosTag,
 };
 
 use alloc::boxed::Box;
@@ -19,7 +19,7 @@ pub struct InformationBuilder {
     basic_memory_info_tag: Option<BasicMemoryInfoTag>,
     boot_loader_name_tag: Option<Box<BootLoaderNameTag>>,
     command_line_tag: Option<Box<CommandLineTag>>,
-    efi_boot_services_not_exited: Option<EFIBootServicesNotExited>,
+    efi_boot_services_not_exited: Option<EFIBootServicesNotExitedTag>,
     efi_image_handle32: Option<EFIImageHandle32Tag>,
     efi_image_handle64: Option<EFIImageHandle64Tag>,
     efi_memory_map_tag: Option<Box<EFIMemoryMapTag>>,
@@ -28,8 +28,8 @@ pub struct InformationBuilder {
     image_load_addr: Option<ImageLoadPhysAddrTag>,
     memory_map_tag: Option<Box<MemoryMapTag>>,
     module_tags: Vec<Box<ModuleTag>>,
-    efisdt32: Option<EFISdt32>,
-    efisdt64: Option<EFISdt64>,
+    efisdt32: Option<EFISdt32Tag>,
+    efisdt64: Option<EFISdt64Tag>,
     rsdp_v1_tag: Option<RsdpV1Tag>,
     rsdp_v2_tag: Option<RsdpV2Tag>,
     smbios_tags: Vec<Box<SmbiosTag>>,
@@ -229,16 +229,16 @@ impl InformationBuilder {
         self.command_line_tag = Some(command_line_tag);
     }
 
-    pub fn efisdt32(&mut self, efisdt32: EFISdt32) {
+    pub fn efisdt32(&mut self, efisdt32: EFISdt32Tag) {
         self.efisdt32 = Some(efisdt32);
     }
 
-    pub fn efisdt64(&mut self, efisdt64: EFISdt64) {
+    pub fn efisdt64(&mut self, efisdt64: EFISdt64Tag) {
         self.efisdt64 = Some(efisdt64);
     }
 
     pub fn efi_boot_services_not_exited(&mut self) {
-        self.efi_boot_services_not_exited = Some(EFIBootServicesNotExited::new());
+        self.efi_boot_services_not_exited = Some(EFIBootServicesNotExitedTag::new());
     }
 
     pub fn efi_image_handle32(&mut self, efi_image_handle32: EFIImageHandle32Tag) {

multiboot2/src/efi.rs

@@ -8,16 +8,16 @@ use core::mem::size_of;
 #[cfg(feature = "builder")]
 use crate::builder::traits::StructAsBytes;
 
-/// EFI system table in 32 bit mode
+/// EFI system table in 32 bit mode tag.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(C)]
-pub struct EFISdt32 {
+pub struct EFISdt32Tag {
     typ: TagTypeId,
     size: u32,
     pointer: u32,
 }
 
-impl EFISdt32 {
+impl EFISdt32Tag {
     /// Create a new tag to pass the EFI32 System Table pointer.
     pub fn new(pointer: u32) -> Self {
         Self {
@@ -34,22 +34,22 @@ impl EFISdt32 {
 }
 
 #[cfg(feature = "builder")]
-impl StructAsBytes for EFISdt32 {
+impl StructAsBytes for EFISdt32Tag {
     fn byte_size(&self) -> usize {
         size_of::<Self>()
     }
 }
 
-/// EFI system table in 64 bit mode
+/// EFI system table in 64 bit mode tag.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(C)]
-pub struct EFISdt64 {
+pub struct EFISdt64Tag {
     typ: TagTypeId,
     size: u32,
     pointer: u64,
 }
 
-impl EFISdt64 {
+impl EFISdt64Tag {
     /// Create a new tag to pass the EFI64 System Table pointer.
     pub fn new(pointer: u64) -> Self {
         Self {
@@ -66,7 +66,7 @@ impl EFISdt64 {
 }
 
 #[cfg(feature = "builder")]
-impl StructAsBytes for EFISdt64 {
+impl StructAsBytes for EFISdt64Tag {
     fn byte_size(&self) -> usize {
         size_of::<Self>()
     }
@@ -140,19 +140,19 @@ impl StructAsBytes for EFIImageHandle64Tag {
 
 #[cfg(all(test, feature = "builder"))]
 mod tests {
-    use super::{EFIImageHandle32Tag, EFIImageHandle64Tag, EFISdt32, EFISdt64};
+    use super::{EFIImageHandle32Tag, EFIImageHandle64Tag, EFISdt32Tag, EFISdt64Tag};
 
     const ADDR: usize = 0xABCDEF;
 
     #[test]
     fn test_build_eftsdt32() {
-        let tag = EFISdt32::new(ADDR.try_into().unwrap());
+        let tag = EFISdt32Tag::new(ADDR.try_into().unwrap());
         assert_eq!(tag.sdt_address(), ADDR);
     }
 
     #[test]
     fn test_build_eftsdt64() {
-        let tag = EFISdt64::new(ADDR.try_into().unwrap());
+        let tag = EFISdt64Tag::new(ADDR.try_into().unwrap());
         assert_eq!(tag.sdt_address(), ADDR);
     }
 

multiboot2/src/framebuffer.rs

@@ -50,7 +50,7 @@ const METADATA_SIZE: usize = size_of::<TagTypeId>()
     + size_of::<u16>()
     + 2 * size_of::<u8>();
 
-/// The VBE Framebuffer information Tag.
+/// The VBE Framebuffer information tag.
 #[derive(ptr_meta::Pointee, Eq)]
 #[repr(C)]
 pub struct FramebufferTag {

multiboot2/src/image_load_addr.rs

@@ -5,8 +5,9 @@ use {
     core::mem::size_of,
 };
 
-/// If the image has relocatable header tag, this tag contains the image's
-/// base physical address.
+/// The physical load address tag. Typically, this is only available if the
+/// binary was relocated, for example if the relocatable header tag was
+/// specified.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(C)]
 pub struct ImageLoadPhysAddrTag {

multiboot2/src/lib.rs

@@ -50,14 +50,14 @@ pub use boot_loader_name::BootLoaderNameTag;
 #[cfg(feature = "builder")]
 use builder::traits::StructAsBytes;
 pub use command_line::CommandLineTag;
-pub use efi::{EFIImageHandle32Tag, EFIImageHandle64Tag, EFISdt32, EFISdt64};
+pub use efi::{EFIImageHandle32Tag, EFIImageHandle64Tag, EFISdt32Tag, EFISdt64Tag};
 pub use elf_sections::{
     ElfSection, ElfSectionFlags, ElfSectionIter, ElfSectionType, ElfSectionsTag,
 };
 pub use framebuffer::{FramebufferColor, FramebufferField, FramebufferTag, FramebufferType};
 pub use image_load_addr::ImageLoadPhysAddrTag;
 pub use memory_map::{
-    BasicMemoryInfoTag, EFIBootServicesNotExited, EFIMemoryAreaType, EFIMemoryDesc,
+    BasicMemoryInfoTag, EFIBootServicesNotExitedTag, EFIMemoryAreaType, EFIMemoryDesc,
     EFIMemoryMapTag, MemoryArea, MemoryAreaType, MemoryMapTag,
 };
 pub use module::{ModuleIter, ModuleTag};
@@ -303,13 +303,13 @@ impl BootInformation {
     }
 
     /// Search for the EFI 32-bit SDT tag.
-    pub fn efi_sdt_32_tag(&self) -> Option<&EFISdt32> {
-        self.get_tag::<EFISdt32, _>(TagType::Efi32)
+    pub fn efi_sdt_32_tag(&self) -> Option<&EFISdt32Tag> {
+        self.get_tag::<EFISdt32Tag, _>(TagType::Efi32)
     }
 
     /// Search for the EFI 64-bit SDT tag.
-    pub fn efi_sdt_64_tag(&self) -> Option<&EFISdt64> {
-        self.get_tag::<EFISdt64, _>(TagType::Efi64)
+    pub fn efi_sdt_64_tag(&self) -> Option<&EFISdt64Tag> {
+        self.get_tag::<EFISdt64Tag, _>(TagType::Efi64)
     }
 
     /// Search for the (ACPI 1.0) RSDP tag.
@@ -345,6 +345,11 @@ impl BootInformation {
         self.get_tag::<EFIImageHandle64Tag, _>(TagType::Efi64Ih)
     }
 
+    /// Search for the EFI boot services not exited tag.
+    pub fn efi_bs_not_exited_tag(&self) -> Option<&EFIBootServicesNotExitedTag> {
+        self.get_tag::<EFIBootServicesNotExitedTag, _>(TagType::EfiBs)
+    }
+
     /// Search for the Image Load Base Physical Address tag.
     pub fn load_base_addr_tag(&self) -> Option<&ImageLoadPhysAddrTag> {
         self.get_tag::<ImageLoadPhysAddrTag, _>(TagType::LoadBaseAddr)

multiboot2/src/memory_map.rs

@@ -12,7 +12,7 @@ use {crate::builder::boxed_dst_tag, crate::builder::traits::StructAsBytes, alloc
 
 const METADATA_SIZE: usize = mem::size_of::<TagTypeId>() + 3 * mem::size_of::<u32>();
 
-/// This tag provides an initial host memory map.
+/// This tag provides an initial host memory map (legacy boot, not UEFI).
 ///
 /// The map provided is guaranteed to list all standard RAM that should be
 /// available for normal use. This type however includes the regions occupied
@@ -151,20 +151,18 @@ pub enum MemoryAreaType {
     Defective = 5,
 }
 
-/// Basic memory info
+/// Basic memory info tag.
+///
+/// This tag includes "basic memory information". This means (legacy) lower and
+/// upper memory: In Real Mode (modeled after the 8086), only the first 1MB of
+/// memory is accessible. Typically, the region between 640KB and 1MB is not
+/// freely usable, because it is used for memory-mapped IO, for instance. The
+/// term “lower memory” refers to those first 640KB of memory that are freely
+/// usable for an application in Real Mode. “Upper memory” then refers to the
+/// next freely usable chunk of memory, starting at 1MB up to about 10MB, in
+/// practice. This is the memory an application running on a 286 (which had a
+/// 24-bit address bus) could use, historically.
 ///
-/// This tag includes "basic memory information".
-/// This means (legacy) lower and upper memory:
-/// In Real Mode (modeled after the 8086),
-/// only the first 1MB of memory is accessible.
-/// Typically, the region between 640KB and 1MB is not freely usable,
-/// because it is used for memory-mapped IO, for instance.
-/// The term “lower memory” refers to those first 640KB of memory that are
-/// freely usable for an application in Real Mode.
-/// “Upper memory” then refers to the next freely usable chunk of memory,
-/// starting at 1MB up to about 10MB, in practice.
-/// This is the memory an application running on a 286
-/// (which had a 24-bit address bus) could use, historically.
 /// Nowadays, much bigger chunks of continuous memory are available at higher
 /// addresses, but the Multiboot standard still references those two terms.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -204,7 +202,7 @@ impl StructAsBytes for BasicMemoryInfoTag {
 
 const EFI_METADATA_SIZE: usize = mem::size_of::<TagTypeId>() + 3 * mem::size_of::<u32>();
 
-/// EFI memory map as per EFI specification.
+/// EFI memory map tag. The [`EFIMemoryDesc`] follows the EFI specification.
 #[derive(ptr_meta::Pointee, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(C)]
 pub struct EFIMemoryMapTag {
@@ -274,23 +272,23 @@ impl StructAsBytes for EFIMemoryDesc {
     }
 }
 
-/// EFI ExitBootServices was not called
+/// EFI ExitBootServices was not called tag.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(C)]
-pub struct EFIBootServicesNotExited {
+pub struct EFIBootServicesNotExitedTag {
     typ: TagTypeId,
     size: u32,
 }
 
-impl EFIBootServicesNotExited {
+impl EFIBootServicesNotExitedTag {
     #[cfg(feature = "builder")]
     pub fn new() -> Self {
         Self::default()
     }
 }
 
 #[cfg(feature = "builder")]
-impl Default for EFIBootServicesNotExited {
+impl Default for EFIBootServicesNotExitedTag {
     fn default() -> Self {
         Self {
             typ: TagType::EfiBs.into(),
@@ -300,7 +298,7 @@ impl Default for EFIBootServicesNotExited {
 }
 
 #[cfg(feature = "builder")]
-impl StructAsBytes for EFIBootServicesNotExited {
+impl StructAsBytes for EFIBootServicesNotExitedTag {
     fn byte_size(&self) -> usize {
         mem::size_of::<Self>()
     }

multiboot2/src/module.rs

@@ -12,8 +12,9 @@ use {
 
 const METADATA_SIZE: usize = size_of::<TagTypeId>() + 3 * size_of::<u32>();
 
-/// This tag indicates to the kernel what boot module was loaded along with
-/// the kernel image, and where it can be found.
+/// The module tag can occur multiple times and specifies passed boot modules
+/// (blobs in memory). The tag itself doesn't include the blog, but references
+/// its location.
 #[derive(ptr_meta::Pointee, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(C)]
 pub struct ModuleTag {