-------------------------------ADVANCED DEMUFFIN-------------------------------
version 1.5                                                          2014-08-08
-------------------------------------------------------------------------------

                                       ~

                                 INTRODUCTION

Advanced Demuffin allows you to convert a disk that is in non-standard format
to DOS 3.3 format. If you supply an RWTS that can read the original disk, it's
likely that Advanced Demuffin can convert it.

To use Advanced Demuffin, you should be familiar with "THE BASIC OF KRAKING BY
KRAKOWICZ". Also helpful (but not required): a sector editor like The
Inspector, Disk Fixer, Nibbles Away, Copy ][+, or Disk Driver; a copy of
"Beneath Apple DOS"; some knowledge of assembly language.

Advanced Demuffin is only an automation tool.  You must capture the RWTS of the
original disk; Advanced Demuffin will not help you do that.  If the disk's RWTS
is too different from a normal RWTS, you may also need to write some assembly
language code (an IOB module, described below).  And even if Advanced Demuffin
is successful in converting a disk to a standard format, any secondary
protection (checksums, nibble counts &c.) that were on the original disk will
still be there on the converted disk. To complete the deprotection process, you
may need to sector edit the copy to take out these "checks".  Advanced Demuffin
will not help you with that either.  (Occasionally you will find a disk that
will not require any further changes after conversion, but this is not common.)

The name "Advanced Demuffin" is an homage to a historical tool, "Demuffin,"
which had severe limitations (for example, it could only copy a disk if it has
a directory).  Advanced Demuffin works completely differently from the original
Demuffin, so it does not share these limitations.

                                       ~

                                BASIC OPERATION

Advanced Demuffin starts at the main menu. Here are the options:

   1) CONVERT DISK: Does the actual copying of the disk.  Allows you to change
      different parameters, like start track, start sector, etc.

   2) LOAD NEW RWTS MODULE: Will load an RWTS for the source disk (the disk you
      are converting to DOS 3.3) from a DOS 3.3 disk.

   3) LOAD NEW IOB MODULE: Will load a new interface for the source disk's RWTS
      from a DOS 3.3 disk. Described in greater detail below.

   4) FORMAT TARGET DISK: Initializing a disk in either drive, in DOS 3.3
      format.

   5) EXIT TO MONITOR: Just what it says on the tin.

To use the options, move the "light bar" with the arrow keys.  The left arrow
moves the bar up and the right arrow moves the bar down.  To execute an option,
just move the bar to it and press RETURN.

The CONVERT DISK option will do the actual converting of the disk.  To use the
convert option move the light bar to "CONVERT DISK" and press RETURN.  When you
access the convert option, make sure that you already have the source RWTS in
memory and have the IOB module pointing to it. (The IOB module normally points
to $BD00.)

Advanced Demuffin will then ask you: "CHANGE DEFAULT VALUES?"  If you want to
copy from track $00, sector $00 to Track $22, sector $0F, by whole tracks, with
1 retry on bad sectors, and the destination (blank) disk in drive 2 then answer
"N" to this question.  If you answer "Y", Advanced Demuffin will ask you a
series of questions to customize the conversion process.

"SECTORS PER TRACK? (13/16)" The first digit is always a 1.  You should then
enter a "3" for a thirteen sector disk (DOS 3.2) or a "6" for a sixteen sector
disk (DOS 3.3).

(If you don't know if the disk has 13 or 16 sectors, try to convert it with 16
sectors. If you get errors on all sectors past $0C on each track, it is most
likely a 13 sector disk.  All the "SECTORS PER TRACK" option does is tell
Advanced Demuffin at what sector to change to a new track.)

"START TRACK:" Enter the start track in hex (normally $00).  You may enter half
tracks; just type a "." after you enter the track and Advanced Demuffin will
automatically tack a ".5" on the end of the track.

"START SECTOR:" Enter the start sector number in hex (normally $00).

"END TRACK:" Enter the end track in hex (normally $22).

"END SECTOR:" Enter the end sector in hex (normally $0F).

The start track and sector must come before the end track and sector.

      This is fine --+                        +--- but this is illegal
                     |                        |
                     v                        v
      Start track:  $00        Start track:  $22
      Start sector: $00        Start sector: $0F
      End track:    $22        End track:    $00
      End sector:   $0F        End sector:   $00

