                           REGENERATOR 1.2
                          =================
                              n0stalgia
                     
Welcome to Regenerator - an interactive disassemble for C64 binaries.
Regenerator will load any standard C64 .PRG file (or VICE snapshot)and
disassemble it for your convenience. There are a few options you can
choose to change the output and a few tools to make the output look
better and more useful to programmers. There are a few tools like this
one out there but we thought none are really simple to use and up to the
task, really. :)

Oh, and you will need .net 3.5 (or 4.0) runtime. Download from the
Microsoft place.

Regenerator makes files compatible with 64tass. The output should be
directly compilable by that assembler. However you might need to uncheck
the "Use Illegal Opcodes" option since 64tass chokes on illegal opcodes.

First thing to do is to use the "LOAD" button to load any .PRG file.
Right away you will be presented with the initial disassembly in the
main window of the program. You can scroll around to inspect it.

The main window consists of several columns - first column is the line
number, then is the address, then the bytes that make up the instruction,
then the label (if any), the instruction itself and the comment.

*NOTE*: The "END" address always denotes last byte+1 - so basically the
        start of the next block of data!

The following options and tools are available for you on the right side:

"Load"
   will load another .PRG program or a VICE snapshot file with .VSF
   file extension. Any changes since last save will be lost ! Also
   supported is the .O64 extension which has the same format as .PRG.
   If you load a VICE snapshot then the start address will be set to
   $0100 and the end on the end of memory.

"Save"
   will save the disassembly to .TAS format. This is basically a plain
   text file, so you can also view it in other programs. Together with
   the .TAS file there will also be a configuration file saved into the
   "Config" directory which will contain all modifications you made to
   the disassembly. More on this later.
         
"Display Top Labels"
   if this checkbox is enabled then you will see the labels on the top
   of the disassembly. These labels are the ones that are not referenced
   in the disassembly itself - so they have to have their values filled.
   There are several types of labels. By default this option is set to
   disabled. When saving to .TAS file the labels are always saved!
   
"Display ASCII Values"
   if this is enabled then (up to) three bytes that are displayed in the
   third column will be displayed as ASCII characters (converted from
   PETSCII format). So you can easily spot the Text in the assembly.
   This option also does not effect the result .TAS file in any way, it
   is just there for displaying purposes.
   
"Set Data"
   before you can press this button you must select a few (or just one)
   lines in the main window. This button will make those lines be
   represented as data bytes (.BYTE assembler directive). If you only
   select ONE line then only one byte of data will be chosen as .BYTE
   content. If you select more than one line then the LAST line will
   be the END ADDRESS + 1. Which means that the bytes in the last data
   will not be present in the .BYTE directive ! The max number of bytes
   per line is gotten from the next option.
   If you have "Auto Merge" option checked then if there is a block
   before or after this one (and of same type) then that one will be
   merged with your current block!
   
   ***NOTE*** : Some data blocks might be truncated if there is an
                instruction that overlaps with them!

"Max Data Entries"
   the number in this box tells the Set Data button how many entries
   are allowed per .BYTE line. When there are more bytes selected then
   they will be cut into more lines.
   
"Set Text"
   as with "Set Data" button this will generate .TEXT assembler
   directive from the selected lines in the main window. Everything
   else is the same.
   
   ***NOTE*** : If you generate text that is not from characters that
                are in ASCII set then you will get output that will
                NOT assemble back to the original content! So make
                sure that the TEXT blocks that you generate are
                really readable text!
                
"Max Text Chars"
   this will tell how many chars will fit into one line when used with
   "Set Text" button.
   
"Set Code"
   this will turn the .TEXT and .BYTE directives back to code. You
   must be on one of the lines with .TEXT or .BYTE directive for it to
   work. It will convert the WHOLE data or text block back to code!
   
"Clear All"
   this will clear all Data and Text blocks - the whole segment will
   be code again. It will also remove all Blank lines (more to that later).
   
"Merge"
   this will Merge all blocks that are in your currently selected region
   of the source code. Blocks must be of the same type and must follow
   each other exactly, otherwise the merge will not be done.
 
"Auto Merge"
   this option will enable/disable auto merging of blocks when you
   create a text or data block right after or before an already existing
   data/text block.
 
"Start" and "End" with "Start-End" button
   these will be filled with the Start address from the .PRG file and with
   the calculated End address when you load the file. You can change them
   to any address you choose and the program will disassemble only that
   portion of the file. You can change the address and press ENTER or press
   "Start-End" button to set the new address.
   
"Use Illegal Opcodes"
   if this is set then Illegal Opcodes will be generated and written to
   the output file. Many assemblers cannot handle those so this option
   disabled will generate .BYTE directive instead of the illegal opcodes.
   
"Comment Illegals"
   if you don't want to generate illegal opcodes, but you still want to
   know where and what they are then you can turn on this option. This
   will make comments next to .BYTE directives telling you what that
   instruction is.
 
"Change JAM to .BYTE"
   if Illegal Opcodes are being used then it will still use .BYTE for
   all JAM commands.
 
"Use Labels"
   by default disassembler will try and generate labels and references
   for you. If you disable this option that that will turn that off and 
   everything will be disassembled as absolute values. Disassembler will
   try and generate a few types of labels - more on that later.
   
