os8fs

Overview ¶

Package os8fs provides support for reading OS/8 Filesystems and disk images used by PDP-8 computers.

Disk images may contain multiple sides, each with their own filesystem (typically there are only 1 or 2 sides). Filenames may be prefixed by X: to indicate side X of the disk should be used. Sides are numbered starting with A (e.g., A: and B:). If a side is not indicated then the first side is assumed.

The OS/8 Filesystem is a flat filesystem, each file being contiguous on disk. A filesystem may have up to 4,096 blocks. Each block is composed of 256 12 bit words. Image files use 2 bytes per word with the first byte being the lower 8 bits of the 12 bit word and the second by being the upper 4 bits. The bits uuuullllllll are stored as:

+--------+--------+
|llllllll|0000uuuu|
+--------+--------+

File are listed in chained directory blocks starting with block 1 (block 0 is presumed to be a boot block). Each directory block starts with a header of 5 12 bit words:

+------------+
|010000-nfile|   Number of files in the directory block
+------------+
| BLOCK0     |   Index of first data block of first entry
+------------+
| NEXT BLOCK |   Index of next directory block (0 means end)
+------------+
|     ?      |   Unknown
+------------+
|     ?      |   Unknown
+------------+

Numbers are often stored as 010000 - N on a PDP-8 rather than as N. This enables using the ISZ instruction to execute a loop N times.

Following the 5 word header, up to 40 directory entries are listed. The data associated with these entries are contiguous on disk, starting with BLOCK0. Directory entires are either 2 or 6 words long and packed (e.g., 11111122333333). 2 word entries always start with a 0 word and represent free space (a deleted file). The second word is the number of blocks free:

+------------+
|000000000000|
+------------+
|010000 - len|
+------------+

6 word entries represent actual files:

+------+------+
| NAME | NAME |
+------+------+
| NAME | NAME |
+------+------+
| NAME | NAME |
+------+------+
| EXT  | EXT  |
+------+------+
| DATE        |
+-------------+
| 010000 - len|
+-------------+

The NAME and EXT are stored as 6 bit ascii. Each 6 bits represents one byte. Value 0-31 map to 64-95 and values 32-63 map as themselves (e.g., 01 is 'A' and 41 is '!'). NAME and EXT are padded with @ bytes (0). For example, the name NAME.GO would be represented in octal as 1601 1505 0000 0717.

The location of a file is computed by starting with the data block index from the directory block header and then adding all the sizes of all files, and deleted entries, listed in the directory block before the file's entry.

Dates are stored as MMMMDDDDDYYY (4 bit month, 5 bit day, 3 bit year). The year is offset from 1970 so only dates in the range of 1970-1977 can be represented. A 0 date indicates the file has no date associated with it.

When a file is deleted, it's entry is collapsed to two word, a 0 and its length. The remaining entries in the directory block are all moved up by 4 words.

Text files normally store 3 ASCII bytes as two words. The bytes aaaaaaaa, bbbbbbbb, ccccCCCC is stored as:

+------------+
+ccccaaaaaaaa|
+------------+
+CCCCbbbbbbbb|
+------------+