docs: update README.md

README.md

@@ -1,22 +1,120 @@
 # NovaOS
 
-NovaOS is a expository project where I build a kernel from scratch for a Raspberry PI 3 B+.
+![NovaOS banner](docs/banner.png)
 
-## Features
+NovaOS is a hobby operating system kernel written in Rust for the Raspberry Pi 3 B+.
+It is built as a learning project for low-level systems programming, bare-metal boot flow, and kernel development.
 
-- Delay and sleep ✓
-- UART ✓
-- Switching ELs ✓
-- GPIOs ✓
-- GPIO Interrupts ✓
-- Communicate with peripherals via mailboxes ✓
-- Frame Buffer ✓
-- Heap Memory allocation ✓
-- MMU ✓
-- SVC instructions ~
-- Basic Console over UART ~
-- Multi Applications ~
-- Multi Core
-- Dynamic clock speed
-- Kernel Independent Applications
-- Multiprocessing
+## At A Glance
+
+NovaOS currently includes:
+
+- UART initialization and logging
+- Delay and sleep primitives
+- Exception level transitions across EL2, EL1, and EL0
+- GPIO control and interrupt handling
+- Peripheral mailbox communication
+- Framebuffer drawing primitives
+- Heap memory allocation
+- MMU initialization and translation table setup
+
+Work in progress:
+
+- SVC instruction handling
+- Basic UART console improvements
+- Multi-application management
+
+Planned next:
+
+- Multi-core support
+- Dynamic clock speed management
+- Kernel-independent applications
+- Multiprocessing improvements
+
+## Project Structure
+
+- `src/` - kernel source, architecture code, peripherals, interrupts, and runtime
+- `workspace/` - supporting crates such as `heap` and `nova_error`
+- `tools/` - build, simulation, SD image generation, and deployment scripts
+- `firmware_files/` - Raspberry Pi firmware files copied to SD or TFTP
+- `link.ld` - linker script for the kernel image
+
+## Requirements
+
+You will need:
+
+- Rust nightly toolchain (`rust-toolchain.toml` pins `nightly`)
+- Rust target `aarch64-unknown-none`
+- `llvm-objcopy` for generating `kernel8.img`
+- `qemu-system-aarch64` for emulation
+- `mtools` (`mformat`, `mcopy`) for SD image generation
+
+Install the Rust target if needed:
+
+```bash
+rustup target add aarch64-unknown-none
+```
+
+## Build
+
+Debug image:
+
+```bash
+cd tools
+./build_debug.sh
+```
+
+Release image:
+
+```bash
+cd tools
+./build_release.sh
+```
+
+Both scripts produce a `kernel8.img` under `target/aarch64-unknown-none/<profile>/`.
+
+## Run In QEMU
+
+1. Generate an SD image with firmware files:
+
+```bash
+cd tools
+./generate_sd_card.sh
+```
+
+2. Start the emulator:
+
+```bash
+cd tools
+./start_simulator.sh
+```
+
+For debug mode with the GDB stub enabled (`-S -s`):
+
+```bash
+cd tools
+./start_simulator_debug.sh
+```
+
+## Deploy To Hardware
+
+Use the TFTP workflow to deploy to a Raspberry Pi:
+
+1. Copy `.env.example` to `.env` and fill in your values:
+   - `REMOTE_USER`
+   - `REMOTE_HOST`
+   - `TFTP_PATH`
+   - `BUILD_PATH`
+   - `BINARY_NAME`
+   - `KERNEL_NAME`
+2. Run:
+
+```bash
+cd tools
+./deply_to_hw.sh
+```
+
+## Notes
+
+- This is an educational kernel project and is actively evolving.
+- Interfaces and boot flow may change as features are added.