Commands for running Distella

[TonyA]

HI,

 

Are there any tutorials for using Distella? I have been able to use DASM and Stella, now working on using Distella to disassemble .bins.

 

I am using command prompt in windows xp, I need to know the steps from the start. Thanks.

 

Thank you.

TOny

[SeaGtGruff]

HI,

 

Are there any tutorials for using Distella? I have been able to use DASM and Stella, now working on using Distella to disassemble .bins.

 

I am using command prompt in windows xp, I need to know the steps from the start. Thanks.

 

Thank you.

TOny

 

Distella comes with a "distella.txt" file that explains how to use it, but it isn't a tutorial. First thing you need to know is that Distella can't handle ROMs larger than 4K, so if you want to disassemble a game that's larger than 4K, you'll need to split it up into 4K chunks. I wrote a little command line utility for that, called "SplitFile," which you can get here:

 

http://www.atariage.com/forums/index.php?s...c=66892&hl=

 

It's posted down towards the bottom of the thread. If you want instructions on how to use "SplitFile," you can just type "splitfile" at the command prompt and it will give you some help text-- otherwise, read my comments about it in that thread. (Note that I posted *two* versions of it, so be sure to get the second version.)

 

If you have a 4K ROM to work with, the command to disassemble it with Distella will be something like this:

 

[drive:\path\]DISTELLA [-options] [drive:\path\]rom_file [> [drive:\path\]asm_file]

 

[drive:\path\] is optional, but you'll need it if you aren't starting in the directory where Distella is, or if the rom_file isn't in that directory, or if you want the output asm_file to go in a different directory. It's a lot simpler to just start in the directory where Distella is, copy the rom_file there, and output the asm_file there as well.

 

[-options] are optional command switches that give specific instructions to Distella. Each command switch must be preceded by a dash or hyphen, and some command switches must be immediately followed by additional information. Distella 3.0 can disassemble Atari 7800 ROMs, too (and *those* ROMs *can* exceed 4K), but my comments assume that you're wanting to disassemble an Atari 2600 game. Some of the command switches you'll probably be interested in are as follows:

 

-a

Means "Don't add an 'A' to the commands where the A register is implied," e.g., "ROL" vs. "ROL A." The impact of this switch has to do with re-assembling a disassembly, because some assemblers want you to include an 'A' in those commands, and some assemblers want you to leave off the 'A.' If you're going to use DASM to re-assemble a disassembly, then you'll want to use the -a switch.

 

-b

Means "Use the BRK vector when disassembling." Most games don't use the BRK vector; they usually set the BRK vector to be the same as the startup/reset vector. The first time you disassemble a ROM file, it's best to leave off the -b switch. Then, if you look at the disassembly and notice that the BRK vector (last 2 bytes of the ROM, or $FFFE and $FFFF) are different than the startup/reset vector (the next-to-the-last 2 bytes, or $FFFC and $FFFD), then disassemble the ROM again, but this time use the -b switch.

 

-c[drive:\path\]cfg_file

Means "Use this configuration file when disassembling the ROM file." The switch is -c, and it must be immediately followed (i.e., with no separating space) by the name of the configuration file, including the drive and path if it isn't in the current directory. Note that if you're including the drive and path, then the path shouldn't contain any spaces in it. If the path *does* contain spaces, you *might* be able to put quotes around the drive, path, and file name, but I haven't tried that, so I don't know if it will confuse Distella. Again, it's much simpler to just keep everything in one directory-- Distella and its files, the ROM to be disassembled, the configuration file, the disassembled file, etc. The first time you disassemble a ROM file, you can leave off the -c switch, and see what you get. Then, based on those results, you can create a configuration file and start adding to it as needed. A configuration file is used to tell Distella which areas of the ROM contain code that can be disassembled, and which areas contain data that cannot be disassembled. If Distella disassembles data, the results will usually look like a lot of gibberish assembly commands. Also, disassembling data can cause Distella to mess up on disassembling any code that follows the data, because Distella may not begin on the correct byte (e.g., "STA COLUP0" is a 2-byte instruction, and if Distella starts disassembling it on the second byte, the results will be wrong).

 

-d

Means "Disable the automatic code detection logic." Normally, Distella tries to use a smart process to detect which areas contain code vs. which areas contain data that cannot be disassembled, based on things like the startup/reset vector, the BRK vector (if the -b switch is on), the target addresses of any JMP or JSR commands that were correctly disassembled, etc. The first time you disassemble a ROM file, you can leave off the -d switch and let Distella try to figure things out itself. Then you may want to disassemble again using the -d switch. However, if you use the -d switch, then it's best to use the -c switch as well, and use a configuration file to tell Distella where the code areas are and where the data areas are.

 

