multiboot2: add missing docs

Author: phip1611

multiboot2/Changelog.md

@@ -3,9 +3,11 @@
 ## Unreleased
 
 - **Breaking** All functions that returns something useful are now `#[must_use]`
+- **Breaking** More public fields in tags were replaced by public getters, such
+  as `SmbiosTag::major()`
 - updated dependencies
 - MSRV is 1.75
-- doc fixes
+- documentation enhancements
 - Introduced new `TagHeader` type as replacement for the `Tag` type that will
   be changed in the next step.
 

multiboot2/src/boot_information.rs

@@ -3,14 +3,16 @@
 #[cfg(feature = "builder")]
 use crate::builder::AsBytes;
 use crate::framebuffer::UnknownFramebufferType;
-use crate::tag::TagIter;
+use crate::tag::{TagHeader, TagIter};
 use crate::{
     module, BasicMemoryInfoTag, BootLoaderNameTag, CommandLineTag, EFIBootServicesNotExitedTag,
     EFIImageHandle32Tag, EFIImageHandle64Tag, EFIMemoryMapTag, EFISdt32Tag, EFISdt64Tag,
     ElfSectionIter, ElfSectionsTag, EndTag, FramebufferTag, ImageLoadPhysAddrTag, MemoryMapTag,
     ModuleIter, RsdpV1Tag, RsdpV2Tag, SmbiosTag, TagTrait, VBEInfoTag,
 };
 use core::fmt;
+use core::mem;
+use core::ptr;
 use derive_more::Display;
 
 /// Error type that describes errors while loading/parsing a multiboot2 information structure
@@ -39,19 +41,25 @@ impl core::error::Error for MbiLoadError {}
 #[repr(C)]
 pub struct BootInformationHeader {
     // size is multiple of 8
-    pub total_size: u32,
+    total_size: u32,
     _reserved: u32,
     // Followed by the boot information tags.
 }
 
-#[cfg(feature = "builder")]
 impl BootInformationHeader {
+    #[cfg(feature = "builder")]
     pub(crate) const fn new(total_size: u32) -> Self {
         Self {
             total_size,
             _reserved: 0,
         }
     }
+
+    /// Returns the total size of the structure.
+    #[must_use]
+    pub const fn total_size(&self) -> u32 {
+        self.total_size
+    }
 }
 
 #[cfg(feature = "builder")]
@@ -70,18 +78,18 @@ impl BootInformationInner {
     /// Checks if the MBI has a valid end tag by checking the end of the mbi's
     /// bytes.
     fn has_valid_end_tag(&self) -> bool {
-        let end_tag_prototype = EndTag::default();
-
-        let self_ptr = unsafe { self.tags.as_ptr().sub(size_of::<BootInformationHeader>()) };
+        let self_ptr = ptr::addr_of!(*self);
 
         let end_tag_ptr = unsafe {
             self_ptr
+                .cast::<u8>()
                 .add(self.header.total_size as usize)
-                .sub(size_of::<EndTag>())
+                .sub(mem::size_of::<EndTag>())
+                .cast::<TagHeader>()
         };
-        let end_tag = unsafe { &*(end_tag_ptr as *const EndTag) };
+        let end_tag = unsafe { &*end_tag_ptr };
 
-        end_tag.typ == end_tag_prototype.typ && end_tag.size == end_tag_prototype.size
+        end_tag.typ == EndTag::ID && end_tag.size as usize == mem::size_of::<EndTag>()
     }
 }
 
@@ -127,7 +135,7 @@ impl<'a> BootInformation<'a> {
             return Err(MbiLoadError::IllegalTotalSize(mbi.total_size));
         }
 
-        let slice_size = mbi.total_size as usize - size_of::<BootInformationHeader>();
+        let slice_size = mbi.total_size as usize - mem::size_of::<BootInformationHeader>();
         // mbi: reference to full mbi
         let mbi = ptr_meta::from_raw_parts::<BootInformationInner>(ptr.cast(), slice_size);
         let mbi = &*mbi;

multiboot2/src/boot_loader_name.rs

