# Gap analysis: velxio-chip.h vs wokwi-api.h

> Comparación de superficie de API. **No copiamos código** — solo identificamos qué
> features útiles del modelo de Wokwi todavía no implementamos para que el sandbox
> cubra los mismos casos de uso.

Fecha: 2026-04-28.

## Resumen

Implementadas: GPIO básico, attr (numérico), I2C slave, UART, timer, log.

Faltantes a considerar (en orden de prioridad):

| Prioridad | Feature | Estado | Notas |
|---|---|---|---|
| 🔴 Alta | **SPI slave** (`spi_init`, `spi_start`, `spi_stop`) | No tenemos | Protocolo de uso muy común |
| 🔴 Alta | **`OUTPUT_LOW` / `OUTPUT_HIGH` modes** | No tenemos | Inicializar pin output con valor inicial sin race |
| 🟡 Media | **`pin_watch_stop`** | No tenemos | Remover una suscripción |
| 🟡 Media | **`pin_dac_write`** | No tenemos | Salida analógica (DAC) |
| 🟡 Media | **`pin_mode`** | No tenemos | Cambiar modo después de init |
| 🟢 Baja | **String attributes** | No tenemos | Atributos texto / select |
| 🟢 Baja | **`attr_init_float` separado** | Cubierto | Nuestro `vx_attr_*` usa double — funciona |
| 🟢 Baja | **Framebuffer** (displays custom) | No tenemos | LCDs raros |
| 🟢 Baja | **`reserved[8]` en configs** | No tenemos | Forward-compat — añadir cuando publiquemos v1 |
| ⚪ N/A | Experimental `_mcu_*` | Skip | Acceso a memoria del CPU emulado, no esencial |

## Detalle por categoría

### GPIO

| wokwi-api.h | velxio-chip.h | Estado |
|---|---|---|
| `pin_init(name, mode) → pin_t` | `vx_pin_register(name, mode) → vx_pin` | ✅ |
| `pin_read(pin) → uint32` | `vx_pin_read(pin) → int` | ✅ |
| `pin_write(pin, value)` | `vx_pin_write(pin, value)` | ✅ |
| `pin_watch(pin, &config)` con struct | `vx_pin_watch(pin, edge, cb, ud)` (args directos) | ✅ (mejor) |
| `pin_watch_stop(pin)` | — | ❌ Falta |
| `pin_mode(pin, value)` | — | ❌ Falta |
| `pin_adc_read(pin) → float` | `vx_pin_read_analog(pin) → double` | ✅ |
| `pin_dac_write(pin, voltage) → float` | — | ❌ Falta |
| Modos: `INPUT/OUTPUT/INPUT_PULLUP/INPUT_PULLDOWN/ANALOG` | Tenemos los 5 | ✅ |
| Modos extra: `OUTPUT_LOW = 16`, `OUTPUT_HIGH = 17` | — | ❌ Falta |

**Ejemplo concreto donde importa**: el `inverter.c` llama `vx_pin_register("OUT", VX_OUTPUT)` y
luego inmediatamente `vx_pin_write(out, ...)` para poner el valor inicial. Hay una pequeña ventana
donde el pin queda en LOW antes de la primera escritura. `OUTPUT_HIGH` evitaría esa ventana
inicializando con HIGH desde el init.

### Atributos

| wokwi-api.h | velxio-chip.h | Estado |
|---|---|---|
| `attr_init(name, default_uint32) → uint32` | `vx_attr_register(name, default_double) → vx_attr` | ✅ (cambio de tipo) |
| `attr_read(attr) → uint32` | `vx_attr_read(attr) → double` | ✅ |
| `attr_init_float / attr_read_float` | (cubierto por double) | ✅ funcional |
| `attr_string_init / string_get_length / string_read` | — | ❌ Falta (caso raro) |

### I2C

| wokwi-api.h | velxio-chip.h | Estado |
|---|---|---|
| `i2c_init(&config) → i2c_dev_t` | `vx_i2c_attach(&cfg) → vx_i2c` | ✅ |
| Callbacks `connect/read/write/disconnect` | Mismos (con renombre `disconnect → on_stop`) | ✅ |
| `reserved[8]` en config | — | ⚠️ Falta (forward-compat) |

### UART

| wokwi-api.h | velxio-chip.h | Estado |
|---|---|---|
| `uart_init(&config) → uart_dev_t` | `vx_uart_attach(&cfg) → vx_uart` | ✅ |
| `uart_write(uart, buffer, count) → bool` | `vx_uart_write(uart, buffer, count) → bool` | ✅ |
| Callbacks `rx_data / write_done` | Mismos (renombre `rx_data → on_rx_byte`) | ✅ |

### SPI

| wokwi-api.h | velxio-chip.h | Estado |
|---|---|---|
| `spi_init(&config) → spi_dev_t` | — | ❌ Falta |
| `spi_start(spi, buffer, count)` | — | ❌ Falta |
| `spi_stop(spi)` | — | ❌ Falta |

**Implementación**: requiere agregar un `SPIBus` similar al `I2CBus` (con avr8js
no hay un `AVRSPI` directo igual de limpio que `AVRTWI`, pero hay `AVRSPI` en el
paquete avr8js — habría que envolverlo). Es trabajo de medio día.

### Timers

| wokwi-api.h | velxio-chip.h | Estado |
|---|---|---|
| `timer_init(&config) → timer_t` | `vx_timer_create(cb, ud) → vx_timer` | ✅ |
| `timer_start(timer, micros, repeat)` | `vx_timer_start(timer, nanos, repeat)` | ✅ (pero µs vs ns) |
| `timer_start_ns(timer, nanos, repeat)` | `vx_timer_start` ya en nanos | ✅ |
| `timer_stop(timer)` | `vx_timer_stop(timer)` | ✅ |
| `get_sim_nanos() → uint64` | `vx_sim_now_nanos() → uint64` | ✅ |

### Framebuffer (displays)

Todo el bloque `framebuffer_init / buffer_read / buffer_write` no lo tenemos.
Se necesita cuando un chip representa un display custom (LCDs, OLEDs raros).
**Decisión**: dejarlo para v2. El simulador de Velxio ya tiene `wokwi-elements`
para los displays comunes (SSD1306, ILI9341).

### Experimental MCU access

`_mcu_read_memory`, `_mcu_read_pc`, `_mcu_monitor_sp` — permite a un chip
inspeccionar el estado del CPU emulado. Útil para chips de debug pero no
para operación normal. **Skip**.

## Acciones recomendadas

1. **Agregar SPI al header y al runtime** — el caso de uso más común que falta.
   Hay chips populares (display drivers, ADCs externos, módulos LoRa) que solo
   hablan SPI.
2. **Agregar `OUTPUT_LOW` / `OUTPUT_HIGH`** — un enum extra y unas líneas en
   `_pin_register` para inicializar el state. Trivial.
3. **Agregar `vx_pin_watch_stop`** — devolver un handle desde `vx_pin_watch`
   y permitir cancelarlo. ~10 líneas.
4. **Agregar `reserved[8]` a los configs** — para que el ABI sea estable cuando
   añadamos campos en el futuro sin romper chips ya compilados. Cambio binario,
   hay que hacerlo antes de v1.
5. **`pin_dac_write`** y **`pin_mode`** — bajo riesgo, agregar cuando aparezca
   el primer chip que los necesite.
6. **Strings y framebuffer** — postponer.

Esos cambios todos juntos son ~1 día de trabajo + sus respectivos tests.