Add docs for crate and Config struct

Author: phil-opp

Cargo.toml

@@ -3,7 +3,7 @@ name = "bootloader"
 version = "0.10.0-alpha-03"
 authors = ["Philipp Oppermann <dev@phil-opp.com>"]
 license = "MIT/Apache-2.0"
-description = "An experimental pure-Rust x86 bootloader."
+description = "An experimental x86_64 bootloader that works on both BIOS and UEFI systems."
 repository = "https://github.com/rust-osdev/bootloader"
 edition = "2018"
 build = "build.rs"

src/config.rs

@@ -1,7 +1,36 @@
 /// Allows configuring the bootloader behavior.
 ///
 /// To control these, use a `[package.metadata.bootloader]` table in the `Cargo.toml` of
-/// your kernel.
+/// your kernel. The naming convention for all config fields is `kebab-case`, otherwise the
+/// config keys correspond to the field names of this struct (i.e. just replace `_` with `-`).
+/// Unknown config keys lead to an error.
+///
+/// ## Example
+///
+/// To map the complete physical memory starting at virtual address `0x0000_4000_0000_0000`, add
+/// the following to your kernel's `Cargo.toml`:
+///
+/// ```toml
+/// [package.metadata.bootloader]
+/// map-physical-memory = true
+/// physical-memory-offset = 0x0000_4000_0000_0000
+/// ```
+///
+/// ## Memory Addresses
+///
+/// Memory addresses must be positive and page aligned. Since TOML does not support unsigned 64-bit
+/// integers, we also support string input to specify addresses larger than `i64::MAX`. For example:
+///
+/// ```toml
+/// physical-memory-offset = "0xf000_0000_0000_0000"
+/// ```
+///
+/// The above example would fail if the address was specified as integer instead (i.e. without
+/// the quotes).
+///
+/// All memory addresses are optional, even if their corresponding switch is enabled. If no
+/// address is specified, the bootloader will choose an unused entry of the level 4 page table
+/// at runtime.
 #[derive(Debug)]
 pub struct Config {
     /// Whether to create a virtual mapping of the complete physical memory.

src/lib.rs

@@ -1,9 +1,51 @@
-//! This library part of the bootloader allows kernels to retrieve information from the bootloader.
-//!
-//! To combine your kernel with the bootloader crate you need a tool such
-//! as [`bootimage`](https://github.com/rust-osdev/bootimage). See the
-//! [_Writing an OS in Rust_](https://os.phil-opp.com/minimal-rust-kernel/#creating-a-bootimage)
-//! blog for an explanation.
+/*!
+An experimental x86_64 bootloader that works on both BIOS and UEFI systems.
+
+To use this crate, specify it as a dependency in the `Cargo.toml` of your operating system
+kernel. Then you can use the [`entry_point`] macro to mark your entry point function. This
+gives you access to the [`BootInfo`] struct, which is passed by the bootloader.
+
+## Disk Image Creation
+
+Including the `bootloader` crate as a dependency makes the kernel binary suitable for booting,
+but does not create any bootable disk images. To create them, two additional steps are needed:
+
+1. **Locate the source code of the `bootloader` dependency** on your local system. By using the
+   dependency source code directly, we ensure that the kernel and bootloader use the same version
+   of the [`BootInfo`] struct.
+    - When creating a builder binary written in Rust, the
+      [`bootloader_locator`](https://docs.rs/bootloader-locator/0.0.4/bootloader_locator/) crate can
+      be used to automate this step.
+    - Otherwise, the
+      [`cargo metadata`](https://doc.rust-lang.org/cargo/commands/cargo-metadata.html) subcommand
+      can be used to locate the dependency. The command outputs a JSON object with various metadata
+      for the current package. To find the `bootloader` source path in it, first look for the
+      "bootloader" dependency under `resolve.nodes.deps` to find out its ID (in the `pkg` field).
+      Then use that ID to find the bootloader in `packages`. Its `manifest_path` field contains the
+      local path to the `Cargo.toml` of the bootloader.
+2. **Run the following command** in the source code directory of the `bootloader` dependency to create
+   the bootable disk images:
+
+    ```notrust
+    cargo builder --kernel-manifest path/to/kernel/Cargo.toml --kernel-binary path/to/kernel_bin
+    ```
+
+    The `--kernel-manifest` argument should point to the `Cargo.toml` of your kernel. It is used
+    for applying configuration settings. The `--kernel-binary` argument should point to the kernel
+    executable that should be used for the bootable disk images.
+
+    In addition to the `--kernel-manifest` and `--kernel-binary` arguments, it is recommended to also
+    set the `--target-dir` and `--out-dir` arguments. The former specifies the directory that should
+    used for cargo build artifacts and the latter specfies the directory where the resulting disk
+    images should be placed. It is recommended to set `--target-dir` to the `target` folder of your
+    kernel and `--out-dir` to the the parent folder of `--kernel-binary`.
+
+## Configuration
+
+The bootloader can be configured through a `[package.metadata.bootloader]` table in the
+`Cargo.toml` of the kernel (the one passed as `--kernel-manifest`). See the [`Config`] struct
+for all possible configuration options.
+*/
 
 #![cfg_attr(not(feature = "builder"), no_std)]
 #![feature(asm)]