Merge pull request #87 from rust-osdev/cargo-toml-prepare-relase-v0.12

Cargo toml prepare relase v0.12 + changelog

Author: phip1611

Cargo.toml

@@ -1,11 +1,34 @@
 [package]
 name = "multiboot2"
-version = "0.11.0"
-authors = ["Philipp Oppermann <[email protected]>", "Calvin Lee <[email protected]>", "Isaac Woods"]
+description = """
+Library that helps you to parse the multiboot information structure (mbi) from
+Multiboot2-compliant bootloaders, like GRUB. It supports all tags from the specification
+including full support for the sections of ELF-64. This library is `no_std` and can be
+used in a Multiboot2-kernel.
+"""
+version = "0.12.0"
+authors = [
+    "Philipp Oppermann <[email protected]>",
+    "Calvin Lee <[email protected]>",
+    "Isaac Woods",
+    "Philipp Schuster <[email protected]>"
+]
 license = "MIT/Apache-2.0"
-description = "An experimental Multiboot 2 crate for ELF-64/32 kernels."
-repository = "https://github.com/rust-osdev/multiboot2-elf64"
 edition = "2018"
+categories = [
+    "parsing",
+]
+keywords = [
+    "Multiboot2",
+    "kernel",
+    "boot",
+]
+# without this, sometimes crates.io doesn't show the preview of the README
+# I expeciended this multiple times in the past
+readme = "README.md"
+homepage = "https://github.com/rust-osdev/multiboot2"
+repository = "https://github.com/rust-osdev/multiboot2"
+documentation = "https://docs.rs/multiboot2"
 
 [dependencies]
 bitflags = "1"

Changelog.md

