QIC-117 command interface¶

QIC-117 is the command and status interface of a floppy-tape drive. It turns three floppy-controller lines into a slow serial protocol: the host sends commands as counted Step pulses, and the drive answers report commands one bit at a time on Track Zero. Tapewyrm uses it to select the drive, move the tape, and read the drive's state before and during a capture.

Source: QIC-117 Rev J, 28 Aug 96 (qic117j.pdf).

Signals¶

QIC-117 Rev J §1.2 defines three signals. Pin numbers are on the Greaseweazle page.

Signal	Direction	Sensitivity	Use
Step	Host to drive	Edge	A train of N pulses is command N, or an argument.
Track Zero	Drive to host	Level	One report bit at a time, least significant bit first. Inactive except during a report.
Index	Drive to host	Edge	Cue pulses while idle, reporting or waiting for an argument; one pulse per segment during Logical Forward.

Track Zero stays inactive outside reports so that a PC's diskette-detect test does not mistake the drive for a floppy (Rev J §1.3).

Timing¶

QIC-117 Rev J Table 1:

Parameter	Description	Min	Nom	Max
TTIMEOUT	Command time-out (ends a pulse train)	2.2 ms	2.5 ms	2.9 ms
—	Alternate command time-out	6.2 ms	6.5 ms	6.9 ms
TSTEPW	Step pulse width	1 µs	—	1,100 µs
TSTEP	Step pulse interval	0.9 ms	2.0 ms	2.1 ms
—	Alternate Step pulse interval	0.9 ms	6.0 ms	6.1 ms
TINXW	Index pulse width	20 µs	—	1,100 µs
TINX	Cue Index interval	2 ms	4 ms	12 ms
TINXON	Time to issue cue Index	—	—	2.5 ms
TINXOFF	Time to clear cue Index	—	—	2.5 ms
TACK	Time to report ACK	—	—	2.5 ms
TBIT	Time to report a bit	—	—	900 µs
TCLR	Time to clear Track Zero	—	—	900 µs

Warning

A pulse train must stay grouped. If the gap between two pulses exceeds the drive's command time-out, the drive sees two commands. A stray single pulse is Soft Reset, and a stray five is Alternate Command Time-out. On a drive whose time-out sits at the 2.2 ms minimum, a 2.2 ms Step period is enough to cause this; see TEAC FT-3010.

Tapewyrm's firmware measures the Step gap from the trailing edge of each pulse, so the period the drive sees is pulse_us + inter_pulse_us. The generic profile uses 200 + 1800 µs = 2.0 ms, Rev J's nominal.

Commands and arguments¶

A command is N Step pulses, where N is the command code. Some commands take one to three arguments, each sent as a further pulse train in N+2 form: the value plus two pulses. N+2 keeps an argument from ever being a single pulse (Soft Reset) and makes zero sendable. Each argument is limited to six bits (Rev J §1.4.3). Soft Select is the exception: its argument is a literal 20 pulses.

Rev J §1.4 groups commands as report, mode and motion commands, and gates each by the restriction table (Table 2a: the modes it is illegal in, and the status it requires).

Command table¶

From QIC-117 Rev J Tables 2a, 2b and 2d. Flags: n non-interruptible, h high-speed. Timeouts are Rev J's maxima over every tape length and speed. The authoritative copy is packages/tapewyrm-cli/tapewyrm/qic117/commands.py.

