tawasuyu/brahman

1// =============================================================================
2//  renaser :: kernel/src/wasm — Fase 4/5 :: el escudo de aislamiento (WASM)
3// -----------------------------------------------------------------------------
4//  Aqui renaser sustituye las costosas fronteras de hardware (la MMU, los
5//  anillos de la CPU) por limites MATEMATICOS sobre el bytecode. Una aplicacion
6//  WebAssembly se ejecuta en su propia memoria lineal; sus unicas puertas al
7//  exterior son las capacidades que el enlazador del host le concede. Lo que
8//  no este importado no existe: no hay camino fisico para ejecutarlo.
9//
10//  FASE 5 :: el aislamiento deja de ser solo ESPACIAL (memoria) y pasa a ser
11//  tambien TEMPORAL (tiempo de CPU). Cada `tick` se ejecuta con un presupuesto
12//  estricto de COMBUSTIBLE (fuel): si una app lo agota —un bucle infinito, un
13//  trabajo desmedido—, el runtime lanza una trampa, el kernel recupera el mando
14//  y la desaloja. Ningun modulo, por discolo que sea, secuestra el procesador.
15// =============================================================================
16
17pub mod env;
18
19use wasmi::{
20    CompilationMode, Config, Engine, Linker, Module, Store, StoreLimitsBuilder, TrapCode, TypedFunc,
21};
22
23use crate::grafico::{Color, RegionPantalla};
24use env::ContextoCapacidades;
25
26/// Combustible concedido a `init`. Cubre con holgura el pintado inicial del
27/// fondo de una region a pantalla casi completa — un gasto unico, de arranque.
28const FUEL_ARRANQUE: u64 = 20_000_000;
29
30/// Combustible concedido a cada `tick`. Sobra para un fotograma honesto (unos
31/// cientos de miles de operaciones); una app en bucle infinito lo agota en
32/// milisegundos y es desalojada. Este numero ES el techo temporal del userspace.
33const FUEL_FOTOGRAMA: u64 = 2_000_000;
34
35/// Por que el kernel da por terminada —desaloja— una aplicacion WASM.
36#[derive(Clone, Copy)]
37pub enum FallaApp {
38    /// El modulo no se pudo cargar, validar, enlazar o instanciar.
39    Carga,
40    /// La aplicacion agoto su combustible dentro de un `tick`: bucle infinito
41    /// o trabajo desmedido. El guardarrail TEMPORAL en accion.
42    SinCombustible,
43    /// La aplicacion intento crecer su memoria lineal mas alla de su cuota.
44    /// El guardarrail ESPACIAL en accion.
45    SinMemoria,
46    /// La aplicacion ejecuto una trampa: acceso fuera de limites, instruccion
47    /// `unreachable`, una capacidad violada... su propio codigo la abortó.
48    Trampa,
49}
50
51impl FallaApp {
52    /// El color de la baliza de desalojo segun la causa de la falla: amarillo
53    /// palido si reviento su techo de memoria, purpura para cualquier otra.
54    pub fn color_baliza(self) -> Color {
55        match self {
56            FallaApp::SinMemoria => Color::DESALOJO_MEMORIA,
57            _ => Color::DESALOJO,
58        }
59    }
60}
61
62/// Una aplicacion WebAssembly viva: su estado PERSISTE entre fotogramas. A
63/// diferencia de la Fase 4 —que instanciaba y cedia el control de un gesto—,
64/// aqui la instancia se conserva y el kernel la hace avanzar `tick` a `tick`.
65pub struct AplicacionWasm {
66    /// El almacen: todo el estado de ESTA instancia — su memoria lineal, sus
67    /// globales y el contexto de capacidades con su region de pantalla.
68    almacen: Store<ContextoCapacidades>,
69    /// El punto de entrada de fotograma, ya resuelto y con seguridad de tipos.
70    /// `TypedFunc` es un asa autosuficiente dentro del `Store`: conservada esta,
71    /// el handle de la `Instance` no aporta nada y no se retiene.
72    func_tick: TypedFunc<(), ()>,
73    /// La region de pantalla de la app — su ventana, y donde se tatua su baliza
74    /// de desalojo si llega a fallar.
75    region: RegionPantalla,
76}
77
78impl AplicacionWasm {
79    /// Carga, valida, instancia y arranca una aplicacion WASM aislada, ligada a
80    /// una region de pantalla. Si algo falla en el camino, se devuelve la falla
81    /// en lugar de incendiar el kernel.
82    ///
83    /// El nuevo ABI del userspace exige dos exportaciones: `init` —invocada una
84    /// sola vez, aqui— y `tick` —un fotograma de trabajo, invocada despues por
85    /// el reactor en cada pulso del reloj.
86    ///
87    /// `techo_memoria` es la cuota de memoria lineal de ESTA app, en bytes —
88    /// desde la Fase 7 la dicta su `EntradaApp` del manifiesto. `indice_app` es
89    /// su posicion en el manifiesto: su identidad para las capacidades de
90    /// estado persistido (Fase 7c).
91    pub fn cargar(
92        bytecode: &[u8],
93        region: RegionPantalla,
94        techo_memoria: usize,
95        indice_app: usize,
96    ) -> Result<AplicacionWasm, FallaApp> {
97        // 1. El motor, con metricas de combustible y compilacion ANTICIPADA: la
98        //    traduccion del modulo ocurre ahora, de modo que el `fuel` mida
99        //    despues solo EJECUCION, jamas compilacion diferida.
100        let mut config = Config::default();
101        config.consume_fuel(true);
102        config.compilation_mode(CompilationMode::Eager);
103        let motor = Engine::new(&config);
104
105        // 2. Validar y traducir el modulo — ya instrumentado con fuel.
106        let modulo = Module::new(&motor, bytecode).map_err(|_| FallaApp::Carga)?;
107
108        // 3. El almacen, con el contexto de capacidades de ESTA app: su region
109        //    de pantalla, su canal de teclado y su techo de memoria. El canal
110        //    se crea ahora pero se inscribe en la difusion de la IRQ1 al final,
111        //    ya con la app cargada: una carga fallida no deja canales huerfanos.
112        let canal = crate::async_system::teclado::crear_canal();
113        let limites = StoreLimitsBuilder::new()
114            .memory_size(techo_memoria)
115            // Una expansion denegada se convierte en TRAMPA, no en un -1 que la
116            // app pudiera ignorar: asi el kernel la captura y la desaloja.
117            .trap_on_grow_failure(true)
118            .build();
119        let mut almacen = Store::new(
120            &motor,
121            ContextoCapacidades {
122                region,
123                canal,
124                limites,
125                indice_app,
126            },
127        );
128        // Ligar el limitador de recursos: `wasmi` lo consultara en cada
129        // `memory.grow`, tambien durante la instanciacion.
130        almacen.limiter(|contexto| &mut contexto.limites);
131        // Dotar de combustible ANTES de instanciar: la instanciacion no debe
132        // quedarse a cero y abortar.
133        almacen.set_fuel(FUEL_ARRANQUE).map_err(|_| FallaApp::Carga)?;
134
135        // 4. El enlazador y la matriz de capacidades (ver `env`).
136        let mut enlazador: Linker<ContextoCapacidades> = Linker::new(&motor);
137        env::enlazar_capacidades(&mut enlazador).map_err(|_| FallaApp::Carga)?;
138
139        // 5. Instanciar, resolviendo las importaciones contra las capacidades.
140        let instancia = enlazador
141            .instantiate_and_start(&mut almacen, &modulo)
142            .map_err(|_| FallaApp::Carga)?;
143
144        // 6. Resolver los dos puntos del ABI de fotograma: `init` y `tick`.
145        let func_init = instancia
146            .get_typed_func::<(), ()>(&almacen, "init")
147            .map_err(|_| FallaApp::Carga)?;
148        let func_tick = instancia
149            .get_typed_func::<(), ()>(&almacen, "tick")
150            .map_err(|_| FallaApp::Carga)?;
151
152        // 7. Arranque unico: `init` prepara el estado inicial de la aplicacion.
153        almacen.set_fuel(FUEL_ARRANQUE).map_err(|_| FallaApp::Carga)?;
154        func_init
155            .call(&mut almacen, ())
156            .map_err(|_| FallaApp::Carga)?;
157
158        // 8. Con la app ya cargada e instanciada, inscribir su canal de teclado
159        //    en la difusion de la IRQ1: desde aqui recibe cada pulsacion.
160        crate::async_system::teclado::registrar_canal(&almacen.data().canal);
161
162        Ok(AplicacionWasm {
163            almacen,
164            func_tick,
165            region,
166        })
167    }
168
169    /// Hace avanzar la aplicacion un fotograma. Recarga su presupuesto de
170    /// combustible y le cede el control con `tick`. Si la app lo agota o ejecuta
171    /// una trampa, el kernel recupera el mando y la falla se devuelve para que
172    /// la tarea proceda al desalojo. El kernel nunca pierde el control.
173    pub fn tick(&mut self) -> Result<(), FallaApp> {
174        // Recargar el deposito: cada fotograma parte con su techo intacto.
175        self.almacen
176            .set_fuel(FUEL_FOTOGRAMA)
177            .map_err(|_| FallaApp::Trampa)?;
178
179        match self.func_tick.call(&mut self.almacen, ()) {
180            Ok(()) => Ok(()),
181            // `as_trap_code` da un codigo publico y univoco para cada causa:
182            // `OutOfFuel` pliega toda variante de agotamiento de combustible;
183            // `GrowthOperationLimited` es la cuota de memoria denegada.
184            Err(error) => match error.as_trap_code() {
185                Some(TrapCode::OutOfFuel) => Err(FallaApp::SinCombustible),
186                Some(TrapCode::GrowthOperationLimited) => Err(FallaApp::SinMemoria),
187                _ => Err(FallaApp::Trampa),
188            },
189        }
190    }
191
192    /// La region de pantalla asignada a la aplicacion.
193    pub fn region(&self) -> RegionPantalla {
194        self.region
195    }
196}
197
198/// Reconciliacion del ciclo de vida. Cuando una `AplicacionWasm` muere —porque
199/// fue desalojada y su tarea concluyo—, su canal de teclado debe darse de baja
200/// de la difusion de la IRQ1. Sin esto, el manejador de interrupciones seguiria
201/// empujando scancodes a una cola muerta: una fuga lenta pero segura.
202impl Drop for AplicacionWasm {
203    fn drop(&mut self) {
204        crate::async_system::teclado::cerrar_canal(&self.almacen.data().canal);
205    }
206}