Refactor image creation API

Author: phil-opp

Cargo.lock

@@ -33,6 +33,7 @@ anyhow = "1.0.32"
 fatfs = "0.3.4"
 gpt = "3.0.0"
 mbrman = "0.4.2"
+tempfile = "3.3.0"
 
 [dev-dependencies]
 bootloader_test_runner = { path = "tests/runner" }

Cargo.toml

@@ -1,74 +1,15 @@
 /*!
 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`.
-
-This will result in the following files, which are placed in the specified `--out-dir`:
-
-- A disk image suitable for BIOS booting, named `boot-bios-<kernel>.img`, where `<kernel>` is the
-  name of your kernel executable. This image can be started in QEMU or booted on a real machine
-  after burning it to an USB stick..
-- A disk image suitable for UEFI booting, named `boot-uefi-<kernel>.img`. Like the BIOS disk image,
-  this can be started in QEMU (requires OVMF) and burned to an USB stick to run it on a real
-  machine.
-- Intermediate UEFI files
-  - A FAT partition image named `boot-uefi-<kernel>.fat`, which can be directly started in QEMU
-    or written as an EFI system partition to a GPT-formatted disk.
-  - An EFI file named `boot-uefi-<kernel>.efi`. This executable is the combination of the
-    bootloader and kernel executables. It can be started in QEMU or used to construct a bootable
-    disk image: Create an EFI system partition formatted with the FAT filesystem and place the
-    EFI file under `efi\boot\bootx64.efi` on that filesystem.
-
-**You can find some examples that implement the above steps [in our GitHub repo](https://github.com/rust-osdev/bootloader/tree/main/examples).**
-
-## 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.
 */
 
 #![warn(missing_docs)]
 
 use anyhow::Context;
-use std::{collections::BTreeMap, path::Path};
+use std::{
+    collections::BTreeMap,
+    path::{Path, PathBuf},
+};
+use tempfile::NamedTempFile;
 
 mod fat;
 mod gpt;
@@ -79,61 +20,116 @@ const KERNEL_FILE_NAME: &str = "kernel-x86_64";
 const BIOS_STAGE_3: &str = "boot-stage-3";
 const BIOS_STAGE_4: &str = "boot-stage-4";
 