If you enter it this way Advanced Demuffin will give you the message "BACKWARDS
COPYING NOT SUPPORTED!"

"INCREMENT:" Enter the increment between tracks (usually 1).

"MAX # OF RETRIES?" Enter the number of times you want Advanced Demuffin to
retry reading or writing a sector (usually 1).

"COPY FROM DRIVE 1 TO DRIVE:" Enter the drive for the target disk (1 or 2).
The original disk is always in drive 1.

If you specified 2 drives, Advanced Demuffin will prompt you

    "INSERT DISKS AND PRESS RETURN"

Insert the original disk in drive 1 and the target disk in drive 2, then press
RETURN.

If you specified 1 drive, Advanced Demuffin will prompt you

    "INSERT SOURCE DISK AND PRESS RETURN"

Insert the source disk and press RETURN.  Advanced Demuffin will then read
as many tracks as it can from the original disk (usually 7), then prompt you

    "INSERT TARGET DISK AND PRESS RETURN"

Then it will write those tracks to the target disk in standard DOS 3.3 format.
With the default options, it takes 5 passes to copy an entire disk.

After the disk is converted, Advanced Demuffin will display the message

    "PRESS ANY KEY TO CONTINUE"

If you press 1-7 now (or at any time during the conversion process), Advanced
Demuffin will dump the screen to the printer in the specified slot.  Any other
key will return you to the main menu.

                                       ~

                              THE STATUS DISPLAY

At the beginning of the conversion process, the screen looks like this:

ADVANCED DEMUFFIN 1.5     (C) 1983, 2014
ORIGINAL BY THE STACK     UPDATES BY 4AM
========================================
TRK:
+.5:
    0123456789ABCDEF0123456789ABCDEF0123
SC0:
SC1:
SC2:
SC3:
SC4:
SC5:
SC6:
SC7:
SC8:
SC9:
SCA:
SCB:
SCC:
SCD:
SCE:
SCF:
========================================
16SC $00,$00-$22,$0F BY 1.0 S6,D1->S6,D2

The top 2 lines are just the title lines.  Then comes the disk map.  The first
two lines contain the track list.  Each track number is displayed here, from
$00 to $23.  Most disks only use tracks $00-$22, but occasionally some software
uses track $23.  (Note that all the values are displayed in hex format, not
decimal.)

The first line of the disk map (marked with "TRK" on the left side of the
screen) is for normal tracks.  The next line is for half tracks (marked with a
"+.5").  The next line is the actual track numbers.  After this is the sector
map, which will show the status code of each sector as the conversion
progresses.

At the bottom of the screen is the options line.  It shows what format the disk
is in (13 or 16 sector), then the start track and sector, then the end track
and sector.  The next thing on the options line is the track increment.  The
last thing is the slot and drive of the source and target disks.  If you opted
to change default values, the options line will reflect the choices you made.

There are a number of status codes that appear in these displays.  An inverse
"R" on the disk map shows a sector being read in.  An inverse "W" in the disk
map shows a sector being written out to disk.  An inverse "R" or "W" on track
list shows which track is being read or written.  A "." on either the disk map
or the track display shows the sector or track copied correctly.

Error codes and messages:

"R" on the track list - Some sectors on the track could not be read.

"W" on the track list - Advanced Demuffin could not write out some sectors on
                        that track.

"R" on the disk map --- That sector could not be read.

"W" on the disk map --- That sector could not be written.

When Advanced Demuffin detects that the target disk is "write protected", it
will replace the title lines with this message:

             DISK WRITE-PROTECTED!
    PRESS "S" TO START OVER, "C" TO CONTINUE

You should then remove the write protect tab or insert another disk. If you
want Advanced Demuffin to start copying from the start sector and track, press
"S". If you want it to continue copying from where it is, press "C".

At any point in the conversion process, you can press "ESC" to cancel the
conversion and return to the main menu.

                                       ~

                             LOADING RWTS MODULES

