Merge pull request #76 from phip1611/debug-format-improved

much improved debug output of BootInformation + enum TagType

src/elf_sections.rs

@@ -1,4 +1,5 @@
 use header::Tag;
+use core::fmt::{Formatter, Debug};
 
 /// This tag contains section header table from an ELF kernel.
 ///
@@ -41,7 +42,7 @@ impl ElfSectionsTag {
     ///     }
     /// }
     /// ```
-    pub fn sections(&self) -> impl Iterator<Item = ElfSection> {
+    pub fn sections(&self) -> ElfSectionIter {
         let string_section_offset = (self.get().shndx * self.get().entry_size) as isize;
         let string_section_ptr =
             unsafe { self.first_section().offset(string_section_offset) as *const _ };
@@ -64,7 +65,7 @@ impl ElfSectionsTag {
 }
 
 /// An iterator over some ELF sections.
-#[derive(Clone, Debug)]
+#[derive(Clone)]
 pub struct ElfSectionIter {
     current_section: *const u8,
     remaining_sections: u32,
@@ -96,6 +97,28 @@ impl Iterator for ElfSectionIter {
     }
 }
 
+impl Debug for ElfSectionIter {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        let mut debug = f.debug_list();
+        self.clone().for_each(|ref e| {
+            debug.entry(e);
+        });
+        debug.finish()
+    }
+}
+
+impl Default for ElfSectionIter {
+    fn default() -> Self {
+        Self {
+            current_section: core::ptr::null(),
+            remaining_sections: 0,
+            entry_size: 0,
+            string_section: core::ptr::null(),
+            offset: 0
+        }
+    }
+}
+
 /// A single generic ELF Section.
 #[derive(Debug)]
 pub struct ElfSection {

src/header.rs

@@ -1,13 +1,95 @@
 use core::marker::PhantomData;
+use core::fmt::{Debug, Formatter};
+use core::cmp::Ordering;
 
-#[derive(Clone, Copy, Debug)]
+/// Possible Types of a [`Tag`]. The names and values are taken from the example C code
+/// at the bottom of the Multiboot2 specification.
+#[repr(u32)]
+#[derive(Copy, Clone, Debug)]
+pub enum TagType {
+    End = 0,
+    Cmdline = 1,
+    BootLoaderName = 2,
+    Module = 3,
+    BasicMeminfo = 4,
+    Bootdev = 5,
+    Mmap = 6,
+    Vbe = 7,
+    Framebuffer = 8,
+    ElfSections = 9,
+    Apm = 10,
+    Efi32 = 11,
+    Efi64 = 12,
+    Smbios = 13,
+    /// Also called "AcpiOld" in other multiboot2 implementations.
+    AcpiV1 = 14,
+    /// Refers to version 2 and later of Acpi.
+    /// Also called "AcpiNew" in other multiboot2 implementations.
+    AcpiV2 = 15,
+    Network = 16,
+    EfiMmap = 17,
+    EfiBs = 18,
+    Efi32Ih = 19,
+    Efi64Ih = 20,
+    LoadBaseAddr = 21,
+}
+
+// each compare/equal direction must be implemented manually
+impl PartialEq<u32> for TagType {
+    fn eq(&self, other: &u32) -> bool {
+        *self as u32 == *other
+    }
+}
+
+// each compare/equal direction must be implemented manually
+impl PartialEq<TagType> for u32 {
+    fn eq(&self, other: &TagType) -> bool {
+        *self == *other as u32
+    }
+}
+
+impl PartialEq<TagType> for TagType {
+    fn eq(&self, other: &TagType) -> bool {
+        *self as u32 == *other as u32
+    }
+}
+
+impl PartialOrd<u32> for TagType {
+    fn partial_cmp(&self, other: &u32) -> Option<Ordering> {
+        let num = *self as u32;
+        Some(
+            if num < *other {
+                Ordering::Less
+            } else if num == *other {
+                Ordering::Equal
+            } else {
+                Ordering::Greater
+            }
+        )
+    }
+}
+
+/// All tags that could passed via the Multiboot2 information structure to a payload/program/kernel.
+/// Better not confuse this with the Multiboot2 header tags. They are something different.
+#[derive(Clone, Copy)]
 #[repr(C)]
 pub struct Tag {
-    pub typ: u32,
+    // u32 value
+    pub typ: TagType,
     pub size: u32,
     // tag specific fields
 }
 
+impl Debug for Tag {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        f.debug_struct("Tag")
+            .field("typ", &self.typ)
+            .field("typ (numeric)", &(self.typ as u32))
+            .field("size", &(self.size))
+            .finish()
+    }
+}
+
 #[derive(Clone, Debug)]
 pub struct TagIter<'a> {
     pub current: *const Tag,
@@ -28,7 +110,7 @@ impl<'a> Iterator for TagIter<'a> {
 
     fn next(&mut self) -> Option<&'a Tag> {
         match unsafe { &*self.current } {
-            &Tag { typ: 0, size: 8 } => None, // end tag
+            &Tag { typ: TagType::End, size: 8 } => None, // end tag
             tag => {
                 // go to next tag
                 let mut tag_addr = self.current as usize;

src/lib.rs

@@ -16,7 +16,7 @@ pub use elf_sections::{
     ElfSection, ElfSectionFlags, ElfSectionIter, ElfSectionType, ElfSectionsTag,
 };
 pub use framebuffer::{FramebufferColor, FramebufferField, FramebufferTag, FramebufferType};
-use header::{Tag, TagIter};
+use header::{Tag, TagIter, TagType};
 pub use memory_map::{
     EFIMemoryAreaType, EFIMemoryDesc, EFIMemoryMapTag, MemoryArea, MemoryAreaIter, MemoryAreaType,
     MemoryMapTag,
@@ -131,59 +131,59 @@ impl BootInformation {
 
     /// Search for the ELF Sections tag.
     pub fn elf_sections_tag(&self) -> Option<ElfSectionsTag> {
-        self.get_tag(9)
+        self.get_tag(TagType::ElfSections)
             .map(|tag| unsafe { elf_sections::elf_sections_tag(tag, self.offset) })
     }
 
     /// Search for the Memory map tag.
     pub fn memory_map_tag<'a>(&'a self) -> Option<&'a MemoryMapTag> {
-        self.get_tag(6)
+        self.get_tag(TagType::Mmap)
             .map(|tag| unsafe { &*(tag as *const Tag as *const MemoryMapTag) })
     }
 
     /// Get an iterator of all module tags.
-    pub fn module_tags(&self) -> impl Iterator<Item = &ModuleTag> {
+    pub fn module_tags(&self) -> ModuleIter {
         module::module_iter(self.tags())
     }
 
     /// Search for the BootLoader name tag.
     pub fn boot_loader_name_tag<'a>(&'a self) -> Option<&'a BootLoaderNameTag> {
-        self.get_tag(2)
+        self.get_tag(TagType::BootLoaderName)
             .map(|tag| unsafe { &*(tag as *const Tag as *const BootLoaderNameTag) })
     }
 
     /// Search for the Command line tag.
     pub fn command_line_tag<'a>(&'a self) -> Option<&'a CommandLineTag> {
-        self.get_tag(1)
+        self.get_tag(TagType::Cmdline)
             .map(|tag| unsafe { &*(tag as *const Tag as *const CommandLineTag) })
     }
 
     /// Search for the VBE framebuffer tag.
     pub fn framebuffer_tag<'a>(&'a self) -> Option<FramebufferTag<'a>> {
-        self.get_tag(8).map(|tag| framebuffer::framebuffer_tag(tag))
+        self.get_tag(TagType::Framebuffer).map(|tag| framebuffer::framebuffer_tag(tag))
     }
 
     /// Search for the EFI 32-bit SDT tag.
     pub fn efi_sdt_32_tag<'a>(&self) -> Option<&'a EFISdt32> {
-        self.get_tag(11)
+        self.get_tag(TagType::Efi32)
             .map(|tag| unsafe { &*(tag as *const Tag as *const EFISdt32) })
     }
 
     /// Search for the EFI 64-bit SDT tag.
     pub fn efi_sdt_64_tag<'a>(&self) -> Option<&'a EFISdt64> {
-        self.get_tag(12)
+        self.get_tag(TagType::Efi64)
             .map(|tag| unsafe { &*(tag as *const Tag as *const EFISdt64) })
     }
 
     /// Search for the (ACPI 1.0) RSDP tag.
     pub fn rsdp_v1_tag<'a>(&self) -> Option<&'a RsdpV1Tag> {
-        self.get_tag(14)
+        self.get_tag(TagType::AcpiV1)
             .map(|tag| unsafe { &*(tag as *const Tag as *const RsdpV1Tag) })
     }
 
     /// Search for the (ACPI 2.0 or later) RSDP tag.
     pub fn rsdp_v2_tag<'a>(&'a self) -> Option<&'a RsdpV2Tag> {