-k

Means "Use POKEY equates." I can't tell you much about this switch, but you can almost always leave it off, because very few games use POKEY equates (only 2 actual released games-- BallBlazer and Commando-- plus maybe a few homebrews). Use of the -k switch may interfere with the correct disassembly of bankswitching logic with certain bankswitching methods, so leave off the -k switch unless you're disassembling a game that you know for sure uses POKEY equates.

 

-o#

Means "Use the specified format for the 'ORG' statements." If you want Distella to use DASM's 'ORG' format, then use -o1.

 

-r

Means "Relocate references to addresses which are outside the normal range." This has to do with the fact that the Atari 2600 uses 13-bit addresses, so $1000 is the same as $F000. Use the -r switch to ensure that the addresses will be referenced correctly. But some games use(d) $1000 instead of $F000, so if you disassemble those games with the -r switch, and then re-assemble the disassembly, the re-assembled ROM won't be an exact binary match of the original ROM file (although it should still run the same way).

 

-s

Means "Include the machine cycle counts in the disassembly." This can be useful if you're going to be studying the disassembly for programming purposes, but the current version of Distella (3.0) doesn't adjust the cycle counts for situations like crossing a page boundary.

 

So to summarize, the easiest way to use Distella is to copy the ROM image you want to disassemble into Distella's directory, and let Distella put the disassembled listing there, too. If the ROM is larger than 4K, you can download my SplitFile utility and put it in that directory, too, then use it to split the ROM into as many 4K chunks as needed. Then you can disassemble each 4K chunk with Distella. It's easier to work with a non-bankswitched 4K game, though, since the code in one 4K bank might refer to code in another 4K bank. It's advisable to stick with non-bankswitched games while you're still learning how to use Distella, and wait until after you understand the use of the optional configuration file before trying to disassemble a bankswitched game.

 

Assuming you've got everything in one directory, and you've switched to that directory after starting up the command prompt, and you want a DASM-compatible disassembly, you just type something like this:

 

distella -a -o1 -r rom_file > asm_file

 

where rom_file is the name of the ROM file, and asm_file is the name you want the disassembly to have (e.g., distella -a -o1 -r adventur.bin > adventur.asm).

 

Then examine the resulting disassembly and look for places where the disassembly doesn't look right, which might be data areas. Then start making a configuration file to tell Distella which areas are code, and which areas are data, and try disassembling again with the -c switch. "distella.txt" has information about the configuration files.

 

Another option you might want to consider is using DIS6502 instead of Distella. DIS6502 doesn't come with an equates file for the Atari 2600, but I've made one for it. The advantage of DIS6502 is that it can work with ROM files larger than 4K, and disassembling is an interactive process, plus you can look at a dump of the ROM (as with Hack-O-Matic II) to help you see where the player data is. But that's a subject for another post!

 

Michael Rideout

[vectrex]

I know it's bad form to bump 12 year old threads but the suggestions here don't work with Turmoil rom I have. it plays in stella when I disassemble it:

 

 

./distella -pafs -o1 -b -r ./turmoil.bin > turmoil-1.s

(I tried many other command lines too, with and without -c -b -r -f -p)

 

and then assemble with dasm it I get either a 1030 byte binary (that loaded in stella and just shows a black screen) or 4098 bytes (black screen and that plays a screechy tone in a loop)

 

distella is ver 3.01

dasm is 2.20.11

 

any help? should I just use another disassembler if so which?

[+stephena]

At this point, it's probably best to just use Stella and have it generate a disassembly file directly. Stella (since at least version 4 or so) has Distella integrated, and can generate a much better disassembly than Distella standalone ever could, since it uses runtime analysis to figure out code vs. data sections, etc.

 

It currently only outputs a disassembly for single-banked ROMs, but that's all that Distella standalone does as well. Eventually we will add support for it to output multi-bank ROM disassembly (the functionality is all there in Stella, we just need to get to work on cleaning it up).

 

Also, the disassembly file that Stella outputs will always be of the correct size, and be immediately re-compilable into the same ROM.

 

For example, attached is the disassembly for Turmoil from the latest test build of Stella: Turmoil (1982) (20th Century Fox).asm

 

Note that you should play the game a little first, so that the disassembler has the opportunity to 'hit' the various sections and mark them as code/graphics/playfield/etc.

[vectrex]

wow that's like a million times more useful than the source I was stepping through commenting before I realized it didn't assemble :S

 

thanks for the tip.

[+stephena]

Just realized I didn't actually explain how to do it

• load a game and play it a little while (try to exercise different code paths, die once or twice, increase score to get all digits, etc)
• enter the debugger with '~', then type 'savedis'
• open the file that is generated by Stella and enjoy