From 90a853ed71574d70ef4343d79f7da704ee752ba5 Mon Sep 17 00:00:00 2001 From: Philipp Oppermann Date: Mon, 1 Apr 2019 13:44:10 +0200 Subject: [PATCH 1/8] Rename example-kernel to test-kernel --- azure-pipelines.yml | 8 ++++---- {example-kernel => test-kernel}/.gitignore | 0 {example-kernel => test-kernel}/Cargo.lock | 14 +++++++------- {example-kernel => test-kernel}/Cargo.toml | 2 +- {example-kernel => test-kernel}/src/main.rs | 0 .../x86_64-test-kernel.json | 0 6 files changed, 12 insertions(+), 12 deletions(-) rename {example-kernel => test-kernel}/.gitignore (100%) rename {example-kernel => test-kernel}/Cargo.lock (99%) rename {example-kernel => test-kernel}/Cargo.toml (84%) rename {example-kernel => test-kernel}/src/main.rs (100%) rename example-kernel/x86_64-example-kernel.json => test-kernel/x86_64-test-kernel.json (100%) diff --git a/azure-pipelines.yml b/azure-pipelines.yml index c7b8f1ae..a46e6136 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -90,13 +90,13 @@ steps: failOnStderr: true displayName: 'Install QEMU (Windows)' -- script: cargo xbuild --target x86_64-example-kernel.json - workingDirectory: example-kernel - displayName: 'Build Example Kernel' +- script: cargo xbuild --target x86_64-test-kernel.json + workingDirectory: test-kernel + displayName: 'Build Test Kernel' - script: cargo xbuild --release displayName: 'Build Bootloader' - env: { KERNEL: "example-kernel/target/x86_64-example-kernel/debug/example-kernel" } + env: { KERNEL: "test-kernel/target/x86_64-test-kernel/debug/test-kernel" } - script: cargo objcopy -- -I elf64-x86-64 -O binary --binary-architecture=i386:x86-64 target/x86_64-bootloader/release/bootloader target/x86_64-bootloader/release/bootloader.bin displayName: 'Convert Bootloader ELF to Binary' diff --git a/example-kernel/.gitignore b/test-kernel/.gitignore similarity index 100% rename from example-kernel/.gitignore rename to test-kernel/.gitignore diff --git a/example-kernel/Cargo.lock b/test-kernel/Cargo.lock similarity index 99% rename from example-kernel/Cargo.lock rename to test-kernel/Cargo.lock index be9487bc..e2a6a681 100644 --- a/example-kernel/Cargo.lock +++ b/test-kernel/Cargo.lock @@ -18,13 +18,6 @@ name = "bitflags" version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" -[[package]] -name = "example-kernel" -version = "0.1.0" -dependencies = [ - "x86_64 0.3.4 (registry+https://github.com/rust-lang/crates.io-index)", -] - [[package]] name = "nodrop" version = "0.1.13" @@ -35,6 +28,13 @@ name = "os_bootinfo" version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" +[[package]] +name = "test-kernel" +version = "0.1.0" +dependencies = [ + "x86_64 0.3.4 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "usize_conversions" version = "0.2.0" diff --git a/example-kernel/Cargo.toml b/test-kernel/Cargo.toml similarity index 84% rename from example-kernel/Cargo.toml rename to test-kernel/Cargo.toml index a9c76f70..85bcf7a9 100644 --- a/example-kernel/Cargo.toml +++ b/test-kernel/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "example-kernel" +name = "test-kernel" version = "0.1.0" authors = ["Philipp Oppermann "] edition = "2018" diff --git a/example-kernel/src/main.rs b/test-kernel/src/main.rs similarity index 100% rename from example-kernel/src/main.rs rename to test-kernel/src/main.rs diff --git a/example-kernel/x86_64-example-kernel.json b/test-kernel/x86_64-test-kernel.json similarity index 100% rename from example-kernel/x86_64-example-kernel.json rename to test-kernel/x86_64-test-kernel.json From 1c3d7e52a335f5e086191918704ebcb8c0fd611a Mon Sep 17 00:00:00 2001 From: Philipp Oppermann Date: Mon, 1 Apr 2019 13:46:33 +0200 Subject: [PATCH 2/8] Use a default target for test-kernel --- azure-pipelines.yml | 2 +- test-kernel/.cargo/config | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 test-kernel/.cargo/config diff --git a/azure-pipelines.yml b/azure-pipelines.yml index a46e6136..8123f323 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -90,7 +90,7 @@ steps: failOnStderr: true displayName: 'Install QEMU (Windows)' -- script: cargo xbuild --target x86_64-test-kernel.json +- script: cargo xbuild workingDirectory: test-kernel displayName: 'Build Test Kernel' diff --git a/test-kernel/.cargo/config b/test-kernel/.cargo/config new file mode 100644 index 00000000..92e8659b --- /dev/null +++ b/test-kernel/.cargo/config @@ -0,0 +1,2 @@ +[build] +target = "x86_64-test-kernel.json" From 39cc62e802cc5553521c789b9b9a82fd6a2bf462 Mon Sep 17 00:00:00 2001 From: Philipp Oppermann Date: Mon, 1 Apr 2019 13:46:52 +0200 Subject: [PATCH 3/8] Add a rust-toolchain file to default to nightly --- rust-toolchain | 1 + 1 file changed, 1 insertion(+) create mode 100644 rust-toolchain diff --git a/rust-toolchain b/rust-toolchain new file mode 100644 index 00000000..07ade694 --- /dev/null +++ b/rust-toolchain @@ -0,0 +1 @@ +nightly \ No newline at end of file From e2a00a44ff39c74aca712b19b47a69f483938b39 Mon Sep 17 00:00:00 2001 From: Philipp Oppermann Date: Mon, 1 Apr 2019 13:58:58 +0200 Subject: [PATCH 4/8] Add an example kernel that can be used to try the bootloader --- azure-pipelines.yml | 3 + example-kernel/.cargo/config | 2 + example-kernel/.gitignore | 2 + example-kernel/Cargo.lock | 69 +++++++++++++++++++++++ example-kernel/Cargo.toml | 8 +++ example-kernel/src/main.rs | 31 ++++++++++ example-kernel/x86_64-example-kernel.json | 15 +++++ 7 files changed, 130 insertions(+) create mode 100644 example-kernel/.cargo/config create mode 100644 example-kernel/.gitignore create mode 100644 example-kernel/Cargo.lock create mode 100644 example-kernel/Cargo.toml create mode 100644 example-kernel/src/main.rs create mode 100644 example-kernel/x86_64-example-kernel.json diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 8123f323..fc16323b 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -106,3 +106,6 @@ steps: if [ $? -eq 123 ]; then (exit 0); else (exit 1); fi displayName: 'Test Bootloader' +- script: cargo xbuild + workingDirectory: example-kernel + displayName: 'Build Example Kernel' diff --git a/example-kernel/.cargo/config b/example-kernel/.cargo/config new file mode 100644 index 00000000..ab792469 --- /dev/null +++ b/example-kernel/.cargo/config @@ -0,0 +1,2 @@ +[build] +target = "x86_64-example-kernel.json" diff --git a/example-kernel/.gitignore b/example-kernel/.gitignore new file mode 100644 index 00000000..eccd7b4a --- /dev/null +++ b/example-kernel/.gitignore @@ -0,0 +1,2 @@ +/target/ +**/*.rs.bk diff --git a/example-kernel/Cargo.lock b/example-kernel/Cargo.lock new file mode 100644 index 00000000..be9487bc --- /dev/null +++ b/example-kernel/Cargo.lock @@ -0,0 +1,69 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +[[package]] +name = "array-init" +version = "0.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "nodrop 0.1.13 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "bit_field" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "bitflags" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "example-kernel" +version = "0.1.0" +dependencies = [ + "x86_64 0.3.4 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "nodrop" +version = "0.1.13" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "os_bootinfo" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "usize_conversions" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "ux" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "x86_64" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "array-init 0.0.4 (registry+https://github.com/rust-lang/crates.io-index)", + "bit_field 0.9.0 (registry+https://github.com/rust-lang/crates.io-index)", + "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", + "os_bootinfo 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)", + "usize_conversions 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", + "ux 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[metadata] +"checksum array-init 0.0.4 (registry+https://github.com/rust-lang/crates.io-index)" = "23589ecb866b460d3a0f1278834750268c607e8e28a1b982c907219f3178cd72" +"checksum bit_field 0.9.0 (registry+https://github.com/rust-lang/crates.io-index)" = "ed8765909f9009617974ab6b7d332625b320b33c326b1e9321382ef1999b5d56" +"checksum bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" = "228047a76f468627ca71776ecdebd732a3423081fcf5125585bcd7c49886ce12" +"checksum nodrop 0.1.13 (registry+https://github.com/rust-lang/crates.io-index)" = "2f9667ddcc6cc8a43afc9b7917599d7216aa09c463919ea32c59ed6cac8bc945" +"checksum os_bootinfo 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)" = "66481dbeb5e773e7bd85b63cd6042c30786f834338288c5ec4f3742673db360a" +"checksum usize_conversions 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "f70329e2cbe45d6c97a5112daad40c34cd9a4e18edb5a2a18fefeb584d8d25e5" +"checksum ux 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "53d8df5dd8d07fedccd202de1887d94481fadaea3db70479f459e8163a1fab41" +"checksum x86_64 0.3.4 (registry+https://github.com/rust-lang/crates.io-index)" = "b14609bad1c2c6a41113a1054f94394154e99bcb4b24cd7051109113c656c5a9" diff --git a/example-kernel/Cargo.toml b/example-kernel/Cargo.toml new file mode 100644 index 00000000..a9c76f70 --- /dev/null +++ b/example-kernel/Cargo.toml @@ -0,0 +1,8 @@ +[package] +name = "example-kernel" +version = "0.1.0" +authors = ["Philipp Oppermann "] +edition = "2018" + +[dependencies] +x86_64 = "0.3.4" diff --git a/example-kernel/src/main.rs b/example-kernel/src/main.rs new file mode 100644 index 00000000..7f472954 --- /dev/null +++ b/example-kernel/src/main.rs @@ -0,0 +1,31 @@ +#![no_std] // don't link the Rust standard library +#![no_main] // disable all Rust-level entry points + +use core::panic::PanicInfo; + +static HELLO: &[u8] = b"Hello World!"; + +#[no_mangle] // don't mangle the name of this function +pub extern "C" fn _start() -> ! { + // this function is the entry point, since the linker looks for a function + // named `_start` by default + + let vga_buffer = 0xb8000 as *mut u8; + + // print `HELLO` to the screen (see + // https://os.phil-opp.com/minimal-rust-kernel/#printing-to-screen) + for (i, &byte) in HELLO.iter().enumerate() { + unsafe { + *vga_buffer.offset(i as isize * 2) = byte; + *vga_buffer.offset(i as isize * 2 + 1) = 0xb; + } + } + + loop {} +} + +/// This function is called on panic. +#[panic_handler] +fn panic(_info: &PanicInfo) -> ! { + loop {} +} diff --git a/example-kernel/x86_64-example-kernel.json b/example-kernel/x86_64-example-kernel.json new file mode 100644 index 00000000..9afe809f --- /dev/null +++ b/example-kernel/x86_64-example-kernel.json @@ -0,0 +1,15 @@ +{ + "llvm-target": "x86_64-unknown-none", + "data-layout": "e-m:e-i64:64-f80:128-n8:16:32:64-S128", + "arch": "x86_64", + "target-endian": "little", + "target-pointer-width": "64", + "target-c-int-width": "32", + "os": "none", + "executables": true, + "linker-flavor": "ld.lld", + "linker": "rust-lld", + "panic-strategy": "abort", + "disable-redzone": true, + "features": "-mmx,-sse,+soft-float" + } From f427ce52fabfeeaac1fae7caa68e869e54e91708 Mon Sep 17 00:00:00 2001 From: Philipp Oppermann Date: Mon, 1 Apr 2019 13:59:34 +0200 Subject: [PATCH 5/8] Update build instructions in the Readme --- README.md | 42 ++++++++++++++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 008c7e56..f6251df2 100644 --- a/README.md +++ b/README.md @@ -10,28 +10,50 @@ Written for the [second edition](https://github.com/phil-opp/blog_os/issues/360) TODO -## Build and Run -You need a nightly [Rust](https://www.rust-lang.org) compiler and [cargo xbuild](https://github.com/rust-osdev/cargo-xbuild). +## Requirements -Then you can run the `builder` executable with your kernel as argument: +You need a nightly [Rust](https://www.rust-lang.org) compiler and [cargo xbuild](https://github.com/rust-osdev/cargo-xbuild). You also need the `llvm-tools-preview` component, which can be installed through `rustup component add llvm-tools-preview`. + +## Build + +The simplest way to use the bootloader is in combination with the [bootimage](https://github.com/rust-osdev/bootimage) tool. With the tool installed, you can add a normal cargo dependency on the `bootloader` crate to your kernel and then run `bootimage build` to create a bootable disk image. You can also execute `bootimage run` to run your kernel in [QEMU](https://www.qemu.org/) (needs to be installed). + +To compile the bootloader manually, you need to invoke `cargo xbuild` with a `KERNEL` environment variable that points to your kernel executable (in the ELF format): + +``` +KERNEL=/path/to/your/kernel/target/debug/your_kernel cargo xbuild +``` + +As an example, you can build the bootloader with example kernel from the `example-kernel` directory with the following commands: ``` -cd builder -cargo run -- --kernel path/to/your/kernel/elf/file +cd example-kernel +cargo xbuild +cd .. +KERNEL=example-kernel/target/x86_64-example-kernel/debug/example-kernel cargo xbuild --release ``` -This will output a file named `bootimage.bin` in the `../target/x86_64-bootloader/release` folder. +This results in a bootloader executable at `target/x86_64-bootloader.json/release/bootloader`. This executable is still an ELF file, which can't be run directly. + +## Run + +To run the compiled bootloader executable, you need to convert it to a binary file. You can use the `llvm-objcopy` tools that ships with the `llvm-tools-preview` rustup component. The easiest way to use this tool is using [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils), which can be installed through `cargo install cargo-binutils`. Then you can perform the conversion with the following command: + +``` +cargo objcopy -- -I elf64-x86-64 -O binary --binary-architecture=i386:x86-64 \ + target/x86_64-bootloader/release/bootloader target/x86_64-bootloader/release/bootloader.bin +``` -You can run this file using [QEMU](https://www.qemu.org/): +You can run the `bootloader.bin` file using [QEMU](https://www.qemu.org/): ``` -qemu-system-x86_64 -drive format=raw,file=target/x86_64-bootloader/release/bootimage.bin +qemu-system-x86_64 -drive format=raw,file=target/x86_64-bootloader/release/bootloader.bin ``` -Or burn it to an USB drive: +Or burn it to an USB drive to boot it on real hardware: ``` -dd if=target/x86_64-blog_os/debug/bootimage-blog_os.bin of=/dev/sdX && sync +dd if=target/x86_64-bootloader/release/bootloader.bin of=/dev/sdX && sync ``` Where sdX is the device name of your USB stick. **Be careful** to choose the correct device name, because everything on that device is overwritten. From 68e57587e135fc2755a1cc4feb8130c1b2f131c2 Mon Sep 17 00:00:00 2001 From: Philipp Oppermann Date: Mon, 1 Apr 2019 13:59:59 +0200 Subject: [PATCH 6/8] Document all crate features in the Readme --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f6251df2..d9137fa1 100644 --- a/README.md +++ b/README.md @@ -62,3 +62,5 @@ Where sdX is the device name of your USB stick. **Be careful** to choose the cor The bootloader crate can be configured through some cargo features: - `vga_320x200`: This feature switches the VGA hardware to mode 0x13, a graphics mode with resolution 320x200 and 256 colors per pixel. The framebuffer is linear and lives at address `0xa0000`. +- `recursive_page_table`: Maps the level 4 page table recursively and adds the [`recursive_page_table_address`](https://docs.rs/bootloader/0.4.0/bootloader/bootinfo/struct.BootInfo.html#structfield.recursive_page_table_addr) field to the passed `BootInfo`. +- `map_physical_memory`: Maps the complete physical memory in the virtual address space and passes a [`physical_memory_offset`](https://docs.rs/bootloader/0.4.0/bootloader/bootinfo/struct.BootInfo.html#structfield.physical_memory_offset) field in the `BootInfo`. From b9a4dff043cad552d07f89321f85410fdc7d436e Mon Sep 17 00:00:00 2001 From: Philipp Oppermann Date: Mon, 1 Apr 2019 14:00:11 +0200 Subject: [PATCH 7/8] Mention the license at the end of the Readme --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index d9137fa1..bbee206d 100644 --- a/README.md +++ b/README.md @@ -64,3 +64,15 @@ The bootloader crate can be configured through some cargo features: - `vga_320x200`: This feature switches the VGA hardware to mode 0x13, a graphics mode with resolution 320x200 and 256 colors per pixel. The framebuffer is linear and lives at address `0xa0000`. - `recursive_page_table`: Maps the level 4 page table recursively and adds the [`recursive_page_table_address`](https://docs.rs/bootloader/0.4.0/bootloader/bootinfo/struct.BootInfo.html#structfield.recursive_page_table_addr) field to the passed `BootInfo`. - `map_physical_memory`: Maps the complete physical memory in the virtual address space and passes a [`physical_memory_offset`](https://docs.rs/bootloader/0.4.0/bootloader/bootinfo/struct.BootInfo.html#structfield.physical_memory_offset) field in the `BootInfo`. + +## License + +Licensed under either of + +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or + http://www.apache.org/licenses/LICENSE-2.0) +- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. From 44b436d50252104f5c158138fee5ec54b82c1fb4 Mon Sep 17 00:00:00 2001 From: Philipp Oppermann Date: Mon, 1 Apr 2019 14:04:59 +0200 Subject: [PATCH 8/8] Update changelog --- Changelog.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Changelog.md b/Changelog.md index 24392c37..341c9ce0 100644 --- a/Changelog.md +++ b/Changelog.md @@ -1,3 +1,9 @@ +## Breaking + +- Change the build system: Use a build script that expects a `KERNEL` environment variable instead of using a separate `builder` executable as before. See [#51](https://github.com/rust-osdev/bootloader/pull/51) and [#53](https://github.com/rust-osdev/bootloader/pull/53) for more information. + - This makes the bootloader incompatible with versions `0.6.*` and earlier of the `bootimage` tool. + - The bootloader also requires the `llvm-tools-preview` rustup component now. + # 0.4.0 ## Breaking