A RWTS module is the RWTS will be used to copy the source disk.  When you
access the "LOAD NEW RWTS MODULE" Advanced Demuffin will prompt you to "PAGE TO
LOAD AT (MUST BE A 2 DIGIT HEX NUMBER):" You must then enter the page number of
the address that you want to load RWTS at.  For example, "B8" would load it at
$B800.  (Most RWTS's start at $B800.)  Advanced Demuffin will only allow you to
load the RWTS between $20 and $BF. It will then ask you to "PLEASE TYPE THE
NAME OF THE FILE TO LOAD".  You should then enter the file name.  When you
press RETURN, Advanced Demuffin will ask you what drive to load it from.  You
should then enter a 1 or a 2.  Possible errors:

  1) NO SUCH BINARY FILE EXISTS! This is the same as a "FILE NOT FOUND" error.

  2) PLEASE INSERT THE CORRECT DISK CORRECTLY IN CORRECT THE DRIVE AND PRESS
     <RETURN> This means that Advanced Demuffin had problems reading your RWTS.

                                       ~

                             CREATING IOB MODULES

An IOB module is an interface for the source RWTS.  Advanced Demuffin uses the
IOB module to set up the RWTS parameter table and jump to the RWTS entry point.
The IOB module is stored from $1400-$14FB.  When Advanced Demuffin loads in an
IOB module, it reads the first sector of the file off the track-sector list and
stores it at $13FC-$14FB.  When Advanced Demuffin wants to read a sector it
JSRs to the IOB module with the phase number, sector number, and the page
number stored in the A, Y and X registers respectively.  Since the source drive
always has to be drive 1, Advanced Demuffin can make the IOB module very
compact.  After it gets the page, track, and sector, Advanced Demuffin sets up
the RWTS parameter table and JMPs to the RWTS entry point.  Here is a
disassembly of the IOB module that is built in to Advanced Demuffin:

*1400L

1400-   4A          LSR          ; Convert phase # to track #
1401-   8D 22 0F    STA   $0F22  ; Store track number
1404-   8C 23 0F    STY   $0F23  ; Store sector number
1407-   8E 27 0F    STX   $0F27  ; Store page number
140A-   A9 01       LDA   #$01
140C-   8D 20 0F    STA   $0F20  ; Store the drive number
140F-   8D 2A 0F    STA   $0F2A  ; Store the read code
1412-   A9 0F       LDA   #$0F   ; With high byte of IOB
1414-   A0 1E       LDY   #$1E   ; With low byte of IOB
1416-   4C 00 BD    JMP   $BD00  ; Goto RWTS

Here are some reasons why you might need to write a custom IOB module:

  1) The source RWTS uses some of the same zero page locations as Advanced
     Demuffin. The IOB module would have to swap those out before the read, and
     swap them back in after the read.

  2) The source RWTS resides within the text window, or over part of Advanced
     Demuffin.  The IOB module would have to save those memory ranges before
     the read and swap them back in after the read.

  3) The source RWTS starts at a non-standard location (for example, at $3800
     instead of $B800). Your IOB might need to change the memory ranges that
     Advanced Demuffin uses to store sector data during a copy, so that the
     data does not overwrite the RWTS.

  4) The source RWTS uses a different entry point for reading a sector (for
     example, at $BA00 instead of $BD00).

  5) The source RWTS requires initialization (for example, it relies on values
     stored in zero page locations during early boot).

  6) The source disk stores data on half or quarter tracks. If you need to read
     half tracks, modify the LSR at $1400 that normally converts the phase
     number to a track number.

If you need to change memory locations that Advanced Demuffin relies on, you
should make sure that you JSR to the RWTS instead of JMPing to it, so that you
can move the things back to their right place after the RWTS returns.  A
complete list of reserved memory locations is included in this documentation.

                                       ~

                            A STEP-BY-STEP EXAMPLE