Code	Command	Kind	Argument	Flags	Timeout	Tapewyrm
1	Soft Reset	Reset	—	—	460 s to ready	Avoided: deselects phantom drives
2	Report Next Bit	Report clock	—	—	900 µs	Clocks every report
3	Pause	Motion	—	n	16 s
4	Micro Step Pause	Motion	—	n	16 s
5	Alternate Command Time-out	Config	—	—	—	Never sent
6	Report Drive Status	Report	—	—	2.5 ms ACK	Used
7	Report Error Code	Report	—	—	2.5 ms ACK	Used; requires Ready
8	Report Drive Configuration	Report	—	—	2.5 ms ACK	Used; recorded in every capture
9	Report ROM Version	Report	—	—	2.5 ms ACK	Used
10	Logical Forward	Streaming motion	—	—	650 s	Every capture
11	Physical Reverse	Motion	—	h	650 s	`tw drive rev`, cleaning
12	Physical Forward	Motion	—	h	650 s	`tw drive fwd`, cleaning
13	Seek Head to Track	Motion	Track+2	—	15 s	Used
14	Seek Load Point	Motion	—	n	670 s	Used
15	Enter Format Mode	Mode	—	—	—	Refused (writes)
16	Write Reference Burst	Motion	—	n	940 s	Refused (writes)
17	Enter Verify Mode	Mode	—	—	—
18	Stop Tape	Motion	—	n	8 s	Used
19–20	Reserved
21	Micro Step Head Up	Motion	—	—	200 ms	`tw drive micro`
22	Micro Step Head Down	Motion	—	—	200 ms	`tw drive micro`
23	Soft Select	Select	Literal 20 pulses	—	—	`mountain` wake
24	Soft Deselect	Select	—	—	—
25	Skip N Segments Reverse	Motion	(N&15)+2, (N>>4)+2	n	650 s
26	Skip N Segments Forward	Motion	(N&15)+2, (N>>4)+2	n	650 s
27	Select Rate or Format	Config	Rate+2 or Format+2	—	—	`tw drive rate`, `tw drive format`
28	Enter Diagnostic Mode 1	Mode	Code sent twice	—	—	Refused
29	Enter Diagnostic Mode 2	Mode	Code sent twice	—	—	Refused
30	Enter Primary Mode	Mode	—	—	—	End of most wakes
31	Vendor unique
32	Report Vendor ID	Report	—	—	2.5 ms ACK	Used
33	Report Tape Status	Report	—	—	2.5 ms ACK	Used when supported
34	Skip N Segments Extended Reverse	Motion	3 nibbles, each +2	n	Tape length / speed
35	Skip N Segments Extended Forward	Motion	3 nibbles, each +2	n	Tape length / speed
36	Calibrate Tape Length	Motion	—	n	~1,300 s
37	Report Format Segments	Report	—	—	2.5 ms ACK	Used when supported
38	Set N Format Segments	Config	3 nibbles, each +2	—	—
39	Reserved
40–45	Vendor unique
46	Phantom Select	Select	Unit+2	—	—	`colorado` wake
47	Phantom Deselect	Select	—	—	—

Rev J: a drive ignores codes above 32 that it does not support, and reports "undefined command" for undefined codes below 32. It ignores a train of more than 32 pulses entirely.

Select Rate or Format (27) arguments (Rev J Table 2b):

Argument	Meaning
Rate 0	250 kbit/s or 4 Mbit/s, by drive type
Rate 1	2 Mbit/s
Rate 2	500 kbit/s
Rate 3	1 Mbit/s
Format	`tape_format × 4 + increment`. Formats: 1 QIC-40, 2 QIC-80, 3 QIC-3020, 4 QIC-3010. Increment: 1 standard, 3 wide (8 mm).

tw refuses every command that writes to tape (15, 16) and the diagnostic modes (28, 29), unless the drive object is built with writes allowed.

The report protocol¶

Rev J §1.4.2:

Send the report command (for example, 6 pulses for Report Drive Status).
Wait TACK plus the nominal command time-out from the last Step pulse, then read Track Zero. This first bit is Acknowledge and is always true. If it is false, the drive has failed or is resetting.
For each data bit, send Report Next Bit (2 pulses) and read Track Zero within TBIT of the second pulse. Bits arrive least significant first.
Send Report Next Bit once more and read the Final bit. It is normally true; false means an error ended the report.

