Mercurial > repos > blastem
annotate README @ 1014:ef923c4b8977
More README updates
author | Michael Pavone <pavone@retrodev.com> |
---|---|
date | Mon, 02 May 2016 18:27:07 -0700 |
parents | f2f983e262e2 |
children | 216fa63749b3 |
rev | line source |
---|---|
1013 | 1 BlastEm 0.4.0 |
468 | 2 ------------- |
3 | |
4 Installation | |
5 ------------ | |
6 | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
7 Extract this archive to a directory of your choosing. If you wish to change the |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
8 configuration settings, copy default.cfg to $HOME/.config/blastem/blastem.cfg and |
468 | 9 modify the copy. You may also whish to add the blastem directory to your PATH |
10 environment variable. | |
11 | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
12 Usage |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
13 ----- |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
14 |
1013 | 15 This version of BlastEm has an experimental GUI that is implemented as a Genesis |
16 ROM running inside the emulator. This UI can be operated with either a mouse or | |
17 the first emulated gamepad. By default, both the keyboard and the first game | |
18 controller are mapped to said gamepad. For more information on bindings see the | |
19 Bindings section. | |
20 | |
21 Some operations are currently only supported through the command line. To get a | |
22 list of supported command line options on Linux or OSX type: | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
23 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
24 ./blastem -h |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
25 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
26 From within your BlastEm directory. On Windows type: |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
27 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
28 blastem.exe -h |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
29 |
468 | 30 Configuration |
31 ------------- | |
32 | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
33 Configuration is read from the file at $HOME/.config/blastem/blastem.cfg if it |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
34 exists, othwerise it is read from default.cfg from the same directory as the |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
35 BlastEm executable. Sections are denoted by a section name followed by an open |
468 | 36 curly bracket, the section's contents and a closing curly bracket. Individual |
37 configuration values are set by entering the value's name followed by a space | |
38 or tab and followed by the desired value. | |
39 | |
40 Bindings | |
41 -------- | |
42 | |
43 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI | |
44 actions. The key name goes on the left and the action is on the right. | |
45 Most keys are named for the character they produce when pressed. Additionally, | |
46 the arrow, enter and escape keys have the symbolic names up, down, left, right, | |
47 enter and esc respectively. Other keys that do not produce characters are not | |
48 yet supported. | |
49 | |
50 The pads subsection is used to map gamepads and joysticks. Analog axes are not | |
51 currently supported. An example configuration is provided in default.cfg to map | |
1013 | 52 SDL joystick 0 to the first controller and SDL joystick 1 to the second |
53 controller. The button assignments there work well for a 360 controller (at | |
54 least on Linux, it's possible the physical button to button number is different | |
55 on other operating systems). | |
56 | |
57 The mice subsection is used to map mice to emulated Mega/Sega mice. The default | |
58 configuration maps both the first and second host mice to the first emulated | |
59 mouse. This should not need modification for most users. | |
60 | |
61 One special mapping deserves a mention. By default, the 'r' key is mapped to | |
62 ui.release_mouse. When operating in windowed mode the mouse has a capture | |
63 behavior. Mouse events are ignored until you click in the window. The mouse | |
64 will then be "captured" and the cursor will be both made invisible and locked | |
65 to the window. The ui.release_mouse binding releases the mouse so it can be | |
66 used normally. | |
67 | |
68 IO | |
69 -- | |
70 | |
71 This section controls which peripherals are attached to the emulated console. | |
72 IO assignments can be overridden by the ROM database when appropriate. For | |
73 instance, games with mouse support can automatically use the mouse and games | |
74 that only support 3-button pads can automatically force an appropriate pad. | |
75 Unforunately, the ROM database is not yet exhaustive so manual configuration | |
76 may be needed here in some cases. | |
468 | 77 |
78 Video | |
79 ----- | |
80 | |
1013 | 81 The video section contains settings that affect the visual output of BlastEm. |
82 | |
83 "width" is used to control the window size when not in fullscreen mode. The | |
84 height of the window is calculated from this value. Both width and height can | |
85 be overridden from the command line. | |
86 | |
87 "vertex_shader" and "fragment_shader" define the GLSL shader program that | |
88 produces the final image for each frame. Shaders can be used to add various | |
89 visual effects or enhancements. Currently BlastEm only ships with the default | |
90 shader. If you write your own shaders, place them in | |
91 $HOME/.config/blastem/shaders and then specify the basename of the new shader | |
92 files in the "vertex_shader" and "fragment_shader" config options. Note that | |
93 shaders are not available in the SDL fallback renderer. | |
94 | |
95 "scanlines" controls whether there is any emulation of the gaps between display | |
96 lines that are present when driving a CRT television with a 240p signal. This | |
97 emulation is very basic at the moment so this option is off by default. | |
98 | |
99 "vsync" controls whether the drawing of frames is synchronized to the monitor | |
100 refresh rate. Valid values for this setting are "off", "on" and "tear". The | |
101 latter will attempt to use the "late tear" option if it's available and normal | |
102 vsync otherwise. Currently it's recommended to leave this at the default of | |
103 "off" as BlastEm synchronizes to audio and does not yet have the necessary code | |
104 to fully handle conflicts between the audio rate and monitor refresh rate. | |
105 Additionally, the "turbo" feature does not function properly with vsync | |
106 enabled. These issues will be addressed in a future release. If you wish to use | |
107 vsync, please see the VSync section at the bottom of the README. | |
468 | 108 |
109 Audio | |
110 ----- | |
111 | |
1014 | 112 The audio section contains settings that affect the audio output of BlastEm. |
1013 | 113 |
114 "rate" selects the preferred sample rate for audio output. Your operating | |
115 system may not accept this value in which case a different rate will be chosen. | |
116 This should generally be either the native sample rate of your sound card or an | |
117 integral divisor of it. Most modern sound cards have a native output rate that | |
118 is a multiple of 48000 Hz so the default setting should work well for most users. | |
119 | |
120 "buffer size" controls how large of a buffer uses for audio data. Smaller values | |
121 will reduce latency, but too small of a value can lead to dropouts. 512 works | |
122 well for me, but a higher or lower value may be more appropriate for your system. | |
123 | |
124 "lowpass_cutoff" controls the cutoff, or knee, frequency of the RC-style | |
125 low-pass filter. The default value of 3390 Hz is supposedly what is present in | |
126 at least some Genesis/Megadrive models. Other models reportedly use an even | |
127 lower value. | |
468 | 128 |
1014 | 129 Clocks |
130 ------ | |
131 | |
132 The clocks section contains settings that affect how fast things run. | |
133 | |
134 "m68k_divider" describes the relationsip between the master clock (which is | |
135 53693175 Hz for NTSC mode and 53203395 Hz for PAL mode). The default value of 7 | |
136 matches the real hardware. Set this to a lower number to overclock the 68000 | |
137 and set it to a higher number to underclock it. | |
138 | |
139 "max_cycles" controls how often the system is forced to synchronize all | |
140 hardware. BlastEm generally uses a sync on demand approach to synchronizing | |
141 components in the system. This can provide perfect synchronization for most | |
142 components, but since the Z80 can steal cycles from the 68000 at unpredictable | |
143 times 68000/Z80 synchronization is imperfect. The default value of 3420 | |
144 corresponds to the number of master clock cycles per line. Larger numbers may | |
145 produce a modest performance improvement whereas smaller numbers will improve | |
146 68000/Z80 synchronization. | |
147 | |
148 "speeds" controls the speed of the overall emulated console at different | |
149 presets. Preset 0 is the default speed and should normally be set to 100. The | |
150 other presets enable the slow/turbo mode functionality. | |
151 | |
152 UI | |
153 -- | |
154 | |
155 The UI section contains settings that affect the graphical user interface. | |
156 | |
157 "rom" determines the path of the Genesis/Megadrive ROM that implements the UI. | |
158 Relative paths will be loaded relative to the BlastEm executable. | |
159 | |
160 Other Settings | |
161 -------------- | |
162 | |
163 "default_region" determines the console region that will be used when region | |
164 detection fails and when there are multiple valid regions. The default of 'U' | |
165 specifies a 60Hz "foreign" console. | |
166 | |
468 | 167 Debugger |
168 -------- | |
169 | |
170 BlastEm has an integrated command-line debugger loosely based on GDB's | |
171 interface. The interface is very rough at the moment. Available commands in the | |
172 68K debugger are: | |
173 b ADDRESS - Set a breakpoint at ADDRESS | |
536 | 174 d BREAKPOINT - Delete a 68K breakpoint |
1014 | 175 co BREAKPOINT - Run a list of debugger commands each time |
176 BREAKPOINT is hit | |
468 | 177 a ADDRESS - Advance to address |
178 n - Advance to next instruction | |
536 | 179 o - Advance to next instruction ignoring branches to |
180 lower addresses (good for breaking out of loops) | |
181 s - Advance to next instruction (follows bsr/jsr) | |
468 | 182 c - Continue |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
183 bt - Print a backtrace |
468 | 184 p[/(x|X|d|c)] VALUE - Print a register or memory location |
1014 | 185 di[/(x|X|d|c)] VALUE - Print a register or memory location each time |
186 a breakpoint is hit | |
468 | 187 vs - Print VDP sprite list |
188 vr - Print VDP register info | |
536 | 189 zb ADDRESS - Set a Z80 breakpoint |
190 zp[/(x|X|d|c)] VALUE - Display a Z80 value | |
468 | 191 q - Quit BlastEm |
192 Available commands in the Z80 debugger are: | |
536 | 193 b ADDRESS - Set a breakpoint at ADDRESS |
194 de BREAKPOINT - Delete a Z80 breakpoint | |
195 a ADDRESS - Advance to address | |
468 | 196 n - Advance to next instruction |
197 c - Continue | |
198 p[/(x|X|d|c)] VALUE - Print a register or memory location | |
1014 | 199 di[/(x|X|d|c)] VALUE - Print a register or memory location each time |
200 a breakpoint is hit | |
468 | 201 q - Quit BlastEm |
202 | |
203 The -d flag can be used to cause BlastEm to start in the debugger. | |
204 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key | |
1014 | 205 by default) to enter the debugger while a game is running. To debug the menu |
206 ROM, use the -dm flag. | |
468 | 207 |
536 | 208 GDB Remote Debugging |
209 -------------------- | |
210 | |
211 In addition to the native debugger, BlastEm can also act as a GDB remote | |
212 debugging stub. To use this, you'll want to configure your Makefile to produce | |
213 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with | |
214 the ELF file. Once inside the gdb session, type: | |
215 | |
216 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D | |
217 | |
218 where BLASTEM_PATH is the relative or absolute path to your BlastEm | |
219 installation and ROM_FILE.bin is the name of the raw binary for your program. | |
220 BlastEm will halt at the beginning of your program's entry point and return | |
221 control to GDB. This will allow you to set breakpoints before your code runs. | |
222 | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
223 On Windows, the procedure is slightly different. First run |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
224 blastem.exe ROM_FILE.bin -D |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
225 This will cause BlastEm to wait for a socket connection on port 1234. It will |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
226 appear to be frozen until gdb connects to it. Now open the ELF file in gdb |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
227 and type: |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
228 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
229 target remote :1234 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
230 |
536 | 231 Trace points and watch points are not currently supported. |
232 | |
810
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
233 Included Tools |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
234 -------------- |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
235 |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
236 BlastEm ships with a few small utilities that leverage portions of the emulator |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
237 code. |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
238 |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
239 dis - 68K disassembler |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
240 zdis - Z80 disassembler |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
241 vgmplay - Very basic VGM player |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
242 stateview - GST save state viewer |
1013 | 243 |
244 VSync | |
245 ----- | |
246 | |
1014 | 247 This section includes information about using VSync with BlastEm. As mentioned |
248 above, the code is currently designed to only sync to audio and has some issues | |
249 with VSync as a result. That said, if your computer is fast enough and you | |
250 don't care about turbo mode, it can generally made to work. | |
251 | |
252 The native refresh rate of an NTSC Genesis is approximately 59.92 Hz which is | |
253 probably not the native refresh rate of your monitor. Fortunately, it is | |
254 most likely lower than your refresh rate. As long as this is true, VSync will | |
255 generally work as long as your computer is fast enough to cope with the time | |
256 lost waiting for VSync and the audio buffer is large enough to not run out of | |
257 samples during that delay. Latency will suffer a bit and you'll get a doubled | |
258 frame, but things will be fine. | |
259 | |
260 If you enable VSync and you're getting audio dropouts, first try doubling the | |
261 audio buffer setting. If you still experience dropouts, it's possible your | |
262 computer is not fast enough or that your monitor's actual refresh rate is in | |
263 fact lower than that of the emualted console. Not much can be done about the | |
264 former (apart from disabling VSync), but the latter can be dealt with by | |
265 lowering the default speed slightly in the "clocks" section. | |
266 | |
267 A future release will support VSync in a less hacky fashion. | |
810
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
268 |
468 | 269 License |
270 ------- | |
271 | |
272 BlastEm is free software distributed under the terms of the GNU General Public | |
273 License version 3 or higher. This gives you the right to redistribute and/or | |
274 modify the program as long as you follow the terms of the license. See the file | |
275 COPYING for full license details. | |
276 | |
785
0e5f14d9a579
Prep for 0.3.0 release
Michael Pavone <pavone@retrodev.com>
parents:
536
diff
changeset
|
277 Binary releases of BlastEm are packaged with GLEW and SDL2 which have thier own |
0e5f14d9a579
Prep for 0.3.0 release
Michael Pavone <pavone@retrodev.com>
parents:
536
diff
changeset
|
278 licenses. See GLEW-LICENSE and SDL-LICENSE for details. |