Mercurial > repos > blastem
annotate README @ 922:913a6336ce20
Shift slot number to slot behavior mapping by six slots in H40 mode. This makes the line change slot align with the point at which the display turns on and off at the end of the active display area. Also fixed a regression in which an external slot got accidentally changed into a sprite draw slot
author | Michael Pavone <pavone@retrodev.com> |
---|---|
date | Thu, 28 Jan 2016 09:10:14 -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. |