multiboot2: streamline API of ElfSectionsTag

Author: phip1611

integration-test/bins/multiboot2_payload/src/verify/mod.rs

@@ -48,8 +48,9 @@ pub(self) fn print_memory_map(mbi: &BootInformation) -> anyhow::Result<()> {
 
 pub(self) fn print_elf_info(mbi: &BootInformation) -> anyhow::Result<()> {
     let sections_iter = mbi
-        .elf_sections()
+        .elf_sections_tag()
         .ok_or("Should have elf sections")
+        .map(|tag| tag.sections())
         .map_err(anyhow::Error::msg)?;
     println!("ELF sections:");
     for s in sections_iter {

multiboot2/CHANGELOG.md

@@ -5,6 +5,9 @@
 ## v0.23.1 (2024-10-21)
 
 - Fix wrong tag ID when using `BootdevTag::new`
+- `BootInformation::elf_sections` is now deprecated and replaced by the newly
+- added `BootInformation::elf_sections_tag`. On the returned type, you can call
+  `.sections()` to iterate the sections
 
 ## v0.23.0 (2024-09-17)
 

multiboot2/src/boot_information.rs

@@ -254,7 +254,7 @@ impl<'a> BootInformation<'a> {
     /// # use multiboot2::{BootInformation, BootInformationHeader};
     /// # let ptr = 0xdeadbeef as *const BootInformationHeader;
     /// # let boot_info = unsafe { BootInformation::load(ptr).unwrap() };
-    /// if let Some(sections) = boot_info.elf_sections() {
+    /// if let Some(sections) = boot_info.elf_sections_tag().map(|tag| tag.sections()) {
     ///     let mut total = 0;
     ///     for section in sections {
     ///         println!("Section: {:?}", section);
@@ -263,14 +263,21 @@ impl<'a> BootInformation<'a> {
     /// }
     /// ```
     #[must_use]
+    #[deprecated = "Use elf_sections_tag() instead and corresponding getters"]
     pub fn elf_sections(&self) -> Option<ElfSectionIter> {
         let tag = self.get_tag::<ElfSectionsTag>();
         tag.map(|t| {
             assert!((t.entry_size() * t.shndx()) <= t.header().size);
-            t.sections_iter()
+            t.sections()
         })
     }
 
+    /// Search for the [`ElfSectionsTag`].
+    #[must_use]
+    pub fn elf_sections_tag(&self) -> Option<&ElfSectionsTag> {
+        self.get_tag()
+    }
+
     /// Search for the [`FramebufferTag`]. The result is `Some(Err(e))`, if the
     /// framebuffer type is unknown, while the framebuffer tag is present.
     #[must_use]

multiboot2/src/elf_sections.rs

@@ -37,9 +37,9 @@ impl ElfSectionsTag {
         )
     }
 
-    /// Get an iterator of loaded ELF sections.
+    /// Get an iterator over the ELF sections.
     #[must_use]
-    pub(crate) const fn sections_iter(&self) -> ElfSectionIter {
+    pub const fn sections(&self) -> ElfSectionIter {
         let string_section_offset = (self.shndx * self.entry_size) as isize;
         let string_section_ptr =
             unsafe { self.sections.as_ptr().offset(string_section_offset) as *const _ };
@@ -96,12 +96,12 @@ impl Debug for ElfSectionsTag {
             .field("number_of_sections", &self.number_of_sections)
             .field("entry_size", &self.entry_size)
             .field("shndx", &self.shndx)
-            .field("sections", &self.sections_iter())
+            .field("sections", &self.sections())
             .finish()
     }
 }
 
-/// An iterator over some ELF sections.
+/// An iterator over [`ElfSection`]s.
 #[derive(Clone)]
 pub struct ElfSectionIter<'a> {
     current_section: *const u8,

multiboot2/src/lib.rs

@@ -168,7 +168,7 @@ mod tests {
         assert_eq!(addr, bi.start_address());
         assert_eq!(addr + bytes.0.len(), bi.end_address());
         assert_eq!(bytes.0.len(), bi.total_size());
-        assert!(bi.elf_sections().is_none());
+        assert!(bi.elf_sections_tag().is_none());
         assert!(bi.memory_map_tag().is_none());
         assert!(bi.module_tags().next().is_none());
         assert!(bi.boot_loader_name_tag().is_none());
@@ -191,7 +191,7 @@ mod tests {
         assert_eq!(addr, bi.start_address());
         assert_eq!(addr + bytes.0.len(), bi.end_address());
         assert_eq!(bytes.0.len(), bi.total_size());
-        assert!(bi.elf_sections().is_none());
+        assert!(bi.elf_sections_tag().is_none());
         assert!(bi.memory_map_tag().is_none());
         assert!(bi.module_tags().next().is_none());
         assert!(bi.boot_loader_name_tag().is_none());
@@ -214,7 +214,7 @@ mod tests {
         assert_eq!(addr, bi.start_address());
         assert_eq!(addr + bytes.0.len(), bi.end_address());
         assert_eq!(bytes.0.len(), bi.total_size());
-        assert!(bi.elf_sections().is_none());
+        assert!(bi.elf_sections_tag().is_none());
         assert!(bi.memory_map_tag().is_none());
         assert!(bi.module_tags().next().is_none());
         assert!(bi.boot_loader_name_tag().is_none());
@@ -240,7 +240,7 @@ mod tests {
         assert_eq!(addr, bi.start_address());
         assert_eq!(addr + bytes.0.len(), bi.end_address());
         assert_eq!(bytes.0.len(), bi.total_size());
-        assert!(bi.elf_sections().is_none());
+        assert!(bi.elf_sections_tag().is_none());
         assert!(bi.memory_map_tag().is_none());
         assert!(bi.module_tags().next().is_none());
         assert_eq!(
@@ -834,7 +834,7 @@ mod tests {
         assert_eq!(addr, bi.start_address());
         assert_eq!(addr + bytes.len(), bi.end_address());
         assert_eq!(bytes.len(), bi.total_size());
-        let mut es = bi.elf_sections().unwrap();
+        let mut es = bi.elf_sections_tag().unwrap().sections();
         let s1 = es.next().expect("Should have one more section");
         assert_eq!(".rodata", s1.name().expect("Should be valid utf-8"));
         assert_eq!(0xFFFF_8000_0010_0000, s1.start_address());
@@ -1022,7 +1022,7 @@ mod tests {
         assert_eq!(addr, bi.start_address());
         assert_eq!(addr + bytes.0.len(), bi.end_address());
         assert_eq!(bytes.0.len(), bi.total_size());
-        let mut es = bi.elf_sections().unwrap();
+        let mut es = bi.elf_sections_tag().unwrap().sections();
         let s1 = es.next().expect("Should have one more section");
         assert_eq!(".shstrtab", s1.name().expect("Should be valid utf-8"));
         assert_eq!(string_addr, s1.start_address());