Mercurial > repos > blastem
comparison README @ 1066:58e3d50f6a4e
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 |