Mercurial > repos > blastem
annotate README @ 1013:f2f983e262e2
WIP README updates
| author | Michael Pavone <pavone@retrodev.com> |
|---|---|
| date | Mon, 02 May 2016 00:31:44 -0700 |
| parents | 1f75614d7be8 |
| children | ef923c4b8977 |
| 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 | |
| 22 Some operations are currently only supported through the command line. To get a | |
| 23 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
|
24 |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
25 ./blastem -h |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
26 |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
27 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
|
28 |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
29 blastem.exe -h |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
30 |
| 468 | 31 Configuration |
| 32 ------------- | |
| 33 | |
|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
34 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
|
35 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
|
36 BlastEm executable. Sections are denoted by a section name followed by an open |
| 468 | 37 curly bracket, the section's contents and a closing curly bracket. Individual |
| 38 configuration values are set by entering the value's name followed by a space | |
| 39 or tab and followed by the desired value. | |
| 40 | |
| 41 Bindings | |
| 42 -------- | |
| 43 | |
| 44 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI | |
| 45 actions. The key name goes on the left and the action is on the right. | |
| 46 Most keys are named for the character they produce when pressed. Additionally, | |
| 47 the arrow, enter and escape keys have the symbolic names up, down, left, right, | |
| 48 enter and esc respectively. Other keys that do not produce characters are not | |
| 49 yet supported. | |
| 50 | |
| 51 The pads subsection is used to map gamepads and joysticks. Analog axes are not | |
| 52 currently supported. An example configuration is provided in default.cfg to map | |
| 1013 | 53 SDL joystick 0 to the first controller and SDL joystick 1 to the second |
| 54 controller. The button assignments there work well for a 360 controller (at | |
| 55 least on Linux, it's possible the physical button to button number is different | |
| 56 on other operating systems). | |
| 57 | |
| 58 The mice subsection is used to map mice to emulated Mega/Sega mice. The default | |
| 59 configuration maps both the first and second host mice to the first emulated | |
| 60 mouse. This should not need modification for most users. | |
| 61 | |
| 62 One special mapping deserves a mention. By default, the 'r' key is mapped to | |
| 63 ui.release_mouse. When operating in windowed mode the mouse has a capture | |
| 64 behavior. Mouse events are ignored until you click in the window. The mouse | |
| 65 will then be "captured" and the cursor will be both made invisible and locked | |
| 66 to the window. The ui.release_mouse binding releases the mouse so it can be | |
| 67 used normally. | |
| 68 | |
| 69 IO | |
| 70 -- | |
| 71 | |
| 72 This section controls which peripherals are attached to the emulated console. | |
| 73 IO assignments can be overridden by the ROM database when appropriate. For | |
| 74 instance, games with mouse support can automatically use the mouse and games | |
| 75 that only support 3-button pads can automatically force an appropriate pad. | |
| 76 Unforunately, the ROM database is not yet exhaustive so manual configuration | |
| 77 may be needed here in some cases. | |
| 468 | 78 |
| 79 Video | |
| 80 ----- | |
| 81 | |
| 1013 | 82 The video section contains settings that affect the visual output of BlastEm. |
| 83 | |
| 84 "width" is used to control the window size when not in fullscreen mode. The | |
| 85 height of the window is calculated from this value. Both width and height can | |
| 86 be overridden from the command line. | |
| 87 | |
| 88 "vertex_shader" and "fragment_shader" define the GLSL shader program that | |
| 89 produces the final image for each frame. Shaders can be used to add various | |
| 90 visual effects or enhancements. Currently BlastEm only ships with the default | |
| 91 shader. If you write your own shaders, place them in | |
| 92 $HOME/.config/blastem/shaders and then specify the basename of the new shader | |
| 93 files in the "vertex_shader" and "fragment_shader" config options. Note that | |
| 94 shaders are not available in the SDL fallback renderer. | |
| 95 | |
| 96 "scanlines" controls whether there is any emulation of the gaps between display | |
| 97 lines that are present when driving a CRT television with a 240p signal. This | |
| 98 emulation is very basic at the moment so this option is off by default. | |
| 99 | |
| 100 "vsync" controls whether the drawing of frames is synchronized to the monitor | |
| 101 refresh rate. Valid values for this setting are "off", "on" and "tear". The | |
| 102 latter will attempt to use the "late tear" option if it's available and normal | |
| 103 vsync otherwise. Currently it's recommended to leave this at the default of | |
| 104 "off" as BlastEm synchronizes to audio and does not yet have the necessary code | |
| 105 to fully handle conflicts between the audio rate and monitor refresh rate. | |
| 106 Additionally, the "turbo" feature does not function properly with vsync | |
| 107 enabled. These issues will be addressed in a future release. If you wish to use | |
| 108 vsync, please see the VSync section at the bottom of the README. | |
| 468 | 109 |
| 110 Audio | |
| 111 ----- | |
| 112 | |
| 1013 | 113 The audio section contains settings that affect the audio output of BlastEm |
| 114 | |
| 115 "rate" selects the preferred sample rate for audio output. Your operating | |
| 116 system may not accept this value in which case a different rate will be chosen. | |
| 117 This should generally be either the native sample rate of your sound card or an | |
| 118 integral divisor of it. Most modern sound cards have a native output rate that | |
| 119 is a multiple of 48000 Hz so the default setting should work well for most users. | |
| 120 | |
| 121 "buffer size" controls how large of a buffer uses for audio data. Smaller values | |
| 122 will reduce latency, but too small of a value can lead to dropouts. 512 works | |
| 123 well for me, but a higher or lower value may be more appropriate for your system. | |
| 124 | |
| 125 "lowpass_cutoff" controls the cutoff, or knee, frequency of the RC-style | |
| 126 low-pass filter. The default value of 3390 Hz is supposedly what is present in | |
| 127 at least some Genesis/Megadrive models. Other models reportedly use an even | |
| 128 lower value. | |
| 468 | 129 |
| 130 Debugger | |
| 131 -------- | |
| 132 | |
| 133 BlastEm has an integrated command-line debugger loosely based on GDB's | |
| 134 interface. The interface is very rough at the moment. Available commands in the | |
| 135 68K debugger are: | |
| 136 b ADDRESS - Set a breakpoint at ADDRESS | |
| 536 | 137 d BREAKPOINT - Delete a 68K breakpoint |
| 1013 | 138 di[/(x|X|d|c)] VALUE - Print a register or memory location when a |
| 139 breakpoint is hit | |
| 140 co BREAKPOINT - Run a list of debugger commands when BREAKPOINT is | |
| 141 hit | |
| 468 | 142 a ADDRESS - Advance to address |
| 143 n - Advance to next instruction | |
| 536 | 144 o - Advance to next instruction ignoring branches to |
| 145 lower addresses (good for breaking out of loops) | |
| 146 s - Advance to next instruction (follows bsr/jsr) | |
| 468 | 147 c - Continue |
|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
148 bt - Print a backtrace |
| 468 | 149 p[/(x|X|d|c)] VALUE - Print a register or memory location |
| 150 vs - Print VDP sprite list | |
| 151 vr - Print VDP register info | |
| 536 | 152 zb ADDRESS - Set a Z80 breakpoint |
| 153 zp[/(x|X|d|c)] VALUE - Display a Z80 value | |
| 468 | 154 q - Quit BlastEm |
| 155 Available commands in the Z80 debugger are: | |
| 536 | 156 b ADDRESS - Set a breakpoint at ADDRESS |
| 157 de BREAKPOINT - Delete a Z80 breakpoint | |
| 158 a ADDRESS - Advance to address | |
| 468 | 159 n - Advance to next instruction |
| 160 c - Continue | |
| 161 p[/(x|X|d|c)] VALUE - Print a register or memory location | |
| 162 di[/(x|X|d|c)] VALUE - Print VALUE before every debugger prompt | |
| 163 q - Quit BlastEm | |
| 164 | |
| 165 The -d flag can be used to cause BlastEm to start in the debugger. | |
| 166 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
|
167 by default) to enter the debugger while a game is running. |
| 468 | 168 |
| 536 | 169 GDB Remote Debugging |
| 170 -------------------- | |
| 171 | |
| 172 In addition to the native debugger, BlastEm can also act as a GDB remote | |
| 173 debugging stub. To use this, you'll want to configure your Makefile to produce | |
| 174 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with | |
| 175 the ELF file. Once inside the gdb session, type: | |
| 176 | |
| 177 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D | |
| 178 | |
| 179 where BLASTEM_PATH is the relative or absolute path to your BlastEm | |
| 180 installation and ROM_FILE.bin is the name of the raw binary for your program. | |
| 181 BlastEm will halt at the beginning of your program's entry point and return | |
| 182 control to GDB. This will allow you to set breakpoints before your code runs. | |
| 183 | |
|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
184 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
|
185 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
|
186 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
|
187 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
|
188 and type: |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
189 |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
190 target remote :1234 |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
191 |
| 536 | 192 Trace points and watch points are not currently supported. |
| 193 | |
|
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
|
194 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
|
195 -------------- |
|
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
196 |
|
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
197 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
|
198 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
|
199 |
|
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
200 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
|
201 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
|
202 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
|
203 stateview - GST save state viewer |
| 1013 | 204 |
| 205 VSync | |
| 206 ----- | |
| 207 | |
| 208 This section includes information | |
|
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
|
209 |
| 468 | 210 License |
| 211 ------- | |
| 212 | |
| 213 BlastEm is free software distributed under the terms of the GNU General Public | |
| 214 License version 3 or higher. This gives you the right to redistribute and/or | |
| 215 modify the program as long as you follow the terms of the license. See the file | |
| 216 COPYING for full license details. | |
| 217 | |
|
785
0e5f14d9a579
Prep for 0.3.0 release
Michael Pavone <pavone@retrodev.com>
parents:
536
diff
changeset
|
218 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
|
219 licenses. See GLEW-LICENSE and SDL-LICENSE for details. |