Skip to content

multiboot2: various small fixes and doc improvements #245

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 21, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions multiboot2-common/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,13 @@ safely cast to the target type.
![Generic parsing flow overview](./parsing-flow-generic.drawio.png "Generic parsing flow overview: From raw bytes to specific structures")

The next figure is like the previous figure, but shows a more specific parsing
flow by using types of the `multiboot2` crate. Green shows the raw memory.
Purple boxes refers to logic in `multiboot2-common`. Red components show structs
from the `multiboot2` crate.
flow by using example types of the `multiboot2` crate. Specifically, it shows
how the header structs for each multiboot2 structure, each implementing
the `Header` trait, are utilized as generic types to get the right size
information of the final type tag type.

Green shows the raw memory, purple boxes refer to logic in `multiboot2-common`,
and red components show structs from the `multiboot2` crate.

![Specific parsing flow overview](./parsing-flow-specific.drawio.png "Specific parsing flow overview: From raw bytes to multiboot2 structures")

Expand Down
Binary file modified multiboot2-common/parsing-flow-specific.drawio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
161 changes: 94 additions & 67 deletions multiboot2-common/parsing-flow-specific.drawio.xml

Large diffs are not rendered by default.

11 changes: 8 additions & 3 deletions multiboot2-common/src/iter.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,14 @@ use core::marker::PhantomData;
use core::mem;