ACTUALLY DEMUFFINING A DISK: Using Castle Wolfenstein as an example. (I used
this because it is the only thing that I that have that wasn't cracked!)

  1) Boot up Castle Wolfenstein.  Before the cursor appears press CTRL-C. The
     one character buffer in the keyboard will remember it and when DOS asks
     for a character it will give the CTRL-C. The CTRL-C will cause Castle
     Wolfenstein's hello program to break into BASIC after it is loaded.

  2) Enter the monitor with "CALL-151". Enter "4000<B800.BFFFM". this will move
     MUSE's RWTS down to a "safe" area of memory.

  3) Insert a "slave" disk in drive one and boot the disk with 6 CTRL-P (if
     your disk drive is in slot 6 of course).  Press RESET when the prompt (])
     appears.  This will prevent your "HELLO" program from erasing MUSE's DOS.

  4) Insert a disk with at least 10 free sectors on it.  Save out the RWTS with
     "BSAVE MUSE-RWTS,A$4000,L$800".

  5) BRUN Advanced Demuffin.  Move the light bar to "LOAD A NEW RWTS MODULE"
     and press RETURN.

  6) Type the page number to load the RWTS at ($B8).  Then type the file name
     that you saved it under and press RETURN.

  7) Move the light bar to "CONVERT DISK" and press RETURN.  You do want to
     change default options.

  8) The disk is a thirteen sector disk, so enter a "3" for the question
     "SECTORS PER TRACK? (13/16)".

  9) You want to copy from track $03,sector $00 to track $22, sector $0C.  The
     increment is 1. (You are copying from track $03 because you don't need
     MUSE's DOS on tracks 0-2. You are stopping on T22,S0C because each track
     of the original disk only has 13 sectors.)

  10) You might encounter some errors, so use "1" as the number of retries.

  11) If you have two drives in the same slot, enter a "2" for target drive.
      If you only have one drive, enter "1".

  12) Insert the proper disk(s) when Advanced Demuffin prompts you.

After it completes the conversion process, Advanced Demuffin will display the
message "PRESS ANY KEY TO CONTINUE". You should write down all the sectors that
had read errors, if any.  If you have a printer, all you have to do is press
the slot number of the printer, and Advanced Demuffin will dump the screen to
the printer.

You should then re-convert the sectors that had read errors (use at least
2-retries).  If those sectors don't convert this time, they are probably just
un-written DOS 3.2 sectors.

