diff --git a/Makefile.build b/Makefile.build index 7d0de3b..b805ed0 100644 --- a/Makefile.build +++ b/Makefile.build @@ -8,6 +8,12 @@ ifdef E LDLIBS += -static -lregex endif +nroff ?= nroff +groff ?= groff + +nroff_txt_flags ?= -c +groff_pdf_flags ?= + build_dir ?= build ifndef top_dir @@ -29,10 +35,17 @@ vpath % $(top_dir) obj_targets = gw2dmk.o dmk2gw.o gw.o gwx.o msg.o m2.o gwhisto.o \ gwhist.o gwdetect.o crc.o -targets = gw2dmk$E dmk2gw$E gwhist$E m2$E +bins = gw2dmk dmk2gw gwhist +bin_targets = $(foreach b,$(bins), $b$E) + +man_txt_targets = $(foreach b,$(bins),$b.1.txt) +man_pdf_targets = $(foreach b,$(bins),$b.1.pdf) +man_html_targets = $(foreach b,$(bins),$b.1.html) +man_targets = $(man_txt_targets) $(man_pdf_targets) $(man_html_targets) + +targets = $(bin_targets) $(man_targets) -#tar_files = LICENSE README.md $(targets) $(tar_extras) -tar_files = LICENSE README.md gw2dmk$E dmk2gw$E gwhist$E $(tar_extras) +tar_files = LICENSE README.md $(targets) $(tar_extras) clean_files = $(targets) $(obj_targets) @@ -90,6 +103,16 @@ gwhist$E: msg.o gw.o gwx.o gwhisto.o gwdetect.o gwhist.o m2$E: msg.o m2.o gw.o gwx.o $(LINK.c) $^ $(LOADLIBES) $(LDLIBS) -o '$@' +%.txt: % + $(nroff) -man -Tascii $(nroff_txt_flags) $< | col -b | cat -s > $@ + +%.pdf: % + $(groff) -man -Tpdf $(groff_pdf_flags) $< > $@ + +%.html: % + $(groff) -man -Thtml $(groff_html_flags) $< > $@ + + $(TARBALLGZ): $(tar_files) tar -czP \ --transform='s:^$(top_dir)/::' \ diff --git a/dmk2gw.1 b/dmk2gw.1 new file mode 100644 index 0000000..b2e87b0 --- /dev/null +++ b/dmk2gw.1 @@ -0,0 +1,455 @@ +.TH dmk2gw 1 +.SH NAME +dmk2gw \- Write a DMK archive file to a floppy disk using a Greaseweazle +.SH SYNOPSIS +.B dmk2gw [options] filename.dmk +.SH DESCRIPTION +The \fBdmk2gw\fP program uses a Greaseweazle universal floppy disk +controller to write a disk archive file in DMK format to a physical +floppy disk. + +\fBdmk2gw\fP can write all floppy disk formats that can be written +by the Western Digital 177x/179x floppy disk controllers used in +the original TRS-80 machines and all formats that can be written by +the NEC 765-compatible floppy disk controllers used in PCs. Even +formats that mix FM (single density) and MFM (double/high density) +on the same track can be written. + +\fBdmk2gw\fP has also been extended to write Digital Equipment +Corporation\[aq]s RX02 format, and some support for UDOS, CZ-MDOS, and +CZ-SDOS formats written by Mikroelektronik M\(:uhlhausen U8xxx FDCs. + +\fBdmk2gw\fP by default guesses the drive type and disk format to +be written by measuring the rotational speed of the drive (300 or +360 RPM) and checking the track length and other fields in the DMK +file. You can override these defaults with command line arguments +if needed. However, \fBdmk2gw\fP does not automatically double-step +if you are writing a 40-track disk in an 80-track drive. See the +\fB\-m\%\fP flag. Also, if you are using a single sided drive, see +the \fB\-s\%\fP flag. +.SH OPTIONS +.TP +.B \-G|\-\-device \fIname\fP +Specify the Greaseweazle\[aq]s device \fIname\fP. On Linux, this will +typically be a device under the \fB/dev\%\fP path. The default name is +\fB/dev/greaseweazle\%\fP. If not found, \fB/dev/ttyACM0\%\fP. +On Microsoft Windows, the device name defaults to \fBCOM3\fP. + +If you are unsure of your device\[aq]s name, run \fBgw\~info\%\fP and +use the string returned after \[lq]Port:\[rq]. +.TP +.B \-d|\-\-drive \fIunit\fP +Specify the drive unit number. + +If your drive is connected via an IBM PC bus (flat cable with +twist), use \fBa\fP or \fBb\fP. For a Shugart bus (straight-through +flat cable), use \fB0\fP, \fB1\fP, or \fB2\fP. +.TP +.B \-v|\-\-verbosity \fIlevel\fP +Specify how much output is printed. Larger levels select more +output. The default level is 1. + +Possible values for \fIlevel\fP: +.RS +.TP +0 +No output. +.TP +1 +Print progress information. +.TP +2 +Also dump the bytes from the DMK file being encoded for the device. + +When the encoding changes, print a character in angle brackets to show +the new encoding: +.RS +.TP +F +FM data byte(s) +.TP +I +An FM Index Address Mark (IAM) +.TP +A +FM ID (IDAM) or Data Address Mark (DAM) +.TP +M +MFM data byte(s) +.TP +J +MFM pre-index address mark +.TP +B +MFM pre-data or pre-ID address mark +.TP +X +RX02-modified MFM data +.RE + +.RS +Output a newline before each address mark encoding. Output a +\(oq|\(cq after the last byte of valid data for a sector, counting +the sector CRC and any extra bytes specified by quirks. +.RE +.TP +3 +Also dump the DMK bytes being written, prefixing each with the +encoding used. This option argument is primarily for debugging +purposes. +.TP +4 +Like 2, but also dump the Greaseweazle\[aq]s samples generated for each +byte. This option argument is primarily for debugging purposes. +.RE +.TP +.B \-k|\-\-kind \fIdrivetype\fP +Specify the type of drive and type of media in use. + +This option is generally not needed, as \fBdmk2gw\fP should always +autorecognize the correct value. You can use it if you want to +eliminate the slight delay for autodetection, or in the special +case where you want to treat a 3.5-inch high density disk as +an 8-inch disk (ignoring the last 1/6 of each track) by giving +the \fB\-k\~3\%\fP option where \fB\-k\~4\%\fP would have been the +autorecognized value. + +Possible \fIdrivetype\%\fP values: +.RS +.TP +1 +5.25-inch SD/DD disk in 1.2MB drive +.TP +2 +5.25-inch SD/DD disk in 360KB/720KB drive, or 3.5-inch SD/DD disk +.TP +3 +5.25-inch HD disk, or 8-inch SD/DD disk +.TP +4 +3.5-inch HD disk +.RE +.TP +.B \-m|\-\-steps {1,2} +Specify the step multiplier with a 1 or 2. The default step is 1. + +A step multiplier of 2 is used when writing a 40-track (or 35-track) +disk in an 80-track drive. + +If you set \fB\-m\~2\%\fP, you should bulk-erase the media first to +eliminate residual magnetization from the odd numbered tracks that +may cause problems when the disk is read in a 40-track drive. +.TP +.B \-s|\-\-sides {1,2} +Specifies the number of sides. The default is 2. + +Use \fB\-s\~1\%\fP if your physical floppy drive has only one head +(that is, if it can only write to side 0 of the disk). If you +forget to do this and the DMK file has space reserved for side +1 data (even if there are no valid sectors in that space), +\fBdmk2gw\fP will overwrite the side 0 data on each track of the +media with the side 1 data. +.TP +.B \-T|\-\-stepdelay \fIstep_time\fP[,\fIsettling_time\fP] +Time in milliseconds to delay after each step pulse (sometimes +called \[lq]step rate\[rq]), and additional time to delay +after the last step pulse (head settling time). The comma and +\fIsettling_time\%\fP value are optional. + +The defaults are 10ms step time and 15ms settling time, or the +values as configured into the Greaseweazle. Use \fBgw\~delays\%\fP +to check those values. + +If your drive has difficulty stepping, try a slower step rate. If +you often see errors on the first sector or first few sectors of a +track, especially when reading with \fB\-\-nohole\%\fP, or if you know +your drive requires it, add some additional head settling time. +.TP +.B \-u|\-\-logfile \fIfilename\fP +Specify the \fIfilename\%\fP for logging output. The default is not +to log to a file unless you give a two-digit \fB\-v\%\fP option. + +If you give a two-digit \fB\-v\%\fP option and do not give the +\fB\-u\%\fP option, the default logfile name is formed by stripping +any extension off the DMK file name and appending \fB.log\%\fP. + +If you give the \fB\-u\%\fP option with a one-digit \fB\-v\%\fP option, +the same output is logged to the file and to the screen. +.TP +.B \-U|\-\-gwlogfile \fIfilename\fP +Specify the \fIfilename\%\fP to capture communication with the +Greaseweazle device in text form. The default is not to log any +communication with the Greaseweazle. +.TP +.B \-\-[no]reset +Reset the Greaseweazle (or not) on start up of \fBgw2dmk\fP. +Default is to reset. + +If some Greaseweazle parameters are manually set by running +\fBgw\fP and don\[aq]t want those settings undone by \fBdmk2gw\fP +on reset, suppress the reset operation with \fB\-\-noreset\%\fP. +.P +The remaining options usually do not need to be changed from their +default values. +.TP +.B \-p|\-\-precomp \fIplo[,phi]\fP +Specifies the number of nanoseconds to advance or retard transitions +for write precompensation. The default is 140ns. + +If one value is given, the same precompensation is used on all +tracks. If a comma-separated pair of values are given, \fIplo\fP +is used for track 0 and \fIphi\fP for the highest track, with tracks +between interpolated linearly. + +The actual distance between transitions is always rounded to +a multiple of the Greaseweazle clock period, so making finer +adjustments are not worthwhile. + +For more information, see \[lq]Precompensation Further +Explanation\[rq] in the \fBNOTES\fP section. +.TP +.B \-h|\-\-hd {1,2,3,4} +Controls pin 2 on the floppy drive bus setting it for media type, +high-density (logic 0) or double-density (logic 1). The default +is 4. + +For \fB\-h\~0\%\fP or \fB\-h\~1\%\fP set the HD line to the +indicated value. + +For \fB\-h\~2\%\fP, set the HD line to 0 for tracks 0 to 43 and to 1 +for tracks greater than 43. + +For \fB\-h\~3\%\fP, set the HD line to 1 for tracks 0 to 43, to 0 +for tracks greater than 43. + +For \fB\-h\~4\%\fP (the default), the line is set according +to the disk kind (\fB\-k\%\fP flag), 0 for \fB\-k\~1\%\fP and +\fB\-k\~2\%\fP or to 1 for \fB\-k\~3\%\fP and \fB\-k\~4\%\fP. + +This pin is only used on high-density drives. The pin is not +connected on single- or double-density drives. + +On high-density drives, setting this pin while reading often has +little to no use, but in some situations, may still be handy. + +Some high-density drives while reading may enable additional data +separation circuitry for the matching media. While some dual-speed, +high-density drives may use the pin to control switching between 300 +and 360 RPM. + +Often high-density drives have a jumper that inverts the logic of +this pin both for density type and RPM. You may want to check +your drive\[aq]s manual, and if it has such a jumper, ensure it is +strapped appropriately. +.TP +.B \-l|\-\-len \fIvalue\fP +Causes \fBdmk2gw\fP to ignore any data beyond the first \fIvalue\fP +bytes in the DMK file of each track. This option is applied before +\fB\-g\%\fP or \fB\-i\%\fP. It has no effect if len is greater than +the track data length recorded in the DMK file. +.TP +.B \-g|\-\-ignore \fIvalue\fP +Causes \fBdmk2gw\fP to ignore the first \fIvalue\fP bytes in the +DMK file of each track. If \fIvalue\fP is negative, an extra +\-\fIvalue\fP bytes of padding are inserted at the beginning of each +track. +.TP +.B \-i|\-\-ipos \fIvalue\fP +Causes \fBdmk2gw\fP to force the first IAM (Index Address Mark) +encountered on each track to be exactly \fIvalue\fP bytes from the +physical start of the track, by ignoring bytes or adding padding at +the start of the track as with the \fB\-g\%\fP flag. + +The default of \fB\-1\%\fP disables this feature. Instead, it +records the gap exactly as in the DMK file. Note that if you set +\fBvalue\%\fP too small, there will not be enough bytes in the +initial gap for the IAM to be recognized when the disk is read. +.TP +.B \-\-[no]reverse +If \fB\-\-reverse\%\fP is given, \fBdmk2gw\fP reverses the sides of +the disk. That is, it writes side 0 of the DMK file to physical +side 1 of the disk and side 1 of the DMK (if any) to physical side 0 +of the disk. The default is to not reverse the sides. + +This option may be useful if you want to write a separate 1-sided +DMK file to each side of a disk in a double-side drive. You +can do this by running \fBdmk2gw\fP twice, once writing with +head 0 using \fB\-s\~1\~\-r\~0\%\fP, then with head 1 using +\fB\-s\~1\~\-r\~1\%\fP. +.TP +.B \-f|\-\-fill \fIvalue\fP +If the track data being written (after possibly being shortened by +the options above) is not sufficient to fill the physical track, +\fBdmk2gw\fP writes the rest of the physical track with a fill +pattern. The default fill value is 0. + +Fill values and their meanings: +.RS +.RS +.TP +0 +If the last data byte written was FM or RX02 encoded, the +fill pattern is 0xff. If MFM, the pattern ix 0x4e. +.TP +1 +Erases the remainder of the track and writes nothing. +.TP +2 +A sequence of very long transitions, which also effectively erases +the remainder of the track. +.TP +3 +No fill, the Greaseweazle stops writing leaving whatever was +left on the track untouched. +.TP +0x1\fInn\fP +The fill pattern is 0x\fInn\fP encoded in FM. +.TP +0x2\fInn\fP +The fill pattern is 0x\fInn\fP encoded in MFM. +.RE +.RE +.TP +.B \-a|\-\-rateadj \fIvalue\fP +Causes dmk2gw to multiply the average data rate by \fIvalue\fP +(default 1.0). Values should be close to 1.0. For example, 1.005 +makes the data rate 0.5% faster, while 0.995 makes it 0.5% slower. + +Making the data rate 1% faster has a similar effect to running the +drive motor 1% slower: more data fits on the track. Of course if +the data rate is adjusted to be too far off from the standard value, +the resulting disk may not be readable. +.TP +.B \-\-[no]dither +If dithering (\fB\-\-dither\%\fP), \fBdmk2gw\fP adjusts the number +of Greaseweazle clock ticks in the intervals between transitions by ++/-1 when needed to keep the average data rate accurate. + +If not dithering (\fB\-\-nodither\%\fP) (the default), no such +adjustment is done. As a result, the interval sizes are consistent +across the whole track, but the average data rate may be off +(typically by much less than 1%) because of cumulative rounding +error. + +If a disk needs the \fB\-a\%\fP option to adjust the average data +rate very precisely, turning on dither too may help. Using this +feature, it is not yet clear whether it is an improvement or whether +the occasional +/\-1 tick will make disks more difficult to read. +.TP +.B \-\-[no]gwdebug +With this option enabled, file names of the format +\fBgwflux\-\fP\f[BI]nn\f[]\fB\-\fP\f[BI]m\f[]\fB.bin\%\fP are +created where \fInn\%\fP is the track number and \fIm\fP is the +side. The files store the raw flux stream as written to the +Greaseweazle. + +.TP +.B \-y \fItestmode\fP +Set various undocumented test modes for debugging. +.SH DIAGNOSTICS +Common fatal diagnostics: +.TP +.B Failed to find or initialize Greaseweazle. +The Greaseweazle device could not be found. You may need to +provide a \fB\-G\~\fP\fIdevicename\%\fP option. +.TP +.B dmk2gw: Cannot determine drive RPM. +You may need to provide a \fB\-d\~\fP\fIunit\%\fP option or check +for a floppy disk properly inserted into the drive. +.TP +.B dmk2gw: Failed to open DMK file '\fIfilename\fP': \fIreason\fP +The DMK file could not be opened successfully. See \fIreason\fP for +explanation. +.TP +.B dmk2gw: File '\fIfilename\fP' not in expected DMK format. +The DMK file was opened successfully, but a read from it failed. +.TP +.B dmk2gw: Failed to guess drive kind; use \-k. +This message is printed if drive/media autodetection fails. Either +the drive speed could not be measured, or the track length was not +one of the common values used in most DMK files. You can specify +the kind of drive and media in use with the \fB\-k\%\fP flag. +.TP +.B dmk2gw: Drive is 1\-sided, but DMK file is 2\-sided. This +message means that there is space reserved in the DMK file for two +sides, and some apparently valid data was found on side 1, but you +gave the \fB\-s\~1\%\fP flag to say that your disk drive is only +one-sided. +.SH NOTES +.SS Conversion from other archive formats to DMK +If you have a JV1 or JV3 archive file to write to disk, convert it +to a DMK archive file by using \fBjv2dmk\fP. +.SS Precompensation Further Explanation +The magnetic flux transitions on a floppy disk tend to move slightly +farther apart if they are recorded very close together, thus +lengthening the short intervals and shortening the long ones, a +phenomenon sometimes called bit-shifting. When a disk is recorded, +the disk controller ordinarily applies write precompensation to +reduce this effect; that is, it makes the short intervals extra +short and the long ones correspondingly longer, especially on the +inner, higher-numbered tracks. In \fBdmk2gw\fP, if the shortest +legal interval appears immediately to the left (or right) of a +longer one, the flux transition between them is moved to the left +(or respectively, right). + +In general, disks need more precompensation on the inner +(higher-numbered) tracks than on the outer tracks, and this effect +is more pronounced for larger disks where the difference in length +between the inner and outer tracks is greater. + +The default value of 140ns for all tracks seems to work reasonably +well on 3.5-inch and 5.25-inch disks, though it is likely not +optimal. + +For 8-inch disks, a few experiments with the \fBgwhist\fP program +suggest that \fB\-o\~70,700\%\fP is a good value. It makes tracks 1 +and 76 have much more similar histograms than if a constant value is +used. + +If you have trouble reading disks written by \fBdmk2gw\fP with a +regular floppy disk controller, try using \fBgwhist\fP to compare +track histograms of natively-written media that read successfully in +your controller with media written by \fBdmk2gw\fP. If there is a +substantial difference, try different \fB\-o\%\fP values to see if +you can get \fBdmk2gw\fP to write disks that are more similar to the +native disks. +.SH SEE ALSO +.SS Other related commands +.BR gw2dmk (1), +.BR gwhist (1) +.SS Greaseweazle +For more information about Greaseweazle controllers and other +software that works with them, see: +.EX +.RS 4 +.UR https://github.com/keirf/greaseweazle/wiki +.UE +.RE +.EE +.SS DMK floppy disk archive file format +For information about the DMK file format and the emulators that +use it, see: +.EX +.RS 4 +.UR https://www.trs\-80.com/wordpress/tips/formats/#dmk +.UE +.UR https://www.trs\-80.com/wordpress/intro\-to\-emulators/ +.UE +.RE +.EE +.SH AUTHORS +\fBdmk2gw\fP was written by +.UR https://github.com/qbarnes/ +Quentin Barnes +.UE +based on the \fBcw2dmk\fP utilities by +.UR https://tim\-mann.org/ +Tim Mann +.UE +\&. + +\fBgw2dmk\fP is free software released under the GNU General Public +License. + +Thanks to David Keil for designing and documenting the DMK file +format for archiving floppy disks. diff --git a/gw2dmk.1 b/gw2dmk.1 new file mode 100644 index 0000000..d35c88d --- /dev/null +++ b/gw2dmk.1 @@ -0,0 +1,947 @@ +.TH gw2dmk 1 +.SH NAME +gw2dmk \- Read a floppy disk using a Greaseweazle to a DMK archive file +.SH SYNOPSIS +.B gw2dmk [options] filename.dmk +.SH DESCRIPTION +\fBgw2dmk\fP utilizes a Greaseweazle universal floppy disk +controller to read disks and save their contents to files in DMK +format, originally used by some TRS-80 emulators. The DMK file +format precisely represents the disk, including sector positioning, +spacing, and gap contents, enabling accurate reproduction of many +disks, including some with copy-protection. + +\fBgw2dmk\fP supports reading all formats written by Western Digital +177x/179x floppy disk controllers used in the original TRS-80 +machines, all formats written by NEC 765-compatible floppy disk +controllers used in PCs, and the Digital Equipment Corporation RX02 +format. + +\fBgw2dmk\fP automatically recognizes most variations of drive kind +and disk media format, but its autodetection can be overridden with +command line arguments; see \fBOPTIONS\fP. Detection of FM (single +density) or MFM (double/high density) encoding works even for disks +that have both types of encoding within the same track, such as +disks that were made to dual boot on both TRS-80 Models I and III. +.SH OPTIONS +.TP +.B \-G|\-\-device \fIname\fP +Specify the Greaseweazle\[aq]s device \fIname\fP. On Linux, this will +typically be a device under the \fB/dev\fP path. The default name is +.nh +\fB/dev/greaseweazle\%\fP. +.hy +If not found, +.nh +\fB/dev/ttyACM0\%\fP. +.hy +On Microsoft Windows, the device name defaults to \fBCOM3\fP. + +If you are unsure of your device\[aq]s name, run \fBgw\~info\%\fP +and use the string returned after \[lq]Port:\[rq]. +.TP +.B \-d|\-\-drive \fIunit\fP +Specify the drive unit number. + +If your drive is connected via an IBM PC bus (flat cable with +twist), use \fBa\fP or \fBb\fP. For a Shugart bus (straight-through +flat cable), use \fB0\fP, \fB1\fP, or \fB2\fP. +.TP +.B \-v|\-\-verbosity \fIlevel\fP +Specify how much output is printed. Larger levels select more +output. The default level is 2. + +Different levels of output can be logged to the logfile and to the +screen (i.e., stdout) by giving a two-digit number. The first digit +specifies how much output to log to the logfile and the second how +much to log to the screen. +.RS +.TP +0 +No output. +.TP +1 +Print a summary at the end of conversion. +.TP +2 +Also print the number of good sectors and errors on each track. +When a retry is needed, print the number of errors on the previous +try and the retry number. +.TP +3 +Also print the sector numbers, plus a short message in brackets when +an error is encountered or the FM/MFM/RX02 encoding detector switches +state. +.TP +4 +Also print the track\[aq]s IDAMs (ID Address Marks) and DAMs (Data +Address Marks). +.TP +5 +Also print all data in hexadecimal. Print \[lq]{\[rq] and +\[lq]}\[rq] to indicate where the index hole sensor went on and off. +Print \[lq](\-\fIN\%\fP)\[rq] or \[lq](+\fIN\%\fP)\[rq] where the +decoder dropped or duplicated \fIN\fP clock/data bits in an attempt +to resynchronize itself with the data bit and byte boundaries. +Print a \[lq]?\[rq] before any byte where a clock was missing or +unexpectedly present even after the resynchronization heuristics +were applied. +.TP +6 +Like 4, but also print the data as raw characters. +.TP +7 +Like 5, but also print the histogram generated when autodetecting +the drive and media type, and print each Greaseweazle sample and +its classification as tiny (t), short (s), medium (m), or long +(l). Enclose the decoded hexadecimal data bytes in angle brackets +(\[lq]<\~>\[rq]) to distinguish them from the samples. +.RE +.TP +.B \-u|\-\-logfile \fIfilename\fP +Specify the \fIfilename\fP for logging output. The default is not +to log to a file unless you give a two-digit \fB\-v\fP option. +If you give a two-digit \fB\-v\fP option and do not give the +\fB\-u\fP option, the default logfile name is formed by stripping +any extension off the DMK file name and appending \fB.log\fP. + +If you give the \fB\-u\fP option with a one-digit \fB\-v\fP option, +the same output is logged to the file and to the screen. +.TP +.B \-U|\-\-gwlogfile \fIfilename\fP +Specify the \fIfilename\fP to capture communication with the +Greaseweazle device in text form. The default is not to log any +communication with the Greaseweazle. +.TP +.B \-R|\-\-replay \fIfilename\fP +\fB[Feature currently unavailable.]\fP + +Replay a level 7 verbosity logfile instead of reading a new disk +from the Greaseweazle. This option can be useful to retry decoding +a disk using different command line options, without physically +rereading the disk. First capture a logfile at verbosity level 7 +using the \fB\-v\%\fP and \fB\-u\%\fP options. Then run \fBgw2dmk\fP +as many times as desired, using the \fB\-R\fP option to replay +the logfile, together with other command line options as desired. +The \fB\-k\%\fP option is always required with \fB\-R\%\fP, and the +\fB\-\-nohole\%\fP option generally should be used if the +original capture was performed with \fB\-\-nohole\%\fP, while the +\fB\-m\%\fP, \fB\-T\%\fP, \fB\-M\%\fP, \fB\-d\%\fP, \fB\-a\%\fP, +\fB\-\-reverse\%\fP, and \fB\-x\%\fP options are not allowed. +.TP +.B \-M|\-\-menu {i,e,d} +Controls interactive menu mode through using \fBi\fP, \fBe\fP, +or \fBd\fP option-arguments. + +Possible letters for \fB\-M\%\fP: +.RS +.TP +i +Enables the menu when the interrupt key is pressed, typically +\fB^C\%\fP. +.TP +e +Enables the menu when the number of retries due to errors from +reading the current track has been reached. +.TP +d +Disables any enabled menu modes (default). +.RE +.P +When the menu is invoked, \fBgw2dmk\fP will pause reading the +current floppy disk and present a menu with the actions: +.RS +.TP +c +Continue reading without change. +.TP +q +Abandon reading and quit the program (^C while at the menu prompt +also does the same action). +.TP +r +Prompt to change the number of retries (allows changing +\fB\-x\%\fP\[aq]s value on-the-fly). +.TP +g +Give up attempting to reread the current track, accept the data +as read, and move on to the next track or side. (Choice does not +appear when the current track being read has no errors.) +.RE +.P +The remaining options are usually not needed. \fBgw2dmk\fP will +ordinarily detect or guess the correct values. +.TP +.B \-k|\-\-kind \fIdrivetype\fP +Specify the type of drive and type of media in use. This option is +generally not needed, as \fBgw2dmk\fP should always autorecognize +the correct value. You can use it if you want to eliminate the +slight delay for autodetection, or in the special case where you +want to treat a 3.5-inch high density disk as an 8-inch disk +(ignoring the last 1/6 of each track) by giving the \fB\-k\~3\fP +option where \fB\-k\~4\%\fP would have been the autorecognized value. + +Possible \fIdrivetype\fP values for \fB\-k\%\fP: +.RS +.TP +1 +5.25-inch SD/DD disk in 1.2MB drive +.TP +2 +5.25-inch SD/DD disk in 360KB/720KB drive, or 3.5-inch SD/DD disk +.TP +3 +5.25-inch HD disk, or 8-inch SD/DD disk +.TP +4 +3.5-inch HD disk +.RE +.TP +.B \-m|\-\-steps {1,2} +Step multiplier, 1 or 2. A step multiplier of 2 is used when +reading a 40-track (or 35-track) disk in an 80-track drive. + +If this option is not given, \fBgw2dmk\fP guesses a likely value +and checks its guess by trying to read the first few tracks. If +the guess appears wrong, \fBgw2dmk\fP will use the other step +multiplier instead. + +Giving this option will speed up \fBgw2dmk\fP slightly by +eliminating the time to check the guess, and will remove the +small possibility that the guess is wrong even after having been +checked. This may occur with copy-protected disks that have +nonstandard track numbers. The initial guess step is 2 if the +drive/media type (\fB\-k\%\fP option) is set or autodetected to be a +\fIdrivetype\%\fP of 1; otherwise the initial guess step is 1. +.TP +.B \-t|\-\-tracks \fIcount\fP +Specifies the number of tracks per side. + +If this option is not given, \fBgw2dmk\fP will guess 44 if the +\fB\-m\%\fP option is set (or guessed) to be 2, otherwise 88. + +If \fBgw2dmk\fP is operating with a guessed value for \fB\-t\%\fP, +and the next track after one of the more likely ending places (35, +40, 77, or 80 tracks) has no valid sectors or has the same logical +track number as the previous track, it will lower its guess and +immediately stop reading at that point. +.TP +.B \-s|\-\-sides {1,2} +Specifies the number of sides. + +If this option is not given, \fBgw2dmk\fP will guess 2 sides if +the second side appears to be formatted, then revise its guess to +1 side if there are no valid sectors on the first track or two of +the second side. Giving the \fB\-s\~1\%\fP option explicitly for a +single-sided disk will save the time needed for this autodetection. +.TP +.B \-T|\-\-stepdelay \fIstep_time\fP[,\fIsettling_time\fP] +Time in milliseconds to delay after each step pulse (sometimes +called \[lq]step rate\[rq]), and additional time to delay +after the last step pulse (head settling time). The comma and +\fIsettling_time\%\fP value are optional. + +The defaults are 10ms step time and 15ms settling time, or the +values as configured into the Greaseweazle. Use \fBgw delays\%\fP +to check those values. + +If your drive has difficulty stepping, try a slower step rate. If +you often see errors on the first sector or first few sectors of a +track, especially when reading with \fB\-\-nohole\%\fP, or if you +know your drive requires it, add some additional head settling time. +.TP +.B \-\-hd|\-\-dd +Controls pin 2 on the floppy drive bus for controlling media type, +high-density (logic 0) or double-density (logic 1). If neither +option is provided, \fBgw2dmk\fP will make a best guess from drive +kind and media type. + +This pin is only used on high-density drives. The pin is not +connected on double-density drives. + +On high-density drives, setting this pin while reading often has +little to no use, but in some situations, may still be handy. + +Some high-density drives while reading may enable additional data +separation circuitry for the matching media. While some dual-speed, +high-density drives may use the pin to control switching between 300 +and 360 RPM. + +Often high-density drives have a jumper that inverts the logic of +this pin both for density type and RPM. You may want to check +your drive\[aq]s manual, and if it has such a jumper, ensure it is +strapped appropriately. +.TP +.B \-\-[no]compat +Controls whether the sides of track 0 are compared for incompatible +formats. The option \fB\-\-nocompat\%\fP disables the comparison +where \fB\-\-compat\%\fP enables it (default). + +If side 1 of track 0 has 512-byte sectors, but side 0 has any other +sector size, the read is restarted as single-sided. This often +happens when a 5.25-inch floppy disk came pre-formatted from its +factory for MS-DOS but was later reformatted in a single-sided drive +by another OS for its use. +.TP +.B \-\-[no]reset +Reset the Greaseweazle (or not) on start up of \fBgw2dmk\fP. +Default is to reset. + +If some Greaseweazle parameters are manually set by running \fBgw\fP +and you don\[aq]t want those settings undone by \fBgw2dmk\fP on +reset, suppress the reset operation with \fB\-\-noreset\%\fP. + +.TP +.B \-\-[no]force +When \fBgw2dmk\fP starts up, it checks to ensure that the DMK file +argument doesn\[aq]t already exist. If it does, it immediately +quits with an error. That way it won\[aq]t accidentally overwrite +the file. The default is \fB\-\-noforce\%\fP. + +If the contents of the DMK file are unimportant, the check can be +disabled with \fB\-\-force\%\fP, and \fBgw2dmk\fP will overwrite the +DMK file. +.TP +.B \-\-[no]dmkopt +When \fBgw2dmk\fP goes to write out the DMK file, it will select +a pre-set DMK track size based on drive kind and media type. +Default is \fB\-\-nodmkopt\%\fP. + +If \fB\-\-dmkopt\%\fP is enabled, \fBgw2dmk\fP will select the +smallest DMK track size that will store all the tracks\[aq] +information. + +Why \fB\-\-dmkopt\%\fP isn\[aq]t enabled by default is because some +emulators make assumptions about the DMK\[aq]s drive format type +based on hard-coded lookups of DMK track size. If those values vary +by even a byte, that may break some emulators, so pre-set values +are used by default. +.TP +.B \-w|\-\-fmtimes {1,2} +Normally, FM bytes are written into the DMK file twice +(\fB-w\~2\%\fP), so that they take up the correct proportion of the +space on mixed-density tracks. You can set \fB-w\~1\%\fP to cause +FM bytes to be written only once. This does not save space in the +DMK file unless you also reduce the track length with the \fB-l\%\fP +option. +.TP +.B \-e|\-\-encoding {1,2,3} +Overrides the normal FM/MFM/RX02 autodetection. + +To try only FM decoding, specify \fB-e\~1\%\fP; to try only MFM, +specify \fB-e\~2\%\fP; to try only RX02, specify \fB-e\~3\%\fP. + +Using this option does not speed up \fBgw2dmk\fP appreciably; +however, it can help on noisy disks where the decoder occasionally +makes an error while looking for all three possible encodings. +.P +The following are special options for dealing with hard to read +disks: +.TP +.B \-\-[no]join +Join sectors between retries. Enabled by default. + +When enabled in the case of errors, \fBgw2dmk\fP will re-use good +sector reads from previous attempts to replace corresponding bad +sectors in the current read attempt. This allows \fBgw2dmk\fP to +recover a track even if it can never fully read all the sectors in a +single pass. However, this option may not work reliably for some +copy protected disks or when a track\[aq]s sectors are too degraded. +.TP +.B \-S|\-\-minsectors \fImin_sectors\fP +This option specifies the minimum number of sectors per track that +must be seen before continuing to the next track. + +This option is only useful when a sector is completely missed +without also triggering an error. For this to occur, the IDAM +and DAM for a given sector both must be misread. + +The \fImin_sectors\%\fP argument can be just a number or optionally +a comma-separated list of track ranges. See section \fBLIST OF +TRACKS AND SIDES\fP for more information. + +If more or fewer sectors are encountered during a track read than +are anticipated by this option, a fractional sector number is +reported with the denominator being the minimum sector value for +that track\[aq]s read (e.g. \[lq]9/10\[rq] or \[lq]19/18\[rq]). +.TP +.B \-x|\-\-maxretries \fImax_retry\fP +While reading a track, \fBgw2dmk\fP tries to recognize sector IDs +and sector data, and it checks that each ID has a corresponding +sector and that both have correct CRCs. If any of these checks +fail, \fBgw2dmk\fP will try reading the track again, up to the +number of additional times specified by this option. The default +value is 4. + +If you have an old disk with CRC errors, increasing the number of +retries to a large value may still allow the disk to be read. If +you have a copy-protected disk with intentional CRC errors, or other +strange formatting that \fBgw2dmk\fP interprets as a possible error, +you might want to reduce or eliminate the retries to speed up the +conversion. + +The \fImax_retry\%\fP argument can be just a number or optionally a +comma-separated list of track ranges. See section \fBLIST OF TRACKS +AND SIDES\fP for more information. +.TP +.B \-X|\-\-minretry \fImin_retry\fP +This option asks \fBgw2dmk\fP to retry reading a track at least the +given minimum number of times, even if the track was decoded with +no detected errors. Except in replay mode, however, the number +of retries is still limited by the track\[aq]s \fImax_retry\%\fP +value as specified by the \fB\-x\%\fP option. The \fImin_retry\%\fP +argument accepts the same syntax as the \fImax_retry\%\fP argument. +The default value is 0. + +This feature can be useful when gathering a level 7 verbosity log +for later replay, in order to be sure that each track is captured +multiple times. +.TP +.B \-a|\-\-alternate {0,1,2,3} +This option is used only when when reading a 40-track disk in +an 80-track drive (\fB-m\~2\%\fP). + +If \fB-a\%\fP is set to 0 (the default), \fBgw2dmk\fP reads from +the even-numbered head positions, skipping the odd-numbered ones. +That is, disk track \fIn\fP is read from head position 2\fIn\%\fP. +Occasionally, more data may be recoverable by reading at the next +higher head position. + +If you set \fB\-a\%\fP to 1, \fBgw2dmk\fP will always read at odd +positions (2\fIn\fP+1). If \fB\-a\%\fP is 2 or 3, \fBgw2dmk\fP will +alternate between even and odd positions when retries are needed to +read a track, trying even positions first if \fB\-a\%\fP is 2; odd +if \fB\-a\%\fP is 3. +.TP +.B \-p|\-\-postcomp \fIvalue\fP +If you have a disk that shows a lot of CRC errors, you can try +re-reading it with different values for this parameter. The default +is 0.5. Try larger values if errors occur mostly on high-numbered +tracks, smaller values if errors occur on lower-numbered tracks or +all tracks. Values must be between 0.0 and 1.0. + +See \[lq]Postcompensation and magnetic flux\[rq] in section +\fBNOTES\fP for further information. +.TP +.B \-\-[no]hole +If hole is enabled (the default), \fBgw2dmk\fP uses the disk\[aq]s +index hole to determine where each track starts. If hole is +disabled (\fB\-\-nohole\%\fP), \fBgw2dmk\fP reads disks without +using the index hole. + +With \fB\-\-nohole\fP, the tracks in the DMK file will not start +with the same sector as on the original disk. Instead, each +track will start 48 bytes before the ID address mark (IDAM) of +the first sector that \fBgw2dmk\fP happens to read on the media. +Alternatively, if the tracks have an index address mark (IAM), the +\fB\-i\%\fP option (see below) can be used to position the track +start relative to the IAM. + +Note that if a disk actually has no index hole, \fBgw2dmk\fP +cannot autodetect the drive kind and media type, so you must +give the \fB\-k\%\fP option to specify the type as well as giving +\fB\-\-nohole\%\fP. + +For an additional use of the \fB\-\-nohole\%\fP option with flippy +disks in a custom modified drive, see \[lq]Flippy Disks\[rq] in +section \fBNOTES\fP. +.TP +.B \-g|\-\-ignore \fIcount\fP +Causes \fBgw2dmk\fP to ignore the first \fIcount\fP bytes decoded on +each track. If \fIcount\fP is negative, an extra \-count bytes of +padding are inserted at the beginning of each track. +.TP +.B \-i|\-\-ipos \fIcount\fP +If this option is given, \fBgw2dmk\fP forces the first IAM (index +address mark) encountered to be exactly \fIcount\fP bytes from the +physical start of the track by ignoring bytes or adding padding at +the start of the track as with the \fB-g\%\fP option. The default +value is \[lq]\-1\[rq], which disables this feature. + +This feature can be useful in conjunction with the +\fB\-\-nohole\%\fP option. If your disk was originally formatted +with an IAM at the start of each track, \fBgw2dmk\fP can start +the tracks at the same point in the DMK file, even though the +\fB\-\-nohole\%\fP option keeps it from being able to use the +physical index hole to find the start. For this purpose, +\fB-i\~96\%\fP is a good value to make sure that gap0 (the pre-IAM +gap) is large enough to meet the IBM format spec. Use a smaller +value if \fB-i\~96\%\fP causes the last sector of some tracks to be +partially cut off. + +This feature can also be useful to reproduce certain copy-protected +disks exactly. Some copy-protection schemes work only if the data +is precisely positioned on the physical track. If you have this +problem, you may need to experiment with different values for the +\fB-i\%\fP or \fB-g\%\fP options. +.TP +.B \-z|\-\-maxsize \fIvalue\fP +Changes the maximum value expected for IBM-compatible sector size +codes. + +This option does not affect the actual data that is read from the +disk and written to the DMK file. It only affects the CRC checking +and error retry algorithm described under the \fB-x\%\fP option +above. + +The default value is correct for disks that were written by Western +Digital WD177x/179x controllers used in TRS-80s. On most of these +controllers, only the two low-order bits of the code are ever +significant, and the sector size is given by 128 << (code & 3). On +the 1771, there is also an optional \[lq]non-IBM\[rq] feature that +can be selected when a sector is read or written. When this feature +is used, the sector size is given by 16 * code (or 16 * 256 if code +is zero). + +As a heuristic, \fBgw2dmk\fP assumes the non-IBM feature was used +if a sector is recorded in FM (single density) and its size code +is more than \fIvalue\fP. In contrast, with NEC765-compatible +floppy disk controllers as used in PCs, the sector size is given by +128 << (code & 7). Thus if you have a disk written by a PC with +sectors larger than 1024 bytes, setting \fIvalue\fP to 7 will allow +\fBgw2dmk\fP to correctly determine the sector sizes and avoid +reporting false CRC errors. +.TP +.B \-\-[no]reverse +If \fB\-\-reverse\%\fP, \fBgw2dmk\fP reverses the sides of the disk; +that is, it reads side 0 of the DMK file from physical side 1 of +the disk and side 1 of the DMK (if any) from physical side 0 of the +disk. The default is \fB\-\-noreverse\%\fP, which does not reverse +the sides. + +This option is most likely to be useful if you have a disk +that was recorded in a double-sided drive with a separate +single-sided filesystem on each side. Reading such a disk +twice, once with \fB\-s\~1\~\-\-noreverse\%\fP and once with +\fB-s\~1\~\-\-reverse\%\fP, gives you a separate 1-sided DMK file of +each side of the disk. (Note: this option is not useful for reading +the back of a flippy disk; see the \fB\-\-nohole\%\fP option.) + +.TP +.B \-q|\-\-quirks \fIvalues\fP +Enable support for various format quirks. So far, these quirks have +been observed only on UDOS and CZ-SDOS disks; see \fBLIMITATIONS\fP. + +To enable multiple quirks, add the values together. The value can +be given either in hex with a 0x prefix or in decimal. For example, +\fB\-q\~17\%\fP enables quirks 1 and 16. The three QUIRK_EXTRA* +quirks are mutually exclusive. If any are given together, a fatal +error message will be displayed. +.RS +.TP +0x01 (1) QUIRK_ID_CRC +The ID CRCs are calculated without including the a1 a1 a1 premark +bytes. If this quirk is needed but not enabled (or enabled when not +needed!), \fBgw2dmk\fP will detect an ID CRC error on every sector. +.TP +0x02 (2) QUIRK_DATA_CRC +The data CRCs are calculated without including the a1 a1 a1 premark +bytes. If this quirk is needed but not enabled (or enabled when not +needed!), \fBgw2dmk\fP will detect a data CRC error on every sector. +.TP +0x04 (4) QUIRK_PREMARK +In the a1 a1 a1 premark, possibly only the first two bytes have +a missing clock. If this quirk is needed but not enabled, +\fBgw2dmk\fP will fail to detect some ID address marks and/or data +address marks. If this quirk is enabled when not needed, there is a +very small chance it could lead to a problem where an address mark +is falsely detected and \fBgw2dmk\fP reports it as an error. +.TP +0x08 (8) QUIRK_EXTRA +Immediately following the CRC of each data sector, there are some +extra, meaningful data bytes. This quirk prevents the extra bytes +from being damaged, by forbidding the decoder from resynchronizing +to apparent MFM 4e 4e or 00 00 byte sequences as expected in the +gap. As a result, the decoder generally will not resynchronize +until the a1 a1 a1 sequence preceding the next ID address mark, so +the gap bytes preceding it that should be 4e 4e... 00 00... are +likely to be decoded incorrectly. +.TP +0x10 (16) QUIRK_EXTRA_CRC +Immediately following the CRC of each data sector, there are four +extra, meaningful data bytes, followed by two extra CRC bytes that +cover the four extra data bytes. The extra CRC is checked and the +track read is retried if the CRC is invalid. Unlike with quirk +0x08, the decoder is allowed to resynchronize to apparent MFM 4e 4e +or 00 00 byte sequences following the extra CRC. +.TP +0x20 (32) QUIRK_EXTRA_DATA +Each sector has 4 more data bytes preceding the CRC than its size +code indicates. For example, if the size code indicates 128 bytes, +there are actually 132 data bytes, followed by a standard 2-byte CRC +that covers the data address mark and all 132 data bytes. +.TP +0x40 (64) QUIRK_IAM +A standard index address mark (IAM) in FM is the data value 0xfc +with a 0xd7 clock pattern. If this quirk is specified, \fBgw2dmk\fP +recognizes 0xfc with either a 0xd7 or 0xc7 clock pattern as an IAM. +.TP +0x80 (128) QUIRK_MFM_CLOCK +In general, floppy disk data is encoded as a stream of alternating +clock and data bit cells. With MFM encoding, a clock bit cell +should contain a 1 if and only if the data bit cells immediately +before and after it both contain 0. If this quirk is not specified, +\fBgw2dmk\fP makes a strong assumption that the MFM clocking rule +is not violated, and so it may fail to decode a disk that has +clock bits set to 1 that should be 0. If this quirk is specified, +\fBgw2dmk\fP relaxes that assumption and may successfully decode +such a disk. It is probably harmless to set this quirk even when +not needed, but that is mostly untested. +.RE +.P +The next few options modify individual parameters that are normally +set correctly by the \fB\-k\%\fP option (or by autodetection of the +correct value for the \fB\-k\%\fP option). These options can be +given only after the \fB\-k\%\fP option. To see the default values +for a particular disk kind \fIN\fP, type the command \fBgw2dmk\fP +\fB\-k\~\fP\f[BI]N\%\f[] with no other arguments; they will be shown +in brackets in the usage message. +.TP +.B \-1|\-\-mfmthresh1 \fIthreshold\fP +MFM threshold for short (10) vs. medium (100), in number of samples. +.TP +.B \-2|\-\-mfmthresh2 \fIthreshold\fP +MFM threshold for medium (100) vs. long (1000), in number of samples. +.TP +.B \-f|\-\-fmthresh \fIthreshold\fP +FM threshold for short (1) vs. long (10), in number of samples. +Used only in \fB\-e\~1\%\fP mode; in the default mode where encoding +is autodetected on the fly, FM samples must lie outside the range +between the two MFM thresholds to be decoded correctly. +.TP +.B \-\-[no]usehisto\fP +Enable the use of a histogram to automatically choose new values for +FM and MFM thresholds. The values used will be displayed in the log +at level 2 or higher. + +Use of \fB\-\-usehisto\%\fP will often result in a better (or same) +read of a disk. However, it is not enabled by default because on +some disks with a severely degraded side 0, track 0, it may chose +wild values resulting in a much worse read. +.TP +.B \-l \fIbytes\fP +DMK track length in bytes. The maximum is 0x4000 hex or 16384 +decimal. Note that \fBgw2dmk\fP uses this value as part of its +heuristic to determine when it has read one complete track and is +starting to see wraparound back to the start of the track. If the +DMK track buffer is more than 95% full and a sector with the same +header as the first sector on the track is seen again, \fBgw2dmk\fP +assumes it has wrapped around to the start of the track again and +stops reading. This heuristic will be defeated if you set the track +length to a huge value, so set it at most a few percent higher than +the default for the disk kind (\fB\-k\%\fP option) you are using. + +.SH LIST OF TRACKS AND SIDES +The options \fB\-S\%\fP, \fB\-x\%\fP, and \fB\-X\%\fP allow a +list of ranges giving tracks and sides. These ranges can be +straightforward for simple needs, but grow in complexity for more +intricate specifications. + +The list are always parsed from left to right with the later ranges +taking precedence. + +A track range always starts with the number to be used as the value +for the option and may be followed by an optional colon and track +and side ranges that the number applies to. + +The format of a track range is +.nh +\fBnumber[:{start\~track[/side][\-[end\~track[/side]]]}]\fP. +.hy + +Sides are specified with a \[aq]0\[aq] (front) or \[aq]1\[aq] (back). + +If a \fB\-\%\fP is given without an \fBend\~track\%\fP, the range is +for all remaining tracks. + +A track list may have multiple track ranges separated by commas. + +Some examples may make understanding the track list easier to +follow. +.RS 4 +.TP +\fB\-x 40\fP +Set the number of retries for all tracks and sides to 40. +.TP +\fB\-x 40,0:4-12\fP +Set the number of retries for all tracks and sides to 40, except +disable retries for tracks 4 through 12. +.TP +\fB\-x 10,20:30-,0:33/0\fP +Set retries for all tracks and sides to 10, except set to 20 for +tracks 30 through end of media, then disable retries for track 33 +side 0. +.TP +\fB\-x 15:27-30,80:35-\fP +Leave default retries (4) for all tracks and sides except set it to +15 for tracks 27 through 30, then set it to 80 for tracks 35 through +end of media. +.TP +\fB\-S 18,10:0/0 +Set the minimum number of sectors for all tracks and sides to 18, +except for track 0, side 0, make it 10. (Common for a Model 1 DSDD +disk.) +.TP +\fB\-X 5 +Set the minimum number of retries for all tracks and sides to 5. +.RE +.SH LIMITATIONS +Below are some cases where the results may not be correct unless an +additional command line option is given. + +If the disk has a defect but can be successfully read by using a +larger number of retries than normal, use the \fB\-x\%\fP option. + +If the disk is noisy, \fBgw2dmk\fP\[aq]s decoder may sometimes +misclassify a sample or even misdetect the encoding (FM, MFM, or +RX02), usually resulting in a CRC error or a missing sector. You +can sometimes work around this (especially for FM-only disks) by +using the \fB\-e\%\fP option to force only one encoding to be +considered. Another workaround that can help is the \fB\-o\%\fP +option. In rare cases, tweaking thresholds with the \fB\-1\%\fP, +\fB\-2\%\fP, and \fB\-f\%\fP options may help. The histogram +displayed by the \fB\-v\~7\%\fP option or the separate cwtsthst +program may help you find the best thresholds. + +If the disk was formatted with more than 44 tracks in a 40-track +drive, or more than 88 tracks in an 80-track drive, use the +\fB\-t\%\fP option. + +Double-stepping is used to read 35- or 40-track disks in an 80-track +drive. If a copy-protected disk has nonstandard track numbers that +fool \fBgw2dmk\fP when it tries to detect whether the drive needs to +be single or double-stepped, use the \fB\-s\%\fP option. + +If the TRS-80 program on a copy-protected disk does a Read Track +when it is run, and it expects the raw track data to be precisely +aligned, but the data comes out shifted a few bytes forward or +backward when read with the Greaseweazle, use the \fB\-g\%\fP or +\fB\-i\%\fP option. + +If the last sector on a track wraps around through the index +hole and extends too far past it, \fBgw2dmk\fP\[aq]s normal +\fB\-\-hole\%\fP reading strategy may cut off the end of it, +resulting in a CRC error. Using the \fB\-\-nohole\%\fP option may +take care of the problem. + +If the disk was made by a NEC765-compatible controller and has +sectors longer than 1024 bytes, use the \fB\-z\~7\%\fP option. + +If a disk has fewer tracks than \fBgw2dmk\fP guesses, reading will +sometimes continue past the last valid track. It is harmless for +extra tracks of garbage to be written to the end of the DMK file, +but if you know the correct number of tracks, you can use the +\fB\-t\%\fP option to force \fBgw2dmk\fP to stop at the right place. +Remember that track numbers start from zero, so (for example) giving +the option \fB\-t\~35\%\fP will cause tracks numbered 0 to 34 to be +read. + +Atari 800 floppy disk drives typically rotate at 288 RPM instead of +300 RPM, allowing for somewhat more data per track than standard +drives, and they write data to the disk without regard for the +position of the index hole. To read one of these disks with +\fBgw2dmk\fP in a standard floppy drive, give the \fB\-\-nohole\%\fP +option to ignore the index hole position, the \fB\-k\~1\%\fP or +\fB\-k\~2\fP option as needed to specify the kind of drive and media +in use, and the \fB\-l\%\fP 0x1A40 option to increase the DMK track +length. + +Various East German computers that used floppy disk controllers +built from discrete logic and that ran variants of the UDOS +operating system produce disks with nonstandard formats. See +.UR https://www.robotrontechnik.de/html/software/udos.htm. +.UE +To read these disks, use \fBgw2dmk\fP\[aq]s quirk support +(\fB\-q\%\fP option). UDOS disks generally have four extra bytes +of meaningful data for each sector. These bytes may either follow +the data CRC and have no CRC covering them (use QUIRK_EXTRA to +ensure the bytes are read correctly), follow the data CRC and have +their own CRC covering them (use QUIRK_EXTRA_CRC to ensure the +bytes are read correctly and their CRC is checked), or precede +the data CRC and are included in the data CRC\[aq]s coverage (use +QUIRK_EXTRA_DATA to avoid a data CRC error on every sector). Some +of the variants also have other nonstandard features that require +QUIRK_PREMARK, QUIRK_ID_CRC, and/or QUIRK_IAM. + +The following information is based on a small sample of UDOS +disks. It does not cover all UDOS variants and may not be +fully accurate, so try other combinations of quirks if these +don\[aq]t work: UDOS PRG v4 disks need \fB\-q\~0x0d\%\fP +(QUIRK_ID_CRC, QUIRK_PREMARK, QUIRK_EXTRA). UDOS 1526 v4 needs +only \fB\-q\~0x08\%\fP (QUIRK_EXTRA). UDOS 1526 v5 needs +\fB\-q\~0x0c\%\fP (QUIRK_PREMARK, QUIRK_EXTRA). CZ-SDOS needs +\fB\-q\~0x60\%\fP (QUIRK_EXTRA_DATA, QUIRK_IAM). Note: If you have +a version of UDOS where QUIRK_EXTRA_CRC works, it is preferable to +use it instead of QUIRK_EXTRA, so that \fBgw2dmk\fP will check the +extra CRC and retry if it shows an error. +.SH DIAGNOSTICS +.TP +.B \fBgw2dmk\fP: Failed to detect Greaseweazle +A Greaseweazle device was not detected. You may need to provide +a \fB\-G \fP\fIdevname\fP option. +.TP +.B \fBgw2dmk\fP: Failed to detect any drives +You did not specify a drive to use with the \fB\-d\~\fP\fIunit\%\fP +option, and no drives were detected. The track 0 sensor is used +to detect the presence of a drive, so you may get this message if +your drive has a broken track 0 sensor. In that case, use the +\fB\-d\%\fP option to select which drive to use. +.TP +.B \fBgw2dmk\fP: Drive d not detected; proceeding anyway +You specified a drive for \fBgw2dmk\fP to use with the \fB-d\%\fP +option, but it was not detected. The track 0 sensor is used to +detect the presence of a drive, so you may get this message for a +drive with a broken track 0. However, it\[aq]s more likely that the +specified drive number does not exist. Cabling and drive selection +can be confusing, so before giving up, try the other drive number or +leave out the -d option and let \fBgw2dmk\fP autodetect the drive +number. Note: In versions prior to 3.0, \fBgw2dmk\fP used the +opposite drive numbering convention from the bundled Greaseweazle +software supplied by Individual Computers. This has now been +corrected. +.TP +.B gw2dmk: Track 0 side 0 is unformatted +For drive/media autodetection to work, track 0 of the diskette must +be formatted. This message is printed if the track appears not to be +formatted. +.TP +.B gw2dmk: Failed to detect drive and media type +This message is printed if drive/media autodetection fails for some +unknown reason. The detector\[aq]s estimate of the data clock rate +and disk rotation speed are also printed; if they are wildly wrong, +the disk may be unformatted. +.TP +.B gw2dmk: Flux read failure: ... +.TQ +.B gw2dmk: Flux read failure: ... [Is diskette in drive?] +The Greaseweazle could not read flux from the drive. + +If no index hole was detected, \fBgw2dmk\fP will ask if the diskette +is in the drive. + +These messages usually mean that there is no disk in the drive. +They might also appear in some cases if the drive is not connected +properly, the door is not closed, the disk is inserted upside-down, +etc. + +If the disk really does not have an index hole -- in particular, +if you are reading the back of a disk that was written in a flippy +drive by inserting it upside-down into a normal drive (see the +\fB\-\-nohole\%\fP option) -- \fBgw2dmk\fP cannot autodetect the drive +and media type or if side 1 is formatted, so you will have to give +the \fB\-k\%\fP and \fB\-s\%\fP flags to tell it the correct type and +number of sides. +.TP +.B Possibly a flippy disk. Check reverse side too. +This message is not an error. It means that you are reading a disk +in a double-sided drive and \fBgw2dmk\fP detected there might be +\[lq]flippy\[rq] data on the back of the disk in addition to the +normal data on the front. \fBgw2dmk\fP cannot read all of this data +unless you flip the disk over (see the \fB\-\-nohole\%\fP option for +details), but it can usually read enough to detect that there is +some data present and print this message. +.SH NOTES +.SS DEC RX02 Disks +RX02 disks use a nonstandard encoding for double density. A +slight extension to the DMK format is used to represent them: Bit +5 (previously unused) is set in the DMK header\[aq]s options byte +(byte 4). The DMK double density flag (bit 15 of the IDAM pointer) +is not set for RX02 double density sectors on the grounds that only +the data and CRC are in MFM, not the ID, DAM, gap, etc. A program +reading a DMK with the RX02 option bit set should expect a sector to +contain twice as many valid data bytes as its sizecode indicates if +the sector\[aq]s DAM is 0xf9 (deleted RX02 MFM data) or 0xfd (normal +RX02 MFM data). Note that as with other disk types, FM bytes are +written to the DMK file twice unless you set the \fB-w\~1\%\fP option, +while MFM bytes are written only once. RX02 autodetection will fail +if the first track with RX02 sectors has only deleted data (0xf9 +DAMs). This is unlikely to occur, but using \fB\-e\~3\%\fP will work +around the problem if it does. +.SS Postcompensation and magnetic flux +The magnetic flux transitions on a floppy disk tend to move slightly +farther apart if they are recorded very close together, thus +lengthening the short intervals and shortening the long ones, a +phenomenon sometimes called bit-shifting. When a disk is recorded, +the disk controller ordinarily applies write-precompensation to +reduce this effect; that is, it makes the short intervals extra +short and the long ones correspondingly longer, especially on +the inner, higher-numbered tracks. Sometimes a disk is recorded +with too little write precompensation, or perhaps the bits shift +even more as the disk ages. + +With the \fB\-p\%\fP option, if \fBgw2dmk\fP observes that an +interval is longer or shorter than its nominal length, it will +assume that the interval\[aq]s ending transition moved slightly, +and will lengthen or shorten the next interval as a sort of +read-postcompensation. The deviation of each interval is multiplied +by \fIvalue\fP before being added to the next interval. +.SS \[lq]Flippy\[rq] Disks +Generally, a \[lq]flippy\[rq] disk is a disk that has a separate +single-sided format written on each side, where the format on the +back was written by flipping the disk over and reinserting it into +the drive upside-down. To accomplish this, the disk jacket either +had to have been modified with an extra index hole and write-protect +notch, or the disk had to have been written in a flippy disk drive +with double sensors. + +Unfortunately, you can't read a flippy-formatted disk using a +double-sided (two head) drive in a single pass. \fBgw2dmk\fP could +compensate for the disk rotating the opposite way, however, a more +serious limitation exists. With double-sided drives, their heads +for the back side are displaced by a few tracks (e.g. by 4 tracks +for 48 TPI drives). That means that their back side heads cannot +access those first few tracks of a flippy disk. + +For flippy disks with modified jackets, there is no problem. Just +flip the disk over and read the reverse side. With disks written +in a flippy drive, you can modify its jacket yourself by adding the +extra hole to its jacket with a hole punch. + +For those who are truly adventurous, you may also attempt to modify +your drive with the directions found here: +.UR http://icomp.de/man/flipside.html +.UE +\&. + +After modification, if still having trouble reading some diskettes, +using the \fB\-\-nohole\%\fP may help. +.SH SEE ALSO +.SS Other related commands +.BR dmk2gw (1), +.BR gwhist (1) +.SS Greaseweazle +For more information about Greaseweazle controllers and other +software that works with them, see: +.EX +.RS 4 +.UR https://github.com/keirf/greaseweazle/wiki +.UE +.RE +.EE +.SS DMK floppy disk archive file format +For information about the DMK file format and the emulators that +use it, see: +.EX +.RS 4 +.UR https://www.trs\-80.com/wordpress/tips/formats/#dmk +.UE +.UR https://www.trs\-80.com/wordpress/intro\-to\-emulators/ +.UE +.RE +.EE +.SH AUTHORS +\fBgw2dmk\fP was written by +.UR https://github.com/qbarnes/ +Quentin Barnes +.UE +based on the \fBcw2dmk\fP utilities by +.UR https://tim\-mann.org/ +Tim Mann +.UE +\&. + +\fBgw2dmk\fP is free software released under the GNU General Public +License. + +Thanks to David Keil for designing and documenting the DMK file +format for archiving floppy disks. diff --git a/gwhist.1 b/gwhist.1 new file mode 100644 index 0000000..c6427e1 --- /dev/null +++ b/gwhist.1 @@ -0,0 +1,140 @@ +.TH gwhist 1 +.SH NAME +gwhist \- Display a histogram after read a floppy using a Greaseweazle +.SH SYNOPSIS +.B gwhist [options] +.SH DESCRIPTION +\fBgwhist\fP utilizes a Greaseweazle universal floppy disk +controller to read a floppy disk then displays a histogram of its +flux and some statistics. + +This utility is primarily used for aiding with debugging. +.SH OPTIONS +.TP +.B \-G|\-\-device \fIname\fP +Specify the Greaseweazle's device \fIname\fP. On Linux, this will +typically be a device under the \fB/dev\%\fP path. The default name +is \fB/dev/greaseweazle\%\fP. If not found, \fB/dev/ttyACM0\%\fP. +On Microsoft Windows, the device name defaults to \fBCOM3\fP. + +If you are unsure of your device\[aq]s name, run \fBgw\~info\%\fP and +use the string returned after \[lq]Port:\[rq]. +.TP +.B \-d|\-\-drive \fIunit\fP +Specify the drive unit number. + +If your drive is connected via an IBM PC bus (flat cable with +twist), use \fBa\fP or \fBb\fP. For a Shugart bus (straight-through +flat cable), use \fB0\fP, \fB1\fP, or \fB2\fP. +.TP +.B \-t|\-\-track \fInumber\fP +Specify the track \fInumber\fP to read and analyze. Default is +track 0. +.TP +.B \-s|\-\-side {0,1} +Specify the side to read and analyze. Default is side 0. +.TP +.B \-r|\-\-revs \fInumber\fP +Specify the \fInumber\fP of revolutions to read for analysis. +Default is 1 revolution. +.TP +.B \-\-hd|\-\-dd +Controls pin 2 on the floppy drive bus for controlling media type, +high-density (logic 0) or double-density (logic 1). The default +is \fB\-\-dd\%\fP. +.TP +.B \-T|\-\-stepdelay \fIstep_time\fP[,\fIsettling_time\fP] +Time in milliseconds to delay after each step pulse (sometimes +called \[lq]step rate\[rq]), and additional time to delay +after the last step pulse (head settling time). The comma and +\fIsettling_time\fP value are optional. + +The defaults are 10ms step time and 15ms settling time, or the +values as configured into the Greaseweazle. Use \fBgw\~delays\%\fP +to check those values. + +If your drive has difficulty stepping, try a slower step rate. If +you often see errors on the first sector or first few sectors of a +track, especially when reading with \fB\-\-nohole\%\fP, or if you know +your drive requires it, add some additional head settling time. +.TP +.B \-\-[no]reset +Reset the Greaseweazle (or not) on start up of \fBgwhist\fP. +Default is to reset. + +If some Greaseweazle parameters are manually set by running \fBgw\fP +and you don\[aq]t want those settings undone by \fBgwhist\fP on +reset, suppress the reset operation with \fB\-\-noreset\%\fP. +.TP +.B \-v|\-\-verbosity \fIlevel\fP +Specify how much output is printed. Larger levels select more +output. The default level is 1. + +Different levels of output can be logged to the logfile and to the +screen (i.e., stdout) by giving a two-digit number. The first digit +specifies how much output to log to the logfile and the second how +much to log to the screen. +.RS +.TP +0 +No output. +.TP +1 +Print a histogram and statistical analysis of media\[aq]s flux. +.RE +.TP +.B \-u|\-\-logfile \fIfilename\fP +Specify the \fIfilename\fP for logging output. The default is not +to log to a file unless you give a two-digit \fB\-v\%\fP option. +If you give a two-digit \fB\-v\%\fP option and do not give the +\fB\-u\%\fP option, the default logfile name is \fBgw.log\fP. + +If you give the \fB\-u\%\fP option with a one-digit \fB\-v\%\fP +option, the same output is logged to the file and to the screen. +.TP +.B \-U|\-\-gwlogfile \fIfilename\fP +Specify the \fIfilename\fP to capture communication with the +Greaseweazle device in text form. The default is not to log any +communication with the Greaseweazle. +.SH DIAGNOSTICS +.TP +.B \fBgwhist\fP: Failed to open Greaseweazle's serial device '\fIdevname\fP' ... +A Greaseweazle device was not detected. You may need to provide +a \fB\-G\~\fP\fIdevname\fP option. +.SH SEE ALSO +.SS Other related commands +.BR gw2dmk (1), +.BR dmk2gw (1) +.SS Greaseweazle +For more information about Greaseweazle controllers and other +software that works with them, see: +.EX +.RS 4 +.UR https://github.com/keirf/greaseweazle/wiki +.UE +.RE +.EE +.SS DMK floppy disk archive file format +For information about the DMK file format and the emulators that +use it, see: +.EX +.RS 4 +.UR https://www.trs\-80.com/wordpress/tips/formats/#dmk +.UE +.UR https://www.trs\-80.com/wordpress/intro\-to\-emulators/ +.UE +.RE +.EE +.SH AUTHORS +\fBgwhist\fP was written by +.UR https://github.com/qbarnes/ +Quentin Barnes +.UE +based on the \fBcw2dmk\fP utilities by +.UR https://tim\-mann.org/ +Tim Mann +.UE +\&. + +\fBgwhist\fP is free software released under the GNU General Public +License.