EMUTools

by Marat Fayzullin

What is EMUTools?

EMUTools is a set of simple utilities which I wrote to handle various ROM images, play and convert soundtrack files, disassemble programs, and perform other small but helpful tasks. EMUTools are available from

http://www.komkon.org/fms/EMUL8/

All programs will automatically unpack GZIPped files when compiled with #define ZLIB. You can find out whether your copy of a program can do that by typing its name without parameters: there should be an explicit mention of this feature in the help text printed by a program.

Copyright Notice

Both EMUTools and EMULib source code and documentation are copyrighted by me, Marat Fayzullin. Following restrictions apply to these materials:

How To Compile EMUTools

If you've obtained the source code version of EMUTools, check the Makefile for compilation options first. Your actual Makefile may differ from the original one as "make" utilities behave differently on various platforms. You may need additional modules from EMULib, available at the same WWW site as EMUTools.

How To Use EMUTools?

BDIFF [-as] <file1> <file2>

BDIFF will compare two binary files and print out the differences side by side, in hexadecimal and ASCII formats. Options:
  -a  - Use ANSI color sequences to highlight differing bytes.
  -s  - Show complete hexadecimal dumps, not only the differences.

UNDOUBLE <infile> [<outfile>]

UNDOUBLE will check whether the given file contains doubled (quadrupled, etc.) copies of the same data and if so, write out a single copy of this data into the output file. It will use the standard output if the output filename is not given.

BEHEAD <bytes> [<infile> [<outfile>]]

BEHEAD will cut a given number of bytes off the head of the input file and write the result into given output file. It will use standard input and output if corresponding filenames are omitted.

DASM6502 [-o<origin>] [-h] <file>

This is a little 6502 disassembler. It will output disassembled code of a given binary file. Don't expect anything fancy though. If you are using DASM6502 to disassemble a NES/Famicom program, be aware that .NES ROM images contain a 16-byte header in the beginning, so you probably want to use -o-7FF0 option on them. Options:
  -o  - Count addresses from a given origin (in hexadecimal form,
        can be negative).
  -h  - Show original hexadecimal data beside disassembled code.

DASMZ80 [-o<origin>] [-h] <file>

This is a little Z80 disassembler. It will output disassembled code of a given binary file. Don't expect anything fancy though. Options:
  -o  - Count addresses from a given origin (in hexadecimal form,
        can be negative).
  -h  - Show original hexadecimal data beside disassembled code.

GBDASM [-o<origin>] [-hi] <file>

This is a little GameBoy disassembler. It will output disassembled code of a given binary file. Don't expect anything fancy though. GBDASM is almost identical to DASMZ80, but recognizes special GameBoy opcodes and cartridge headers. Options:
  -o  - Count addresses from a given origin (in hexadecimal form,
        can be negative).
  -h  - Show original hexadecimal data beside disassembled code.
  -i  - Show information from the GameBoy cartridge header.

GBLIST [-acfhp] <file1>.GB <file2>.GB ...

GBLIST is a tool to process GameBoy ROM images (.GB files). It extracts and verifies cartridge information from the images and may fix invalid images if requested. It will also list the images in an easy to read format, either as ASCII or as HTML text. GBLIST understands wildcards. Options:
  -a  - Use ANSI color sequences to highlight errors.
  -c  - Check CMP/CRC and file sizes.
  -f  - Fix CMP/CRC and file sizes. The fixed image will be written
        into a file with extension .FIX.
  -h  - Output results in HTML format.
  -p  - Show supposed producer.
The cartridge attributes which GBLIST shows in its output deserve some additional explanation:
   G  - Cartridge is compatible with the "normal" GameBoy.
   S  - Cartridge is compatible with the Super GameBoy.
   C  - Cartridge is compatible with the GameBoy Color.
   J  - Cartridge produced for Japan only.
   T  - Cartridge contains a timer (MBC3).
   U  - Cartirdge is a rumble pack (MBC5).
   R  - Cartridge contains ROM (i.e. [R]eadable).
   W  - Cartridge contains RAM (i.e. [W]ritable).
   B  - Cartridge contains battery-backed RAM.
The last attribute is the memory bank controller (MBC) type:
   1  - Cartridge contains MBC1 chip.  
   2  - Cartridge contains MBC2 chip.  
   3  - Cartridge contains MBC3 chip.  
   5  - Cartridge contains MBC5 chip.  
   A  - Cartridge contains HuC1 chip.  
   B  - Cartridge contains HuC3 chip.  

NESLIST [-ahcpd] <file1>.NES <file2>.NES ...

NESLIST is a tool to process NES ROM images (.NES files). It extracts and verifies header information from the images, and may fix invalid images by truncating the unnecessary data and modifying the headers. Additionally, NESLIST will generate separate header files (.HDR) and try to write out Pasofami-compatible files, although the latter feature does not work very well. NESLIST understands wildcards. Options:
  -a  - Use ANSI color sequences to highlight errors.
  -h  - Write headers into separate .HDR files.
  -c  - Check file sizes.
  -p  - Generate PASOFAMI files: .PRM,.PRG,.CHR.
  -d  - Check ROMs for doubling and truncate.
The cartridge attributes which NESLIST shows in its output deserve some additional explanation:
   V  - Uses two screen buffers with vertical mirroring.
   H  - Uses two screen buffers with horizontal mirroring.
   4  - Cartridge has all four screen buffers.
   B  - Cartridge contains battery-backed RAM.
   T  - There is a 512-byte trainer.
   S  - This is a VS-System game.

GBALIST [-acfhp] <file1>.GBA <file2>.GBA ...

GBALIST is a tool to process GameBoy Advance ROM images (.GBA files). It extracts and verifies header information from the images. GBALIST understands wildcards. Options:
  -a  - Use ANSI color sequences to highlight errors.
  -c  - Check CMP.
  -f  - Fix CMP. The fixed image will be written into a file
        with extension .FIX.
  -h  - Output results in HTML format.
  -p  - Show supposed producer.

FDSLIST <file>.FDS

FDSLIST is a tool to list contents of the Famicom DiskSystem disk images (.FDS files). It prints a directory of files contained in one or more disk images stored in the given .FDS file. Each disk image is 65000 bytes long and corresponds to a single side of an FDS disk. There may be multiple images in a single .FDS file.

FAM2FDS <file>.FAM <file>.FDS

FAM2FDS will convert Famicom DiskSystem disk images from .FAM format to the .FDS format supported by iNES. Simply supply the program with names of the source .FAM file and the destination .FDS file.

©2001 Copyright by Marat Fayzullin