/// Iterates over the tags (modelled by [`DynSizedStructure`]) of the underlying
/// byte slice. Each tag is expected to have the same common [`Header`].
/// byte slice. Each tag is expected to have the same common [`Header`] with
/// the corresponding ABI guarantees.
///
/// As the iterator emits elements of type [`DynSizedStructure`], users should
/// casted them to specific [`Tag`]s using [`DynSizedStructure::cast`] following
/// a user policy. This can for example happen on the basis of some ID.
/// cast them to specific [`Tag`]s using [`DynSizedStructure::cast`] following
/// a user-specific policy. This can for example happen on the basis of some ID.
///
/// This iterator also emits end tags and doesn't treat them separately.
///
/// This type ensures the memory safety guarantees promised by this crates
/// documentation.
Expand All @@ -30,6 +33,8 @@ pub struct TagIter<'a, H: Header> {
impl<'a, H: Header> TagIter<'a, H> {
/// Creates a new iterator.
#[must_use]
// TODO we could take a BytesRef here, but the surrounding code should be
// bullet-proof enough.
pub fn new(mem: &'a [u8]) -> Self {
// Assert alignment.
assert_eq!(mem.as_ptr().align_offset(ALIGNMENT), 0);
Expand Down
2 changes: 1 addition & 1 deletion multiboot2-common/src/tag.rs
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ pub trait MaybeDynSized: Pointee {
/// data, read the tag size from [`Self::header`] and create a sub slice.
fn as_bytes(&self) -> BytesRef<Self::Header> {
let ptr = core::ptr::addr_of!(*self);
// Actual tag size, optionally with terminating padding.
// Actual tag size with optional terminating padding.
let size = mem::size_of_val(self);
let slice = unsafe { slice::from_raw_parts(ptr.cast::<u8>(), size) };
// Unwrap is fine as this type can't exist without the underlying memory
Expand Down
2 changes: 1 addition & 1 deletion multiboot2-header/src/entry_address.rs
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ impl Debug for EntryAddressHeaderTag {
.field("type", &self.typ())
.field("flags", &self.flags())
.field("size", &self.size())
.field("entry_addr", &(self.entry_addr as *const u32))
.field("entry_addr", &self.entry_addr)
.finish()
}
}
Expand Down
2 changes: 1 addition & 1 deletion multiboot2-header/src/entry_efi_32.rs
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ impl Debug for EntryEfi32HeaderTag {
.field("type", &self.typ())
.field("flags", &self.flags())
.field("size", &self.size())
.field("entry_addr", &(self.entry_addr as *const u32))
.field("entry_addr", &self.entry_addr)
.finish()
}
}
Expand Down
2 changes: 1 addition & 1 deletion multiboot2-header/src/entry_efi_64.rs
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ impl Debug for EntryEfi64HeaderTag {
.field("type", &self.typ())
.field("flags", &self.flags())
.field("size", &self.size())
.field("entry_addr", &(self.entry_addr as *const u32))
.field("entry_addr", &self.entry_addr)
.finish()
}
}
Expand Down
8 changes: 4 additions & 4 deletions multiboot2-header/src/relocatable.rs
Original file line number Diff line number Diff line change
Expand Up @@ -108,10 +108,10 @@ impl Debug for RelocatableHeaderTag {
.field("flags", &self.flags())
.field("size", &self.size())
// trick to print this as hexadecimal pointer
.field("min_addr", &(self.min_addr as *const u32))
.field("max_addr", &(self.max_addr as *const u32))
.field("align", &{ self.align })
.field("preference", &{ self.preference })
.field("min_addr", &self.min_addr)
.field("max_addr", &self.max_addr)
.field("align", &self.align)
.field("preference", &self.preference)
.finish()
}
}
Expand Down
2 changes: 2 additions & 0 deletions multiboot2/src/boot_information.rs
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,7 @@ impl<'a> BootInformation<'a> {

/// Get the start address of the boot info.
#[must_use]
// TODO deprecated and use pointers only (see provenance discussions)
pub fn start_address(&self) -> usize {
self.as_ptr() as usize
}
Expand All @@ -153,6 +154,7 @@ impl<'a> BootInformation<'a> {
/// let end_addr = boot_info.start_address() + boot_info.total_size();
/// ```
#[must_use]
// TODO deprecated and use pointers only (see provenance discussions)
pub fn end_address(&self) -> usize {
self.start_address() + self.total_size()
}
Expand Down
4 changes: 2 additions & 2 deletions multiboot2/src/elf_sections.rs
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ impl<'a> Iterator for ElfSectionIter<'a> {
}
}

impl<'a> Debug for ElfSectionIter<'a> {
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| {
Expand Down Expand Up @@ -183,7 +183,7 @@ struct ElfSectionInner64 {
entry_size: u64,
}

impl<'a> ElfSection<'a> {
impl ElfSection<'_> {
/// Get the section type as a `ElfSectionType` enum variant.
#[must_use]
pub fn section_type(&self) -> ElfSectionType {
Expand Down
2 changes: 1 addition & 1 deletion multiboot2/src/framebuffer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -319,7 +319,7 @@ pub enum FramebufferType<'a> {
Text,
}

impl<'a> FramebufferType<'a> {
impl FramebufferType<'_> {
#[must_use]
#[cfg(feature = "builder")]
const fn id(&self) -> FramebufferTypeId {
Expand Down
4 changes: 2 additions & 2 deletions multiboot2/src/memory_map.rs
Original file line number Diff line number Diff line change
Expand Up @@ -455,13 +455,13 @@ impl<'a> Iterator for EFIMemoryAreaIter<'a> {
}
}

impl<'a> ExactSizeIterator for EFIMemoryAreaIter<'a> {
impl ExactSizeIterator for EFIMemoryAreaIter<'_> {
fn len(&self) -> usize {
self.entries
}
}

impl<'a> Debug for EFIMemoryAreaIter<'a> {
impl Debug for EFIMemoryAreaIter<'_> {
fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
let mut debug = f.debug_list();
let iter = self.clone();
Expand Down
2 changes: 1 addition & 1 deletion multiboot2/src/module.rs
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ impl<'a> Iterator for ModuleIter<'a> {
}
}

impl<'a> Debug for ModuleIter<'a> {
impl Debug for ModuleIter<'_> {
fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
let mut list = f.debug_list();
self.clone().for_each(|tag| {
Expand Down
Loading