D i S t e l l a
v 2.10
By
Dan Boris and Bob Colbert
Thanks to:
Alex Hornby, Vesa-Matti Puro, Jarkko Sonninen, Jouko Valta
----------------------------------------------------------------------------
Quick Docs: Type DiStella at the command prompt.
What is it?
Distella is a disassembler specifically for the Atari 2600. It creates
source code that is usually recompilable without any human intervention.
It examines the code and performs some basic tracing routines which allow it
to accurately distinguish data from code.
Features:
o Written in portable ANSI C - source code is included.
o Very fast
o Distinguishes data from code
o Uses labels for Atari 2600 register locations
o Allows user to override or disable auto data determination
o Optionally includes 6502 cycle times as comments
o Freeware - Use it, Love it, Live it!
Command format:
Distella [options] romimage [> sourcefile]
Distella puts the sourcecode generated to standard output, so to
put it in a file use the '>' redirection. Unlike Distella 1.0, the
.bin suffix is not assumed, and you must use the -c flag to tell
DiStella the name of a config file if you choose to use one.
Options:
-a -> Disables the printing of the letter 'A' for opcodes in which
the A register is implied. Some assemblers don't like the 'A'
and others require it.
Example: LSL A would be just LSL
-c -> Defines a config file to use for disassembly. The name of the
file must follow the c immediately without any spaces. See the
section called "Config File" for more details about the config
file.
-d -> Disables automatic code determination. When this flag is used,
DiStella is "dumb" and thinks everything is code unless told
specifically otherwise in the config file.
-i -> DiStella will read the address indicated in the last 2 bytes of
the ROM file - the interrupt vector - and trace through it to
help determine data areas. Not all programs use the interrupt
vector. The best thing to do is try disassembling the image
without this flag and see if the last two bytes point to an
area that is not disassembled. If that is the case, try the
flag and see if the interrupt routine contains valid code. I
found that a majority of games do not use the interrupt.
-o# -> ORG mnemonic variation.
o1 -> ORG $XXXX
o2 -> *=$XXXX
o3 -> .OR $XXXX
-r -> Relocate calls out of normal address range. Only the lowest 13
bits in an address are significant in the 2600, so $1000 is
equivalent to $f000. Unfortunately, some ROM images use these
addresses interchangeably. If this flag is NOT used, a section of
code may look like this:
LF000 lda $D004 ; this actually refers to LF004
rts
LF004 .byte $3c
If this flag IS used, the same code would look like this:
LF000 lda LF004 ; ahh! This is a little clearer :)
rts
LF004 .byte $3c
It is important to note that if the -r flag is used, the code will
recompile fine, but the ROM image will be altered. If you want your
source to recompile into an exact copy of the original ROM image, do
not use this flag!
-s -> Includes the cycle count for each instruction. It only includes
the basic cycle count, and does not adjust for page boundries (YET).
Config File
The config file is a very simple text file that defines various
parameters for disassembly. Each line in the config file defines either a
range of addresses or the ORG. The addresses should be 4 digit hex numbers
and there should be only 1 space between the command and each address.
The valid config commands are as follows:
ORG XXXX
Defines where the ROM image should be disassembled to. Distella
automatically determines the origin of the ROM image. It takes into
consideration the start address (the address specified in lo/hi byte
format starting from the 4th byte from the end of the ROM image), and
the length of the image. The ORG command will override DiStella's
automatic determination. Be careful, if you are wrong, you won't get
much in the way of code on your output!
CODE XXXX XXXX
Defines an address range as being code. Distella is not perfect,
and can mistake code for data. The most common way that this happens
is when Absolute Indirect addressing is used. See the Limitations
section for more information.
The CODE command overrides DiStella's automatic DATA determination,
but is overridden by all other config commands, so if there are any
conflicts with DATA or ORG commands, the range in question will not be
handled as code.
GFX XXXX XXXX
Defines an address range as being graphics. This causes each byte
to be displayed visually in a comment, along with the address of each
byte to the right of the graphic display.
Here is an example from Pacman:
.byte $38 ; | XXX | $FDB5
.byte $7C ; | XXXXX | $FDB6
.byte $FE ; |XXXXXXX | $FDB7
.byte $E0 ; |XXX | $FDB8
.byte $FE ; |XXXXXXX | $FDB9
.byte $6C ; | XX XX | $FDBA
.byte $38 ; | XXX | $FDBB
.byte $7E ; | XXXXXX | $FDBC
.byte $E0 ; |XXX | $FDBD
.byte $C0 ; |XX | $FDBE
.byte $E0 ; |XXX | $FDBF
.byte $6C ; | XX XX | $FDC0
.byte $38 ; | XXX | $FDC1
Note that the graphics are upside down, this is common in games
because of the way the code is written.
The GFX command overrides the DATA command.
DATA XXXX XXXX
Defines an address range as being data. Up to 16 bytes will be
put on each line. If an address is reached that is referenced somewhere
else in the code, a new line will be created with its own .byte mnemonic.
Here is an example from Pacman:
LFF06: .byte $20,$40,$80,$60,$01,$05
LFF0C: .byte $00
LFF0D: .byte $00,$00,$01,$00,$00,$01,$06,$05,$04,$03,$02,$01
LFF19: .byte $00,$02
Limitations:
DiStella does a good job at determining the difference between code and
data. There are a couple of instances that may cause DiStella to confuse
code for data and visa-versa.
Absolute-Indirect Addressing:
DiStella traces the code in the ROM image starting at the reset
vector. Each time it sees a relative branch, it puts the branch address
in a queue only if that address hasn't been traced already. It continues
on until it reaches an RTS, RTI, or JMP. It then gets an address from
the queue and traces it repeating the process until no more addresses
are in the queue. Unfortunately, an absolute-indirect JMP - jmp ($ZP) -
doesn't provide enough information for DiStella. It is possible that
an entire section of the ROM image will be determined to be DATA when
it is really CODE. The best thing to do is to look at the code that
loads $ZP and $ZP+1 with the address to jump to (usually there is a list
of address like .byte $00,$f0,$20,$f0,$30,$f0) and use the CODE command
in a config file to force that area to be disassembled.
Relative "Unconditional" Branches:
Well, as you may or may not know, the 6502 processor does not have
a relative unconditional branch. Programmers can cheat and use a
relative branch as an absolute branch when they know the status of one
of the status register bits. For example, if this code is executed:
LDA #$01
BNE LF034
LF030 .byte $10,$20,$30,$40
LF034 RTS
LF030 will never be reached because 1 is never equal to zero!
DiStella isn't that smart! If you get a large section of code that is
unreadable, look for a relative branch directly before the unreadable
section. Chances are that the data starts directly after that relative
branch. You would need to use the DATA command in a config file to fix
this problem.
RTS Ending An Interrupt Routing:
Usually a BRK initiates an interrupt and the code pointed to by the
interrupt vector is executed. The proper way of exiting an interrupt is
to execute an RTI. A problem occurs when an RTS is executed instead.
This is because an RTS pulls the return address off of the stack and then
adds 1 to it, where an RTI does not. What does this mean to you? Well,
look at the following code:
LF000 LDA #$01
BRK
.byte $03 ;.SLO
LF004 TAX
This is an example of what the code might look like if an RTS is
used in the interrupt routine instead of RTI. If an RTI was used, the
code would look like this:
LF000 LDA #$01
BRK
LF003 TAX
The extra byte in the first code segment could cause DiStella to
get off sync, which has numerous side effects. Here it didn't, but keep
in mind that it is possible.
That's it! Have fun, and report all bugs and errors to:
Bob Colbert - rcolbert@oasis.novia.net
http://www.novia.net/~rcolbert
Dan Boris - dan.boris@coat.com
http://www.geocities.com/SiliconValley/9461/