annotate README @ 1036:fc29a122f817

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