TagType-enum introduced in v0.11 is now actually public

Author: phip1611

Changelog.md

@@ -1,3 +1,7 @@
+# 0.12.1
+- `TagType`-enum introduced in `v0.11` is now actually public
+- internal code improvements
+
 # 0.12.0
 
 - **breaking:** `load()` and `load_with_offset` now returns a result
@@ -7,7 +11,7 @@
 
 # 0.11.0
 
-- lib now contains public `TagType`-enum that contains
+- lib now contains `TagType`-enum that contains
   all possible mbi tags that are specified (taken from spec)
 - much improved debug-formatting of `BootInformation`
 - internal code improvements / formatting

src/header.rs

@@ -10,35 +10,89 @@ use core::marker::PhantomData;
 /// that the Rust compiler output changes `eax` before you can access it.
 pub const MULTIBOOT2_BOOTLOADER_MAGIC: u32 = 0x36d76289;
 
-/// Possible Types of a [`Tag`]. The names and values are taken from the example C code
+/// Possible types of a Tag in the Multiboot2 Information Structure (MBI), therefore the value
+/// of the the `typ` field in [`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)]
+#[allow(missing_docs)]
 pub enum TagType {
+    /// Marks the end of the tags.
     End = 0,
+    /// Additional command line string.
+    /// For example `''` or `'--my-custom-option foo --provided by_grub`, if your GRUB config
+    /// contains `multiboot2 /boot/multiboot2-binary.elf --my-custom-option foo --provided by_grub`
     Cmdline = 1,
+    /// Name of the bootloader, e.g. 'GRUB 2.04-1ubuntu44.2'
     BootLoaderName = 2,
+    /// Additional Multiboot modules, which are BLOBs provided in memory. For example an initial
+    /// ram disk with essential drivers.
     Module = 3,
+    /// ‘mem_lower’ and ‘mem_upper’ indicate the amount of lower and upper memory, respectively,
+    /// in kilobytes. Lower memory starts at address 0, and upper memory starts at address 1
+    /// megabyte. The maximum possible value for lower memory is 640 kilobytes. The value returned
+    /// for upper memory is maximally the address of the first upper memory hole minus 1 megabyte.
+    /// It is not guaranteed to be this value.
+    ///
+    /// This tag may not be provided by some boot loaders on EFI platforms if EFI boot services are
+    /// enabled and available for the loaded image (EFI boot services not terminated tag exists in
+    /// Multiboot2 information structure).
     BasicMeminfo = 4,
+    /// This tag indicates which BIOS disk device the boot loader loaded the OS image from. If the
+    /// OS image was not loaded from a BIOS disk, then this tag must not be present. The operating
+    /// system may use this field as a hint for determining its own root device, but is not
+    /// required to.
     Bootdev = 5,
+    /// Memory map. The map provided is guaranteed to list all standard RAM that should be
+    /// available for normal use. This type however includes the regions occupied by kernel, mbi,
+    /// segments and modules. Kernel must take care not to overwrite these regions.
+    //
+    // This tag may not be provided by some boot loaders on EFI platforms if EFI boot services are
+    // enabled and available for the loaded image (EFI boot services not terminated tag exists in
+    // Multiboot2 information structure).
     Mmap = 6,
+    /// Contains the VBE control information returned by the VBE Function 00h and VBE mode
+    /// information returned by the VBE Function 01h, respectively. Note that VBE 3.0 defines
+    /// another protected mode interface which is incompatible with the old one. If you want to use the new protected mode interface, you will have to find the table yourself.
     Vbe = 7,
+    /// Framebuffer.
     Framebuffer = 8,
+    /// This tag contains section header table from an ELF kernel, the size of each entry, number
+    /// of entries, and the string table used as the index of names. They correspond to the
+    /// ‘shdr_*’ entries (‘shdr_num’, etc.) in the Executable and Linkable Format (ELF)
+    /// specification in the program header.
     ElfSections = 9,
+    /// APM table. See Advanced Power Management (APM) BIOS Interface Specification, for more
+    /// information.
     Apm = 10,
+    /// This tag contains pointer to i386 EFI system table.
     Efi32 = 11,
+    /// This tag contains pointer to amd64 EFI system table.
     Efi64 = 12,
+    /// This tag contains a copy of SMBIOS tables as well as their version.
     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,
+    /// This tag contains network information in the format specified as DHCP. It may be either a
+    /// real DHCP reply or just the configuration info in the same format. This tag appears once
+    /// per card.
     Network = 16,
+    /// This tag contains EFI memory map as per EFI specification.
+    /// This tag may not be provided by some boot loaders on EFI platforms if EFI boot services are
+    /// enabled and available for the loaded image (EFI boot services not terminated tag exists in Multiboot2 information structure).
     EfiMmap = 17,
+    /// This tag indicates ExitBootServices wasn't called.
     EfiBs = 18,
+    /// This tag contains pointer to EFI i386 image handle. Usually it is boot loader image handle.
     Efi32Ih = 19,
+    /// This tag contains pointer to EFI amd64 image handle. Usually it is boot loader image handle.
     Efi64Ih = 20,
+    /// This tag contains image load base physical address. The spec tells
+    /// "It is provided only if image has relocatable header tag." but experience showed
+    /// that this is not true for at least GRUB 2.
     LoadBaseAddr = 21,
 }
 

