Mercurial > repos > blastem
annotate README @ 875:54ffba3768d6
Make menu stuff work on Android (theoretically)
author | Michael Pavone <pavone@retrodev.com> |
---|---|
date | Sun, 08 Nov 2015 22:03:34 -0800 |
parents | 1f75614d7be8 |
children | f2f983e262e2 |
rev | line source |
---|---|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
1 BlastEm 0.3.1 |
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 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
15 BlastEm does not have much of a GUI at the moment and expects a filename to be |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
16 passed to it at startup. You can do this by either running it from the command |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
17 line or associating it with a file type. To get a list of supported command |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
18 line options on Linux or OSX type: |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
19 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
20 ./blastem -h |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
21 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
22 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
|
23 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
24 blastem.exe -h |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
25 |
468 | 26 Configuration |
27 ------------- | |
28 | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
29 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
|
30 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
|
31 BlastEm executable. Sections are denoted by a section name followed by an open |
468 | 32 curly bracket, the section's contents and a closing curly bracket. Individual |
33 configuration values are set by entering the value's name followed by a space | |
34 or tab and followed by the desired value. | |
35 | |
36 Bindings | |
37 -------- | |
38 | |
39 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI | |
40 actions. The key name goes on the left and the action is on the right. | |
41 Most keys are named for the character they produce when pressed. Additionally, | |
42 the arrow, enter and escape keys have the symbolic names up, down, left, right, | |
43 enter and esc respectively. Other keys that do not produce characters are not | |
44 yet supported. | |
45 | |
46 The pads subsection is used to map gamepads and joysticks. Analog axes are not | |
47 currently supported. An example configuration is provided in default.cfg to map | |
48 SDL joystick 0 to the second controller. | |
49 | |
50 Video | |
51 ----- | |
52 | |
536 | 53 The video section currently has three settings: "width", "vertex_shader" and |
54 "fragment_shader". "width" sets the width of the window in pixels. Height is | |
55 calculated from this value. Both width and height can be overridden from the | |
56 command line. "vertex_shader" and "fragment_shader" control which GLSL shader | |
57 files are used for rendering the display when in Open GL rendering mode. | |
58 Shaders can be used to implement graphical filters and other effects. | |
468 | 59 |
60 Audio | |
61 ----- | |
62 | |
63 The audio section has two config values: rate and buffer. rate selects the | |
64 sample rate and buffer sets the size of the output buffer in samples. 512 is | |
65 generally a good value, but if you're experiencing audio dropouts you might | |
66 want to increase it to 1024. | |
67 | |
68 Debugger | |
69 -------- | |
70 | |
71 BlastEm has an integrated command-line debugger loosely based on GDB's | |
72 interface. The interface is very rough at the moment. Available commands in the | |
73 68K debugger are: | |
74 b ADDRESS - Set a breakpoint at ADDRESS | |
536 | 75 d BREAKPOINT - Delete a 68K breakpoint |
468 | 76 a ADDRESS - Advance to address |
77 n - Advance to next instruction | |
536 | 78 o - Advance to next instruction ignoring branches to |
79 lower addresses (good for breaking out of loops) | |
80 s - Advance to next instruction (follows bsr/jsr) | |
468 | 81 c - Continue |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
82 bt - Print a backtrace |
468 | 83 p[/(x|X|d|c)] VALUE - Print a register or memory location |
84 vs - Print VDP sprite list | |
85 vr - Print VDP register info | |
536 | 86 zb ADDRESS - Set a Z80 breakpoint |
87 zp[/(x|X|d|c)] VALUE - Display a Z80 value | |
468 | 88 q - Quit BlastEm |
89 Available commands in the Z80 debugger are: | |
536 | 90 b ADDRESS - Set a breakpoint at ADDRESS |
91 de BREAKPOINT - Delete a Z80 breakpoint | |
92 a ADDRESS - Advance to address | |
468 | 93 n - Advance to next instruction |
94 c - Continue | |
95 p[/(x|X|d|c)] VALUE - Print a register or memory location | |
96 di[/(x|X|d|c)] VALUE - Print VALUE before every debugger prompt | |
97 q - Quit BlastEm | |
98 | |
99 The -d flag can be used to cause BlastEm to start in the debugger. | |
100 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
101 by default) to enter the debugger while a game is running. |
468 | 102 |
536 | 103 GDB Remote Debugging |
104 -------------------- | |
105 | |
106 In addition to the native debugger, BlastEm can also act as a GDB remote | |
107 debugging stub. To use this, you'll want to configure your Makefile to produce | |
108 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with | |
109 the ELF file. Once inside the gdb session, type: | |
110 | |
111 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D | |
112 | |
113 where BLASTEM_PATH is the relative or absolute path to your BlastEm | |
114 installation and ROM_FILE.bin is the name of the raw binary for your program. | |
115 BlastEm will halt at the beginning of your program's entry point and return | |
116 control to GDB. This will allow you to set breakpoints before your code runs. | |
117 | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
118 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
|
119 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
|
120 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
|
121 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
|
122 and type: |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
123 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
124 target remote :1234 |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
125 |
536 | 126 Trace points and watch points are not currently supported. |
127 | |
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
|
128 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
|
129 -------------- |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
130 |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
131 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
|
132 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
|
133 |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
134 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
|
135 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
|
136 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
|
137 stateview - GST save state viewer |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
138 |
468 | 139 License |
140 ------- | |
141 | |
142 BlastEm is free software distributed under the terms of the GNU General Public | |
143 License version 3 or higher. This gives you the right to redistribute and/or | |
144 modify the program as long as you follow the terms of the license. See the file | |
145 COPYING for full license details. | |
146 | |
785
0e5f14d9a579
Prep for 0.3.0 release
Michael Pavone <pavone@retrodev.com>
parents:
536
diff
changeset
|
147 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
|
148 licenses. See GLEW-LICENSE and SDL-LICENSE for details. |