Next, reboot into a disk utility such as Copy ][+, Super Copy III, or Master
Create to copy a standard DOS 3.3 onto the target disk.  Rename the file named
"^HELLO" to "HELLO" so that DOS 3.3 will find it and run it automatically.

You should now have a cracked copy of Castle Wolfenstein!

                                       ~

                               MEMORY LOCATIONS

Advanced Demuffin uses the following memory locations:

  $22  WNDTOP   These 2 zero page locations, WNDTOP and WNDBTM, are used so
  $23  WNDBTM    that the character that the character output routines in the
                 monitor will output characters only in the window below the
                 first 3 lines and above the bottom 2 lines.  The top 3 and
                 bottom 2 lines are used for title lines and status display.
                 These locations should be restored to normal upon return from
                 your RWTS if it uses them, although most RWTS's don't use
                 these reserved monitor locations.

  $26  GBASL    These 2 zero page locations are used by routines throughout
  $27  GBASH     Advanced Demuffin, such as the PRINT routine and the routines
                 to display the status codes on the disk map, but they do not
                 need to be saved before going to your RWTS.  Many RWTS's,
                 including DOS 3.3, use these locations in several places.

  $36  CSWL     CSWL and CSWH should always point to the address of the current
  $37  CSWH      character output routine.  Advanced Demuffin sets these
                 locations to point to $FDF0, the standard character output
                 routine.  Note that the outputed characters will no longer go
                 through DOS as there may be no DOS in the machine.  Advanced
                 Demuffin changes the contents of these locations to point to
                 $Cx00 when a number from 1-7 is pressed during or after a
                 conversion, where x is the number pressed.  These locations
                 should be restored to point to $FDF0 if your RWTS uses them in
                 any way.  Most RWTS's, including DOS 3.3, don't touch these.

  $4A  TEMP1    Although most RWTS's don't use these locations, they are used
  $4B  TEMP2     as scratch locations by Advanced Demuffin and are VERY
  $4C  TEMP3     IMPORTANT!  Be sure and save them if your RWTS even looks at
  $4D  TEMP4     them.  The most important location to save is $4B, which
                 contains the page number that the current sector is being
                 loaded into.  Note that this is a duplicate of the X register
                 upon entry into the user's IOB module at $1400.

 $200  BUF      Page 2, the character input buffer, is used as a buffer to hold
                 the file name of the RWTS or IOB module to be loaded.  This
                 page may be used by your RWTS, but your RWTS may not reside in
                 the area between $200-$21E (unless you don't plan on loading
                 anything), as this portion of page 2 will be destroyed upon a
                 load.

 $3F2  RESET    Advanced Demuffin sets this pointer to pnint to $FF59.  This
                 means that whenever the RESET key is pressed, the Apple will
                 jump into the monitor.  If this is not desired, $12C9 (low
                 byte) and $12CE (high byte) may be changed to have the RESET
                 key go wherever you want it to go including $801 (Advanced
                 Demuffin entry).  $12C9 normally contains a $59 and $12CE
                 normally contains an $FF.

 $3F5  AMPVEC   Advanced Demuffin sets up these locations to jump to the main
 $3F8  CTYVEC    entry point ($801) when Applesoft receives the "&" command
                 or when the monitor receives the CTRL-Y command.  This is a
                 convenient way to get back into Advanced Demuffin after
                 selecting "EXIT TO MONITOR" from the main menu.

 $400-$7FF      Advanced Demuffin displays data and status marks on the screen
                 by storing this data directly into this area of memory.  This
                 includes all marks on both the track map and the disk map as
                 well as numbers on the bottom screen line, and dashes and
                 other messages on the 3rd and 23rd lines. If your disk's RWTS
                 resides in the text screen (like some old Sirius games), you
                 will need to create an IOB module that saves and restores the
                 text screen before and after calling the RWTS.

 $800-$1EFF     Advanced Demuffin code and data

 $800  ENTRY    This is the location where Advanced Demuffin is designed to run
                 from.  This location contains an $EA (NOP) as the byte at $800
                 is often replaced by a $00.  This is NOT the entry point to
                 Advanced Demuffin ($801 is the entry) although if there is an
                 $EA here it won't make any difference.

 $801  START0   This is the entry point to Advanced Demuffin where there are 2
                 instructions, SEI and CLD, before the actual START of the
                 program.

 $803  START    This is the actual start of the program.  It sets CSWL and CSWH
                 to point to the monitor routine COUT1, sets the RESET, AMPVEC,
                 and CTYVEC as mentioned above, sets the full screen as a
                 window except for the top 3 and the bottom 2 lines, clears the
                 screen, puts the title at the top, the options line at the
                 bottom, displays the main menu, and waits for input.


 $F1E  IOB      This is the RWTS parameter table that Advanced Demuffin uses when
                 it reads from the original disk or writes to the target disk.
                 Both the built-in IOB module (IOB33, below) and any custom IOB
                 module (at $1400) can read or write parameters in this table.
                 The default contents of this IOB are as follows:

                 $F1E:01 60     IOB      DFB $01,$60
                 $F20:01        DRIVE    DFB $01
                 $F21:00        VOLUME   DFB $00
                 $F22:00        TRACK    DFB $00
                 $F23:00        SECTOR   DFB $00
                 $F24:2F 0F              DW DCT
                 $F26:00        DPAGL    DFB $00
                 $F27:80        DPAG     DFB $80
                 $F28:00 00              DFB $00,$00
                 $F2A:01        CODE     DFB $01
                 $F2B:00        ERROR    DFB $00
                 $F2C:00 60 01           DFB $00,$60,$01
                 $F2F:00 01     DCT      DFB $00,$01
                 $F31:EF D8              DFB $EF,D8

                 Note that the slot number used by Advanced Demuffin can be
                 changed by changing $F1F to $x0, where x is the slot number of
                 the desired drive.  Starting in version 1.5, you can press 1-7
                 at the main menu to change the slot number.  This is reflected
                 in the options line at the bottom of the screen.  The slot
                 number is global and affects all disk operations, including
                 loading RWTS files and IOB modules. [CHGSLOT, MENUKEYS]

 $F33  IOB33    This is the built-in IOB module used to write to DOS 3.3
                 formatted disks.  A disassembled listing follows:

 $F33- IOB33  STY SECTOR    ;Store sector
 $F36-        STX DPAG      ;and page number
 $F39-        LSR A         ;Convert phase # to track #
 $F3A-        STA TRACK     ;and store it
 $F3D-        LDA DRV       ;Check # of drives
 $F40-        STA DRIVE     ;and store it as drive to write to
 $F43- THERE  LDA #2        ;Set command code to write
 $F45-        STA CODE      ;and store it
 $F48-        JSR GORWTS    ;and go to 3.3 RWTS to write it
 $F4B-        LDA #1        ;Restore read
 $F4D-        STA CODE      ;command code
 $F50-        LDA ERROR     ;Check for an error
 $F53-        BCC RTS4      ;Exit if none
 $F55-        CMP #$10      ;Write protect error?
 $F57-        SEC           ;Keep carry set
 $F58-        BNE RTS4      ;Not write protect, exit w/carry set
 $F5A-        LDY #$27      ;Display write protected
 $F5C- MOV4   LDA WPER1,Y   ;error message
 $F5F-        STA SCLN1,Y   ;and ask whether
 $F62-        LDA WPER2,Y   ;to continue or
 $F65-        STA SCLN2,Y   ;start over
 $F68-        DEY
 $F69-        BPL MOV4
 $F6B-        JSR PRINT     ;Print 3 beeps
 $F6E-        DFB $07,$07,$87
 $F71- KEY10  JSR KEYIN     ;Read a key - go back to menu if esc
 $F74-        CMP #$C3      ;Continue?
 $F76-        BEQ CONTIN    ;Yes, branch
 $F78-        CMP #$D3      ;Start over?
 $F7A-        BNE KEY10     ;No
 $F7C-        PLA           ;Yes
 $F7D-        PLA           ;Pull return address off stack
 $F7E-        JSR REPLNS    ;Replace top 2 lines w/ title lines
 $F81-        JMP GOTVAL    ;Starts over
 $F84- CONTIN JSR REPLNS
 $F87-        BMI THERE     ;Always taken

$13FA-$13FB     (unused)

$13FC-$13FF     Reserved for the address and length of the IOB module when it
                 is being loaded.  Advanced Demuffin loads the first sector
                 from the track/sector list of the IOB module at $13FC.  Since
                 the first 4 bytes of this sector contain the address and the
                 length of the file, those bytes reside in these locations.
                 Therefore, the actual IOB module will start at $1400.

$1400  IOBM     This is the user IOB module.  Selecting "LOAD NEW IOB MODULE"
                 will load a file into this area.

$1419-$14FB     This range is reserved for your user IOB module, if it needs to
                 be longer than the default one.  A user IOB module to can take
                 up as much as $FC bytes in total.

$14FC-$14FF     (unused)

$1500-$1CDB     This range contains a copy of the standard DOS 3.3 RWTS, with
                 absolute addresses relocated so it can run at this address.
                 Advanced Demuffin uses the entry at $1A00.

Below are some other locations used as scratch by Advanced Demuffin.  These may
be examined by your IOB module in to determine how to read sectors from the
original disk. (This is not common.)

$1CE0  SCVER    This location contains either a $0C or a $0F for 13 and 16
                 sector modes, respectively.

$1CE1  STPHS    This location contains phase number to start reading data from
                 the disk.  It defaults to $00.  Since it is a phase number and
                 not a track number, a $01 would mean track 0.5, $02 would mean
                 track $01, and so on.

$1CE2  ENPHS    ENPHS is the same as STPHS except that it contains the last
                 phase to read data.

$1CE3  STSEC    STSEC contains the first sector to read data, within the phase
                 specified by STPHS.

$1CE4  ENSEC    ENSEC contains the last sector to read data, within the phase
                 specified by ENPHS.

$1CE5  CRPHS    This location contains the current phase from which Advanced
                 Demuffin is reading data.

$1CE6  CRSEC    This location contains the current sector from which Advanced
                 Demuffin is reading data.

$1CE7  BGSEC    BGSEC contains the sector number within the phase specified by
                 BGPHS (below) that data has started being read from this pass.
                 i.e. If you are converting an entire 16 sector disk with the
                 default options and the default buffer size ($70 pages),
                 during the first pass BGPHS and BGSEC will both contain a $00
                 (phase 00, sector 00 were the start phase and sector in this
                 pass).  During the second pass, BGPHS and BGSEC will contain
                 $0E and $00, respectively.  (The second pass started with
                 track 07, sector 00, and track 07 is phase $0E.)

$1CE8  BGPHS    (see BGSEC, above)

$1CE9  BYPHS    This byte contains the increment in phases. The default value
                 is $02, meaning Advanced Demuffin will increment 1 track at a
                 time.

$1CEA  NRETRY   This byte contains the maximum number of retries. The default
                 value is $01.

$1CEB  RETRY    This byte is used as a counter counting down from the maximum
                 number of retries to $00.  On the first attempt to read a
                 sector, RETRY will equal NRETRY.  If the carry is set upon
                 return from the user's IOB module, RETRY will be decreased.
                 If it is less than zero, a read error will result.  If not, a
                 read will be attempted again.  This process will continue
                 until the sector either reads correctly or until RETRY is less
                 than zero.

$1CEC  DRV      This location contains $01 or $02, depending on how many disk
                 drives are being used. The original disk is always read from
                 drive 1, but the built-in IOB module uses this location to
                 determine which drive to write data to.

$1CED-$1CEF     (unused)

$1CF0  BUFST    BUFST contains the page number of the start of the buffer.
                 This buffer is used to store data read off the source disk.
                 By changing this location and/or BUFEN (below) you can easily
                 change the buffer size and the location of Advanced Demuffin's
                 buffer.  This location normally contains a $20, meaning that
                 the buffer normally starts at $2000.

$1CF1  BUFEN    BUFEN contains the page number of the first page not to be
                 included in Advanced Demuffin's buffer.  i.e. If this location
                 is $90 and BUFST is $20 (the default values), the buffer would
                 reside from $2000 to $8FFF.  If you changed this from $90 to
                 $B0, Advanced Demuffin would read 9 tracks at a time instead
                 of 7. This would overwrite most of DOS (which normally starts
                 at $9600), but Advanced Demuffin does not require DOS (not
                 even for loading RWTS and IOB modules).  On the other hand, if
                 you changed this from $90 to $30, Advanced Demuffin would only
                 read 1 track at a time. This would be slow and painful with
                 only one disk drive, but it would allow you to convert a disk
                 whose RWTS resides in low memory. (Some disks have their RWTS
                 starting at $3800.)

$1CF2-$1CFF     (unused)

$1D00  RWTSBUG  [introduced in 1.5] A patch to load the last 4 bytes of an RWTS
                 file into $BFFC-$BFFF if necessary.  Earlier versions had a
                 bug in the RWTS file load routine that would fail to load the
                 last sector of an RWTS file that extended all the way to the
                 top of main memory ($BFFF). Since most RWTS files are exactly
                 $800 bytes long, the last sector contains the last 4 bytes of
                 the RWTS and should be loaded into $BFFC-$BFFF. (DOS 3.3 uses
                 the first 4 bytes of the file to store the address and length,
                 so an $800 byte file requires $804 bytes to store on disk.)
                 Some RWTS's actually use those last 4 bytes (e.g. Math Blaster
                 stores its nibble table at $BF96-$BFFF), so earlier versions
                 of Advanced Demuffin would fail to convert those disks.

