Documentación › LOCI

LOCI — Lovely Oric Computer Interface

Emulación del dispositivo LOCI de Sodiumlightbaby (sodiumlb, 2024): un cartucho RP2040 que se conecta al bus del Oric y ofrece almacenamiento masivo (USB / SD / flash interna), teclado-ratón-gamepads USB HID, módem WiFi (PicoWiFiModemUSB), intercambio de ROM en caliente y menú integrado.

Referencias: loci-hardware · loci-firmware · loci-rom (menú). La emulación está alineada con la fuente del firmware (release de referencia: v0.3.1) y verificada sobre hardware; las divergencias conocidas se listan al final.

Inicio rápido

# LOCI + módem WiFi picowifi (ACIA 6551 en $0380, direccione $0380 NO $03A0)
./oric1-emu -r roms/basic11b.rom --loci --serial picowifi

# Menú LOCI directamente al arrancar
./oric1-emu -r roms/loci/locirom --loci

# Imagen SD FAT16/32 en bruto como almacenamiento
./oric1-emu -r roms/basic11b.rom --loci --loci-sdimg tarjeta.img

Mapa de memoria

Ventana	Contenido
`$0310-$031F`	WD1793 + control DSK (modo Microdisc del LOCI; `$0319` = 'L')
`$0315-$0317`	Protocolo TAP de bajo nivel (PLAY/REC/READ_BIT, trama de 14 bits)
`$0380-$0383`	ACIA 6551 (módem picowifi) — por defecto bajo `--loci`
`$03A0-$03BF`	MIA: consola UART, registros de API (xstack `$03AC`, errno `$03AD/E`, op `$03AF`), stub `$03B0` (spin/BLOCKED), BUSY `$03B2` bit 7, trap de botón `$03BA-$03BF`

API (op `$03AF`) — 36/36 ops implementadas

Sistema (PIX_XREG, CPU_PHI2→1000 kHz, OEM_CODEPAGE, RNG_LRAND, STDIN_OPT), reloj (CLOCK, CLK_GET/SETTIME, GETRES), archivos (OPEN/CLOSE/READ/WRITE_XSTACK/XRAM/LSEEK/UNLINK/RENAME), directorios (OPENDIR/CLOSEDIR/READDIR/MKDIR/GETCWD), montaje (MOUNT/UMOUNT, TAP SEEK/TELL/READ_HEADER, UNAME), boot/tuning (MIA_BOOT, MAP_TUNE_*, ADJ_SCAN), centinela $FF (exit → spin).

ABI conforme al firmware (verificada contra la fuente)

errno: errores de sistema de archivos = 32 + FRESULT FatFS (archivo ausente → 36, directorio ausente → 37, denegado/no-vacío/lleno → 39, ya existe → 40…); los códigos 1-18 se reservan para errores de API (EBADF, EMFILE, ENODEV, ENOSYS, guarda anti-escape) — igual que el api.h del firmware.
Descriptores: archivos 3-18 (FAT, STD_FIL_OFFS=3), directorios 64+ (FD_OFFS_FAT); el iterador de dispositivos es el fd 0 (FD_OFFS_DEV).
xstack: 512 bytes, push/pop y cadenas sin NUL conformes.
MAP_TUNE_*: valor en el registro A; A ≤ 31 ajusta el retardo, cualquier otro valor es una consulta; la op siempre devuelve el valor actual en AX. ADJ_SCAN barre tior 0-31 (~100 ms + 5 ms/paso) con progreso visible en el byte ROM $FFF0.

Almacenamiento

El LOCI real tiene tres niveles; sus equivalentes en Phosphoric:

Hardware real	Emulación
Flash interna (LittleFS del RP2040, presembrada con `basic11b.rom`, `basic10.rom`, `microdis.rom`, `locirom`)	flash root: `--loci-flash DIR` (por defecto: directorio actual). Rutas `0:` y desnudas. Las ROM del sistema ausentes del flash root se resuelven como respaldo en la carpeta de la ROM `-r` (es decir, `roms/`).
Llave USB (FAT, puerto USB host)	`--loci-usb DIR` (repetible, 4 máx.) o autodetección de los medios montados en `/media/$USER` y `/run/media/$USER` al lanzar. Rutas de volumen `1:`-`4:`. Etiqueta + tamaño mostrados en el menú. Sin hot-plug: conectar antes de lanzar.
Tarjeta SD (imagen en bruto)	`--loci-sdimg PATH` (FAT16/32). Cuando está activo, este backend posee todas las ops de archivos (las llaves USB siguen listadas pero no navegables).

La lista de dispositivos (selector del menú) la sirve opendir(""): «0: Internal storage [15MB]», luego una línea por dispositivo USB (la llave MSC, el picowifi «CDC modem mounted»), luego un nombre vacío.

Botón Acción (F8)

Se reproduce el comportamiento del firmware (ext.c):

Pulsación corta: instantánea de la sesión (→ <flash root>/loci_resume.ost), trap IRQ $03BA, luego arranque del menú LOCI (locirom del flash root, respaldo roms/loci/locirom). Como el firmware real, la versión FW (0.3.1) y los timings se parchean en la ROM en los placeholders $FFF7-9 / $FFEF-F3. La entrada resume del menú reintercambia la ROM anterior y restaura la instantánea. Pulsar F8 en el menú se ignora.
Pulsación larga (≥ 2 s): arranque de la ROM de diagnóstico de Mike Brown (roms/loci/test108k.rom, v1.08k, incluida en las compilaciones de firmware reales con su permiso). Test paso a paso CPU/ULA/DRAM/VIA/PSG.
En modo --control: comando loci-button [long].
F5 = reset MIA (registros/xstack/op) conservando los montajes, como el botón de reset del Pico.

Timing del bus MIA

La MIA muestrea el bus 6502 por PIO en desfases sub-ciclo ajustados por MAP_TUNE_*. Un tior mal calibrado corrompe la ventana ACIA del picowifi — síntoma de hardware real reproducido: --loci-mia-window LO-HI define el rango fiable (por defecto 0-31 = siempre fiable); fuera de la ventana, $0380 lee $FF e ignora las escrituras.

Divergencias conocidas (fuera de alcance)

Flash interna LittleFS no emulada como tal — el flash root cumple ese papel con semántica FAT.
Directorio dev «0» del firmware, el pattern matcher ULA real, BUSY observable durante una op larga.
Detección USB solo al arranque (sin hot-plug).
El dsk_fdc del LOCI se mantiene en timing FDC rápido — fiel: en el hardware real su «unidad» es el RP2040 + SD, sin mecánica (el Microdisc, en cambio, usa timing mecánico real por defecto).

Reproducido de docs/loci.md (versión de referencia actualizada en GitHub).

← Documentación · SEDORIC →