Virtio9PFS-handler

Virtio9PFS-handler
==================

A FileSysBox-based handler for AmigaOS 4.1 FE that mounts QEMU host-shared
folders as DOS volumes via the VirtIO 9P (9P2000.L) protocol.

Status: Beta (v0.10.1) -- tested on QEMU AmigaOne (legacy VirtIO),
Pegasos2 (modern VirtIO), and SAM460ex. Use at your own risk.

Important: Official QEMU for Windows (x64) does not include -virtfs
support. However, it can be patched -- see "Windows QEMU Setup" below.


What It Does
------------

When running AmigaOS under QEMU with a -virtfs shared folder, this handler
presents the host directory as a native AmigaOS volume (e.g. SHARED:). You
can browse, copy, create, rename, and delete files on the host filesystem
directly from Workbench or the Shell.


Features
--------

- 9P2000.L protocol -- full Linux client dialect for maximum QEMU
  compatibility
- Dual VirtIO transport -- supports both legacy (device 0x1009) and modern
  VirtIO 1.0 (device 0x1049) PCI devices
- Legacy mode -- I/O BAR access, native big-endian vring fields; tested on
  AmigaOne (Articia S)
- Modern mode -- MMIO BAR access via stwbrx/lwbrx inline asm, little-endian
  vring fields; tested on Pegasos2 (MV64361) and SAM460ex
- FileSysBox FUSE interface -- implements 25 FUSE callbacks; all DOS packet
  handling is done by filesysbox.library v54+
- Full filesystem operations -- directory listing, file read/write, create,
  delete, rename, mkdir, rmdir, truncate, chmod, chown, statfs, utimens,
  fsync, symlink, readlink, hard link
- Large file support -- reads and writes larger than msize are automatically
  split into multiple 9P transactions
- 512 KB message size -- negotiates 512 KB msize with QEMU for maximum
  throughput; a 1 MB file transfer needs only 2 round-trips instead of 16
- DMA-safe buffers -- uses MEMF_SHARED allocations with cached physical
  addresses and PPC dcbst/dcbf cache management for zero-copy DMA
- Polled completion -- fast used-ring polling for VirtIO completions; avoids
  signal-based Wait() conflicts with FileSysBox event loop. Asks the device
  not to interrupt on every completion (VRING_AVAIL_F_NO_INTERRUPT) to keep
  poll-mode overhead low
- Wall-clock transaction timeout -- every 9P transaction has a 10-second PPC
  time-base budget; stalled transactions are cancelled with a Tflush on a
  dedicated buffer and the FID is marked orphaned
- No newlib dependency -- uses _start() entry point with -nostartfiles;
  inline string/memory helpers in string_utils.h
- Automatic installer -- AmigaOS Shell script copies handler and DOSDriver


Requirements
------------

- AmigaOS 4.1 Final Edition (or later)
- filesysbox.library v54 or newer (included with OS 4.1 FE)
- QEMU 10.0+ with VirtIO 9P support (Linux, WSL2, macOS, or patched
  Windows -- see "Windows QEMU Setup" below)
- QEMU emulating a PPC AmigaOS machine (tested on AmigaOne, Pegasos2, and
  SAM460ex)


Installation
------------

Quick Install:

  Extract the distribution archive and double-click the install.py
  icon in the extracted drawer -- the AmigaOS Installation Utility
  wizard performs the installation.  From an AmigaOS Shell:

    cd RAM:Virtio9PFS
    "SYS:Utilities/Installation Utility" PACKAGE=install.py

  This copies the handler to L: and the DOSDriver to DEVS:DOSDrivers/.
  Reboot to activate the SHARED: volume.

Manual Install:

  1. Copy Virtio9PFS-handler to L:
  2. Copy SHARED to DEVS:DOSDrivers/SHARED
  3. Reboot to activate (or mount manually)


QEMU Configuration
------------------

Add the -virtfs option to your QEMU command line to share a host folder:

    qemu-system-ppc -M amigaone 
        -virtfs
local,path=/path/to/shared/folder,mount_tag=SHARED,security_model=none,id=share0

        ...

The mount_tag must match the DOSDriver name (e.g. SHARED for
DEVS:DOSDrivers/SHARED). QEMU automatically creates the appropriate VirtIO
9P PCI device for the machine type.


Windows QEMU Setup
------------------

Official Windows QEMU builds do not include VirtIO 9P (-virtfs) support.
You can patch and rebuild QEMU yourself to enable it. Community-maintained
patches are available at:

  Pre-built Windows QEMU binaries with 9P patches:
    https://github.com/arixmkii/qcw/tags

  Patch files (to apply to upstream QEMU source):
    https://github.com/arixmkii/qcw/tree/main/patches/qemu

On Windows, the -virtfs shorthand may not work. Use the explicit -fsdev +
-device syntax instead:

    -fsdev local,security_model=mapped-xattr,id=fsdev0,path=D:SHARED
    -device virtio-9p-pci-non-transitional,id=fs0,fsdev=fsdev0,mount_tag=SHARED