$1D2D  CHGSLOT  [introduced in 1.5] A patch to display the current slot number
                 (from $0F1F) on the options line at the bottom of the screen.

$1D3F  MENUKEYS [introduced in 1.5] A patch to handle more keys on the main
                 menu. Up and down arrow keys now work like left and right
                 arrows.  You can press the keys in (P)arentheses to execute
                 that option immediately.  You can press 1-7 to change the slot
                 number.  (Advanced Demuffin will use that slot for reading and
                 writing disks, loading RWTS files, and loading IOB modules.)

$1D8E-$1EFF     (unused, reserved for future patches)

$1F00  DIRSEC   This page is used as a scratch page when loading sectors from a
                 disk.  When loading a RWTS or an IOB module, the directory
                 sector containing the name of the file to load will be read
                 into this page.  The track and sector of the track/sector list
                 will be found and the track/sector list will then be loaded
                 here.

$BD00  USRRWTS  This is address JuMPed to by the default user RWTS.  You should
                 either have an RWTS here or the IOB module should be changed
                 to point to a different location.  Note the $BD00 does not
                 necessarily have to be the start of the RWTS when using the
                 default user IOB module, it must be the ENTRY POINT of the
                 RWTS.  In fact, most RWTS's have a STARTING ADDRESS of $B800
                 but an ENTRY POINT at $BD00.  Keep this in mind when you load
                 an RWTS module from disk.