-        self.get_tag(15)
+        self.get_tag(TagType::AcpiV2)
             .map(|tag| unsafe { &*(tag as *const Tag as *const RsdpV2Tag) })
     }
 
@@ -191,35 +191,35 @@ impl BootInformation {
     pub fn efi_memory_map_tag<'a>(&'a self) -> Option<&'a EFIMemoryMapTag> {
         // If the EFIBootServicesNotExited is present, then we should not use
         // the memory map, as it could still be in use.
-        match self.get_tag(18) {
+        match self.get_tag(TagType::EfiBs) {
             Some(_tag) => None,
             None => self
-                .get_tag(17)
+                .get_tag(TagType::EfiMmap)
                 .map(|tag| unsafe { &*(tag as *const Tag as *const EFIMemoryMapTag) }),
         }
     }
 
     /// Search for the EFI 32-bit image handle pointer.
     pub fn efi_32_ih<'a>(&'a self) -> Option<&'a EFIImageHandle32> {
-        self.get_tag(19)
+        self.get_tag(TagType::Efi32Ih)
             .map(|tag| unsafe { &*(tag as *const Tag as *const EFIImageHandle32) })
     }
 
     /// Search for the EFI 64-bit image handle pointer.
     pub fn efi_64_ih<'a>(&'a self) -> Option<&'a EFIImageHandle64> {