@@ -19,6 +19,7 @@ pub struct BootLoaderNameTag {
 }
 
 impl BootLoaderNameTag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new(name: &str) -> BoxedDst<Self> {
@@ -30,6 +31,18 @@ impl BootLoaderNameTag {
         BoxedDst::new(&bytes)
     }
 
+    /// Returns the underlying [`TagType`].
+    #[must_use]
+    pub fn typ(&self) -> TagType {
+        self.header.typ.into()
+    }
+
+    /// Returns the underlying tag size.
+    #[must_use]
+    pub const fn size(&self) -> usize {
+        self.header.size as usize
+    }
+
     /// Reads the name of the bootloader that is booting the kernel as Rust
     /// string slice without the null-byte.
     ///

multiboot2/src/builder/mod.rs

@@ -8,8 +8,11 @@ pub use boxed_dst::BoxedDst;
 pub use information::InformationBuilder;
 
 /// Helper trait for all structs that need to be serialized that do not
-/// implement `TagTrait`.
+/// implement [`TagTrait`].
+///
+/// [`TagTrait`]: crate::TagTrait
 pub trait AsBytes: Sized {
+    /// Returns the raw bytes of the type.
     fn as_bytes(&self) -> &[u8] {
         let ptr = core::ptr::addr_of!(*self);
         let size = core::mem::size_of::<Self>();

multiboot2/src/efi.rs

@@ -82,6 +82,7 @@ pub struct EFIImageHandle32Tag {
 }
 
 impl EFIImageHandle32Tag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new(pointer: u32) -> Self {
@@ -114,6 +115,7 @@ pub struct EFIImageHandle64Tag {
 }
 
 impl EFIImageHandle64Tag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new(pointer: u64) -> Self {
@@ -144,6 +146,7 @@ pub struct EFIBootServicesNotExitedTag {
 }
 
 impl EFIBootServicesNotExitedTag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new() -> Self {

multiboot2/src/end.rs

@@ -6,8 +6,8 @@ use crate::{Tag, TagTrait, TagType, TagTypeId};
 #[repr(C)]
 #[derive(Debug)]
 pub struct EndTag {
-    pub typ: TagTypeId,
-    pub size: u32,
+    typ: TagTypeId,
+    size: u32,
 }
 
 impl Default for EndTag {

multiboot2/src/framebuffer.rs

@@ -84,6 +84,7 @@ pub struct FramebufferTag {
 }
 
 impl FramebufferTag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new(

multiboot2/src/image_load_addr.rs

@@ -16,6 +16,7 @@ pub struct ImageLoadPhysAddrTag {
 }
 
 impl ImageLoadPhysAddrTag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new(load_base_addr: u32) -> Self {

multiboot2/src/lib.rs

@@ -12,7 +12,7 @@
 // now allow a few rules which are denied by the above statement
 // --> They are either ridiculous, not necessary, or we can't fix them.
 #![allow(clippy::multiple_crate_versions)]
-// #![deny(missing_docs)]
+#![deny(missing_docs)]
 #![deny(missing_debug_implementations)]
 #![deny(rustdoc::all)]
 // --- END STYLE CHECKS ---

multiboot2/src/memory_map.rs

@@ -35,6 +35,7 @@ pub struct MemoryMapTag {
 }
 
 impl MemoryMapTag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new(areas: &[MemoryArea]) -> BoxedDst<Self> {
@@ -260,21 +261,24 @@ pub struct BasicMemoryInfoTag {
 }
 
 impl BasicMemoryInfoTag {
+    /// Constructs a new tag.
     #[must_use]
     pub fn new(memory_lower: u32, memory_upper: u32) -> Self {
         Self {
-            header: TagHeader::new(Self::ID, size_of::<Self>().try_into().unwrap()),
+            header: TagHeader::new(Self::ID, mem::size_of::<Self>().try_into().unwrap()),
             memory_lower,
             memory_upper,
         }
     }
 
     #[must_use]
+    /// Returns the lower memory bound.
     pub const fn memory_lower(&self) -> u32 {
         self.memory_lower
     }
 
     #[must_use]
+    /// Returns the upper memory bound.
     pub const fn memory_upper(&self) -> u32 {
         self.memory_upper
     }
@@ -317,10 +321,10 @@ pub struct EFIMemoryMapTag {
 }
 
 impl EFIMemoryMapTag {
-    #[cfg(feature = "builder")]
     /// Create a new EFI memory map tag with the given memory descriptors.
     /// Version and size can't be set because you're passing a slice of
     /// EFIMemoryDescs, not the ones you might have gotten from the firmware.
+    #[cfg(feature = "builder")]
     #[must_use]
     pub fn new_from_descs(descs: &[EFIMemoryDesc]) -> BoxedDst<Self> {
         // TODO replace this EfiMemorydesc::uefi_desc_size() in the next uefi_raw
@@ -347,8 +351,8 @@ impl EFIMemoryMapTag {
         )
     }
 
-    #[cfg(feature = "builder")]
     /// Create a new EFI memory map tag from the given EFI memory map.
+    #[cfg(feature = "builder")]
     #[must_use]
     pub fn new_from_map(desc_size: u32, desc_version: u32, efi_mmap: &[u8]) -> BoxedDst<Self> {
         assert!(desc_size > 0);

multiboot2/src/module.rs

@@ -23,6 +23,7 @@ pub struct ModuleTag {
 }
 
 impl ModuleTag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new(start: u32, end: u32, cmdline: &str) -> BoxedDst<Self> {

multiboot2/src/rsdp.rs

@@ -35,6 +35,7 @@ pub struct RsdpV1Tag {
 }
 
 impl RsdpV1Tag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new(
@@ -114,6 +115,7 @@ pub struct RsdpV2Tag {
 }
 
 impl RsdpV2Tag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[allow(clippy::too_many_arguments)]
     #[must_use]

multiboot2/src/smbios.rs

@@ -15,20 +15,39 @@ const METADATA_SIZE: usize = core::mem::size_of::<TagTypeId>()
 #[repr(C)]
 pub struct SmbiosTag {
     header: TagHeader,
-    pub major: u8,
-    pub minor: u8,
+    major: u8,
+    minor: u8,
     _reserved: [u8; 6],
-    pub tables: [u8],
+    tables: [u8],
 }
 
 impl SmbiosTag {
+    /// Constructs a new tag.
     #[cfg(feature = "builder")]
     #[must_use]
     pub fn new(major: u8, minor: u8, tables: &[u8]) -> BoxedDst<Self> {
         let mut bytes = [major, minor, 0, 0, 0, 0, 0, 0].to_vec();
         bytes.extend(tables);
         BoxedDst::new(&bytes)
     }
+
+    /// Returns the major number.
+    #[must_use]
+    pub const fn major(&self) -> u8 {
+        self.major
+    }
+
+    /// Returns the major number.
+    #[must_use]
+    pub const fn minor(&self) -> u8 {
+        self.minor
+    }
+
+    /// Returns the raw tables.
+    #[must_use]
+    pub const fn tables(&self) -> &[u8] {
+        &self.tables
+    }
 }
 
 impl TagTrait for SmbiosTag {

multiboot2/src/tag.rs

@@ -41,14 +41,15 @@ impl core::error::Error for StringError {
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 #[repr(C)]
 pub struct TagHeader {
+    /// The ABI-compatible [`TagType`].
     pub typ: TagTypeId, /* u32 */
+    /// The total size of the tag including the header.
     pub size: u32,
-    // Followed by additional, tag specific fields.
+    // Followed by optional additional tag specific fields.
 }
 
 impl TagHeader {
     /// Creates a new header.
-    #[cfg(feature = "builder")]
     pub fn new(typ: impl Into<TagTypeId>, size: u32) -> Self {
         Self {
             typ: typ.into(),
@@ -67,6 +68,7 @@ impl TagHeader {
 /// different.
 #[derive(Clone, Copy)]
 #[repr(C)]
+#[allow(missing_docs)] // type will be removed soon anyway in its form
 pub struct Tag {
     pub typ: TagTypeId, // u32
     pub size: u32,