$C000  KEYBD    These are the only I/O switches used by Advanced Demuffin.
$C010  KEYCLR

The following ROM routines are used by Advanced Demuffin:

$Cx00  used during screen dump (x is the slot number)
$F847  GBASCALC
$FB2F  INIT
$FC58  HOME
$FD8E  CROUT
$FDED  COUT
$FDF0  COUT1
$FF59  MONITOR

                                       ~

                                VERSION HISTORY

1.5 was released in 2014 by 4am

- fixed 4-byte RWTS bug [RWTSBUG]

- added slot number to options line [CHGSLOT]

- added more keyboard shortcuts on main menu [MENUKEYS]

- combined DOCS, EXAMPLE, and TECH DOCS into one file and updated it with
  grammatical and technical corrections

This version is based entirely on version 1.1 by The Stack.  The version number
is 1.5 to avoid confusion with an earlier fork by The Brain Trust, which was
released as "version 1.4".  No code from version 1.4 was used in version 1.5.
Source code for version 1.1 was not available, so this is a set of binary
patches to version 1.1.

RWTSBUG:

$10F0 - change "AD 27 0F C9 BF B0 06" to "4C 00 1D EA EA EA EA" to call patch
$1D00 - patch to load last 4 bytes of RWTS file into $BFFC..$BFFF if necessary

