====== Using cpmtools ======

cpmtools is a set of command-line utilities for reading, writing, and managing CP/M disk images from a modern OS. No emulator needed — you can inject or extract files directly.

===== The diskdefs File =====

cpmtools has no way to auto-detect a disk's geometry — CP/M itself never standardized this — so every format you want to work with has to be defined in a **diskdefs** file. This file lives at:

<code>/etc/cpmtools/diskdefs</code>

Each entry looks like this:
<code>
diskdef mdsad350
    seclen 512
    tracks 70
    sectrk 10
    blocksize 2048
    maxdir 64
    boottrk 2
    skew 5
    os 2.2
end
</code>

If your disk image doesn't match any built-in definition, you can add your own entry here — that's how you'd support an unusual or homebrew format. You reference a definition by its name with the ''-f'' flag on any cpmtools command (e.g. ''-f mdsad350'').

===== Basic Commands =====

**# List directory contents of an image:**
<code>cpmls -f mdsad350 your_image.img</code>

**# Inject (copy in) a file:**
<code>cpmcp -f mdsad350 your_image.img /path/to/local/file.COM 0:file.COM</code>

**# Extract (copy out) a file:**
<code>cpmcp -f mdsad350 your_image.img 0:file.COM /path/to/local/file.COM</code>

**# Delete a file from an image:**
<code>cpmrm -f mdsad350 your_image.img 0:file.COM</code>

**# Change file attributes (Read-Only, System, Archive):**
<code>cpmchattr -f mdsad350 your_image.img +r 0:file.COM</code>
Common attribute flags:
  * ''r'' — Read-Only
  * ''s'' — System (hidden from normal DIR listing)
  * ''a'' — Archive

**# Change Unix-side file mode when extracting:**
<code>cpmchmod -f mdsad350 your_image.img 644 0:file.COM</code>

**# Check a CP/M filesystem for errors:**
<code>fsck.cpm -f mdsad350 your_image.img</code>

**# Create a brand new, blank CP/M filesystem in an existing image file:**
<code>mkfs.cpm -f mdsad350 your_image.img</code>

**# Interactively browse/edit a raw image (advanced/recovery use):**
<code>fsed.cpm -f mdsad350 your_image.img</code>

===== Notes on User Numbers =====

CP/M disks support multiple "user areas" (0–15) on a single disk — think of them like separate namespaces on the same volume. That's the ''0:'' you see in front of filenames above. To list or work with a different user area, change the number:
<code>cpmls -f mdsad350 your_image.img -u 2</code>

===== Disk Type Definitions =====

The format name you pass to ''-f'' has to match an entry in ''diskdefs'' exactly. Below are common definitions, including the full Northstar family.

==== Northstar Micro-Disk System ====

^ Name ^ Description ^ Capacity ^
| mdsad87  | Northstar MDS-A1 — SSSD, 48 tpi, 5.25", 256-byte sectors x 10/track | ~87K |
| mdsad175 | Northstar MDS-A-D 175 — SSDD, 48 tpi, 5.25", 512-byte sectors x 10/track | ~175K |
| mdsad350 | Northstar MDS-A-D 350 — DSDD, 48 tpi, 5.25", 512-byte sectors x 10/track | ~350K |

All three use a 5-sector skew and CP/M 2.2. The 350K format is effectively the double-sided version of the 175K disk — same sector layout, twice the tracks.

==== Other Common Vintage Formats ====

^ Name ^ Description ^ Capacity ^
| ibm3740   | IBM 3740 — the original 8" SSSD "standard" CP/M format | ~250K |
| osborne1  | Osborne 1 — SSDD, 5.25", 1024-byte sectors x 5/track | ~100K |
| osborne4  | Osborne Nuevo/Vixen/4 — DSDD, 5.25" | ~200K |
| kaypro2   | Kaypro II — SSDD, 5.25", 10 sectors/track | ~191K |
| kaypro4   | Kaypro 4/10 — DSDD, 5.25" | ~390K |
| apple2    | Apple II CP/M (via Softcard/CP/M card) | ~140K |
| nshd8     | Northstar Hard Disk, 8MB partition style image | 8MB |

===== Tips =====

  * If ''cpmls'' errors out with something like "cannot read boot sector" or garbage output, the ''-f'' definition doesn't match the actual disk — double-check capacity/format before assuming the image is corrupt.
  * CP/M filenames are limited to 8.3 uppercase characters — lowercase local filenames get silently uppercased on injection.
  * Always extract a copy before editing/deleting on an image you can't easily re-create — cpmtools has no undo.