Click And See

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 singular GZIPped and PKZIPped 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.

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 [-acf] <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.
The cartridge attributes which GBLIST shows in its output deserve some additional explanation:
   J  - Cartridge produced for Japan only.
   S  - Cartridge extended for Super GameBoy.
   C  - Cartridge extended for Color GameBoy.
   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.

FDSLIST <file1>.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.

PSGPLAY [-l] [-v<volume>] [-f<freq>] <file1> <file2> ...

This utility will play several kinds of sound files saved by some emulators. It will also convert some of these files into simplified .SND format. Wildcards are understood. PSGPLAY recognizes following formats:
  .SND - Simplified format where data is written in the
         Channel/Frequency/Volume packets.
  .PSG - Files containing AY8910 or SN76489 data.
and acepts following options:
  -l  - Loop play.
  -v  - Set volume to a given value (0..255).
  -f  - Set tempo to a given frequency (Hz).
WARNING: Current version of PSGPLAY does not support .PSG files, only .SND ones!

SND2MID [<infile> [<outfile>]]

This is a convertor from the .SND format into standard .MID. It will send data to the standard output, and get data from the standard input if no respective filenames were given. The quality of results may greatly vary. The convertor assumes GeneralMIDI MIDI patches.

©1998 Copyright by Marat Fayzullin