The value is latched when the drive receives the report command, so slow clocking by the host does no harm. Any command other than Report Next Bit or Soft Reset during a report is an error (code 8) and ends the report.

Warning

Do not leave a report half-clocked. Some drives stop responding entirely afterwards and need a power cycle. See TEAC FT-3010.

Report layouts¶

QIC-117 Rev J Table 2c. Bit 0 is the first data bit after Acknowledge.

Report Drive Status (6), 8 bits. Bits 1, 5, 6 and 7 are valid only when bit 0 is set.

Bit	Field
0	Drive ready or idle
1	Error detected
2	Cartridge present
3	Cartridge write protected
4	New cartridge
5	Cartridge referenced
6	At physical BOT
7	At physical EOT

Report Error Code (7), 16 bits. Bits 0–7 are the error code; bits 8–15 are the command that caused it. Defined only when the drive is Ready with Error Detected set; reading it clears the error and the new-cartridge flag.

Report Drive Configuration (8), 8 bits.

Bits	Field
0	Reserved (0)
1–2	Vendor unique
3–4	Rate: 00 = 250 kbit/s or 4 Mbit/s, 01 = 2 Mbit/s, 10 = 500 kbit/s, 11 = 1 Mbit/s
5	Vendor unique
6	Extra-length tape detected
7	QIC-80 mode

Report ROM Version (9), 8 bits: bits 0–6 version, bit 7 beta.

Report Vendor ID (32), 16 bits: bits 6–15 make, bits 0–5 model. Some older drives report a whole word instead; the Colorado Jumbo 350's 0x0047 is Colorado's legacy ID 71.

Report Tape Status (33), 8 bits: bits 0–3 tape format, 4–6 tape type, 7 wide tape. The values are on the Cartridges page.

Report Format Segments (37), 16 bits: segments per tape track.

Error codes Tapewyrm sees¶

QIC-117 Rev J §3.5, Sequential Error Code List. The full list is in packages/tapewyrm-cli/tapewyrm/qic117/status.py. These are the codes that matter most during recovery. Codes 2, 8, 13, 26, 27, 31 and 41 have been seen on the bench.

Code	Name	Meaning for Tapewyrm
1	Command Received while Drive Not Ready	A command arrived during motion or a load point. Wait for Ready.
2	Cartridge Not Present or Removed	No cartridge, or a cleaning cartridge the drive does not detect.
8	Illegal Command in Report Subcontext	A report was left unfinished.
10	Broken Tape Detected	Fatal. `tw` aborts the sweep.
13	Command Received While New Cartridge Pending	Read the error code before sending motion commands.
19	Command Illegal When Cartridge Not Referenced	The tape has not been referenced; run a load point.
26	Power On Reset Occurred	Benign. Latched after power-up.
27	Software Reset Occurred	Benign. Also seen with no Soft Reset sent, from a split pulse train.
31	Rate or Format Selection Error	The drive cannot read that format or rate.
41	Drive Wakeup Reset Occurred	Benign. Latched after a phantom deselect and reselect.

With the exception of initialization errors, a later error never overwrites an earlier one (Rev J §1.4.4). Read the error code after every failure, and before any command that needs a clear error status.

Vendor make codes¶

QIC-117 Rev J, Assigned Vendor Make Codes, with the recommended format fill byte each vendor writes into unused space:

Make	Vendor	Format fill
4 and 71	Colorado Memory Systems	`6B`
5	Archive/Conner	`AA`
6	Mountain/Summit Memory Systems	`6D`
7	Wangtek/Rexon/Tecmar	`FE`
8	Sony	—
10	Irwin Magnetic Systems	—
15	Teac	`FE`
546	Iomega	`6D`

The full list is in tapewyrm_archive.qic117.VENDOR_MAKES. The fill byte matters for recovery: segments that were formatted but never written hold the fill byte with no valid parity, and tw convert reports them as "unwritten (format fill)" rather than as damage. On the bench, a QIC-80 tape showed unwritten segments filled with 6B.