improve README.md

README.md

@@ -1,17 +1,38 @@
 # <img width="40" height="40" alt="red-pepper" src="https://i.ibb.co/mrHH6d1m/pixil-frame-0-4.png" /> pepperOS: "will never be done"
 
-## Trying the kernel
+## Description
 
-First install the dependencies: `sudo apt install python3 xorriso make qemu-system`
+PepperOS is a 64-bit freely-licensed monolithic kernel for x86 processors, with round-robin preemptive scheduling and 4-level paging. See the [manual](docs/MANUAL.md) for more.
 
-Also, you have to get an x86_64 toolchain for compilation. The easiest way to do that on most systems is to install it from Homebrew:
+## Trying the kernel in QEMU
+
+### Debian-based distributions
+
+First, install the dependencies: `sudo apt install nasm python3 xorriso make qemu-system`
+
+Then, you can get an x86_64 toolchain for compilation. The easiest way to do that on most systems is to install it from Homebrew:
 
 ```
 brew install x86_64-elf-gcc
 ```
 
-Then, to compile the kernel and make an ISO image file: `make build-iso`
+If you're already on a 64-bit machine (which you probably are), and don't want to install a cross-compiler, you can just override `CC` and `LD` variables in the Makefile, like so:
-To run it with QEMU, `make run`
+
+```
+CC := gcc
+LD := ld
+```
+
+Then, to compile the kernel and make an ISO image file, run: `make build-iso`
+To run it with QEMU, do: `make run`
+
+## Trying the kernel on real hardware
+
+Compile the kernel and generate an ISO image like described above, then burn the image to a USB stick, `/dev/sdX` being the device name (you can get it using `lsblk`):
+
+```
+sudo dd if=pepper.iso of=/dev/sdX
+```
 
 ## TODO
 
@@ -44,7 +65,7 @@ In the future, maybe?
 PepperOS wouldn't be possible without the following freely-licensed software:
 
 - the [Limine](https://codeberg.org/Limine/Limine) portable bootloader
-- Marco Paland's freestanding [printf implementation](https://github.com/mpaland)
+- Charles Nicholson's [nanoprintf](https://github.com/charlesnicholson/nanoprintf)
 - Mintuski's [Flanterm](https://codeberg.org/Mintsuki/Flanterm) terminal emulator
 
 ...and without these amazing resources:
@@ -52,3 +73,4 @@ PepperOS wouldn't be possible without the following freely-licensed software:
 - the [OSDev](https://osdev.org) wiki & forums
 - Intel 64 and IA-32 Architectures Software Developer's Manual
 - Documentation for the [GNU Compiler Collection](https://gcc.gnu.org/onlinedocs/gcc/)
+- dreamos82's [OSDev Notes](https://github.com/dreamportdev/Osdev-Notes/tree/master)

docs/MANUAL.md

@@ -0,0 +1,19 @@
+# PepperOS Manual
+
+# Table of Contents
+
+- nothing (yet).
+
+## I. Kernel architecture
+
+### a. Boot process
+
+### b. Memory management
+
+### c. Scheduling
+
+### d. Input/Output
+
+## II. Syscall table
+
+Not yet implemented.