1# renaser — guía operativa
2
3**renaser** es un kernel asíncrono de *Espacio de Direccionamiento Único*
4(SASOS) en Rust `#![no_std]`, bare-metal x86_64. Rompe con POSIX: interfaz
5visual nativa desde el arranque, aislamiento **por software** (no por MMU),
6el texto como caso particular del dibujo.
7
8Documentos hermanos: `ARCHITECTURE.md` (arquitectura), `ROADMAP.md` (fases y
9plan), `CHANGELOG.md` (registro técnico de cambios), `DIARIO.md` (crónica en
10lenguaje llano), `README.md` (presentación).
11
12## Construir y ejecutar
13
14Desde la raíz del repositorio:
15
16| Comando | Efecto |
17|---|---|
18| `cargo run` | compila el kernel, forja la imagen UEFI y abre QEMU |
19| `cargo build` | compila el kernel + la imagen, sin lanzar QEMU |
20| `cargo kernel` | alias: compila solo el kernel para `x86_64-unknown-none` |
21
22Verificación headless (sin ventana): añadir
23`-- -display none -monitor unix:/tmp/q.sock,server,nowait` y capturar con
24`screendump` por el socket del monitor.
25
26Reconstruir la app WASM del userspace tras tocar `apps/hello_wasm`:
27
28```sh
29cd apps/hello_wasm
30cargo build --target wasm32-unknown-unknown --release
31cp target/wasm32-unknown-unknown/release/hello_wasm.wasm ../../kernel/assets/app.wasm
32```
33
34## Estructura del espacio de trabajo
35
36- `boot/` — orquestador de **anfitrión**: construye la imagen de disco UEFI con
37  la crate `bootloader` 0.11 y lanza QEMU. Es el **único miembro** del workspace.
38- `kernel/` — el kernel **bare-metal**. Está **excluido** del workspace y se
39  compila solo como dependencia de artefacto de `boot` (target
40  `x86_64-unknown-none`). NUNCA debe ser miembro del workspace ni compilarse
41  para el anfitrión: lo haría fallar por un `_start` duplicado.
42- `apps/` — aplicaciones del userspace, módulos `.wasm`
43  (target `wasm32-unknown-unknown`). Workspaces propios, excluidos.
44
45Módulos del kernel (`kernel/src/`): `main`, `grafico`, `consola`, `baliza`,
46`sync`, `gdt`, `interrupts`, `pic`, `drivers/`, `almacen`, `memory/`,
47`async_system/`, `texto`, `wasm/`. El detalle de cada uno está en
48`ARCHITECTURE.md`.
49
50## Toolchain
51
52Nightly, fijado en `rust-toolchain.toml`. Targets `x86_64-unknown-none` y
53`wasm32-unknown-unknown`. Componentes `rust-src` y `llvm-tools` (los exige el
54build script de la crate `bootloader`). Entorno verificado: Artix Linux,
55QEMU 11, OVMF en `/usr/share/edk2/x64/OVMF.4m.fd` (sin módulo KVM → TCG).
56
57## Convenciones
58
59- **Idioma:** comentarios E identificadores en español.
60- **`unsafe`:** confinado en células mínimas, envuelto de inmediato en una
61  abstracción segura. `#![deny(unsafe_op_in_unsafe_fn)]`. Cada bloque `unsafe`
62  lleva un comentario `SEGURIDAD:` que justifica su corrección.
63- **Framebuffer / MMIO:** siempre `core::ptr::write_volatile`; jamás asignación
64  indexada directa (el optimizador la elidiría).
65- **`no_std` estricto:** solo `core::*` y `alloc::*` (heap vivo desde la Fase 3).
66  Prohibido cualquier ruta de `std::*`.
67- **Alineación:** 16 bytes para estructuras genéricas; 4096 bytes (página) para
68  buffers de memoria y regiones de asignador.
69- Código densamente comentado; se cuida la coherencia de estilo entre módulos.
70
71## Estado
72
73Fases 1 a 5, 6.0, 6.1 y 6.2 completas; y la Fase 7 —el userspace nace del
74grafo de objetos— en sus sub-fases 7a (Manifiesto de Génesis, carga desde el
75grafo) y 7b (`boot` siembra la imagen, muere el `include_bytes!` del kernel).
76Todo verificado en QEMU. Pendiente: 7c (persistencia inter-sesión). Ver
77`ROADMAP.md`.
78
79## Flujo de trabajo
80
81En **cada iteración** de trabajo, sin excepción:
82
831. Actualizar `CHANGELOG.md` — la entrada técnica detallada del cambio.
842. Actualizar `DIARIO.md` — la misma jornada contada en lenguaje llano y
85   elegante, sin carga técnica (es una crónica humana, no un registro técnico).
863. Verificar en QEMU si el cambio es observable (con captura de pantalla).
874. `git commit` (mensaje en español, descriptivo) y `git push origin main`.
88
89renaser vive ahora dentro del monorepo **brahman**; los commits van al remoto
90de brahman (`gitea.gioser.net/sergio/brahman`). Mensajes de commit en español.
91Verifica una fase en QEMU antes de darla por cerrada.