annotate README @ 766:1b2f8280ba81

WIP changes to support reading cart memory map from ROM DB
author Michael Pavone <pavone@retrodev.com>
date Sun, 05 Jul 2015 14:21:34 -0700
parents 69cfdc81a87c
children 0e5f14d9a579
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
1 BlastEm 0.2.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
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
7 Extract this tarball to a directory of your choosing. If you wish to change the
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
8 configuration settings, copy default.cfg to ~/.config/blastem/blastem.cfg and
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
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
12 Configuration
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
13 -------------
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
14
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
15 Configuration is read from the file at ~/.config/blastem/blastem.cfg if it
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
16 exists othwerise it is read from default.cfg from the same directory as the
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
17 blastem executable. Sections are denoted by a section name followed by an open
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
18 curly bracket, the section's contents and a closing curly bracket. Individual
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
19 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
20 or tab and followed by the desired value.
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
21
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
22 Bindings
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
23 --------
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
24
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
25 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
26 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
27 Most keys are named for the character they produce when pressed. Additionally,
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
28 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
29 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
30 yet supported.
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
31
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
32 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
33 currently supported. An example configuration is provided in default.cfg to map
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
34 SDL joystick 0 to the second controller.
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
35
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
36 Video
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
37 -----
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
38
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
39 The video section currently has three settings: "width", "vertex_shader" and
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
40 "fragment_shader". "width" sets the width of the window in pixels. Height is
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
41 calculated from this value. Both width and height can be overridden from the
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
42 command line. "vertex_shader" and "fragment_shader" control which GLSL shader
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
43 files are used for rendering the display when in Open GL rendering mode.
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
44 Shaders can be used to implement graphical filters and other effects.
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
45
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
46 Audio
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
47 -----
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
48
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
49 The audio section has two config values: rate and buffer. rate selects the
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
50 sample rate and buffer sets the size of the output buffer in samples. 512 is
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
51 generally a good value, but if you're experiencing audio dropouts you might
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
52 want to increase it to 1024.
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
53
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
54 Debugger
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
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
57 BlastEm has an integrated command-line debugger loosely based on GDB's
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
58 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
59 68K debugger are:
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
60 b ADDRESS - Set a breakpoint at ADDRESS
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
61 d BREAKPOINT - Delete a 68K breakpoint
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
62 a ADDRESS - Advance to address
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
63 n - Advance to next instruction
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
64 o - Advance to next instruction ignoring branches to
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
65 lower addresses (good for breaking out of loops)
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
66 s - Advance to next instruction (follows bsr/jsr)
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
67 c - Continue
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
68 p[/(x|X|d|c)] VALUE - Print a register or memory location
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
69 vs - Print VDP sprite list
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
70 vr - Print VDP register info
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
71 zb ADDRESS - Set a Z80 breakpoint
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
72 zp[/(x|X|d|c)] VALUE - Display a Z80 value
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
73 q - Quit BlastEm
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
74 Available commands in the Z80 debugger are:
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
75 b ADDRESS - Set a breakpoint at ADDRESS
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
76 de BREAKPOINT - Delete a Z80 breakpoint
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
77 a ADDRESS - Advance to address
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
78 n - Advance to next instruction
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
79 c - Continue
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
80 p[/(x|X|d|c)] VALUE - Print a register or memory location
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
81 di[/(x|X|d|c)] VALUE - Print VALUE before every debugger prompt
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
82 q - Quit BlastEm
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
83
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
84 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
85 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
86 by default)to enter the debugger while a game is running.
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
87
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
88 GDB Remote Debugging
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
89 --------------------
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
90
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
91 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
92 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
93 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
94 the ELF file. Once inside the gdb session, type:
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
95
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
96 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
97
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
98 where BLASTEM_PATH is the relative or absolute path to your BlastEm
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
99 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
100 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
101 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
102
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
103 Trace points and watch points are not currently supported.
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
104
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
105 License
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
106 -------
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
107
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
108 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
109 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
110 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
111 COPYING for full license details.
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
112