From 7a7f3da8e4c4a38ce02473fb5bd6904697fe24a1 Mon Sep 17 00:00:00 2001
From: Tulio A M Mendes <tadryanom@hotmail.com>
Date: Fri, 6 Feb 2026 11:41:57 -0300
Subject: [PATCH] docs: update features/todo and build guide

---
 BUILD_GUIDE.md      | 40 +++++++++++-------------------------
 README.md           | 49 +++++++++++++++++++++++++++++++++++++++++++++
 src/arch/x86/boot.S |  2 +-
 3 files changed, 62 insertions(+), 29 deletions(-)

diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md
index 0208288..dd2f7f4 100644
--- a/BUILD_GUIDE.md
+++ b/BUILD_GUIDE.md
@@ -31,43 +31,27 @@ make ARCH=x86
 Isso gera o arquivo `adros-x86.bin`.
 
 ### Criar ISO Bootável (GRUB)
-Para x86, precisamos empacotar o kernel numa ISO com GRUB.
+Para x86, o repositório já inclui uma árvore `iso/` com o GRUB configurado.
 
-1. Compile o gerador de InitRD:
 ```bash
-gcc tools/mkinitrd.c -o mkinitrd
+make ARCH=x86 iso
 ```
 
-2. Crie arquivos de teste:
-```bash
-echo "Hello from File System!" > test.txt
-echo "AdrOS v0.3" > version.txt
-./mkinitrd initrd.img test.txt version.txt
-```
+Isso gera `adros-x86.iso`.
 
-3. Empacote a ISO:
+### Rodar no QEMU
 ```bash
-mkdir -p iso_root/boot/grub
-cp adros-x86.bin iso_root/boot/
-cp initrd.img iso_root/boot/
-
-cat > iso_root/boot/grub/grub.cfg << EOF
-menuentry "AdrOS" {
-    multiboot2 /boot/adros-x86.bin
-    module2 /boot/initrd.img
-    boot
-}
-EOF
-
-grub-mkrescue -o adros.iso iso_root
+make ARCH=x86 run
 ```
 
-### Rodar no QEMU
+Saídas/artefatos gerados:
+- `serial.log`: log do UART (saída principal do kernel)
+- `qemu.log`: só é gerado quando o debug do QEMU está habilitado (veja abaixo)
+
+Para habilitar debug do QEMU (mais leve por padrão, para evitar travamentos por I/O excessivo):
 ```bash
-qemu-system-i386 -cdrom adros.iso -serial stdio
+make ARCH=x86 run QEMU_DEBUG=1
 ```
-- A saída de texto aparecerá no terminal (`-serial stdio`).
-- Se tivermos VGA ativado, uma janela gráfica abrirá.
 
 ## 3. Compilando e Rodando (ARM64)
 
@@ -104,5 +88,5 @@ qemu-system-riscv64 -machine virt -m 128M -nographic \
 ## 5. Troubleshooting Comum
 
 - **"Multiboot header not found"**: Verifique se o `grub-file --is-x86-multiboot2 adros-x86.bin` retorna sucesso (0). Se falhar, a ordem das seções no `linker.ld` pode estar errada.
-- **Triple Fault (Reset infinito)**: Geralmente erro na tabela de paginação (VMM) ou IDT mal configurada. Use `-d int,cpu_reset -D log.txt` no QEMU para debugar.
+- **"Triple Fault (Reset infinito)"**: Geralmente erro na tabela de paginação (VMM) ou IDT mal configurada. Rode `make ARCH=x86 run QEMU_DEBUG=1` e inspecione `qemu.log`.
 - **Tela preta (VGA)**: Se estiver rodando com `-nographic`, você não verá o VGA. Remova essa flag para ver a janela.
diff --git a/README.md b/README.md
index b5490f0..d1f7593 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,55 @@ AdrOS is a multi-architecture operating system developed for research and academ
 - **Bootloader:** GRUB2 (Multiboot2 compliant)
 - **Build System:** Make + Cross-Compilers
 
+## Features
+- **Multi-arch build system**
+  - `make ARCH=x86|arm|riscv|mips`
+  - x86 is the primary, working target
+- **x86 (i386) boot & memory layout**
+  - Multiboot2 (via GRUB)
+  - Higher-half kernel mapping (3GB+)
+  - Early paging + VMM initialization
+  - W^X-oriented linker layout (separate RX/R/RW segments)
+  - Non-executable stack markers in assembly (`.note.GNU-stack`)
+- **Memory management**
+  - Physical Memory Manager (PMM)
+  - Virtual Memory Manager (x86)
+  - Kernel heap allocator (`kmalloc`/`kfree`)
+- **Basic drivers & console**
+  - UART serial console logging
+  - VGA text console (x86)
+  - Keyboard driver + input callback
+  - PIT timer + periodic tick
+- **Kernel services**
+  - Simple scheduler / multitasking (kernel threads)
+  - Basic shell with built-in commands
+- **InitRD + VFS glue**
+  - InitRD-backed filesystem node tree
+  - Minimal VFS helpers (`vfs_read`/`vfs_write`/open/close)
+- **Syscalls & ring3 bring-up (x86)**
+  - `int 0x80` syscall gate
+  - `SYSCALL_WRITE`, `SYSCALL_EXIT`, `SYSCALL_GETPID`
+  - Centralized user-pointer access API (`user_range_ok`, `copy_from_user`, `copy_to_user`)
+  - Ring3 stub test program with fault-injection for invalid pointers
+
+## TODO
+- **Multi-architecture kernel bring-up**
+  - Implement VMM/interrupts/scheduler for ARM/RISC-V/MIPS
+  - Standardize arch entrypoint behavior (`arch_start`) across architectures
+- **Userspace**
+  - Real userspace loader (e.g., ELF)
+  - Process address spaces + page fault handling
+  - Safer syscall ABI expansion
+- **Virtual memory hardening**
+  - Reduce early identity mapping further (keep only what is required)
+  - Guard pages, user/kernel separation checks beyond current page-walk
+- **Filesystem**
+  - Persisted storage (ATA/AHCI/virtio-blk or similar)
+  - Path resolution, directories, permissions
+- **Observability & tooling**
+  - Better memory stats (`mem` shell command)
+  - Debug facilities (panic backtraces, symbolization, structured logs)
+
 ## Directory Structure
 - `src/kernel/` - Architecture-independent kernel code
 - `src/arch/` - Architecture-specific code (boot, context switch, interrupts)
diff --git a/src/arch/x86/boot.S b/src/arch/x86/boot.S
index 9580038..7f06759 100644
--- a/src/arch/x86/boot.S
+++ b/src/arch/x86/boot.S
@@ -192,4 +192,4 @@ stack_top:
 .section .note.GNU-stack,"",@progbits
 
 /* Helper symbol for map loop limit */
-_kernel_physical_end:
\ No newline at end of file
+_kernel_physical_end:
-- 
2.43.0