Meatloaf Dos

Meatloaf DOS Commands — Complete Reference

Meatloaf is an ESP32 firmware that plugs into the C64's IEC bus, emulating one or more virtual disk drives. This document covers every command you can send to a Meatloaf drive over its command channel (secondary address 15, device number 8 by default). It documents the standard CBM DOS 2.6 commands Meatloaf responds to, the SD2IEC-style extensions it inherits, and the Meatloaf-specific commands added in this firmware.

Not what you're looking for? If you want to make HTTP requests (GET/POST/PUT) with custom headers and JSON parsing, you want the full-mode HTTP client protocol — secondary address 2, commands m, h, b, s, status, r-h, r-b, j. See the meatloaf-networking skill for that.

How to send DOS commands

There are three ways to send commands to a Meatloaf drive:

1. BASIC V2 (works everywhere)

CRITICAL: Always use lowercase BASIC keywords. On the C64 you normally type with shift-lock off, so open, print#, close, input#, get#, rem, load, save, list, run, chr$ are all lowercase. Never write OPEN, PRINT#, CLOSE, INPUT#, GET#, REM, LOAD"$",8 etc. in code examples — that looks wrong. Uppercase BASIC is never correct in examples.

open 15,8,15    : rem open command channel to device 8
print#15,"cmd"  : rem send command
close 15        : rem close channel

For commands that return data (like pwd), read the error/status channel after sending:

open 15,8,15
print#15,"cmd"
input#15, e, e$, t, s  : rem e=status code, e$=message, t=track, s=sector
close 15
print e$ : rem prints the response

For commands that return multi-line data:

open 15,8,15
print#15,"cmd"
get#15, a$ : rem read one byte at a time
rem ... loop until st and 64 (eoi)
close 15

Gotcha: colons and input#. BASIC's input# treats : as a field separator. Commands whose output contains colons (like t-ra and t-ri which return HH:MM:SS times) will break with input#. Use get# in a loop for those instead.

2. JiffyDOS @ wedge (if JiffyDOS is active)

If the C64 has a JiffyDOS Kernal ROM, just type @cmd at the ready. prompt. JiffyDOS forwards everything after @ to the drive's command channel and prints the response automatically.

@cmd     ← sends "cmd" to drive command channel, shows response
@        ← by itself, reads the error channel

This works for all commands in this reference — @pwd, @md:dir, @cp2, @t-ra, etc.

3. C (cc65) / 6502 assembly

#include <cbm.h>
cbm_open(15, 8, 15, "");              // open command channel
cbm_write(15, "cmd\r\n", 5);          // send command
cbm_close(15);                         // close

Quick reference (all commands)

Standard CBM DOS 2.6 commands

These are the classic 1541/1571/1581 commands. Meatloaf implements most of them, either natively (for local SD/flash filesystems) or through VDrive emulation (for disk images).

Initialize — i, uj, u9/ui

BASIC V2:

open 15,8,15 : print#15,"i" : close 15

Wedge:

@i

Bus speed — ui+ / ui-

Switching to VIC-20 speed can help with timing-sensitive setups. The status code is always set to OK.

BASIC V2:

open 15,8,15 : print#15,"ui-" : close 15  : rem VIC-20 mode
open 15,8,15 : print#15,"ui+" : close 15  : rem C64 mode

Format — n:name,id

Creates a new (empty) filesystem on the current media. When VDrive mode is active (vd+), n: creates a new disk image file in the current directory — the filename before the colon determines the image name, and the id after the comma sets the disk label. When VDrive is off, n: calls m_cwd->format() on the current directory.

open 15,8,15,"n:mydisk,01" : close 15

Wedge: @n:mydisk,01

Scratch — s:pattern

Deletes files matching a pattern. Supports wildcards * (any characters) and ? (single character). Returns FILES SCRATCHED with the count.

open 15,8,15,"s:backup.*" : close 15

Wedge: @s:backup.*

Rename — r:newname=oldname

Renames a file. The = separator splits old name (right) from new name (left). The match uses isMatch() which supports * and ?.

open 15,8,15,"r:newgame=oldgame" : close 15

Wedge: @r:newgame=oldgame

Copy — c:newname=oldname

Copies a file on the same media. Same = syntax as rename.

open 15,8,15,"c:backup=original" : close 15

Wedge: @c:backup=original

Validate — v

Rebuilds the Block Availability Map (BAM) on disk media. Currently a no-op that logs "validate bam" — the actual BAM rebuild is delegated to VDrive when active.

open 15,8,15,"v" : close 15

Wedge: @v

Buffer/Block commands — b-p, b-r, b-w, b-a, b-f, b-e

These operate on the currently open file stream (not on a raw disk buffer like a 1541 would). They're adapted for Meatloaf's streaming model:

b-p is the most generally useful — it works on any stream (network streams, file streams, disk image streams) for random-access seeking.

b-r reads the block content into the drive's status buffer. You retrieve it by reading the error channel after the command.

