1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
BlastEm 0.4.0
-------------
Installation
------------
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.
Usage
-----
This version of BlastEm has an experimental GUI that is implemented as a Genesis
ROM running inside the emulator. This UI can be operated with either a mouse or
the first emulated gamepad. By default, both the keyboard and the first game
controller are mapped to said gamepad. For more information on bindings see the
Bindings section.
Some operations are currently only supported through the command line. 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
-------------
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.
Bindings
--------
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 first controller and SDL joystick 1 to the second
controller. The button assignments there work well for a 360 controller (at
least on Linux, it's possible the physical button to button number is different
on other operating systems).
The mice subsection is used to map mice to emulated Mega/Sega mice. The default
configuration maps both the first and second host mice to the first emulated
mouse. This should not need modification for most users.
One special mapping deserves a mention. By default, the 'r' key is mapped to
ui.release_mouse. When operating in windowed mode the mouse has a capture
behavior. Mouse events are ignored until you click in the window. The mouse
will then be "captured" and the cursor will be both made invisible and locked
to the window. The ui.release_mouse binding releases the mouse so it can be
used normally.
IO
--
This section controls which peripherals are attached to the emulated console.
IO assignments can be overridden by the ROM database when appropriate. For
instance, games with mouse support can automatically use the mouse and games
that only support 3-button pads can automatically force an appropriate pad.
Unforunately, the ROM database is not yet exhaustive so manual configuration
may be needed here in some cases.
Video
-----
The video section contains settings that affect the visual output of BlastEm.
"width" is used to control the window size when not in fullscreen mode. The
height of the window is calculated from this value. Both width and height can
be overridden from the command line.
"vertex_shader" and "fragment_shader" define the GLSL shader program that
produces the final image for each frame. Shaders can be used to add various
visual effects or enhancements. Currently BlastEm only ships with the default
shader. If you write your own shaders, place them in
$HOME/.config/blastem/shaders and then specify the basename of the new shader
files in the "vertex_shader" and "fragment_shader" config options. Note that
shaders are not available in the SDL fallback renderer.
"scanlines" controls whether there is any emulation of the gaps between display
lines that are present when driving a CRT television with a 240p signal. This
emulation is very basic at the moment so this option is off by default.
"vsync" controls whether the drawing of frames is synchronized to the monitor
refresh rate. Valid values for this setting are "off", "on" and "tear". The
latter will attempt to use the "late tear" option if it's available and normal
vsync otherwise. Currently it's recommended to leave this at the default of
"off" as BlastEm synchronizes to audio and does not yet have the necessary code
to fully handle conflicts between the audio rate and monitor refresh rate.
Additionally, the "turbo" feature does not function properly with vsync
enabled. These issues will be addressed in a future release. If you wish to use
vsync, please see the VSync section at the bottom of the README.
Audio
-----
The audio section contains settings that affect the audio output of BlastEm
"rate" selects the preferred sample rate for audio output. Your operating
system may not accept this value in which case a different rate will be chosen.
This should generally be either the native sample rate of your sound card or an
integral divisor of it. Most modern sound cards have a native output rate that
is a multiple of 48000 Hz so the default setting should work well for most users.
"buffer size" controls how large of a buffer uses for audio data. Smaller values
will reduce latency, but too small of a value can lead to dropouts. 512 works
well for me, but a higher or lower value may be more appropriate for your system.
"lowpass_cutoff" controls the cutoff, or knee, frequency of the RC-style
low-pass filter. The default value of 3390 Hz is supposedly what is present in
at least some Genesis/Megadrive models. Other models reportedly use an even
lower value.
Debugger
--------
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
di[/(x|X|d|c)] VALUE - Print a register or memory location when a
breakpoint is hit
co BREAKPOINT - Run a list of debugger commands when BREAKPOINT is
hit
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
code.
dis - 68K disassembler
zdis - Z80 disassembler
vgmplay - Very basic VGM player
stateview - GST save state viewer
VSync
-----
This section includes information
License
-------
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.
|