-/// Creates a bootable FAT partition at the given path.
-pub fn create_boot_partition(kernel_binary: &Path, out_path: &Path) -> anyhow::Result<()> {
-    let bootloader_path = Path::new(env!("UEFI_BOOTLOADER_PATH"));
-    let stage_3_path = Path::new(env!("BIOS_STAGE_3_PATH"));
-    let stage_4_path = Path::new(env!("BIOS_STAGE_4_PATH"));
-
-    let mut files = BTreeMap::new();
-    files.insert("efi/boot/bootx64.efi", bootloader_path);
-    files.insert(KERNEL_FILE_NAME, kernel_binary);
-    files.insert(BIOS_STAGE_3, stage_3_path);
-    files.insert(BIOS_STAGE_4, stage_4_path);
-
-    fat::create_fat_filesystem(files, &out_path).context("failed to create UEFI FAT filesystem")?;
-
-    Ok(())
+/// Create disk images for booting on legacy BIOS systems.
+pub struct BiosBoot {
+    kernel: PathBuf,
 }
 
-pub fn create_uefi_disk_image(
-    boot_partition_path: &Path,
-    out_gpt_path: &Path,
-) -> anyhow::Result<()> {
-    gpt::create_gpt_disk(boot_partition_path, out_gpt_path)
-        .context("failed to create UEFI GPT disk image")?;
-
-    Ok(())
+impl BiosBoot {
+    /// Start creating a disk image for the given bootloader ELF executable.
+    pub fn new(kernel_path: &Path) -> Self {
+        Self {
+            kernel: kernel_path.to_owned(),
+        }
+    }
+
+    /// Create a bootable UEFI disk image at the given path.
+    pub fn create_disk_image(&self, out_path: &Path) -> anyhow::Result<()> {
+        let bootsector_path = Path::new(env!("BIOS_BOOT_SECTOR_PATH"));
+        let stage_2_path = Path::new(env!("BIOS_STAGE_2_PATH"));
+
+        let fat_partition = self
+            .create_fat_partition()
+            .context("failed to create FAT partition")?;
+
+        mbr::create_mbr_disk(
+            bootsector_path,
+            stage_2_path,
+            fat_partition.path(),
+            out_path,
+        )
+        .context("failed to create BIOS MBR disk image")?;
+
+        fat_partition
+            .close()
+            .context("failed to delete FAT partition after disk image creation")?;
+
+        Ok(())
+    }
+
+    /// Creates an BIOS-bootable FAT partition with the kernel.
+    fn create_fat_partition(&self) -> anyhow::Result<NamedTempFile> {
+        let stage_3_path = Path::new(env!("BIOS_STAGE_3_PATH"));
+        let stage_4_path = Path::new(env!("BIOS_STAGE_4_PATH"));
+
+        let mut files = BTreeMap::new();
+        files.insert(KERNEL_FILE_NAME, self.kernel.as_path());
+        files.insert(BIOS_STAGE_3, stage_3_path);
+        files.insert(BIOS_STAGE_4, stage_4_path);
+
+        let out_file = NamedTempFile::new().context("failed to create temp file")?;
+        fat::create_fat_filesystem(files, out_file.path())
+            .context("failed to create BIOS FAT filesystem")?;
+
+        Ok(out_file)
+    }
 }
 
-pub fn create_bios_disk_image(
-    boot_partition_path: &Path,
-    out_mbr_path: &Path,
-) -> anyhow::Result<()> {
-    let bootsector_path = Path::new(env!("BIOS_BOOT_SECTOR_PATH"));
-    let stage_2_path = Path::new(env!("BIOS_STAGE_2_PATH"));
-
-    mbr::create_mbr_disk(
-        bootsector_path,
-        stage_2_path,
-        boot_partition_path,
-        out_mbr_path,
-    )
-    .context("failed to create BIOS MBR disk image")?;
-
-    Ok(())
+/// Create disk images for booting on UEFI systems.
+pub struct UefiBoot {
+    kernel: PathBuf,
 }
 
-/// Prepare a folder for use with booting over UEFI_PXE.
-///
-/// This places the bootloader executable under the path "bootloader". The
-/// DHCP server should set the filename option to that path, otherwise the
-/// bootloader won't be found.
-pub fn create_uefi_pxe_tftp_folder(kernel_binary: &Path, out_path: &Path) -> anyhow::Result<()> {
-    let bootloader_path = Path::new(env!("UEFI_BOOTLOADER_PATH"));
-
-    pxe::create_uefi_tftp_folder(bootloader_path, kernel_binary, out_path)
-        .context("failed to create UEFI PXE tftp folder")?;
-
-    Ok(())
+impl UefiBoot {
+    /// Start creating a disk image for the given bootloader ELF executable.
+    pub fn new(kernel_path: &Path) -> Self {
+        Self {
+            kernel: kernel_path.to_owned(),
+        }
+    }
+
+    /// Create a bootable BIOS disk image at the given path.
+    pub fn create_disk_image(&self, out_path: &Path) -> anyhow::Result<()> {
+        let fat_partition = self
+            .create_fat_partition()
+            .context("failed to create FAT partition")?;
+
+        gpt::create_gpt_disk(fat_partition.path(), out_path)
+            .context("failed to create UEFI GPT disk image")?;
+
+        fat_partition
+            .close()
+            .context("failed to delete FAT partition after disk image creation")?;
+
+        Ok(())
+    }
+
+    /// Prepare a folder for use with booting over UEFI_PXE.
+    ///
+    /// This places the bootloader executable under the path "bootloader". The
+    /// DHCP server should set the filename option to that path, otherwise the
+    /// bootloader won't be found.
+    pub fn create_pxe_tftp_folder(&self, out_path: &Path) -> anyhow::Result<()> {
+        let bootloader_path = Path::new(env!("UEFI_BOOTLOADER_PATH"));
+
+        pxe::create_uefi_tftp_folder(bootloader_path, self.kernel.as_path(), out_path)
+            .context("failed to create UEFI PXE tftp folder")?;
+
+        Ok(())
+    }
+
+    /// Creates an UEFI-bootable FAT partition with the kernel.
+    fn create_fat_partition(&self) -> anyhow::Result<NamedTempFile> {
+        let bootloader_path = Path::new(env!("UEFI_BOOTLOADER_PATH"));
+
+        let mut files = BTreeMap::new();
+        files.insert("efi/boot/bootx64.efi", bootloader_path);
+        files.insert(KERNEL_FILE_NAME, self.kernel.as_path());
+
+        let out_file = NamedTempFile::new().context("failed to create temp file")?;
+        fat::create_fat_filesystem(files, &out_file.path())
+            .context("failed to create UEFI FAT filesystem")?;
+
+        Ok(out_file)
+    }
 }

src/lib.rs

@@ -13,26 +13,25 @@ const QEMU_ARGS: &[&str] = &[
 pub fn run_test_kernel(kernel_binary_path: &str) {
     let kernel_path = Path::new(kernel_binary_path);
 
-    // create FAT filesystem with kernel executable and UEFI bootloader
-    let out_fat_path = kernel_path.with_extension("fat");
-    bootloader::create_boot_partition(kernel_path, &out_fat_path).unwrap();
-
-    // wrap the created filesystem in an GPT disk image for UEFI booting
-    let out_gpt_path = kernel_path.with_extension("gpt");
-    bootloader::create_uefi_disk_image(&out_fat_path, &out_gpt_path).unwrap();
+    // create an MBR disk image for legacy BIOS booting
+    let mbr_path = kernel_path.with_extension("mbr");
+    bootloader::BiosBoot::new(kernel_path)
+        .create_disk_image(&mbr_path)
+        .unwrap();
 
-    // wrap the created filesystem in an MBR disk image for legacy BIOS booting
-    let out_mbr_path = kernel_path.with_extension("mbr");
-    bootloader::create_bios_disk_image(&out_fat_path, &out_mbr_path).unwrap();
+    // create a GPT disk image for UEFI booting
+    let gpt_path = kernel_path.with_extension("gpt");
+    let uefi_builder = bootloader::UefiBoot::new(kernel_path);
+    uefi_builder.create_disk_image(&gpt_path).unwrap();
 
     // create a TFTP folder with the kernel executable and UEFI bootloader for
     // UEFI PXE booting
-    let out_tftp_path = kernel_path.with_extension(".tftp");
-    bootloader::create_uefi_pxe_tftp_folder(kernel_path, &out_tftp_path).unwrap();
+    let tftp_path = kernel_path.with_extension(".tftp");
+    uefi_builder.create_pxe_tftp_folder(&tftp_path).unwrap();
 
-    run_test_kernel_on_uefi(&out_gpt_path);
-    run_test_kernel_on_bios(&out_mbr_path);
-    run_test_kernel_on_uefi_pxe(&out_tftp_path);
+    run_test_kernel_on_uefi(&gpt_path);
+    run_test_kernel_on_bios(&mbr_path);
+    run_test_kernel_on_uefi_pxe(&tftp_path);
 }
 
 pub fn run_test_kernel_on_uefi(out_gpt_path: &Path) {