disk_image_files.txt

Disk Image Files

The -i option takes a filename of a disk image file.

If the file does not already exist, and the client issues a format command,
the file will be created and filled with nulls and sector headers.

A *.pdd1 TPDD1 disk image file is composed of 80 records.
Each record is composed of 3 fields: Logical Size Code, ID, DATA

   +--------+----------+---------------------------------------+
   |  LSC   |    ID    |                DATA                   |
   +--------+----------+---------------------------------------+
   | 1 byte | 12 bytes |             1280 bytes                |
   +--------+----------+---------------------------------------+

A *.pdd2 TPDD2 disk image file is composed of 160 records.
Each record is composed of 3 fields: ID, unknown, DATA

   +----------+------------------------------------------------+
   |    ID    |   ?    |                DATA                   |
   +----------+--------+---------------------------------------+
   | 12 bytes | 1 byte |             1280 bytes                |
   +----------+--------+---------------------------------------+

for tpdd2 these correspond to these ram addresses:
ID    0x8004 to 0x800F
?     0x8010
DATA  0x8013 to 0x8512

The "?" byte on tpdd2 is an extra byte that isn't described in the manual,
but exists in the drives ram after the ID section. It's normally just 0x00,
but you can write it in ram, commit to disk, and read it back from disk,
so it's included in the disk image format.

There are no delimiters or other formatting or header.

Currently, disk image files are only usable for sector access commands.
Meaning you can not use dl2 to access the files within a disk image,
only read and write the raw sectors.

Two example uses so far are the dictionary disk for Sardine,
and the install disk for Disk Power KC-85.

Sardine's dictionary disk is a pure data disk with no filesystem,
and so Sardine uses FDC-mode to access the sectors like a database.

The install disk for Disk Power is designed to look like a normal disk with a
filesystem, but the installer uses fdc-mode sector access to read sectret data
from some sectors that aren't marked as in-use in the FCB ot SMT tables.

Generally, you also need to use some extra commandline options to disable
TS-DOS directory extensions support (-e off), and to force stricter TPDD1-only
or TPDD2-only emulation (-m 1) or (-m 2). Example:

$ dl -v -e off -m 1 -i Sardine_American_English.pdd1

That isn't required to use disk images in general, it's just that in both of
these real examples, the software involved happens to do things that trigger
responses from an emulator that a real drive wouldn't do, so the extra options
just turn off features and make the server act more strictly like a real drive.

Disk image files can be created with https://github.co/bkw777/pdd.sh

dl2 can also create new disk images from client-issued format and sector
access commands. Example: run "$ dl -vv -e off -m 1 -i ./newdisk.pdd1"
and then use a client (like TS-DOS) to "format" the "disk".

For TPDD1, both the FDC-mode the Operation-mode format commands do what a real
drive does. The FDC-mode format just generates all nulls and the one logical
size code byte per record, which creates a raw data disk with no filesystem,
like the Sardine dictionary disk. The Operation-mode format command does the
same as FDC-mode format with logical size code 0 (64-byte logical sectors) and
then writes the single byte of non-null data at the right address to create a
valid Space Management Table, which makes the disk into a functioning filesystem
disk. If you took the generated .pdd1 or .pdd2 file and used pdd.sh to "restore"
it to a real disk, that disk would be a functioning filesystem disk.

Real disks can only be dumped or restored using the matching type of drive.
Although a real TPDD2 drive can at least read a TPDD1 disk, you must use a
TPDD1 drive to dump a TPDD1 disk to a .pdd1 image file, or to restore a .pdd1
image file to a real disk, and a TPDD2 drive for .pdd2 files.