1# renaser — Arquitectura
2
3Este documento describe la arquitectura del kernel `renaser` subsistema a
4subsistema. Para el estado por fases, ver `ROADMAP.md`.
5
6## 1. Filosofía
7
8renaser es un **SASOS** — *Single Address Space Operating System*. No hay un
9espacio de direcciones por proceso ni cambios de contexto de hardware: todo el
10sistema —kernel y aplicaciones— comparte una única RAM plana.
11
12El aislamiento NO lo da la MMU ni los anillos de privilegio de la CPU. Lo da el
13**software**: las aplicaciones se distribuyen como bytecode WebAssembly y se
14ejecutan dentro de un intérprete que acota matemáticamente cada acceso a
15memoria. Una aplicación solo puede hacer aquello para lo que el kernel le haya
16inyectado una *capacidad* (una función de host). Lo que no está importado no
17tiene camino físico que recorrer.
18
19La interfaz es **visual desde el primer microsegundo**. No hay TTY; el texto se
20rasteriza como gráfico vectorial. "El texto es un caso particular del dibujo."
21
22## 2. La cadena de arranque
23
24```
25Firmware UEFI  →  crate `bootloader` 0.11  →  kernel::_start  →  kernel_main
26```
27
28El miembro `boot/` (que corre en el **anfitrión**) toma el ELF del kernel,
29lo fusiona con el cargador `bootloader` 0.11 en una imagen de disco UEFI GPT y
30la lanza en QEMU con el firmware OVMF. El cargador deja la CPU en modo largo de
3164 bits, mapea el kernel y le entrega una `BootInfo` con el framebuffer GOP.
32
33## 3. Estructura del espacio de trabajo
34
35El workspace tiene **un solo miembro**, `boot`. El `kernel` y las `apps` están
36**excluidos** a propósito:
37
38- El kernel es `#![no_std] #![no_main]` y define su propio `_start`. Si fuese
39  miembro del workspace, `cargo build` intentaría compilarlo para el anfitrión
40  y fallaría por un símbolo `_start` duplicado con el `crt0` del sistema.
41- Por eso el kernel se construye **solo** como *dependencia de artefacto*
42  (RFC 3028) de `boot`, que le fija el target `x86_64-unknown-none`.
43- Las apps WASM tienen su propio target (`wasm32-unknown-unknown`) y se
44  compilan aparte.
45
46El kernel usa el target **nativo precompilado** `x86_64-unknown-none`: sin
47target JSON propio, sin `build-std`. Soft-float y sin SSE, para que las
48interrupciones no corrompan registros de punto flotante.
49
50## 4. Subsistemas del kernel
51
52### `grafico` — el sustrato visual
53`Color` (RGB de 24 bits, independiente del hardware), `Pantalla` (el
54framebuffer GOP físico, envuelto en seguridad) y `Lienzo` (el búfer intermedio
55en RAM). Toda composición ocurre en el `Lienzo`; `Pantalla::presentar` lo
56vuelca de un solo gesto con escrituras volátiles — **doble búfer**, sin
57desgarros. `codificar` traduce un `Color` al formato nativo del framebuffer.
58
59### `consola` — la superficie de texto e imagen
60Une `Lienzo` + `Pantalla` + una pluma de escritura. Rasteriza glifos con
61`fontdue` y los funde sobre el lienzo mezclando por cobertura (anti-aliasing).
62También vuelca fotogramas crudos del userspace WASM. Es global, tras un `Mutex`.
63
64### `baliza` — la red de seguridad visual
65Publica de forma atómica y sin cerrojos los datos mínimos del framebuffer. Los
66manejadores `#[panic_handler]` y `#[alloc_error_handler]` los usan para pintar
67una franja de advertencia —**roja** si el sistema colapsa, **naranja** si el
68heap se agota— escribiendo directo sobre el silicio, sin confiar en el heap ni
69en estructura dinámica alguna.
70
71### `gdt` — cimientos del manejo de fallos
72GDT propia con segmentos de código y datos del kernel, y un TSS cuyo único
73cometido es alojar un **stack de emergencia** (IST) para el doble fallo: ni un
74desbordamiento de la pila del kernel impide su diagnóstico.
75
76### `interrupts` — la tabla de reflejos
77IDT con manejadores de excepción de CPU (breakpoint recuperable; el resto,
78fatales → `panic!`) e interrupciones de hardware. El doble fallo se atiende
79sobre el stack de emergencia del TSS.
80
81### `pic` — el latido del hardware
82Remapea el par 8259 (PIC) fuera del rango de las excepciones de CPU y programa
83el temporizador de intervalos (PIT). El teclado (IRQ1) deposita scancodes en
84una cola lock-free. `desenmascarar` abre una línea de IRQ concreta —la del
85disco, descubierta en tiempo de ejecución (Fase 6.2)—.
86
87### `drivers` — el hardware que el kernel conquista (Fases 6.1, 6.2)
88A diferencia del framebuffer o el temporizador —que el firmware sirve en
89bandeja—, el disco hay que DESCUBRIRLO y reclamarlo.
90- `pci` — `CamPuertos`: acceso al espacio de configuración del bus PCI por el
91  mecanismo #1 (puertos `0xCF8`/`0xCFC`); `linea_irq` lee la IRQ del dispositivo.
92- `disco` — el disco virtio-blk. Un asignador de marcos por **mapa de bits**
93  —con liberación real— reparte páginas físicas para el DMA; `KernelHal`
94  implementa el `trait Hal` de `virtio-drivers` (traducción de direcciones,
95  memoria rebote para el DMA); el `VirtIOBlk` se monta una vez y persiste tras
96  un `Mutex`. La E/S de bloques es **asíncrona** (Fase 6.2): `EsperaDisco` es un
97  `Future` que envía la petición por la API no bloqueante de `virtio-drivers`,
98  cede la CPU y se reanuda con la IRQ del disco (`atender_irq`). `bloquear_en`
99  conduce ese `Future` desde los contextos síncronos durmiendo la CPU con
100  `hlt`; sobre él, `leer_sectores`/`escribir_sectores` sirven al grafo de
101  objetos. La IRQ del disco se enruta por el PIC 8259, no por el IOAPIC.
102
103### `almacen` — el grafo de objetos direccionado por contenido (Fase 6.1c)
104renaser no tiene un sistema de archivos plano POSIX: tiene un DAG de objetos.
105Un `Objeto` es una carga útil de bytes y una lista de aristas (hashes de
106hijos). La identidad de un objeto es el hash BLAKE3 de su forma serializada
107(`postcard`) — de ahí integridad (un objeto se verifica al leerlo) y
108deduplicación (contenido idéntico, un solo registro). El disco es un **log**:
109el sector 0 es el superbloque (magia, versión, cursor, raíz); tras él se anexan
110los registros de objetos. Un índice hash→sector se reconstruye al arrancar
111recorriendo el log. Las capacidades `sys_object_*` exponen el grafo al
112userspace.
113
114### `memory` — el heap dinámico
115`linked_list_allocator` como `#[global_allocator]` sobre una región estática de
11664 MiB en `.bss`. Desbloquea `alloc::*` — `Box`, `Vec`, `BTreeMap`, `Arc`.
117
118### `async_system` — el reactor cooperativo
119- `task` — `Task`: un `Future` anclado (`Pin<Box<dyn Future>>`) con `TaskId`.
120- `executor` — el `Executor`: censo de tareas, cola de listas, y un `hlt`
121  controlado cuando no hay trabajo.
122- `waker` — un `Waker` que reinyecta el `TaskId` en la cola al despertar.
123- `teclado` — los canales de scancodes. Cada app abre el suyo; la IRQ1 **difunde**
124  cada scancode a todos, de modo que varias apps reciben la entrada en paralelo.
125- `reloj` — convierte la IRQ0 (PIT, 100 Hz) en el `Future` `EsperaFrame`, que se
126  resuelve en el siguiente pulso. Es el **compás de los fotogramas**: una tarea
127  WASM hace su trabajo de un fotograma y `.await`-ea el siguiente.
128
129Las interrupciones de hardware no conmutan el contexto de la CPU: **despiertan
130tareas**. El kernel avanza cooperativamente.
131
132### `texto` — tipografía vectorial
133Empotra un `.ttf` en el binario (`include_bytes!`) y lo rasteriza con `fontdue`
134glifo a glifo, bajo demanda.
135
136### `wasm` — el escudo de aislamiento
137- `mod` — el runtime y la `AplicacionWasm`: una instancia **persistente** entre
138  fotogramas (`Store` + `TypedFunc<(), ()>` + región). El ABI del userspace es
139  `init()` (una vez) y `tick()` (un fotograma, y retorna). Dos guardarraíles
140  acotan a cada app: el **temporal** —un presupuesto de **combustible** (`fuel`)
141  por `tick`; agotarlo la desaloja (baliza púrpura)— y el **espacial** —un techo
142  de memoria lineal vía `Store::limiter`; rebasarlo la desaloja (baliza
143  amarilla)—. En ambos casos `wasmi` lanza una trampa, el kernel recupera el
144  mando y el sistema no sufre. El `Drop` de `AplicacionWasm` reconcilia el ciclo
145  de vida: da de baja su canal de teclado.
146- `env` — la **matriz de capacidades**: las funciones de host que el módulo
147  WASM puede invocar. Hoy son siete:
148  - `sys_render_frame(ptr, len)` — compone un fotograma dentro de la **región**
149    de pantalla asignada a la app. El kernel valida **matemáticamente** que
150    `[ptr, ptr+len)` cae dentro de la memoria lineal del módulo, y que el
151    tamaño es el de la región, antes de leer un byte; si no, aborta la app.
152  - `sys_get_scancode()` — entrega, sin bloquear, el siguiente scancode del
153    canal de teclado **propio** de la app.
154  - `sys_object_put` / `sys_object_datos` / `sys_object_hijo` /
155    `sys_object_raiz` / `sys_object_fijar_raiz` — el acceso al grafo de objetos
156    persistente (ver `almacen`): grabar un objeto, leer su carga útil, recorrer
157    sus aristas, y leer o fijar la raíz del DAG. Cada puntero que la app
158    entrega se valida contra su memoria lineal, igual que en `sys_render_frame`.
159
160Todo puntero inválido aborta la app —es su culpa: el `Error` se traduce en una
161trampa de WASM, la app se desaloja y el resto del sistema sigue—. Un fallo del
162almacenamiento, en cambio, no es culpa de la app: se le devuelve un código de
163error que ella decide cómo afrontar.
164
165## 5. Restricciones de ingeniería
166
167- **Escrituras volátiles** obligatorias para framebuffer y MMIO.
168- **`unsafe`** confinado en células mínimas, cada una con un contrato
169  `SEGURIDAD:` y envuelta en una abstracción segura. `unsafe_op_in_unsafe_fn`
170  está en `deny`.
171- **Alineación**: 16 bytes para estructuras genéricas; 4096 (página) para
172  buffers de asignador y el lienzo de respaldo.
173- **`no_std` estricto**: `core` + `alloc`; nada de `std`.