Documentatie › LOCI

LOCI — Lovely Oric Computer Interface

Emulatie van het LOCI-apparaat van Sodiumlightbaby (sodiumlb, 2024): een RP2040-cartridge die op de bus van de Oric wordt gestoken en massaopslag (USB / SD / interne flash), USB HID-toetsenbord-muis-gamepads, een WiFi-modem (PicoWiFiModemUSB), runtime ROM-wissel en een ingebouwd menu biedt.

Referenties: loci-hardware · loci-firmware · loci-rom (menu). De emulatie is afgestemd op de firmwarebron (referentierelease: v0.3.1) en op hardware geverifieerd; bekende afwijkingen staan aan het eind.

Snelstart

# LOCI + picowifi WiFi-modem (ACIA 6551 op $0380, adresseer $0380 NIET $03A0)
./oric1-emu -r roms/basic11b.rom --loci --serial picowifi

# LOCI-menu meteen bij opstart
./oric1-emu -r roms/loci/locirom --loci

# Ruwe FAT16/32 SD-image als opslag
./oric1-emu -r roms/basic11b.rom --loci --loci-sdimg kaart.img

Geheugenkaart

Venster	Inhoud
`$0310-$031F`	WD1793 + DSK-besturing (LOCI-Microdisc-modus; `$0319` = 'L')
`$0315-$0317`	Laag-niveau TAP-protocol (PLAY/REC/READ_BIT, 14-bit-frame)
`$0380-$0383`	ACIA 6551 (picowifi-modem) — standaard onder `--loci`
`$03A0-$03BF`	MIA: UART-console, API-registers (xstack `$03AC`, errno `$03AD/E`, op `$03AF`), stub `$03B0` (spin/BLOCKED), BUSY `$03B2` bit 7, knop-trap `$03BA-$03BF`

API (op `$03AF`) — 36/36 ops geïmplementeerd

Systeem (PIX_XREG, CPU_PHI2→1000 kHz, OEM_CODEPAGE, RNG_LRAND, STDIN_OPT), klok (CLOCK, CLK_GET/SETTIME, GETRES), bestanden (OPEN/CLOSE/READ/WRITE_XSTACK/XRAM/LSEEK/UNLINK/RENAME), mappen (OPENDIR/CLOSEDIR/READDIR/MKDIR/GETCWD), mounten (MOUNT/UMOUNT, TAP SEEK/TELL/READ_HEADER, UNAME), boot/tuning (MIA_BOOT, MAP_TUNE_*, ADJ_SCAN), sentinel $FF (exit → spin).

Firmware-conforme ABI (geverifieerd tegen de bron)

errno: bestandssysteemfouten = 32 + FRESULT FatFS (ontbrekend bestand → 36, ontbrekende map → 37, geweigerd/niet-leeg/vol → 39, bestaat al → 40…); codes 1-18 zijn gereserveerd voor API-fouten (EBADF, EMFILE, ENODEV, ENOSYS, escape-guard) — precies als de api.h van de firmware.
Descriptoren: bestanden 3-18 (FAT, STD_FIL_OFFS=3), mappen 64+ (FD_OFFS_FAT); de apparaat-iterator is fd 0 (FD_OFFS_DEV).
xstack: 512 bytes, conforme push/pop en NUL-loze strings.
MAP_TUNE_*: waarde in register A; A ≤ 31 stelt de vertraging in, elke andere waarde is een query; de op geeft altijd de huidige waarde terug in AX. ADJ_SCAN scant tior 0-31 (~100 ms + 5 ms/stap) met voortgang zichtbaar in ROM-byte $FFF0.

Opslag

De echte LOCI heeft drie niveaus; hun equivalenten in Phosphoric:

Echte hardware	Emulatie
Interne flash (RP2040-LittleFS, voorzien van `basic11b.rom`, `basic10.rom`, `microdis.rom`, `locirom`)	flash root: `--loci-flash DIR` (standaard: huidige map). `0:`- en kale paden. Systeem-ROM's die in de flash root ontbreken worden als fallback opgelost in de map van de `-r`-ROM (dus `roms/`).
USB-stick (FAT, host-USB-poort)	`--loci-usb DIR` (herhaalbaar, max. 4) of autodetectie van media gemount in `/media/$USER` en `/run/media/$USER` bij het starten. Volumepaden `1:`-`4:`. Label + grootte in het menu. Geen hot-plug: insteken vóór het starten.
SD-kaart (ruwe image)	`--loci-sdimg PATH` (FAT16/32). Wanneer actief, bezit deze backend alle bestandsops (USB-sticks blijven vermeld maar niet navigeerbaar).

De apparatenlijst (menuselector) wordt geleverd door opendir(""): «0: Internal storage [15MB]», dan één regel per USB-apparaat (de MSC-stick, de picowifi «CDC modem mounted»), dan een lege naam.

Actieknop (F8)

Het firmwaregedrag (ext.c) wordt gereproduceerd:

Korte druk: sessiesnapshot (→ <flash root>/loci_resume.ost), IRQ-trap $03BA, dan boot van het LOCI-menu (locirom uit de flash root, fallback roms/loci/locirom). Zoals de echte firmware worden de FW-versie (0.3.1) en de timings in de ROM gepatcht op de placeholders $FFF7-9 / $FFEF-F3. De resume-optie van het menu wisselt de vorige ROM terug en herstelt de snapshot. F8 in het menu wordt genegeerd.
Lange druk (≥ 2 s): boot van de diagnose-ROM van Mike Brown (roms/loci/test108k.rom, v1.08k, opgenomen in echte firmwarebuilds met zijn toestemming). Stapsgewijze CPU/ULA/DRAM/VIA/PSG-test.
In --control-modus: het loci-button [long]-commando.
F5 = MIA-reset (registers/xstack/op) met behoud van mounts, zoals de resetknop van de Pico.

MIA-bustiming

De MIA bemonstert de 6502-bus via PIO op sub-cyclus-offsets ingesteld door MAP_TUNE_*. Een verkeerd afgestemde tior corrumpeert het ACIA-venster van de picowifi — een echt hardwaresymptoom gereproduceerd: --loci-mia-window LO-HI definieert het betrouwbare bereik (standaard 0-31 = altijd betrouwbaar); buiten het venster leest $0380 $FF en negeert schrijfacties.

Bekende afwijkingen (buiten bereik)

Interne LittleFS-flash niet als zodanig geëmuleerd — de flash root vervult die rol met FAT-semantiek.
Firmware-dev-map «0», de echte ULA-pattern-matcher, BUSY waarneembaar tijdens een lange op.
USB-detectie alleen bij het opstarten (geen hot-plug).
De dsk_fdc van LOCI blijft op snelle FDC-timing — getrouw: op echte hardware is zijn «station» de RP2040 + SD, zonder mechaniek (de Microdisc gebruikt daarentegen standaard echte mechanische timing).

Gereproduceerd uit docs/loci.md (gezaghebbende, actuele versie op GitHub).

← Documentatie · SEDORIC →