docs: update README and translate build guide

diff --git a/.gitignore b/.gitignore
index da6084d4336e5a51dc86accf88858be0a8e9f248..6143acd6b4fe1e5a040245836db2a00c75f93ba7 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,7 @@ clang-tidy.txt
 cppcheck.txt
 cppcheck2.txt
 cppcheck3.txt
+cppcheck_verify.txt
 scanbuild-out/
 gcc-analyzer.txt
 splint.txt
@@ -27,6 +28,8 @@ tools/mkinitrd
 iso_root/
 isodir/
 
+supplementary-material
+
 # Editor/OS clutter
 .DS_Store
 .vscode/

diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md
index dd2f7f44612b09be0810bd08c98738d903becf50..0572a444421149e769138589bfa1138f6d0dfe00 100644 (file)
--- a/BUILD_GUIDE.md
+++ b/BUILD_GUIDE.md
@@ -1,17 +1,17 @@
 # AdrOS - Build & Run Guide
 
-Este guia explica como compilar e rodar o AdrOS em sua máquina local (Linux/WSL).
+This guide explains how to build and run AdrOS on your local machine (Linux/WSL).
 
-## 1. Dependências
+## 1. Dependencies
 
-Você precisará de:
-- `make` e `gcc` (build system)
-- `qemu-system-*` (emuladores)
-- `xorriso` (para criar ISOs bootáveis)
-- `grub-pc-bin` e `grub-common` (bootloader x86)
-- Compiladores cruzados (Cross-compilers) para ARM/RISC-V
+You will need:
+- `make` and `gcc` (build system)
+- `qemu-system-*` (emulators)
+- `xorriso` (to create bootable ISOs)
+- `grub-pc-bin` and `grub-common` (x86 bootloader)
+- Cross-compilers for ARM/RISC-V
 
-### No Ubuntu/Debian:
+### On Ubuntu/Debian:
 ```bash
 sudo apt update
 sudo apt install build-essential bison flex libgmp3-dev libmpc-dev libmpfr-dev texinfo \
@@ -20,73 +20,82 @@ sudo apt install build-essential bison flex libgmp3-dev libmpc-dev libmpfr-dev t
     gcc-aarch64-linux-gnu gcc-riscv64-linux-gnu
 ```
 
-## 2. Compilando e Rodando (x86)
+## 2. Building & Running (x86)
 
-Esta é a arquitetura principal (PC padrão).
+This is the primary target (standard PC).
 
-### Compilar
+### Build
 ```bash
 make ARCH=x86
 ```
-Isso gera o arquivo `adros-x86.bin`.
+This produces `adros-x86.bin`.
 
-### Criar ISO Bootável (GRUB)
-Para x86, o repositório já inclui uma árvore `iso/` com o GRUB configurado.
+### Create a bootable ISO (GRUB)
+For x86, the repository includes an `iso/` tree with GRUB already configured.
 
 ```bash
 make ARCH=x86 iso
 ```
 
-Isso gera `adros-x86.iso`.
+This produces `adros-x86.iso`.
 
-### Rodar no QEMU
+### Run on QEMU
 ```bash
 make ARCH=x86 run
 ```
 
-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)
+Generated outputs/artifacts:
+- `serial.log`: UART log (primary kernel output)
+- `qemu.log`: only generated when QEMU debug logging is enabled (see below)
 
-Para habilitar debug do QEMU (mais leve por padrão, para evitar travamentos por I/O excessivo):
+To enable QEMU debug logging (disabled by default to avoid excessive I/O):
 ```bash
 make ARCH=x86 run QEMU_DEBUG=1
 ```
 
-## 3. Compilando e Rodando (ARM64)
+To also log hardware interrupts:
+```bash
+make ARCH=x86 run QEMU_DEBUG=1 QEMU_INT=1
+```
+
+Notes:
+- `QEMU_DEBUG=1` enables QEMU logging to `qemu.log` using `-d guest_errors,cpu_reset -D qemu.log`.
+- `QEMU_INT=1` appends `-d int` to QEMU debug flags.
+
+## 3. Building & Running (ARM64)
 
