Mercurial > repos > blastem

comparison README @ 1066:58e3d50f6a4e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated README
author Michael Pavone <pavone@retrodev.com>
date Thu, 04 Aug 2016 19:27:04 -0700
parents 216fa63749b3
children dc05e3a7d8da
comparison
equal deleted inserted replaced
1065:a9de38e3bd20 1066:58e3d50f6a4e
1 BlastEm 0.4.0 1 BlastEm 0.4.1
2 ------------- 2 -------------
3 3
4 Installation 4 Installation
5 ------------ 5 ------------
6 6
7 Extract this archive to a directory of your choosing. If you wish to change the 7 Extract this archive to a directory of your choosing. If you wish to change the
8 configuration settings, copy default.cfg to $HOME/.config/blastem/blastem.cfg and 8 configuration settings, copy default.cfg to $HOME/.config/blastem/blastem.cfg
9 modify the copy. You may also whish to add the blastem directory to your PATH 9 and modify the copy. If you are on Windows, the config file should be placed in
10 environment variable. 10 %localappdata%\blastem. You may also whish to add the blastem directory to your
11 PATH environment variable.
12
13 NOTE: Prior to version 0.4.1, BlastEm was still using Unixy locations for config
14 and save files. If you're upgrading from a previous version on Windows, you will
15 need to move them manually. For config files, the relevant paths are in the
16 previous paragraph. For save files, move all the directories found in
17 %userprofile%\.local\share\blastem to %localappdata%\blastem
11 18
12 Usage 19 Usage
13 ----- 20 -----
14 21
15 This version of BlastEm has an experimental GUI that is implemented as a Genesis 22 This version of BlastEm has an experimental GUI that is implemented as a Genesis
19 Bindings section. 26 Bindings section.
20 27
21 Some operations are currently only supported through the command line. To get a 28 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: 29 list of supported command line options on Linux or OSX type:
23 30
24 ./blastem -h 31 ./blastem -h
25 32
26 From within your BlastEm directory. On Windows type: 33 From within your BlastEm directory. On Windows type:
27 34
28 blastem.exe -h 35 blastem.exe -h
29 36
30 Lock-On Support 37 Lock-On Support
31 --------------- 38 ---------------
32 39
33 This version of BlastEm has some preliminary support for Sonic & Knuckles lock 40 This version of BlastEm has some preliminary support for Sonic & Knuckles lock
34 on technology. This is only available from the command line at the moment. To 41 on technology. This is only available from the command line at the moment. To
35 use it specify the Sonic & Knuckles ROM as the primary ROM and specify the ROM 42 use it specify the Sonic & Knuckles ROM as the primary ROM and specify the ROM
36 to be locked on using the -o option. As an example: 43 to be locked on using the -o option. As an example:
37 44
38 ./blastem ~/romz/sonic_and_knuckles.bin -o ~/romz/sonic3.bin 45 ./blastem ~/romz/sonic_and_knuckles.bin -o ~/romz/sonic3.bin
39 46
40 Please note that Sonic 2 lock-on does not work at this time. Additionally the 47 Please note that Sonic 2 lock-on does not work at this time. Additionally the
41 save RAM added by Sonic 3 won't work either. 48 save RAM added by Sonic 3 won't work either.
42 49
43 Configuration 50 Configuration
44 ------------- 51 -------------
45 52
46 Configuration is read from the file at $HOME/.config/blastem/blastem.cfg if it 53 Configuration is read from the file at $HOME/.config/blastem/blastem.cfg on
47 exists, othwerise it is read from default.cfg from the same directory as the 54 Unix-like systems and %localappdata%\blastem\blastem.cfg if it exists.
48 BlastEm executable. Sections are denoted by a section name followed by an open 55 Othwerise it is read from default.cfg from the same directory as the BlastEm
49 curly bracket, the section's contents and a closing curly bracket. Individual 56 executable. Sections are denoted by a section name followed by an open curly
57 bracket, the section's contents and a closing curly bracket. Individual
50 configuration values are set by entering the value's name followed by a space 58 configuration values are set by entering the value's name followed by a space
51 or tab and followed by the desired value. 59 or tab and followed by the desired value.
52 60
53 Bindings 61 Bindings
54 -------- 62 --------
55 63
56 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI 64 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI
57 actions. The key name goes on the left and the action is on the right. 65 actions. The key name goes on the left and the action is on the right.
58 Most keys are named for the character they produce when pressed. Additionally, 66 Most keys are named for the character they produce when pressed. For keys that
59 the arrow, enter and escape keys have the symbolic names up, down, left, right, 67 don't correspond to a normal character, check the list below:
60 enter and esc respectively. Other keys that do not produce characters are not 68
61 yet supported. 69 Name | Description
70 -----------------
71 up Up arrow
72 down Down arrow
73 left Left arrow
74 right Right arrow
75 space
76 tab
77 backspace Backspace on PC keyboards, Delete on Mac keyboards
78 esc
79 delete
80 lshift Left shift
81 rshift Right shift
82 lctrl Left control
83 rctrl Right control
84 lalt Left alt on PC keyboards, Option on Mac keyboards
85 ralt Right alt on PC keyboards, Option on Mac keyboards
86 home
87 end
88 pageup
89 pagedown
90 f1
91 f2
92 f3
93 f4
94 f5
95 f6
96 f7
97 f8
98 f9
99 f10
100 f11
101 f12
102 select
103 play
104 search
105 back
62 106
63 The pads subsection is used to map gamepads and joysticks. Analog axes are not 107 The pads subsection is used to map gamepads and joysticks. Analog axes are not
64 currently supported. An example configuration is provided in default.cfg to map 108 currently supported. An example configuration is provided in default.cfg to map
65 SDL joystick 0 to the first controller and SDL joystick 1 to the second 109 SDL joystick 0 to the first controller and SDL joystick 1 to the second
66 controller. The button assignments there work well for a 360 controller (at 110 controller. The button assignments there work well for a 360 controller (at
186 -------- 230 --------
187 231
188 BlastEm has an integrated command-line debugger loosely based on GDB's 232 BlastEm has an integrated command-line debugger loosely based on GDB's
189 interface. The interface is very rough at the moment. Available commands in the 233 interface. The interface is very rough at the moment. Available commands in the
190 68K debugger are: 234 68K debugger are:
191 b ADDRESS - Set a breakpoint at ADDRESS 235 b ADDRESS - Set a breakpoint at ADDRESS
192 d BREAKPOINT - Delete a 68K breakpoint 236 d BREAKPOINT - Delete a 68K breakpoint
193 co BREAKPOINT - Run a list of debugger commands each time 237 co BREAKPOINT - Run a list of debugger commands each time
194 BREAKPOINT is hit 238 BREAKPOINT is hit
195 a ADDRESS - Advance to address 239 a ADDRESS - Advance to address
196 n - Advance to next instruction 240 n - Advance to next instruction
197 o - Advance to next instruction ignoring branches to 241 o - Advance to next instruction ignoring branches to
198 lower addresses (good for breaking out of loops) 242 lower addresses (good for breaking out of loops)
199 s - Advance to next instruction (follows bsr/jsr) 243 s - Advance to next instruction (follows bsr/jsr)
200 c - Continue 244 c - Continue
201 bt - Print a backtrace 245 bt - Print a backtrace
202 p[/(x|X|d|c)] VALUE - Print a register or memory location 246 p[/(x|X|d|c)] VALUE - Print a register or memory location
203 di[/(x|X|d|c)] VALUE - Print a register or memory location each time 247 di[/(x|X|d|c)] VALUE - Print a register or memory location each time
204 a breakpoint is hit 248 a breakpoint is hit
205 vs - Print VDP sprite list 249 vs - Print VDP sprite list
206 vr - Print VDP register info 250 vr - Print VDP register info
207 zb ADDRESS - Set a Z80 breakpoint 251 zb ADDRESS - Set a Z80 breakpoint
208 zp[/(x|X|d|c)] VALUE - Display a Z80 value 252 zp[/(x|X|d|c)] VALUE - Display a Z80 value
209 q - Quit BlastEm 253 q - Quit BlastEm
210 Available commands in the Z80 debugger are: 254 Available commands in the Z80 debugger are:
211 b ADDRESS - Set a breakpoint at ADDRESS 255 b ADDRESS - Set a breakpoint at ADDRESS
212 de BREAKPOINT - Delete a Z80 breakpoint 256 de BREAKPOINT - Delete a Z80 breakpoint
213 a ADDRESS - Advance to address 257 a ADDRESS - Advance to address
214 n - Advance to next instruction 258 n - Advance to next instruction
215 c - Continue 259 c - Continue
216 p[/(x|X|d|c)] VALUE - Print a register or memory location 260 p[/(x|X|d|c)] VALUE - Print a register or memory location
217 di[/(x|X|d|c)] VALUE - Print a register or memory location each time 261 di[/(x|X|d|c)] VALUE - Print a register or memory location each time
218 a breakpoint is hit 262 a breakpoint is hit
219 q - Quit BlastEm 263 q - Quit BlastEm
220 264
221 The -d flag can be used to cause BlastEm to start in the debugger. 265 The -d flag can be used to cause BlastEm to start in the debugger.
222 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key 266 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key
223 by default) to enter the debugger while a game is running. To debug the menu 267 by default) to enter the debugger while a game is running. To debug the menu
224 ROM, use the -dm flag. 268 ROM, use the -dm flag.
229 In addition to the native debugger, BlastEm can also act as a GDB remote 273 In addition to the native debugger, BlastEm can also act as a GDB remote
230 debugging stub. To use this, you'll want to configure your Makefile to produce 274 debugging stub. To use this, you'll want to configure your Makefile to produce
231 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with 275 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with
232 the ELF file. Once inside the gdb session, type: 276 the ELF file. Once inside the gdb session, type:
233 277
234 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D 278 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D
235 279
236 where BLASTEM_PATH is the relative or absolute path to your BlastEm 280 where BLASTEM_PATH is the relative or absolute path to your BlastEm
237 installation and ROM_FILE.bin is the name of the raw binary for your program. 281 installation and ROM_FILE.bin is the name of the raw binary for your program.
238 BlastEm will halt at the beginning of your program's entry point and return 282 BlastEm will halt at the beginning of your program's entry point and return
239 control to GDB. This will allow you to set breakpoints before your code runs. 283 control to GDB. This will allow you to set breakpoints before your code runs.
240 284
241 On Windows, the procedure is slightly different. First run 285 On Windows, the procedure is slightly different. First run
242 blastem.exe ROM_FILE.bin -D 286 blastem.exe ROM_FILE.bin -D
243 This will cause BlastEm to wait for a socket connection on port 1234. It will 287 This will cause BlastEm to wait for a socket connection on port 1234. It will
244 appear to be frozen until gdb connects to it. Now open the ELF file in gdb 288 appear to be frozen until gdb connects to it. Now open the ELF file in gdb
245 and type: 289 and type:
246 290
247 target remote :1234 291 target remote :1234
248 292
249 Trace points and watch points are not currently supported. 293 Trace points and watch points are not currently supported.
250 294
251 Included Tools 295 Included Tools
252 -------------- 296 --------------
253 297
254 BlastEm ships with a few small utilities that leverage portions of the emulator 298 BlastEm ships with a few small utilities that leverage portions of the emulator
255 code. 299 code.
256 300
257 dis - 68K disassembler 301 dis - 68K disassembler
258 zdis - Z80 disassembler 302 zdis - Z80 disassembler
259 vgmplay - Very basic VGM player 303 vgmplay - Very basic VGM player
260 stateview - GST save state viewer 304 stateview - GST save state viewer
261 305
262 VSync 306 VSync
263 ----- 307 -----
264 308
265 This section includes information about using VSync with BlastEm. As mentioned 309 This section includes information about using VSync with BlastEm. As mentioned
266 above, the code is currently designed to only sync to audio and has some issues 310 above, the code is currently designed to only sync to audio and has some issues
282 former (apart from disabling VSync), but the latter can be dealt with by 326 former (apart from disabling VSync), but the latter can be dealt with by
283 lowering the default speed slightly in the "clocks" section. 327 lowering the default speed slightly in the "clocks" section.
284 328
285 A future release will support VSync in a less hacky fashion. 329 A future release will support VSync in a less hacky fashion.
286 330
331 Special Thanks
332 --------------
333
334 My work has been made much easier by the contributions of those in the Genesis
335 community past and present. I'd like to thank the people below for their help.
336
337 Nemesis - His work reverse engineering and documenting the VDP and
338 YM-2612 has saved me an immeasurable amount of time. I've
339 found both his sprite overflow test ROM and VDP FIFO
340 Testing ROM to be quite helpful.
341
342 Charles MacDonald - While it hasn't been updated in a while, I still find his
343 VDP document to be my favorite reference. His Genesis
344 hardware document has also come in handy.
345
346 Eke-Eke - Eke-Eke wrote a great document on the use of I2C EEPROM in
347 Genesis games and also left some useful very helpful
348 comments about problematic games in Genesis Plus GX
349
350 Bart Trzynadlowski - His documents on the Genecyst save-state format and the
351 mapper used in Super Street Fighter 2 were definitely
352 appreciated.
353
354 KanedaFR - Kaneda's SpritesMind forum is a great resource for the
355 Sega development community.
356
357 I'd also like to thank the following people who have performed compatibility
358 testing or submitted helpful bug reports
359
360 Mickael Vaseux, Sik, Tim Lawrence, ComradeOj, Vladikcomper
361
287 License 362 License
288 ------- 363 -------
289 364
290 BlastEm is free software distributed under the terms of the GNU General Public 365 BlastEm is free software distributed under the terms of the GNU General Public
291 License version 3 or higher. This gives you the right to redistribute and/or 366 License version 3 or higher. This gives you the right to redistribute and/or