From 26edf65eadfc10297543c004ffcb7ed9859175b2 Mon Sep 17 00:00:00 2001 From: Tulio A M Mendes Date: Sat, 7 Feb 2026 12:27:23 -0300 Subject: [PATCH] docs: update README and translate build guide --- .gitignore | 3 ++ BUILD_GUIDE.md | 81 ++++++++++++++++++++++++++++---------------------- README.md | 25 ++++++++++++---- 3 files changed, 67 insertions(+), 42 deletions(-) diff --git a/.gitignore b/.gitignore index da6084d..6143acd 100644 --- 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 dd2f7f4..0572a44 100644 --- 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 d1f7593..018a03e 100644 --- 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 -- 2.43.0