-### Compilar
+### Build
 ```bash
 make ARCH=arm
 ```
-Isso gera `adros-arm.bin`.
+This produces `adros-arm.bin`.
 
-### Rodar no QEMU
-ARM não usa GRUB/ISO da mesma forma, carregamos o kernel direto na memória.
+### Run on QEMU
+ARM does not use GRUB/ISO in the same way. The kernel is loaded directly into memory.
 
 ```bash
 qemu-system-aarch64 -M virt -cpu cortex-a57 -m 128M -nographic \
     -kernel adros-arm.bin
 ```
-- Para sair do QEMU sem gráfico: `Ctrl+A` solte, depois `x`.
+- To quit QEMU when using `-nographic`: press `Ctrl+A`, release, then `x`.
 
-## 4. Compilando e Rodando (RISC-V)
+## 4. Building & Running (RISC-V)
 
-### Compilar
+### Build
 ```bash
 make ARCH=riscv
 ```
-Isso gera `adros-riscv.bin`.
+This produces `adros-riscv.bin`.
 
-### Rodar no QEMU
+### Run on QEMU
 ```bash
 qemu-system-riscv64 -machine virt -m 128M -nographic \
     -bios default -kernel adros-riscv.bin
 ```
-- Para sair: `Ctrl+A`, `x`.
+- To quit: `Ctrl+A`, then `x`.
 
-## 5. Troubleshooting Comum
+## 5. Common Troubleshooting
 
-- **"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. 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.
+- **"Multiboot header not found"**: Check whether `grub-file --is-x86-multiboot2 adros-x86.bin` returns success (0). If it fails, the section order in `linker.ld` may be wrong.
+- **"Triple Fault (infinite reset)"**: Usually caused by paging (VMM) issues or a misconfigured IDT. Run `make ARCH=x86 run QEMU_DEBUG=1` and inspect `qemu.log`.
+- **Black screen (VGA)**: If you are running with `-nographic`, you will not see the VGA output. Remove that flag to get a window.

diff --git a/README.md b/README.md
index d1f7593f71d3f8941f96834cf7b5af37959c87e4..018a03e1b8b16ab19bd0d7091ec47f42b4e5c58b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ AdrOS is a multi-architecture operating system developed for research and academ
   - Multiboot2 (via GRUB)
   - Higher-half kernel mapping (3GB+)
   - Early paging + VMM initialization
-  - W^X-oriented linker layout (separate RX/R/RW segments)
+  - W^X-oriented userspace layout (separate RX/R and RW segments)
   - Non-executable stack markers in assembly (`.note.GNU-stack`)
 - **Memory management**
   - Physical Memory Manager (PMM)
@@ -44,18 +44,31 @@ AdrOS is a multi-architecture operating system developed for research and academ
   - `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
+- **W^X (Option 1) for user ELFs (x86)**
+  - User segments are mapped RW during load, then write permissions are dropped for non-writable segments
+  - This provides "text is read-only" hardening without requiring NX/PAE
+
+## Running (x86)
+- `make ARCH=x86 iso`
+- `make ARCH=x86 run`
+- Logs:
+  - `serial.log`: kernel UART output
+  - `qemu.log`: QEMU debug output when enabled
+
+QEMU debug helpers:
+- `make ARCH=x86 run QEMU_DEBUG=1`
+- `make ARCH=x86 run QEMU_DEBUG=1 QEMU_INT=1`
 
 ## 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
+  - Process model (fork/exec/wait), per-process address spaces, and cleanup on `exit`
+  - Syscall ABI expansion (read/open/close, file descriptors, etc.)
 - **Virtual memory hardening**
-  - Reduce early identity mapping further (keep only what is required)
-  - Guard pages, user/kernel separation checks beyond current page-walk
+  - Option 2: PAE + NX enforcement (execute disable for data/stack)
+  - Guard pages, and tighter user/kernel separation checks
 - **Filesystem**
   - Persisted storage (ATA/AHCI/virtio-blk or similar)
   - Path resolution, directories, permissions