Struct BootInformation

pub struct BootInformation<'a>(/* private fields */);

A Multiboot 2 Boot Information (MBI) accessor.

Implementations

impl<'a> BootInformation<'a>

pub unsafe fn load(ptr: *const BootInformationHeader) -> Result<Self, LoadError>

Loads the BootInformation from a pointer. The pointer must be valid and aligned to an 8-byte boundary, as defined by the spec.

Example

use multiboot2::{BootInformation, BootInformationHeader};

fn kernel_entry(mb_magic: u32, mbi_ptr: u32) {
    if mb_magic == multiboot2::MAGIC {
        let boot_info = unsafe { BootInformation::load(mbi_ptr as *const BootInformationHeader).unwrap() };
        let _cmd = boot_info.command_line_tag();
    } else { /* Panic or use multiboot1 flow. */ }
}

Safety

• ptr must be valid for reading. Otherwise, this function might cause invalid machine state or crash your binary (kernel). This can be the case in environments with standard environment (segfault), but also in boot environments, such as UEFI.
• The memory at ptr must not be modified after calling load or the program may observe unsynchronized mutation.

pub fn start_address(&self) -> usize

Get the start address of the boot info.

pub const fn as_ptr(&self) -> *const ()

Get the start address of the boot info as pointer.

pub fn end_address(&self) -> usize

Get the end address of the boot info.

This is the same as doing:

let end_addr = boot_info.start_address() + boot_info.total_size();

pub const fn total_size(&self) -> usize

Get the total size of the boot info struct.

pub fn apm_tag(&self) -> Option<&ApmTag>

Search for the ApmTag.

pub fn basic_memory_info_tag(&self) -> Option<&BasicMemoryInfoTag>

Search for the BasicMemoryInfoTag.

pub fn boot_loader_name_tag(&self) -> Option<&BootLoaderNameTag>

Search for the BootLoaderNameTag.

pub fn bootdev_tag(&self) -> Option<&BootdevTag>

Search for the BootdevTag.

pub fn command_line_tag(&self) -> Option<&CommandLineTag>

Search for the CommandLineTag.

pub fn efi_bs_not_exited_tag(&self) -> Option<&EFIBootServicesNotExitedTag>

Search for the EFIBootServicesNotExitedTag.

pub fn efi_memory_map_tag(&self) -> Option<&EFIMemoryMapTag>

Search for the EFIMemoryMapTag, if the boot services were exited. Otherwise, if the TagType::EfiBs tag is present, this returns None as it is strictly recommended to get the memory map from uefi instead.

pub fn efi_sdt32_tag(&self) -> Option<&EFISdt32Tag>

Search for the EFISdt32Tag.

pub fn efi_sdt64_tag(&self) -> Option<&EFISdt64Tag>

Search for the EFISdt64Tag.

pub fn efi_ih32_tag(&self) -> Option<&EFIImageHandle32Tag>

Search for the EFIImageHandle32Tag.

pub fn efi_ih64_tag(&self) -> Option<&EFIImageHandle64Tag>

Search for the EFIImageHandle64Tag.

pub fn elf_sections(&self) -> Option<ElfSectionIter<'_>>

👎Deprecated: Use elf_sections_tag() instead and corresponding getters

Returns an ElfSectionIter iterator over the ELF Sections, if the ElfSectionsTag is present.

Examples

if let Some(sections) = boot_info.elf_sections_tag().map(|tag| tag.sections()) {
    let mut total = 0;
    for section in sections {
        println!("Section: {:?}", section);
        total += 1;
    }
}

pub fn elf_sections_tag(&self) -> Option<&ElfSectionsTag>

Search for the ElfSectionsTag.

pub fn framebuffer_tag( &self, ) -> Option<Result<&FramebufferTag, UnknownFramebufferType>>

Search for the FramebufferTag. The result is Some(Err(e)), if the framebuffer type is unknown, while the framebuffer tag is present.

pub fn load_base_addr_tag(&self) -> Option<&ImageLoadPhysAddrTag>

Search for the ImageLoadPhysAddrTag.

pub fn memory_map_tag(&self) -> Option<&MemoryMapTag>

Search for the MemoryMapTag.

pub fn module_tags(&self) -> ModuleIter<'_>

Get an iterator of all ModuleTags.

pub fn network_tag(&self) -> Option<&NetworkTag>

Search for the NetworkTag.

pub fn rsdp_v1_tag(&self) -> Option<&RsdpV1Tag>

Search for the RsdpV1Tag.

pub fn rsdp_v2_tag(&self) -> Option<&RsdpV2Tag>

Search for the RsdpV2Tag.

pub fn smbios_tag(&self) -> Option<&SmbiosTag>

Search for the SmbiosTag.

pub fn vbe_info_tag(&self) -> Option<&VBEInfoTag>

Search for the VBEInfoTag.

pub fn get_tag<T: Tag<IDType = TagType, Header = TagHeader> + ?Sized + 'a>( &'a self, ) -> Option<&'a T>

Public getter to find any Multiboot tag by its type, including specified and custom ones.

Specified or Custom Tags

The Multiboot2 specification specifies a list of tags, see TagType. However, it doesn’t forbid to use custom tags. Because of this, there exists the TagType abstraction. It is recommended to use this getter only for custom tags. For specified tags, use getters, such as Self::efi_ih64_tag.

Use Custom Tags

The following example shows how you may use this interface to parse custom tags from the MBI. If they are dynamically sized (DST), a few more special handling is required. This is reflected by code-comments.

use std::mem;
use multiboot2::{BootInformation, BootInformationHeader, parse_slice_as_string, StringError, TagHeader, TagType, TagTypeId};    ///
use multiboot2_common::{MaybeDynSized, Tag};

#[repr(C)]
#[derive(multiboot2::Pointee)] // Only needed for DSTs.
struct CustomTag {
    header: TagHeader,
    some_other_prop: u32,
    // Begin of C string, for example.
    name: [u8],
}

impl CustomTag {
    fn name(&self) -> Result<&str, StringError> {
        parse_slice_as_string(&self.name)
    }
}

// Give the library hints how big this tag is.
impl MaybeDynSized for CustomTag {
    type Header = TagHeader;
    const BASE_SIZE: usize = mem::size_of::<TagHeader>() + mem::size_of::<u32>();

    // This differs for DSTs and normal structs. See function
    // documentation.
    fn dst_len(header: &TagHeader) -> usize {
        assert!(header.size >= Self::BASE_SIZE as u32);
        header.size as usize - Self::BASE_SIZE
    }
}

// Make the Tag identifiable.
impl Tag for CustomTag {
    type IDType = TagType;
    const ID: TagType = TagType::Custom(0x1337);
}

let mbi_ptr = 0xdeadbeef as *const BootInformationHeader;
let mbi = unsafe { BootInformation::load(mbi_ptr).unwrap() };

let tag = mbi
    .get_tag::<CustomTag>()
    .unwrap();
assert_eq!(tag.name(), Ok("name"));

pub fn tags(&self) -> TagIter<'_>

Returns an iterator over all tags.

This is public to enable users to iterate over tags that appear multiple times, even tho this is unusual. However, it is recommended to use the tag getters as normal bootloaders provide most tags only once.

Trait Implementations

impl Debug for BootInformation<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.