BASIC V2 — b-p (position):

open 2,8,2,"http://example.com/data" : rem open file
open 15,8,15 : print#15,"b-p 2,256" : close 15  : rem seek to byte 256
rem read from channel 2 continues at position 256

BASIC V2 — b-r (read block, retrieve via status):

open 2,8,2,":myfile" : rem open file on channel 2
open 15,8,15 : print#15,"b-r 2,0,18,0" : rem seek to track 18 sector 0 on channel 2
close 15
input#15, e, e$, t, s : rem read the block data from status

Wedge — b-p:

@b-p 2,256

Memory commands — m-r, m-w, m-e

These operate on Meatloaf's internal DOS RAM (not the C64's memory). This is the firmware's own memory space used for ROM patching and fast-loader detection.

m-r — read from firmware memory:

open 15,8,15 : print#15,"m-r" + chr$(0) + chr$(3) + chr$(4) : rem read 4 bytes from $0300
input#15, a$ : rem read returned bytes
close 15

m-w — write to firmware memory:

rem This is binary — you send raw bytes after m-w
open 15,8,15
print#15,"m-w" + chr$(0) + chr$(3) + chr$(2) + chr$(1) + chr$(2) : rem write bytes $01 $02 to $0300
close 15

These commands use Petroski's "M-W" protocol from the original 1541 and are commonly used by fast-loader cartridges to install custom drive code on-the-fly.

User commands — u1–u9, ua–uh, ui, uj

These are the classic user-command vectors from 1541 DOS:

BASIC V2 — u1 block read:

open 15,8,15,"u1 2,0,18,0" : rem read block at track 18 sector 0 into channel 2's stream
close 15

Navigation and directory commands

Change Directory — cd

Changes Meatloaf's current working directory (the m_cwd pointer). Accepts relative paths (cd dirname, cd..), absolute paths (cd/path/to/dir), and URLs. The : separator, _ (parent), ^ (up/root), / path separators are all handled:

The directory listing is obtained by load"$",8 (without changing the directory), but after a cd command, the $ listing reflects the new current directory.

BASIC V2:

open 15,8,15 : print#15,"cd games"  : rem go into GAMES directory
open 15,8,15 : print#15,"cd.."      : rem go up one level
open 15,8,15 : print#15,"cd/"       : rem go to root
open 15,8,15 : print#15,"cd//sd"    : rem switch to SD card

Wedge:

@cd games
@cd..
@cd/
@cd//sd

Print Working Directory — pwd

Returns the current working directory URL through the error channel. The response is PETSCII-encoded and ends with CR.

BASIC V2:

open 15,8,15
print#15,"pwd"
input#15, e, e$, t, s
print e$          : rem prints the current directory path
close 15

Wedge:

@pwd

Make Directory — md:path

Creates a new directory at the given path. If the path already exists, returns FILE EXISTS. If the filesystem is read-only, returns WRITE PROTECT. On failure, returns WRITE ERROR.

BASIC V2:

open 15,8,15,"md:newdir" : close 15

Wedge:

@md:newdir

Remove Directory — rd:path

Deletes an empty directory. Standard CBM DOS error codes apply: FILE NOT FOUND if it doesn't exist, WRITE PROTECT if read-only, WRITE ERROR on failure.

BASIC V2:

open 15,8,15,"rd:olddir" : close 15

Wedge:

@rd:olddir

Position (Seek) — p ch,hi,mid,lo

Positions the read/write cursor of an open channel's stream. The position is calculated as (hi * 65536) + (mid * 256) + lo. This is the same p command from SD2IEC and works on any open stream, including network streams and disk image streams.

open 2,8,2,"http://example.com/bigfile"
open 15,8,15 : print#15,"p 2,0,1,0" : rem seek to byte 256
close 15

Wedge:

@p 2,0,1,0

Change Partition — cp n / c{shift-p}n

Switches to a different partition on mounted CMD media (DHD hard disks, D1M/D2M/D4M floppy images). The partition number must be 1–254 (a CMD HD holds at most 254 partitions); partition 0 is the system partition and cannot be selected, though it does appear in the $=P listing. Returns PARTITION SELECTED on success or ILLEGAL PARTITION if the partition doesn't exist.

Two forms:

• Text form: cp 2, cp 5 — the number follows cp.
• Binary form: c + {shift-p} + n where n is a raw byte.

After a successful partition change, the working directory is set to that partition's root.

A partition can also be named directly as the first component of an in-image path — hdbackup.dhd/2/game or hdbackup.dhd/subs/game. That loads or saves from that partition without changing the selected one; only cp n and the partition console command change the selection. A partition number of 0 in a path means "the currently selected partition". Where a file has the same name as a partition the partition wins — reach the file by giving the partition number explicitly, e.g. hdbackup.dhd/2/subs.

BASIC V2:

open 15,8,15,"cp 2" : close 15   : rem switch to partition 2

Wedge:

@cp 2