view README @ 810:1f75614d7be8

Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
author Michael Pavone <>
date Sun, 26 Jul 2015 19:45:44 -0700
parents 2953708d02af
children f2f983e262e2
line wrap: on
line source
BlastEm 0.3.1


Extract this archive to a directory of your choosing. If you wish to change the
configuration settings, copy default.cfg to $HOME/.config/blastem/blastem.cfg and
modify the copy. You may also whish to add the blastem directory to your PATH
environment variable.


BlastEm does not have much of a GUI at the moment and expects a filename to be
passed to it at startup. You can do this by either running it from the command
line or associating it with a file type. To get a list of supported command
line options on Linux or OSX type:

	./blastem -h
From within your BlastEm directory. On Windows type:
	blastem.exe -h


Configuration is read from the file at $HOME/.config/blastem/blastem.cfg if it
exists, othwerise it is read from default.cfg from the same directory as the
BlastEm executable. Sections are denoted by a section name followed by an open
curly bracket, the section's contents and a closing curly bracket. Individual
configuration values are set by entering the value's name followed by a space
or tab and followed by the desired value.


The keys subsection of bindings maps keyboard keys to gamepad buttons or UI
actions. The key name goes on the left and the action is on the right.
Most keys are named for the character they produce when pressed. Additionally,
the arrow, enter and escape keys have the symbolic names up, down, left, right,
enter and esc respectively. Other keys that do not produce characters are not
yet supported.

The pads subsection is used to map gamepads and joysticks. Analog axes are not
currently supported. An example configuration is provided in default.cfg to map
SDL joystick 0 to the second controller.


The video section currently has three settings: "width", "vertex_shader" and
"fragment_shader". "width" sets the width of the window in pixels. Height is
calculated from this value. Both width and height can be overridden from the
command line. "vertex_shader" and "fragment_shader" control which GLSL shader
files are used for rendering the display when in Open GL rendering mode.
Shaders can be used to implement graphical filters and other effects.


The audio section has two config values: rate and buffer. rate selects the
sample rate and buffer sets the size of the output buffer in samples. 512 is
generally a good value, but if you're experiencing audio dropouts you might
want to increase it to 1024.


BlastEm has an integrated command-line debugger loosely based on GDB's
interface. The interface is very rough at the moment. Available commands in the
68K debugger are:
	b ADDRESS            - Set a breakpoint at ADDRESS
	d BREAKPOINT         - Delete a 68K breakpoint
	a ADDRESS            - Advance to address
	n                    - Advance to next instruction
	o                    - Advance to next instruction ignoring branches to
	                       lower addresses (good for breaking out of loops)
	s                    - Advance to next instruction (follows bsr/jsr)
	c                    - Continue
	bt                   - Print a backtrace
	p[/(x|X|d|c)] VALUE  - Print a register or memory location
	vs                   - Print VDP sprite list
	vr                   - Print VDP register info
	zb ADDRESS           - Set a Z80 breakpoint
	zp[/(x|X|d|c)] VALUE - Display a Z80 value
	q                    - Quit BlastEm
Available commands in the Z80 debugger are:
	b  ADDRESS           - Set a breakpoint at ADDRESS
	de BREAKPOINT        - Delete a Z80 breakpoint
	a  ADDRESS           - Advance to address
	n                    - Advance to next instruction
	c                    - Continue
	p[/(x|X|d|c)] VALUE  - Print a register or memory location
	di[/(x|X|d|c)] VALUE - Print VALUE before every debugger prompt
	q                    - Quit BlastEm

The -d flag can be used to cause BlastEm to start in the debugger.
Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key
by default) to enter the debugger while a game is running.

GDB Remote Debugging

In addition to the native debugger, BlastEm can also act as a GDB remote
debugging stub. To use this, you'll want to configure your Makefile to produce
both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with
the ELF file. Once inside the gdb session, type:

	target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D

where BLASTEM_PATH is the relative or absolute path to your BlastEm
installation and ROM_FILE.bin is the name of the raw binary for your program.
BlastEm will halt at the beginning of your program's entry point and return
control to GDB. This will allow you to set breakpoints before your code runs.

On Windows, the procedure is slightly different. First run 
	blastem.exe ROM_FILE.bin -D
This will cause BlastEm to wait for a socket connection on port 1234. It will
appear to be frozen until gdb connects to it. Now open the ELF file in gdb
and type:

	target remote :1234

Trace points and watch points are not currently supported.

Included Tools

BlastEm ships with a few small utilities that leverage portions of the emulator
	dis       - 68K disassembler
	zdis      - Z80 disassembler
	vgmplay   - Very basic VGM player
	stateview - GST save state viewer


BlastEm is free software distributed under the terms of the GNU General Public
License version 3 or higher. This gives you the right to redistribute and/or
modify the program as long as you follow the terms of the license. See the file
COPYING for full license details.

Binary releases of BlastEm are packaged with GLEW and SDL2 which have thier own
licenses. See GLEW-LICENSE and SDL-LICENSE for details.