ドキュメント › LOCI

LOCI — Lovely Oric Computer Interface

Sodiumlightbaby（sodiumlb、2024）の LOCI デバイスのエミュレーション：Oric のバスに挿す RP2040 カートリッジで、マスストレージ（USB / SD / 内蔵 flash）、USB HID のキーボード・マウス・ゲームパッド、WiFi モデム（PicoWiFiModemUSB）、実行時 ROM 切替、内蔵メニューを提供します。

参照：loci-hardware · loci-firmware · loci-rom（メニュー）。エミュレーションはファームウェアのソース（参照リリース：v0.3.1）に整合し、実機で検証済み。既知の相違は末尾に列挙します。

クイックスタート

# LOCI + picowifi WiFi モデム（ACIA 6551 は $0380、$03A0 ではなく $0380 を指定）
./oric1-emu -r roms/basic11b.rom --loci --serial picowifi

# 起動時に LOCI メニューを直接
./oric1-emu -r roms/loci/locirom --loci

# 生の FAT16/32 SD イメージをストレージとして
./oric1-emu -r roms/basic11b.rom --loci --loci-sdimg card.img

メモリマップ

ウィンドウ	内容
`$0310-$031F`	WD1793 + DSK 制御（LOCI の Microdisc モード；`$0319` = 'L'）
`$0315-$0317`	低レベル TAP プロトコル（PLAY/REC/READ_BIT、14 ビットフレーム）
`$0380-$0383`	ACIA 6551（picowifi モデム）— `--loci` 下の既定
`$03A0-$03BF`	MIA：UART コンソール、API レジスタ（xstack `$03AC`、errno `$03AD/E`、op `$03AF`）、スタブ `$03B0`（spin/BLOCKED）、BUSY `$03B2` ビット 7、ボタントラップ `$03BA-$03BF`

API（op `$03AF`）— 36/36 の操作を実装

システム（PIX_XREG、CPU_PHI2→1000 kHz、OEM_CODEPAGE、RNG_LRAND、STDIN_OPT）、クロック（CLOCK、CLK_GET/SETTIME、GETRES）、ファイル（OPEN/CLOSE/READ/WRITE_XSTACK/XRAM/LSEEK/UNLINK/RENAME）、ディレクトリ（OPENDIR/CLOSEDIR/READDIR/MKDIR/GETCWD）、マウント（MOUNT/UMOUNT、TAP SEEK/TELL/READ_HEADER、UNAME）、boot/tuning（MIA_BOOT、MAP_TUNE_*、ADJ_SCAN）、番兵 $FF（exit → spin）。

ファームウェア準拠の ABI（ソースに対して検証）

errno：ファイルシステムエラー = 32 + FRESULT（FatFS）（ファイル欠如 → 36、ディレクトリ欠如 → 37、拒否/非空/満杯 → 39、既存 → 40…）；コード 1-18 は API エラー用に予約（EBADF、EMFILE、ENODEV、ENOSYS、エスケープガード）— ファームウェアの api.h と完全に同じ。
ディスクリプタ：ファイル 3-18（FAT、STD_FIL_OFFS=3）、ディレクトリ 64+（FD_OFFS_FAT）；デバイスイテレータは fd 0（FD_OFFS_DEV）。
xstack：512 バイト、準拠した push/pop と NUL なし文字列。
MAP_TUNE_*：値はレジスタ A に；A ≤ 31 は遅延を設定、それ以外は問い合わせ；操作は常に現在値を AX で返します。ADJ_SCAN は tior 0-31 を走査（~100 ms + 5 ms/ステップ）し、進捗は ROM バイト $FFF0 で可視。

ストレージ

実機の LOCI は 3 層あります。Phosphoric での対応：

実ハードウェア	エミュレーション
内蔵 flash（RP2040 の LittleFS、`basic11b.rom`、`basic10.rom`、`microdis.rom`、`locirom` を事前配置）	flash root：`--loci-flash DIR`（既定：カレントディレクトリ）。`0:` および裸のパス。flash root にないシステム ROM は、`-r` ROM のフォルダ（すなわち `roms/`）でフォールバック解決。
USB キー（FAT、ホスト USB ポート）	`--loci-usb DIR`（繰り返し可、最大 4）または起動時に `/media/$USER` と `/run/media/$USER` にマウントされたメディアの自動検出。ボリュームパス `1:`-`4:`。メニューにラベル + サイズ。ホットプラグなし：起動前に接続。
SD カード（生イメージ）	`--loci-sdimg PATH`（FAT16/32）。有効時はこのバックエンドが全ファイル操作を持ちます（USB キーは一覧されるが閲覧不可）。

デバイス一覧（メニューのセレクタ）は opendir("") が提供：「0: Internal storage [15MB]」、続いて USB デバイスごとに 1 行（MSC キー、picowifi「CDC modem mounted」）、そして空の名前。

アクションボタン（F8）

ファームウェアの挙動（ext.c）を再現：

短押し：セッションスナップショット（→ <flash root>/loci_resume.ost）、IRQ トラップ $03BA、続いて LOCI メニューの起動（flash root の locirom、フォールバック roms/loci/locirom）。実機のファームウェア同様、FW バージョン（0.3.1）とタイミングはプレースホルダ $FFF7-9 / $FFEF-F3 で ROM にパッチされます。メニューの resume 項目は直前の ROM に戻しスナップショットを復元。メニュー内の F8 は無視。
長押し（≥ 2 秒）：Mike Brown の診断 ROM（roms/loci/test108k.rom、v1.08k、本人の許可のもと実ファームウェアビルドに同梱）の起動。CPU/ULA/DRAM/VIA/PSG のステップ式テスト。
--control モードでは：loci-button [long] コマンド。
F5 = MIA リセット（レジスタ/xstack/op）でマウントを保持、Pico のリセットボタンと同様。

MIA バスのタイミング

MIA は MAP_TUNE_* で設定されるサブサイクルのオフセットで、PIO により 6502 バスをサンプリングします。tior の調整不良は picowifi の ACIA ウィンドウを破壊します — 実機の症状を再現：--loci-mia-window LO-HI は信頼できる範囲を定義（既定 0-31 = 常に信頼可）；ウィンドウ外では $0380 は $FF を読み、書き込みを無視します。

既知の相違（対象外）

内蔵 LittleFS flash はそのものとしてはエミュレートせず — flash root が FAT セマンティクスでその役割を担います。
ファームウェアの dev ディレクトリ「0」、実際の ULA パターンマッチャ、長い操作中に観測される BUSY。
USB 検出は起動時のみ（ホットプラグなし）。
LOCI の dsk_fdc は高速 FDC タイミングのまま — 忠実：実機ではその「ドライブ」は RP2040 + SD で機械部分がありません（一方 Microdisc は既定で実機の機械的タイミング）。

docs/loci.md から再掲（正となる最新版は GitHub）。

← ドキュメント · SEDORIC →