"Use Exclude file"
   if you use labels then you might want a few of them not to show up as
   labels but instead make them be absolute addresses. If this is the case
   then you can edit the excludes.txt file with the addresses you wish to
   exclude from being made into labels. A few ranges are already defined
   in the file for you. You can insert single addresses or ranges.
   
"Use JMP/JSR Comments"
   For certain addresses (for instance jumps into ROM) you would like to
   know what they are. You can edit the comments.txt file and add these
   to your liking. You can turn on/off the creation of these comments with
   this option.
   
"Use Other Comments"
   The same comments.txt file also contains addresses and comments for
   any address that is encountered, not just for JMP/JSR. You can add your
   own addresses in the second portion of the comments.txt file. This option
   will turn generation of other comments on/off.

"Use ~ for Long Bytes"
   This will use the newest feature of 64tass 1.47. It will add a prefix '~'
   to all abs, abs.x and abs.y addressing modes which go to addresses that
   are in byte range. For example LDA $00F0 will become LDA ~$00F0 . This
   will force the assembler to assemble these operands to WORD sizes instead
   of Zero-Page operands.
   
"BRK Single Byte"
   if this is set then BRK will be treated as a single byte $00. If it is
   not set then BRK will be treated as two bytes $00 $xx , where $xx can be
   any byte. This is proper behaviour of 6502 but some assembler tread a
   single $00 as BRK (64tass does too). You can still make the proper two
   byte BRK compile with these assemblers if you use the next option.
   
"Patch BRK"
   if you use a two-byte BRK ($00 $xx) then you can make the output
   disassembly include a second line with .BYTE $xx which will make this
   compatible with most assemblers.
   
"Display BIN immediates"
   this will display a binary representation of an immediate value as
   a comment to the right of the instruction. Very useful to see which
   bits are turned on.
   
"Include Discarded Data"
   if you manually set the "Start" and "End" address of the disassembly
   then you will miss some of the data at the start and end of the .PRG
   file when that portion is disassembled. With this option turned ON those
   two portions of the data will be appended to the start and end of the
   code as .BYTE directives.

"Tabs Instead of Spaces"
   will generate TAB stops instead of 8 spaces on the left side of the
   disassembly. This might save some bytes in the .TAS file.
   
"Label"
   You can choose your own prefixes (up to two characters per prefix) for
   all labels that are generated: Absolute values, Pointer (indirect)
   values, JMP addresses, JSR (subroutine) addresses, Branch addresses,
   External addresses (only for JMP, JSR and Branch) and fields (tables).

"Set Font"   
   Will let you choose your own font. Make sure you choose a fixed width
   font or else the output will look horrible. If you click on "Default"
   button then the default font will be used.

"Search"
   will search for a specific string that you enter from the currently
   selected line on. You can search for the next occurrence by simply
   pressing 'N' key while the main window is active.
   
"Next"
   will search for the next occurance of the search string.

"Auto Data"
   this will Auto-generate the Data (.BYTE) and text (.TEXT) blocks for
   you from the whole code. ANY previous data and text blocks will be
   deleted first! Any 4 or more consecutive appearances of a byte will be
   generated as .BYTE and any 4 or more consecutive readable text
   characters will be generated as .TEXT sequence. You can choose if you
   want to generate only .BYTE, only .TEXT or both data types. You can
   also specify the minimum occurance value if you want it to be something
   else than 4.
   
"Save Config"
   This will save configuration - all options. Plus it will also save
   all the changes you made to the disassembly to the special config file.
   
In Addition to these options there is also a context menu in the Main
window which lets you do the following:

"Toggle Bookmark" - key 'F1'
   this will toggle the bookmark (an asterix on the left side) on the
   currently selected line. You can move through bookmarks with next two
   commands. If you press F1 again on the same line then this bookmark
   will be removed. Bookmarks are lost when you load next PRG file.
   
"Next Bookmark" - key 'F2' and "Previous Bookmark" - key 'F3"
   You will move to the next/previous bookmark you set. 
   NOTE: If you change the disassembly then also the bookmarks will change
         or be removed. They are relative to the line number and not
         the address.
         
"Set Start" and "Set End"
   this will set the Start or the End address to the currently selected
   line.
   
"Set Data Block" - 'D', "Set Text Block" - 'T', "Set Code Block" - 'C'
   will do the same as the corresponding commends on the right tool bar.
   
"Insert Blank Line" and "Remove Blank Line"
   will insert or remove a blank line AFTER the selected line. This will
   just add a blank line to the disassembly.
   
"Search String" - key 'F' and "Search Next" - key 'N'
   same as "Search" Button. If you press 'N' it will search for next
   occurance of the same string.
   
When you SAVE the .TAS file a local configuration file will also be
generated in the "Config" directory of the program. This file will hold
all Data, Text and Blank lines that you created in this .PRG and next
time you load that .PRG file it will auto-load those portions so you will
not loose your hard work!

author: Tom-Cat (Tomaz Kac) - tomcat@sgn.net

BIG Thanx to Fungus, 6R6, S!R and also thanx to other n0s members:
Ksubi, Slator, Antitrack, Sorex, Lemming, ... and everyone else that I
forgot.

LICENSE:
This is a freeware program. You are not allowed to charge any money for it
or for any media that this program is put on, otherwise you can freely
distribute it.