CHGSLOT:

$083B - change "20 58 FC" to "20 2D 1D" to call patch
$1D2D - patch to display current slot number (from $0F1F) in options line at
        the bottom of the screen

MENUKEYS:

$08BC - change "20 51 0D" to "4C 3F 1D" to call patch
$1D3F - patch to handle more keys on main menu (up/down map to left/right,
        add keyboard shortcuts to each option to directly execute it,
        press 1-7 to change slots)
        
OPTLINE:

$1328 - change default text from "16 SC $00,$00 TO $22,$0F BY 1.0 TO DRV 2"
                              to "16SC $00,$00-$22,$0F BY 1.0 S6,D1->S6,D2"

$09BB - change "06" to "05" (position of start track)
$09D7 - change "0C" to "0B" (position of start sector)
$09F0 - change "11" to "0D" (position of end track)
$0A0A - change "17" to "13" (position of end sector)
$0A5E - change "1C" to "18" (position of increment)



1.4 was released in 1989 by The Brain Trust

- main program was unchanged, but it was bundled with a boot tracing program
  to extract the RWTS from a disk automatically



1.1 was released in 1983 by The Stack / Corrupt Computing, with documentation
    by The Inspector

- All options work, including LOAD RWTS MODULE & LOAD IOB MODULE.

- Does not require a DOS or an RWTS to function properly. However, if you don't
  have an RWTS in memory, you either need to load one with "LOAD NEW RWTS
  MODULE" or change the JMP in the built-in IOB module to point to $1A00.

- Default is to read in $7000 bytes per pass, meaning that the entire disk can
  be converted in 5 passes (especially useful with only one disk drive).

- The buffer start and end can easily be changed by changing locations $1CF0
  and $1CF1. The defaults for these locations are $20 and $90, respectively.

- After "EXIT TO MONITOR", CTRL-Y and & will get you back into the program.

- Can do a screen dump to the printer after the conversion is done. Typing a
  number from 1-7 at any time during the conversion will do a screen dump to
  the specified slot once the conversion is complete.  (Any other key besides
  1-7 will clear the pending screen dump.)  Before printing, the program will
  send "CTRL-I80n" so that the output will not go to the screen during print.

- The left-arrow key <- works as a backspace-delete in inputs when entering
  multi-character values such as track number or filenames.

- You can now specify the maximum number of retries per sector.  This can be
  anything from 0 (only one try, no retries) to $0F (15 retries).  The default
  value is 1.

- If backwards copying is attempted, you will be given an error message instead
  of it incorrectly copying only the first sector.

- You don't have to do the $1318 modification.  The IOB module (which is now at
  $1400 instead of $1300) now points to $BD00 instead of $1900 or whatever.

- The "change default values" screen asks for the "INCREMENT" instead of "BY",
  because this was confusing.

- It does not print through DOS.



1.0 was released in 1983 by The Stack / Corrupt Computing

- Initial release

--------------------------------------EOF--------------------------------------