Mercurial > repos > blastem
annotate README @ 785:0e5f14d9a579
Prep for 0.3.0 release
author | Michael Pavone <pavone@retrodev.com> |
---|---|
date | Tue, 21 Jul 2015 22:03:58 -0700 |
parents | 69cfdc81a87c |
children | 2953708d02af |
rev | line source |
---|---|
785
0e5f14d9a579
Prep for 0.3.0 release
Michael Pavone <pavone@retrodev.com>
parents:
536
diff
changeset
|
1 BlastEm 0.3.0 |
468 | 2 ------------- |
3 | |
4 Installation | |
5 ------------ | |
6 | |
7 Extract this tarball to a directory of your choosing. If you wish to change the | |
8 configuration settings, copy default.cfg to ~/.config/blastem/blastem.cfg and | |
9 modify the copy. You may also whish to add the blastem directory to your PATH | |
10 environment variable. | |
11 | |
12 Configuration | |
13 ------------- | |
14 | |
15 Configuration is read from the file at ~/.config/blastem/blastem.cfg if it | |
16 exists othwerise it is read from default.cfg from the same directory as the | |
17 blastem executable. Sections are denoted by a section name followed by an open | |
18 curly bracket, the section's contents and a closing curly bracket. Individual | |
19 configuration values are set by entering the value's name followed by a space | |
20 or tab and followed by the desired value. | |
21 | |
22 Bindings | |
23 -------- | |
24 | |
25 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI | |
26 actions. The key name goes on the left and the action is on the right. | |
27 Most keys are named for the character they produce when pressed. Additionally, | |
28 the arrow, enter and escape keys have the symbolic names up, down, left, right, | |
29 enter and esc respectively. Other keys that do not produce characters are not | |
30 yet supported. | |
31 | |
32 The pads subsection is used to map gamepads and joysticks. Analog axes are not | |
33 currently supported. An example configuration is provided in default.cfg to map | |
34 SDL joystick 0 to the second controller. | |
35 | |
36 Video | |
37 ----- | |
38 | |
536 | 39 The video section currently has three settings: "width", "vertex_shader" and |
40 "fragment_shader". "width" sets the width of the window in pixels. Height is | |
41 calculated from this value. Both width and height can be overridden from the | |
42 command line. "vertex_shader" and "fragment_shader" control which GLSL shader | |
43 files are used for rendering the display when in Open GL rendering mode. | |
44 Shaders can be used to implement graphical filters and other effects. | |
468 | 45 |
46 Audio | |
47 ----- | |
48 | |
49 The audio section has two config values: rate and buffer. rate selects the | |
50 sample rate and buffer sets the size of the output buffer in samples. 512 is | |
51 generally a good value, but if you're experiencing audio dropouts you might | |
52 want to increase it to 1024. | |
53 | |
54 Debugger | |
55 -------- | |
56 | |
57 BlastEm has an integrated command-line debugger loosely based on GDB's | |
58 interface. The interface is very rough at the moment. Available commands in the | |
59 68K debugger are: | |
60 b ADDRESS - Set a breakpoint at ADDRESS | |
536 | 61 d BREAKPOINT - Delete a 68K breakpoint |
468 | 62 a ADDRESS - Advance to address |
63 n - Advance to next instruction | |
536 | 64 o - Advance to next instruction ignoring branches to |
65 lower addresses (good for breaking out of loops) | |
66 s - Advance to next instruction (follows bsr/jsr) | |
468 | 67 c - Continue |
68 p[/(x|X|d|c)] VALUE - Print a register or memory location | |
69 vs - Print VDP sprite list | |
70 vr - Print VDP register info | |
536 | 71 zb ADDRESS - Set a Z80 breakpoint |
72 zp[/(x|X|d|c)] VALUE - Display a Z80 value | |
468 | 73 q - Quit BlastEm |
74 Available commands in the Z80 debugger are: | |
536 | 75 b ADDRESS - Set a breakpoint at ADDRESS |
76 de BREAKPOINT - Delete a Z80 breakpoint | |
77 a ADDRESS - Advance to address | |
468 | 78 n - Advance to next instruction |
79 c - Continue | |
80 p[/(x|X|d|c)] VALUE - Print a register or memory location | |
81 di[/(x|X|d|c)] VALUE - Print VALUE before every debugger prompt | |
82 q - Quit BlastEm | |
83 | |
84 The -d flag can be used to cause BlastEm to start in the debugger. | |
85 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key | |
86 by default)to enter the debugger while a game is running. | |
87 | |
536 | 88 GDB Remote Debugging |
89 -------------------- | |
90 | |
91 In addition to the native debugger, BlastEm can also act as a GDB remote | |
92 debugging stub. To use this, you'll want to configure your Makefile to produce | |
93 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with | |
94 the ELF file. Once inside the gdb session, type: | |
95 | |
96 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D | |
97 | |
98 where BLASTEM_PATH is the relative or absolute path to your BlastEm | |
99 installation and ROM_FILE.bin is the name of the raw binary for your program. | |
100 BlastEm will halt at the beginning of your program's entry point and return | |
101 control to GDB. This will allow you to set breakpoints before your code runs. | |
102 | |
103 Trace points and watch points are not currently supported. | |
104 | |
468 | 105 License |
106 ------- | |
107 | |
108 BlastEm is free software distributed under the terms of the GNU General Public | |
109 License version 3 or higher. This gives you the right to redistribute and/or | |
110 modify the program as long as you follow the terms of the license. See the file | |
111 COPYING for full license details. | |
112 | |
785
0e5f14d9a579
Prep for 0.3.0 release
Michael Pavone <pavone@retrodev.com>
parents:
536
diff
changeset
|
113 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
|
114 licenses. See GLEW-LICENSE and SDL-LICENSE for details. |