diff --git a/.github/workflows/integrationtest.yml b/.github/workflows/integrationtest.yml index 2386694d..b0851385 100644 --- a/.github/workflows/integrationtest.yml +++ b/.github/workflows/integrationtest.yml @@ -11,6 +11,10 @@ name: "Integration Test" # Run on every push (tag, branch) and pull_request on: [ pull_request, push, merge_group ] +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + env: CARGO_TERM_COLOR: always diff --git a/.github/workflows/qa.yml b/.github/workflows/qa.yml index 62ab336d..0267453c 100644 --- a/.github/workflows/qa.yml +++ b/.github/workflows/qa.yml @@ -2,6 +2,10 @@ name: QA on: [pull_request, push, merge_group] +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + jobs: spellcheck: name: Spellcheck diff --git a/multiboot2-common/src/boxed.rs b/multiboot2-common/src/boxed.rs index bbd45ad4..24a8906d 100644 --- a/multiboot2-common/src/boxed.rs +++ b/multiboot2-common/src/boxed.rs @@ -7,10 +7,11 @@ use core::mem; use core::ops::Deref; use core::ptr; -/// Creates a new tag implementing [`MaybeDynSized`] on the heap. This works for -/// sized and unsized tags. However, it only makes sense to use this for tags -/// that are DSTs (unsized). For regular sized structs, you can just create a -/// typical constructor and box the result. +/// Creates a new tag implementing [`MaybeDynSized`] on the heap. +/// +/// This works for sized and unsized tags. However, it only makes sense to use +/// this for tags that are DSTs (unsized). For regular sized structs, you can +/// just create a typical constructor and box the result. /// /// The provided `header`' total size (see [`Header`]) will be set dynamically /// by this function using [`Header::set_size`]. However, it must contain all diff --git a/multiboot2-common/src/bytes_ref.rs b/multiboot2-common/src/bytes_ref.rs index 45907418..99cdae5e 100644 --- a/multiboot2-common/src/bytes_ref.rs +++ b/multiboot2-common/src/bytes_ref.rs @@ -6,8 +6,10 @@ use core::mem; use core::ops::Deref; /// Wraps a byte slice representing a Multiboot2 structure including an optional -/// terminating padding, if necessary. It guarantees that the memory -/// requirements promised in the crates description are respected. +/// terminating padding, if necessary. +/// +/// Instances of this type guarantee that the memory requirements promised in +/// the crates description are respected. #[derive(Clone, Debug, PartialEq, Eq)] #[repr(transparent)] pub struct BytesRef<'a, H: Header> { diff --git a/multiboot2-common/src/lib.rs b/multiboot2-common/src/lib.rs index 5bc7d5e9..e26df689 100644 --- a/multiboot2-common/src/lib.rs +++ b/multiboot2-common/src/lib.rs @@ -226,10 +226,12 @@ use core::slice; /// The alignment of all Multiboot2 data structures. pub const ALIGNMENT: usize = 8; -/// A sized header type for [`DynSizedStructure`]. Note that `header` refers to -/// the header pattern. Thus, depending on the use case, this is not just a -/// tag header. Instead, it refers to all bytes that are fixed and not part of -/// any optional terminating dynamic `[u8]` slice in a [`DynSizedStructure`]. +/// A sized header type for [`DynSizedStructure`]. +/// +/// Note that `header` refers to the header pattern. Thus, depending on the use +/// case, this is not just a tag header. Instead, it refers to all bytes that +/// are fixed and not part of any optional terminating dynamic `[u8]` slice in a +/// [`DynSizedStructure`]. /// /// The alignment of implementors **must** be the compatible with the demands /// for the corresponding structure, which typically is [`ALIGNMENT`]. @@ -251,9 +253,11 @@ pub trait Header: Clone + Sized + PartialEq + Eq + Debug { } /// An C ABI-compatible dynamically sized type with a common sized [`Header`] -/// and a dynamic amount of bytes. This structures owns all its bytes, unlike -/// [`Header`]. Instances guarantees that the memory requirements promised in -/// the crates description are respected. +/// and a dynamic amount of bytes. +/// +/// This structures owns all its bytes, unlike [`Header`]. Instances guarantees +/// that the memory requirements promised in the crates description are +/// respected. /// /// This can be a Multiboot2 header tag, information tag, boot information, or /// a Multiboot2 header. Depending on the context, the [`Header`] is different. @@ -386,9 +390,10 @@ pub enum MemoryError { impl core::error::Error for MemoryError {} /// Increases the given size to the next alignment boundary, if it is not a -/// multiple of the alignment yet. This is relevant as in Rust's [type layout], -/// the allocated size of a type is always a multiple of the alignment, even -/// if the type is smaller. +/// multiple of the alignment yet. +/// +/// This is relevant as in Rust's [type layout], the allocated size of a type is +/// always a multiple of the alignment, even if the type is smaller. /// /// [type layout]: https://doc.rust-lang.org/reference/type-layout.html #[must_use] diff --git a/multiboot2-common/src/test_utils.rs b/multiboot2-common/src/test_utils.rs index c81cec8d..1a4cfc1e 100644 --- a/multiboot2-common/src/test_utils.rs +++ b/multiboot2-common/src/test_utils.rs @@ -8,8 +8,10 @@ use core::mem; use core::ops::Deref; /// Helper to 8-byte align the underlying bytes, as mandated in the Multiboot2 -/// spec. With this type, one can create manual and raw Multiboot2 boot -/// information or just the bytes for simple tags, in a manual and raw approach. +/// spec. +/// +/// With this type, one can create manual and raw Multiboot2 boot information or +/// just the bytes for simple tags, in a manual and raw approach. #[derive(Debug)] #[repr(C, align(8))] pub struct AlignedBytes(pub [u8; N]); diff --git a/multiboot2-header/src/address.rs b/multiboot2-header/src/address.rs index 70d7c0ef..1bfe7fd8 100644 --- a/multiboot2-header/src/address.rs +++ b/multiboot2-header/src/address.rs @@ -2,6 +2,8 @@ use crate::{HeaderTagFlag, HeaderTagHeader, HeaderTagType}; use core::mem::size_of; use multiboot2_common::{MaybeDynSized, Tag}; +/// Binary address information for non-ELF images. +/// /// This information does not need to be provided if the kernel image is in ELF /// format, but it must be provided if the image is in a.out format or in some /// other format. Required for legacy boot (BIOS). diff --git a/multiboot2-header/src/entry_efi_32.rs b/multiboot2-header/src/entry_efi_32.rs index d62d346b..34a8d26f 100644 --- a/multiboot2-header/src/entry_efi_32.rs +++ b/multiboot2-header/src/entry_efi_32.rs @@ -4,6 +4,8 @@ use core::fmt::{Debug, Formatter}; use core::mem; use multiboot2_common::{MaybeDynSized, Tag}; +/// Contains the entry address for EFI i386 machine state. +/// /// This tag is taken into account only on EFI i386 platforms when Multiboot2 image header /// contains EFI boot services tag. Then entry point specified in ELF header and the entry address /// tag of Multiboot2 header are ignored. diff --git a/multiboot2-header/src/entry_efi_64.rs b/multiboot2-header/src/entry_efi_64.rs index 6b855d5b..1a673496 100644 --- a/multiboot2-header/src/entry_efi_64.rs +++ b/multiboot2-header/src/entry_efi_64.rs @@ -4,6 +4,8 @@ use core::fmt::{Debug, Formatter}; use core::mem; use multiboot2_common::{MaybeDynSized, Tag}; +/// Contains the entry address for EFI amd64 machine state. +/// /// This tag is taken into account only on EFI amd64 platforms when Multiboot2 image header /// contains EFI boot services tag. Then entry point specified in ELF header and the entry address /// tag of Multiboot2 header are ignored. diff --git a/multiboot2-header/src/header.rs b/multiboot2-header/src/header.rs index a55b14e4..53963e5e 100644 --- a/multiboot2-header/src/header.rs +++ b/multiboot2-header/src/header.rs @@ -15,6 +15,7 @@ use multiboot2_common::{DynSizedStructure, Header, MemoryError, Tag, ALIGNMENT}; pub const MAGIC: u32 = 0xe85250d6; /// Wrapper type around a pointer to the Multiboot2 header. +/// /// The Multiboot2 header is the [`Multiboot2BasicHeader`] followed /// by all tags (see [`crate::tags::HeaderTagType`]). /// Use this if you get a pointer to the header and just want diff --git a/multiboot2-header/src/relocatable.rs b/multiboot2-header/src/relocatable.rs index df54e981..987030c7 100644 --- a/multiboot2-header/src/relocatable.rs +++ b/multiboot2-header/src/relocatable.rs @@ -4,10 +4,11 @@ use core::fmt::{Debug, Formatter}; use core::mem; use multiboot2_common::{MaybeDynSized, Tag}; -/// It contains load address placement suggestion for boot loader. Boot loader -/// should follow it. ‘0’ means none, ‘1’ means load image at lowest possible address -/// but not lower than min addr and ‘2’ means load image at highest possible -/// address but not higher than max addr. +/// It contains load address placement suggestion for bootloader. +/// +/// Bootloader should follow it. ‘0’ means none, ‘1’ means load image at lowest +/// possible address but not lower than min addr and ‘2’ means load image at +/// highest possible address but not higher than max addr. #[repr(u32)] #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum RelocatableHeaderTagPreference { diff --git a/multiboot2-header/src/tags.rs b/multiboot2-header/src/tags.rs index 9d9f5aa6..862eea45 100644 --- a/multiboot2-header/src/tags.rs +++ b/multiboot2-header/src/tags.rs @@ -18,9 +18,11 @@ pub enum HeaderTagISA { MIPS32 = 4, } -/// Possible types for header tags of a Multiboot2 header. The names and values are taken -/// from the example C code at the bottom of the Multiboot2 specification. This value -/// stands in the `typ` property of [`HeaderTagHeader`]. +/// Possible types for header tags of a Multiboot2 header. +/// +/// The names and values are taken from the example C code at the bottom of the +/// Multiboot2 specification. This value stands in the `typ` property of +/// [`HeaderTagHeader`]. #[repr(u16)] #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum HeaderTagType { diff --git a/multiboot2/src/framebuffer.rs b/multiboot2/src/framebuffer.rs index c81bd080..78b5da0e 100644 --- a/multiboot2/src/framebuffer.rs +++ b/multiboot2/src/framebuffer.rs @@ -371,9 +371,11 @@ pub struct FramebufferField { pub size: u8, } -/// A framebuffer color descriptor in the palette. On the ABI level, multiple -/// values are consecutively without padding bytes. The spec is not precise in -/// that regard, but looking at Limine's and GRUB's source code confirm that. +/// A framebuffer color descriptor in the palette. +/// +/// On the ABI level, multiple values are consecutively without padding bytes. +/// The spec is not precise in that regard, but looking at Limine's and GRUB's +/// source code confirm that. #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] #[repr(C)] // no align(8) here is correct pub struct FramebufferColor { diff --git a/multiboot2/src/tag_type.rs b/multiboot2/src/tag_type.rs index f7ae50df..3d5921c4 100644 --- a/multiboot2/src/tag_type.rs +++ b/multiboot2/src/tag_type.rs @@ -6,8 +6,10 @@ use core::fmt::{Debug, Formatter}; use core::hash::Hash; /// Serialized form of [`TagType`] that matches the binary representation -/// (`u32`). The abstraction corresponds to the `typ`/`type` field of a -/// Multiboot2 [`TagHeader`]. This type can easily be created from or converted to +/// (`u32`). +/// +/// The abstraction corresponds to the `typ`/`type` field of a Multiboot2 +/// [`TagHeader`]. This type can easily be created from or converted to /// [`TagType`]. /// /// [`TagHeader`]: crate::TagHeader @@ -31,9 +33,10 @@ impl Debug for TagTypeId { } /// Higher level abstraction for [`TagTypeId`] that assigns each possible value -/// to a specific semantic according to the specification. Additionally, it -/// allows to use the [`TagType::Custom`] variant. It is **not binary compatible** -/// with [`TagTypeId`]. +/// to a specific semantic according to the specification. +/// +/// Additionally, it allows to use the [`TagType::Custom`] variant. It is +/// **not binary compatible** with [`TagTypeId`]. #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum TagType { /// Tag `0`: Marks the end of the tags.