ReadyFS Path Research and Translation Notes
Why the public syntax is not native DOS syntax
C64 OS combines device, partition, filename, and path as
device:partition:filename:path. Its documentation explains that filename is
placed before the path partly so a narrow status display keeps the filename
visible. That is useful for its UI, but it makes a typed hierarchical shell
path harder to read and makes an image-file boundary implicit.
ReadyFS instead keeps the hierarchy in traversal order:
8:/FILE— unpartitioned/legacy IEC device11.3:/games/demo.d64!/PROGRAM— IEC device 11, native partition 3, host-side folders, explicit image boundary, contained fileu:/USB1/games/demo.d81!/PROGRAM— UltimateDOS host path plus images3:/games/PROGRAM— SoftwareIEC logical partition 3@work:/src/file.c— exact-place alias
The optional .partition numeric suffix is reserved for CMD/SD2IEC-compatible
IEC drivers. For native SD2IEC, 10.1:/ selects partition 1 on device 10,
while 10.2:/ selects an existing partition 2 on that same device. The suffix
and IEC address are separate decimal numbers. Omitting the suffix, as in 10:/,
uses the device's current partition, queried and pinned for each operation;
internal zero represents current/default, not a fixed data partition 0.
IEC 10: PARTITIONS lists available partitions. Explicit paths do not change
the current selection; IEC 10: PARTITION N --SELECT deliberately does.
Parsing this form does not grant directory capability: the detected driver must
explicitly support partitioned paths before listing or mutation. See
native SD2IEC support for the current implementation.
Translation rules
The public path is always normalized and absolute. A backend may temporarily change its own current directory, but every transaction starts by reasserting the public absolute location; ReadyFS never treats backend current-directory state as durable shell state.
CMD/SD2IEC use a DOS command-string grammar in which a partition and directory
path precede a colon-separated leaf. SD2IEC also treats a disk image as a
directory for CD, and leaving it requires a separate parent/unmount command.
ReadyFS does not leak that stateful behavior into its public path. ! records
the transition from host file to contained filesystem, so planning can reject
an unsupported cross-image operation before changing device state.
The pure CMD/SD2IEC translator is host-harness-proven for the following
commands. The same source cc65-compiles into the cached RFCMDPATH sidecar
($B600, $FFD bytes) on the overlay lab D81. Boot loads it into REU slot 5,
verifies its ABI, runs a compact $:pattern translation self-test, and restores
the matcher before the prompt. The larger callable VICE suite proves file-open,
rename, image-mount, two-command-unmount, and matcher restoration.
The callable native OP PATH [DEST] diagnostic runs from the help sidecar,
swaps into CMD path through resident scratch, restores help, prints the exact
native result, and restores the matcher. A separate RFDRIVE sidecar classifies
bounded status-channel replies while the resident exclusively owns KERNAL IEC
I/O. probe iec DRIVE: is proven in VICE, but translated mutating commands are
not issued until the detected profile explicitly grants their capabilities:
Detected IEC profiles are stored per device in session REU $0888-$08E3 as
individually marked records. The registry is cleared at application boot and
every lookup validates both marker and device number. profile iec 8: mount
therefore answers from a durable, explicit capability record rather than the
last transient status buffer. The current matrix requires P for open and
scratch, P+F for directory and folder/rename operations, and P+F+I for
image mount/unmount.
| ReadyFS | Native operation |
|---|---|
8:/RF* --native-pattern |
$:RF* (flat read-only directory selection) |
11.3:/games/HELLO.PRG |
3//games/:HELLO.PRG |
directory 11.3:/games/tools |
$3//games/tools/ |
scratch 11.3:/games/OLD.SEQ |
S3//games/:OLD.SEQ |
mkdir 11.3:/games/newdir |
MD3//games/:newdir |
rmdir 11.3:/games/old |
RD3//games/:old |
| rename old to new | R3//archive/:NEW.SEQ=3//games/:OLD.SEQ (new=old) |
mount 11.3:/games/demo.d64 |
CD3//games/demo.d64 |
| unmount partition root | CD//, then CD plus PETSCII back-arrow $5F |
11.3:/games/demo.d64!/HELLO |
rejected as stateful until mount/open/restore transaction support exists |
s3:/games/HELLO |
SoftwareIEC KERNAL name 3:/games/HELLO on discovered bus |
The harness also rejects cross-device/cross-partition rename, partitionless
legacy IEC paths, non-IEC endpoints, unsupported image extensions, components
over 16 bytes, and image-contained access that would require hidden mutable
device state. make readyfs-host-tests compiles and runs this contract.
Length and capability policy
- ReadyFS canonical commands and expanded paths are at most 255 bytes.
- C64 OS documents a roughly 232–234 byte directory-path ceiling and 16-byte directory components for its CMD-style drivers. ReadyFS does not adopt its filename-before-path layout, but the limit is useful as a conservative compatibility profile.
- SD2IEC documents patterns/visible Commodore filenames up to 16 characters,
partitions 1–254, CMD-compatible
CD/MD/RD, and image mounting throughCD. Native host long names and their displayed aliases must remain distinct metadata. - Each driver preflights the fully translated command/open-name length, leaf length, partition range, supported image type, and maximum path profile. Unsupported or unproven operations fail before mutation.
--native-patternis the only mode allowed to forward a C64-DOS pattern. Shell*,?, and**otherwise operate on complete ReadyFS relative stems.
Native-pattern action contract
Native patterns may eventually select copy, move, and delete inputs, but they
must never be forwarded as a wildcard mutation such as S:RF*. The accepted
execution model is:
- Translate and open the backend pattern only as a read-only directory query.
- Ignore the directory header and serialize every exact returned filename, type, and block estimate into the existing bounded REU action plan. Hitting the entry limit invalidates the whole plan; it never means “apply the first N”.
- Apply
--include/--exclude, if present, only after native enumeration and against each complete ReadyFS relative stem. This keeps backend selection and shell filtering distinct and inspectable. --whatifprints every exact selected target plus totals and performs no write, scratch, rename, mount, or directory-changing command.- A real run requires
--apply, displays the complete selection, and freezes those exact names before execution. Bare--native-patternremains denied even with--force/--yes. Each frozen target then uses the normal staged copy/move or exact-name delete path with RFJ1-before-ACK and stop/continue policy; the wildcard is never reissued as a mutation command. - Copy/move require a directory destination when more than one source is selected. Directories and unsupported REL transfers reject the entire first-generation plan before mutation; per-type expansion comes only with dedicated evidence.
Preview syntax is copy 8:/RF* 9:/ --native-pattern --whatif, move ..., and
delete 8:/RF* --native-pattern --whatif; execution replaces --whatif with
the explicit --apply opt-in (plus normal conflict/confirmation options).
Users do not add --recursive merely because the implementation reuses the
batch controller. In 171906, resident IEC enumeration feeds exact names and
types through the backend/matcher/recursive sidecars; filtered planning stays
zero-write, singleton native delete succeeds, and native copy/move cross from
IEC8 to IEC9 with exact byte/postcondition checks. Parsed RFJ1 dumps contain
only RFNC1, RFNC2, and RFNM1 exact-name actions. Wildcard scratch, write,
and rename commands remain forbidden. Regular IEC collection destinations must
be the flat root; 171852 additionally proves that a matched REL $13 entry
rejects the entire native plan with the destination still absent.
Sources
- C64 OS file-reference design and path limits: https://c64os.com/c64os/usersguide/filesystem
- C64 OS File Manager device/partition and recursive-operation behavior: https://www.c64os.com/c64os/usersguide/filemanager
- C64 OS discussion of absolute file references rather than shared mutable drive-directory pointers: https://c64os.com/post/cmdhdcurrentdirpointers
- SD2IEC command manual derived from the firmware README, including partition,
directory, and image
CDsemantics: https://c64os.com/post/sd2iecdocumentation - UltimateDOS reference: https://1541ultimate.net/content/download/ultimate_dos_v1.0.pdf
SoftwareIEC host-file/type findings on firmware 3.14
- The BASIC directory stream is not an exhaustive FAT enumeration authority. Physical traces can show the host-path header and one earlier file, then end before the requested later leaf. ReadyFS must not infer absence from that stream.
- Ordinary SoftwareIEC OPEN without an explicit type maps through
.???; explicit SEQ/PRG/USR opens map to.seq,.prg, and.usr. ReadyFS probes only those three explicit types and consumes the DOS status reply. - Never probe REL for existence. Firmware source opens REL with
FA_OPEN_ALWAYS, so a read-style existence check can create a missing host.relfile.rf065128/ap1000.relis the preserved proof artifact. - UCI SoftwareIEC target command
$14closes the data channel selected by its secondary-address byte. Firmware implements it synchronously throughget_data_channel(sa)->ext_close_file()->push_command($E0). ReadyFS uses it for read SA 2 and probe SA 6 via the complete ReadyIRC-derived UCI transport. - UCI status and resident IEC DOS status intentionally share scratch storage. Therefore the exact order is KERNAL close, target-5 close, then DOS-status read. Checking DOS status before the UCI command lets the UCI reply overwrite the evidence and can misclassify an absent host leaf.
SoftwareIEC directory-breadth boundary
The marker-owned run root eventually accumulated many deliberately preserved
diagnostic folders. Firmware 3.14 then stopped entering newly appended root
folders through direct CD: even though UltimateDOS listed them. Seeding
rf094315/rfseed.seq and rebooting with exact SoftIEC config equality did not
change the result. Creating a fresh child under already visible, uncrowded
rf091800 worked immediately, including a nested directory below it. This
aligns with the truncated FAT/BASIC-directory behavior: path design cannot
assume every raw host entry is reachable through SoftwareIEC at arbitrary
parent breadth. Future integration should expose a capability/refresh boundary
and prefer dedicated shallow SoftIEC-visible roots.