Merge #66

66: Add guide on chainloading r=phil-opp a=64



Co-authored-by: Matt Taylor <[email protected]>

Author: bors[bot]

README.md

@@ -66,6 +66,12 @@ The bootloader crate can be configured through some cargo features:
 - `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`.
   - The virtual address where the physical memory should be mapped is configurable by setting the `BOOTLOADER_PHYSICAL_MEMORY_OFFSET` environment variable (supports decimal and hex numbers (prefixed with `0x`)).
 
+## Advanced Documentation
+See these guides for advanced usage of this crate:
+
+- [Chainloading](doc/chainloading.md)
+- Higher Half Kernel - TODO
+
 ## License
 
 Licensed under either of

doc/chainloading.md

@@ -0,0 +1,23 @@
+# Chainloading
+
+Chainloading is a technique that allows one bootloader to call another bootloader as if the system had just booted up. [GNU GRUB](https://www.gnu.org/software/grub/) is one such bootloader which is commonly used for chainloading, as it presents a menu which you can use to select the OS you'd like to boot from. We're using `grub2` here.
+
+Create a file under `iso/boot/grub/grub.cfg` in the root directory of your OS's source tree. In it, put:
+
+```
+menuentry "myOS" {
+	chainloader (hd1)+1
+}
+```
+
+This tells grub that our binary is installed on the first partition of the `hd1` disk. If you're trying to boot on real hardware you may need to edit this value as appropriate. Alternatively, you should be able to create a partition on the same ISO file that grub creates and copy the binary there.
+
+Next, create the ISO with:
+```
+grub-mkrescue -o grub.iso iso
+```
+
+Testing with QEMU (replacing `my_os` with the name of your OS's target):
+```
+qemu-system-x86_64 -hda grub.iso -hdb target/x86_64-my_os/debug/bootimage-my_os.bin
+```