-        self.get_tag(20)
+        self.get_tag(TagType::Efi64Ih)
             .map(|tag| unsafe { &*(tag as *const Tag as *const EFIImageHandle64) })
     }
 
     /// Search for the Image Load Base Physical Address.
     pub fn load_base_addr<'a>(&'a self) -> Option<&'a ImageLoadPhysAddr> {
-        self.get_tag(21)
+        self.get_tag(TagType::LoadBaseAddr)
             .map(|tag| unsafe { &*(tag as *const Tag as *const ImageLoadPhysAddr) })
     }
 
     /// Search for the VBE information tag.
     pub fn vbe_info_tag(&self) -> Option<&'static VBEInfoTag> {
-        self.get_tag(7)
+        self.get_tag(TagType::Vbe)
             .map(|tag| unsafe { &*(tag as *const Tag as *const VBEInfoTag) })
     }
 
@@ -227,7 +227,7 @@ impl BootInformation {
         unsafe { &*self.inner }
     }
 
-    fn get_tag<'a>(&'a self, typ: u32) -> Option<&'a Tag> {
+    fn get_tag<'a>(&'a self, typ: TagType) -> Option<&'a Tag> {
         self.tags().find(|tag| tag.typ == typ)
     }
 
@@ -238,7 +238,7 @@ impl BootInformation {
 
 impl BootInformationInner {
     fn has_valid_end_tag(&self) -> bool {
-        const END_TAG: Tag = Tag { typ: 0, size: 8 };
+        const END_TAG: Tag = Tag { typ: TagType::End, size: 8 };
 
         let self_ptr = self as *const _;
         let end_tag_addr = self_ptr as usize + (self.total_size - END_TAG.size) as usize;
@@ -250,64 +250,59 @@ impl BootInformationInner {
 
 impl fmt::Debug for BootInformation {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        writeln!(f, "multiboot information")?;
-
-        writeln!(
-            f,
-            "S: {:#010X}, E: {:#010X}, L: {:#010X}",
-            self.start_address(),
-            self.end_address(),
-            self.total_size()
-        )?;
-
-        if let Some(boot_loader_name_tag) = self.boot_loader_name_tag() {
-            writeln!(f, "boot loader name: {}", boot_loader_name_tag.name())?;
-        }
-
-        if let Some(command_line_tag) = self.command_line_tag() {
-            writeln!(f, "command line: {}", command_line_tag.command_line())?;
-        }
-
-        if let Some(memory_map_tag) = self.memory_map_tag() {
-            writeln!(f, "memory areas:")?;
-            for area in memory_map_tag.memory_areas() {
-                writeln!(
-                    f,
-                    "    S: {:#010X}, E: {:#010X}, L: {:#010X}",
-                    area.start_address(),
-                    area.end_address(),
-                    area.size()
-                )?;
-            }
-        }
-
-        if let Some(elf_sections_tag) = self.elf_sections_tag() {
-            writeln!(f, "kernel sections:")?;
-            for s in elf_sections_tag.sections() {
-                writeln!(
-                    f,
-                    "    name: {:15}, S: {:#08X}, E: {:#08X}, L: {:#08X}, F: {:#04X}",
-                    s.name(),
-                    s.start_address(),
-                    s.start_address() + s.size(),
-                    s.size(),
-                    s.flags().bits()
-                )?;
-            }
-        }
-
-        writeln!(f, "module tags:")?;
-        for mt in self.module_tags() {
-            writeln!(
-                f,
-                "    name: {:15}, S: {:#010X}, E: {:#010X}",
-                mt.name(),
-                mt.start_address(),
-                mt.end_address()
-            )?;
+        /// Limit how many Elf-Sections should be debug-formatted.
+        /// Can be thousands of sections for a Rust binary => this is useless output.
+        /// If the user really wants this, they should debug-format the field directly.
+        const ELF_SECTIONS_LIMIT: usize = 17;
+
+        let mut debug = f.debug_struct("Multiboot2 Boot Information");
+        debug.field("start_address", &(self.start_address() as *const u64))
+            .field("end_address", &(self.end_address() as *const u64))
+            .field("total_size", &(self.total_size() as *const u64))
+            .field(
+                "boot_loader_name_tag",
+                &self
+                    .boot_loader_name_tag()
+                    .map(|x| x.name())
+                    .unwrap_or("<unknown>"),
+            )
+            .field(
+                "command_line",
+                &self
+                    .command_line_tag()
+                    .map(|x| x.command_line())
+                    .unwrap_or(""),
+            )
+            .field("memory_areas", &self.memory_map_tag())
+            // so far, I didn't found a nice way to connect the iterator with ".field()" because
+            // the iterator isn't Debug
+            .field("module_tags", &self.module_tags());
+            // usually this is REALLY big (thousands of tags) => skip it here
+
+        let elf_sections_tag_entries_count = self.elf_sections_tag().map(|x| x.sections().count()).unwrap_or(0);
+
+        if elf_sections_tag_entries_count > ELF_SECTIONS_LIMIT {
+            debug.field(
+                "elf_sections_tags (count)",
+                &elf_sections_tag_entries_count,
+            );
+        } else {
+            debug.field(
+                "elf_sections_tags",
+                &self
+                    .elf_sections_tag()
+                    .map(|x| x.sections())
+                    .unwrap_or_default(),
+            );
         }
 
-        Ok(())
+        debug
+            .field("efi_32_ih", &self.efi_32_ih())
+            .field("efi_64_ih", &self.efi_64_ih())
+            .field("efi_sdt_32_tag", &self.efi_sdt_32_tag())
+            .field("efi_sdt_64_tag", &self.efi_sdt_64_tag())
+            .field("efi_memory_map_tag", &self.efi_memory_map_tag())
+            .finish()
     }
 }
 

src/module.rs

@@ -1,4 +1,5 @@
-use header::{Tag, TagIter};
+use header::{Tag, TagIter, TagType};
+use core::fmt::{Formatter, Debug};
 
 /// This tag indicates to the kernel what boot module was loaded along with
 /// the kernel image, and where it can be found.
@@ -41,7 +42,7 @@ pub fn module_iter(iter: TagIter) -> ModuleIter {
 }
 
 /// An iterator over all module tags.
-#[derive(Clone, Debug)]
+#[derive(Clone)]
 pub struct ModuleIter<'a> {
     iter: TagIter<'a>,
 }
@@ -51,7 +52,17 @@ impl<'a> Iterator for ModuleIter<'a> {
 
     fn next(&mut self) -> Option<&'a ModuleTag> {
         self.iter
-            .find(|x| x.typ == 3)
+            .find(|x| x.typ == TagType::Module)
             .map(|tag| unsafe { &*(tag as *const Tag as *const ModuleTag) })
     }
 }
+
+impl <'a> Debug for ModuleIter<'a> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        let mut list = f.debug_list();
+        self.clone().for_each(|tag| {
+            list.entry(&tag);
+        });
+        list.finish()
+    }
+}