src/lib.rs

@@ -30,8 +30,9 @@ pub use elf_sections::{
     ElfSection, ElfSectionFlags, ElfSectionIter, ElfSectionType, ElfSectionsTag,
 };
 pub use framebuffer::{FramebufferColor, FramebufferField, FramebufferTag, FramebufferType};
+pub use header::TagType;
 pub use header::MULTIBOOT2_BOOTLOADER_MAGIC;
-use header::{Tag, TagIter, TagType};
+use header::{Tag, TagIter};
 pub use memory_map::{
     EFIMemoryAreaType, EFIMemoryDesc, EFIMemoryMapTag, MemoryArea, MemoryAreaIter, MemoryAreaType,
     MemoryMapTag,
@@ -88,7 +89,10 @@ pub unsafe fn load(address: usize) -> Result<BootInformation, MbiLoadError> {
 /// let boot_info = unsafe { load_with_offset(ptr as usize, 0xCAFEBABE).unwrap() };
 /// println!("{:?}", boot_info);
 /// ```
-pub unsafe fn load_with_offset(address: usize, offset: usize) -> Result<BootInformation, MbiLoadError> {
+pub unsafe fn load_with_offset(
+    address: usize,
+    offset: usize,
+) -> Result<BootInformation, MbiLoadError> {
     let address = address + offset;
     let null_ptr = address == 0;
     let eight_byte_aligned = address & 0b111 == 0;
@@ -106,12 +110,10 @@ pub unsafe fn load_with_offset(address: usize, offset: usize) -> Result<BootInfo
         return Err(MbiLoadError::NoEndTag);
     }
 
-    Ok(
-        BootInformation {
-            inner: multiboot,
-            offset,
-        }
-    )
+    Ok(BootInformation {
+        inner: multiboot,
+        offset,
+    })
 }
 
 /// Error type that describes errors while loading/parsing a multiboot2 information structure
@@ -1058,22 +1060,10 @@ mod tests {
         let addr = bytes.0.as_ptr() as usize;
         let bi = unsafe { load(addr) };
         let bi = bi.unwrap();
-        test_grub2_boot_info(
-            bi,
-            addr,
-            string_addr,
-            &bytes.0,
-            &string_bytes.0,
-        );
+        test_grub2_boot_info(bi, addr, string_addr, &bytes.0, &string_bytes.0);
         let bi = unsafe { load_with_offset(addr, 0) };
         let bi = bi.unwrap();
-        test_grub2_boot_info(
-            bi,
-            addr,
-            string_addr,
-            &bytes.0,
-            &string_bytes.0,
-        );
+        test_grub2_boot_info(bi, addr, string_addr, &bytes.0, &string_bytes.0);
         let offset = 8usize;
         for i in 0..8 {
             bytes.0[796 + i] = ((string_addr - offset as u64) >> (i * 8)) as u8;