Notes:
  - virtio-9p-pci-non-transitional (modern VirtIO 1.0) is required for
    Pegasos2. For AmigaOne, use virtio-9p-pci (legacy) instead.
  - security_model=mapped-xattr stores Unix permission metadata in NTFS
    Alternate Data Streams, allowing protect (chmod) to work on the shared
    volume. security_model=none passes through host permissions directly.


DOSDriver Configuration
-----------------------

The included SHARED DOSDriver file contains:

    Handler   = L:Virtio9PFS-handler
    StackSize = 65536
    Priority  = 5
    GlobVec   = -1
    Activate  = 1
    Control   = "auto"

- Activate = 1 -- auto-mount on boot
- Control = "auto" -- auto-detect the first VirtIO 9P PCI device
- The volume name matches the QEMU mount_tag parameter

If the machine is booted without a VirtIO 9P device (e.g. QEMU started
without -virtfs / -device virtio-9p-pci), the handler declines the mount
silently: no requester appears, boot continues normally, and the volume
simply does not exist. A single diagnostic line is written to the serial
console. The DOSDriver can stay installed permanently regardless of
whether the device is present.


Debug Output
------------

Compile with -DDEBUG to enable serial debug output (QEMU serial console or
Sashimi on real hardware). All debug messages are prefixed with [virtio9p].


Architecture
------------

This is a handler, not a device driver. There is no .device file, no
BeginIO/AbortIO, and no block layer. The 9P protocol is file-level, so
the handler IS the filesystem. FileSysBox handles all DOS packet
translation; we only implement FUSE callbacks.

Endianness:

  9P wire protocol       Always LE    Byte-by-byte extraction (natural on BE
PPC)
  Vring fields (legacy)  Native BE    No swap (vr16/vr32/vr64 = no-op)
  Vring fields (modern)  LE           Swap via vr16/vr32/vr64
  VirtIO config (legacy) Host-native  PCI I/O functions handle it
  VirtIO config (modern) LE           stwbrx/lwbrx handle LE conversion


How This Project Was Created
----------------------------

This handler was developed with the assistance of Claude Code.


Version History
===============


0.10.1-beta (5 July 2026)
-------------------------

  Defect-fix release from a full init-path code review, SDK-verified:
  - Physically contiguous DMA memory (AVT_Contiguous) for the vring
    and transact buffers -- a physically fragmented vring had the
    device DMA into pages owned by other allocations: silent,
    boot-layout-dependent memory corruption behind intermittent
    "boot stops at a shell instead of Workbench" hangs.
  - DMAEntry allocations NULL-checked; an init crash before the mount
    reply used to deadlock the boot against the DosList semaphore.
  - EVERY init failure (VirtIO init, IRQ, DMA, 9P handshake, missing
    filesysbox) now declines the mount gracefully instead of raising
    the blocking boot requester; node removal now uses the
    SDK-sanctioned NonBlockingModifyDosEntry.
  - GCIT_TimeBaseSpeed queried as uint64 (was clobbering 4 bytes of
    stack and skewing the 10 s transact timeout).
  - EndDMA paired with the exact StartDMA size and honest flags.
  - Timeouts that fail to drain outstanding descriptors escalate to a
    full transport reset, so late completions can never corrupt a
    future response.
  - Per-transaction cache maintenance cut from 2x512 KB to the actual
    response length.  100 MB C:Copy (QEMU amigaone, TCG): ~64 MB/s
    SHARED: -> RAM:, ~140 MB/s RAM: -> SHARED:.


0.10.0-beta (10 June 2026)
--------------------------

  Graceful exit when no 9P device is present:
  - No more blocking boot requester -- the handler previously failed
    the mount with DOSFALSE, which made the boot-time mounter raise a
    blocking "Could not mount device" requester that froze the boot
    until dismissed.  The handler now replies success to the startup
    packet and instead removes its own DOS device node, so the volume
    silently vanishes and boot continues straight to Workbench.
  - No more relaunch storm -- a handler that exits without
    establishing dn_Port is restarted by DOS on every subsequent
    reference to the device.  With the device node removed, references
    fail instantly with "object not found" and the handler never
    respawns.
  - The node removal is strictly non-blocking and happens only after
    the startup packet is replied (the mount caller holds the DosList
    semaphore while waiting for that reply).


0.9.1-beta (15 May 2026)
-------------------------

  Bug fixes:
  - v9p_truncate / v9p_ftruncate now return the new file size on
    success instead of 0.  filesysbox.library propagates the FUSE
    callback's return value directly to dos.library/SetFileSize, which
    by AmigaOS DOS convention must return the new size on success or
    -1 on failure.  Returning the standard FUSE zero-on-success caused
    every IDOS->ChangeFileSize() on an open file handle to look like a
    failure to userspace, even though the file was correctly truncated
    server-side.  Surfaced by a new in-guest test that exercises
    SetFileSize on an open dos.library FileHandle.

  Test suite:
  - Unified the legacy stress_suite.py and the v0.9.0 robustness suite
    into a single sequential runner under tools/qemu-regression/
    robustness/.  15 tiers, 44 cases, 43 PASS + 1 SKIP (Windows-host
    symlink follow) in ~12 min.