@@ -1,3 +1,21 @@
+# 0.12.0
+
+- **breaking:** `load()` and `load_with_offset` now returns a result
+- added public constant `MULTIBOOT2_BOOTLOADER_MAGIC`
+- Rust edition 2018 (instead of 2015)
+- internal code improvements
+
+# 0.11.0
+
+- lib now contains public `TagType`-enum that contains
+  all possible mbi tags that are specified (taken from spec)
+- much improved debug-formatting of `BootInformation`
+- internal code improvements / formatting
+
+# 0.10.0
+- allow access to all memory regions (MemoryMap-Tag)
+- internal code improvements
+
 # 0.9.0
 
 - Add a `checksum_is_valid` method to the RSDP tags ([#64](https://github.com/rust-osdev/multiboot2-elf64/pull/64))

README.md

@@ -3,13 +3,14 @@
 [![crates.io](https://img.shields.io/crates/v/multiboot2.svg)](https://crates.io/crates/multiboot2)
 [![docs](https://docs.rs/multiboot2/badge.svg)](https://docs.rs/multiboot2/)
 
-An experimental Multiboot 2 crate for ELF-64 kernels. It's still incomplete, so please open an issue if you're missing some functionality. Contributions welcome!
+Library that helps you to parse the multiboot information structure (mbi) from
+Multiboot2-compliant bootloaders, like GRUB. It supports all tags from the specification
+including full support for the sections of ELF-64. This library is `no_std` and can be
+used in a Multiboot2-kernel.
 
-It uses the Multiboot 2.0 specification at https://www.gnu.org/software/grub/manual/multiboot2/multiboot.html and the ELF 64 specification at http://www.uclibc.org/docs/elf-64-gen.pdf.
+It follows the Multiboot 2.0 specification at https://www.gnu.org/software/grub/manual/multiboot2/multiboot.html and the ELF 64 specification at http://www.uclibc.org/docs/elf-64-gen.pdf.
 
-Below is the draft for a blog post about this. I don't plan to finish it but maybe it's helpful as documentation.
-
-## The Multiboot 2 Information Structure
+## Background: The Multiboot 2 Information Structure
 The Multiboot information structure looks like this:
 
 Field            | Type
@@ -27,46 +28,7 @@ type          | u32
 size          | u32
 other fields  | variable
 
-All tags are 8-byte aligned. The last tag must be the _end tag_, which is a tag of type `0` and size `8`.
-
-## Tags
-
-We are interested in two tags, the _Elf-symbols_ tag and the _memory map_ tag. For a full list of possible tags see section 3.4 in the Multiboot 2 specification ([PDF][Multiboot 2]).
-
-[Multiboot 2]: http://nongnu.askapache.com/grub/phcoder/multiboot.pdf
-
-### The Elf-Symbols Tag
-The Elf-symbols tag contains a list of all sections of the loaded [ELF] kernel. It has the following format:
-
-[ELF]: http://www.uclibc.org/docs/elf-64-gen.pdf
-
-Field                       | Type
---------------------------- | -----------------
-type = 9                    | u32
-size                        | u32
-number of entries           | u32
-entry size                  | u32
-string table                | u32
-section headers             | variable
-
-Note that this format differs from the description in the Multiboot specification because it seems to be wrong for ELF 64 kernels: The `number of entries`, `entry size`, and `string table` fields seem to be `u32` instead of `u16`. The `multiboot2.h` file in the example section of the specification also specifies these fields as being `u32`, which suggests that the `u16` fields are an editing error. The GRUB2 bootloader [uses u32 fields](https://github.com/josefbacik/grub2/blob/96695ad84ce9c93f057ba53ae77d04d8561586e9/include/multiboot2.h#L298-L300), too.
-
-The section headers are just copied from the ELF file, so we need to look at the ELF specification to find the corresponding structure definition. Our kernel is a 64-bit ELF file, so we need to look at the ELF-64 specification ([PDF][ELF specification]). According to section 4 and figure 3, a section header has the following format:
-
-[ELF specification]: http://www.uclibc.org/docs/elf-64-gen.pdf
-
-Field                       | Type             | Value
---------------------------- | ---------------- | -----------
-name                        | u32              | string table index
-type                        | u32              | `0` (unused), `1` (section of program), `3` (string table), `8` (uninitialized section), etc.
-flags                       | u64              | `0x1` (writable), `0x2` (loaded), `0x4` (executable), etc.
-address                     | u64              | virtual start address of section (0 if not loaded)
-file offset                 | u64              | offset (in bytes) of section contents in the file
-size                        | u64              | size of the section in bytes
-link                        | u32              | associated section (only for some section types)
-info                        | u32              | extra information (only for some section types)
-address align               | u64              | required alignment of section (power of 2)
-entry size                  | u64              | contains the entry size for table sections (e.g. string table)
+All tags and the mbi itself are 8-byte aligned. The last tag must be the _end tag_, which is a tag of type `0` and size `8`.
 
 ## License
 

src/lib.rs

@@ -2,11 +2,25 @@
 #![deny(missing_debug_implementations)]
 #![deny(missing_docs)]
 
-//! An experimental Multiboot 2 crate for ELF-64/32 kernels.
+//! Library that helps you to parse the multiboot information structure (mbi) from
+//! Multiboot2-compliant bootloaders, like GRUB. It supports all tags from the specification
+//! including full support for the sections of ELF-64. This library is `no_std` and can be
+//! used in a Multiboot2-kernel.
 //!
-//! The GNU Multiboot specification aims provide to a standardised
+//! The GNU Multiboot(2) specification aims to provide a standardised
 //! method of sharing commonly used information about the host machine at
-//! boot time.
+//! boot time and give the payload, i.e. a kernel, a well defined machien
+//! state.
+//!
+//! ## Example
+//!
+//! ```ignore
+//! use multiboot::load;
+//! fn kmain(multiboot_info_ptr: u32) {
+//!     let boot_info = unsafe { load(ptr as usize).unwrap() };
+//!     println!("{:?}", boot_info);
+//! }
+//! ```
 
 use core::fmt;
 
@@ -55,7 +69,7 @@ mod vbe_info;
 /// use multiboot::load;
 ///
 /// fn kmain(multiboot_info_ptr: u32) {
-///     let boot_info = load(ptr as usize).unwrap();
+///     let boot_info = unsafe { load(ptr as usize).unwrap() };
 ///     println!("{:?}", boot_info);
 /// }
 /// ```
@@ -68,10 +82,10 @@ pub unsafe fn load(address: usize) -> Result<BootInformation, MbiLoadError> {
 /// Examples
 ///
 /// ```ignore
-/// use multiboot::load;
+/// use multiboot::load_with_offset;
 ///
 /// let ptr = 0xDEADBEEF as *const _;
-/// let boot_info = load_with_offset(ptr as usize, 0xCAFEBABE).unwrap();
+/// 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> {