0.9.0-beta (15 May 2026)
-------------------------

  Robustness:
  - Tag-matched 9P transport -- replies are matched against the request
    tag before being accepted, eliminating mis-attribution after a
    timeout
  - Dedicated Tflush buffer -- the cancellation message no longer shares
    a buffer with the transaction it's cancelling
  - Held-open DMA mappings -- vring DMA is established once at handler
    start, eliminating per-op StartDMA/EndDMA churn
  - V9P_Reset() -- clean transport teardown + re-init without restarting
    the handler
  - FID orphan tracking -- FIDs lost to transport timeout/reset are
    marked orphaned and counted instead of leaking silently
  - 10-second PPC time-base wallclock budget on every transaction
  - Legacy VirtIO reset polls device until STATUS=0
  - lwsync barriers in virtqueue producer/consumer (correct PowerPC
    primitive for cacheable RAM, not eieio)
  - PCI iobase mapping caveat warning for AmigaOne Articia S firmware
  - Path-length pre-check in Walk returns ENAMETOOLONG cleanly on
    over-long paths
  - Bounds-checked p9_get_str refuses to read past the response

  Test suite:
  - New robustness harness (tools/qemu-regression/robustness/) covering
    the items above plus general feature coverage
  - 17 tiers, 31 cases, 29 PASS + 2 documented SKIP in ~12.5 minutes
  - ~96% v9p_* FUSE callback coverage (24/25)
  - Makefile gains -MMD -MP header-dependency tracking


0.8.0-beta (17 Apr 2026)
-------------------------

  New features:
  - Modern VirtIO PCI handshake for transitional devices -- ported the
    3-step detection pattern from VirtualSCSIDevice: zero BAR5 high DWORD
    workaround, unconditional modern detect with MMIO probe, and automatic
    fallback to legacy I/O when MMIO fails (Articia S bridge). This fixed
    SHARED: not mounting on Pegasos2.

  Test suite:
  - New comprehensive regression suite (stress_suite.py) with 29 checks
    across 8 tiers; validated on AmigaOne (27/29), Pegasos2 (28/29),
    SAM460ex (27/29)


0.7.1-beta (16 Apr 2026)
-------------------------

  Bug fixes:
  - Fixed crash when flushing files without an open handle -- filesysbox
    can call the fsync callback with a NULL file-info pointer during a
    general flush (e.g. after CMD_UPDATE on an unopened path); the handler
    was dereferencing it unconditionally to read the 9P fid. The resulting
    page fault on address 0x14 killed the SHARED handler process. The
    fsync callback now returns success when no open file handle is
    attached.


0.7.0-beta (27 Mar 2026)
-------------------------

  Bug fixes:
  - Fixed shutdown freeze on Restart System -- the ISR was removed after
    FbxCleanupFS replied to DOS; the OS could kill the process before
    RemIntServer ran, leaving a dangling ISR chain pointer. The ISR is
    now detached before FbxCleanupFS.
    (reported on AmigaOne and Pegasos II)


0.6.0-beta (26 Mar 2026)
-------------------------

  New features:
  - File sync -- flushing files now properly syncs data to the host disk
  - Symbolic links -- create and follow symlinks on the shared volume
  - Hard links -- creating hard links is now supported
  - Append and truncate on open -- these flags now work correctly
  - Request cancellation -- stalled requests are automatically cancelled

  Bug fixes:
  - Fixed crash on restart/shutdown (reported on AmigaOne and Pegasos II)
  - Fixed potential crash from malformed host data
  - Fixed potential crash from invalid device responses
  - Fixed deep directory paths being silently truncated
  - Fixed incorrect free space reporting on large volumes
  - Fixed modern VirtIO init failure on unresponsive devices
  - Fixed startup failure with fragmented memory

  Test suite:
  - 25 integration tests covering all supported filesystem operations


0.4.0-beta (07 Mar 2026)
-------------------------

  - Permission support -- Protect command now works on shared volumes
  - Ownership support -- changing file owner and group is now supported
  - Truncate open files -- ChangeFileSize now works on open files
  - Windows QEMU setup guide added
  - 12 integration tests passing


0.3.0-beta (02 Mar 2026)
-------------------------

  - 8x faster file transfers -- message size increased to 512 KB
  - Faster I/O -- DMA addresses cached at startup
  - Faster directory listings -- zero-copy directory reads


0.2.0-beta (02 Mar 2026)
-------------------------

  - First working release -- SHARED: volume appears in Workbench
  - Tested on QEMU AmigaOne (legacy VirtIO)
  - Includes AmigaOS Shell installer script


0.1.0 (02 Mar 2026)
--------------------

  - Initial implementation with dual VirtIO transport and full 9P2000.L
    filesystem protocol


License
-------

Copyright 2026. All rights reserved.