annotate README @ 989:d70000fdff0b

Implemented IR and undefined bits of info word for address error exception frames
author Michael Pavone <>
date Wed, 27 Apr 2016 21:39:17 -0700
parents 1f75614d7be8
children f2f983e262e2
rev   line source
pavone@808 1 BlastEm 0.3.1
pavone@468 2 -------------
pavone@468 3
pavone@468 4 Installation
pavone@468 5 ------------
pavone@468 6
pavone@808 7 Extract this archive to a directory of your choosing. If you wish to change the
pavone@808 8 configuration settings, copy default.cfg to $HOME/.config/blastem/blastem.cfg and
pavone@468 9 modify the copy. You may also whish to add the blastem directory to your PATH
pavone@468 10 environment variable.
pavone@468 11
pavone@808 12 Usage
pavone@808 13 -----
pavone@808 14
pavone@808 15 BlastEm does not have much of a GUI at the moment and expects a filename to be
pavone@808 16 passed to it at startup. You can do this by either running it from the command
pavone@808 17 line or associating it with a file type. To get a list of supported command
pavone@808 18 line options on Linux or OSX type:
pavone@808 19
pavone@808 20 ./blastem -h
pavone@808 21
pavone@808 22 From within your BlastEm directory. On Windows type:
pavone@808 23
pavone@808 24 blastem.exe -h
pavone@808 25
pavone@468 26 Configuration
pavone@468 27 -------------
pavone@468 28
pavone@808 29 Configuration is read from the file at $HOME/.config/blastem/blastem.cfg if it
pavone@808 30 exists, othwerise it is read from default.cfg from the same directory as the
pavone@808 31 BlastEm executable. Sections are denoted by a section name followed by an open
pavone@468 32 curly bracket, the section's contents and a closing curly bracket. Individual
pavone@468 33 configuration values are set by entering the value's name followed by a space
pavone@468 34 or tab and followed by the desired value.
pavone@468 35
pavone@468 36 Bindings
pavone@468 37 --------
pavone@468 38
pavone@468 39 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI
pavone@468 40 actions. The key name goes on the left and the action is on the right.
pavone@468 41 Most keys are named for the character they produce when pressed. Additionally,
pavone@468 42 the arrow, enter and escape keys have the symbolic names up, down, left, right,
pavone@468 43 enter and esc respectively. Other keys that do not produce characters are not
pavone@468 44 yet supported.
pavone@468 45
pavone@468 46 The pads subsection is used to map gamepads and joysticks. Analog axes are not
pavone@468 47 currently supported. An example configuration is provided in default.cfg to map
pavone@468 48 SDL joystick 0 to the second controller.
pavone@468 49
pavone@468 50 Video
pavone@468 51 -----
pavone@468 52
pavone@536 53 The video section currently has three settings: "width", "vertex_shader" and
pavone@536 54 "fragment_shader". "width" sets the width of the window in pixels. Height is
pavone@536 55 calculated from this value. Both width and height can be overridden from the
pavone@536 56 command line. "vertex_shader" and "fragment_shader" control which GLSL shader
pavone@536 57 files are used for rendering the display when in Open GL rendering mode.
pavone@536 58 Shaders can be used to implement graphical filters and other effects.
pavone@468 59
pavone@468 60 Audio
pavone@468 61 -----
pavone@468 62
pavone@468 63 The audio section has two config values: rate and buffer. rate selects the
pavone@468 64 sample rate and buffer sets the size of the output buffer in samples. 512 is
pavone@468 65 generally a good value, but if you're experiencing audio dropouts you might
pavone@468 66 want to increase it to 1024.
pavone@468 67
pavone@468 68 Debugger
pavone@468 69 --------
pavone@468 70
pavone@468 71 BlastEm has an integrated command-line debugger loosely based on GDB's
pavone@468 72 interface. The interface is very rough at the moment. Available commands in the
pavone@468 73 68K debugger are:
pavone@468 74 b ADDRESS - Set a breakpoint at ADDRESS
pavone@536 75 d BREAKPOINT - Delete a 68K breakpoint
pavone@468 76 a ADDRESS - Advance to address
pavone@468 77 n - Advance to next instruction
pavone@536 78 o - Advance to next instruction ignoring branches to
pavone@536 79 lower addresses (good for breaking out of loops)
pavone@536 80 s - Advance to next instruction (follows bsr/jsr)
pavone@468 81 c - Continue
pavone@808 82 bt - Print a backtrace
pavone@468 83 p[/(x|X|d|c)] VALUE - Print a register or memory location
pavone@468 84 vs - Print VDP sprite list
pavone@468 85 vr - Print VDP register info
pavone@536 86 zb ADDRESS - Set a Z80 breakpoint
pavone@536 87 zp[/(x|X|d|c)] VALUE - Display a Z80 value
pavone@468 88 q - Quit BlastEm
pavone@468 89 Available commands in the Z80 debugger are:
pavone@536 90 b ADDRESS - Set a breakpoint at ADDRESS
pavone@536 91 de BREAKPOINT - Delete a Z80 breakpoint
pavone@536 92 a ADDRESS - Advance to address
pavone@468 93 n - Advance to next instruction
pavone@468 94 c - Continue
pavone@468 95 p[/(x|X|d|c)] VALUE - Print a register or memory location
pavone@468 96 di[/(x|X|d|c)] VALUE - Print VALUE before every debugger prompt
pavone@468 97 q - Quit BlastEm
pavone@468 98
pavone@468 99 The -d flag can be used to cause BlastEm to start in the debugger.
pavone@468 100 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key
pavone@808 101 by default) to enter the debugger while a game is running.
pavone@468 102
pavone@536 103 GDB Remote Debugging
pavone@536 104 --------------------
pavone@536 105
pavone@536 106 In addition to the native debugger, BlastEm can also act as a GDB remote
pavone@536 107 debugging stub. To use this, you'll want to configure your Makefile to produce
pavone@536 108 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with
pavone@536 109 the ELF file. Once inside the gdb session, type:
pavone@536 110
pavone@536 111 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D
pavone@536 112
pavone@536 113 where BLASTEM_PATH is the relative or absolute path to your BlastEm
pavone@536 114 installation and ROM_FILE.bin is the name of the raw binary for your program.
pavone@536 115 BlastEm will halt at the beginning of your program's entry point and return
pavone@536 116 control to GDB. This will allow you to set breakpoints before your code runs.
pavone@536 117
pavone@808 118 On Windows, the procedure is slightly different. First run
pavone@808 119 blastem.exe ROM_FILE.bin -D
pavone@808 120 This will cause BlastEm to wait for a socket connection on port 1234. It will
pavone@808 121 appear to be frozen until gdb connects to it. Now open the ELF file in gdb
pavone@808 122 and type:
pavone@808 123
pavone@808 124 target remote :1234
pavone@808 125
pavone@536 126 Trace points and watch points are not currently supported.
pavone@536 127
pavone@810 128 Included Tools
pavone@810 129 --------------
pavone@810 130
pavone@810 131 BlastEm ships with a few small utilities that leverage portions of the emulator
pavone@810 132 code.
pavone@810 133
pavone@810 134 dis - 68K disassembler
pavone@810 135 zdis - Z80 disassembler
pavone@810 136 vgmplay - Very basic VGM player
pavone@810 137 stateview - GST save state viewer
pavone@810 138
pavone@468 139 License
pavone@468 140 -------
pavone@468 141
pavone@468 142 BlastEm is free software distributed under the terms of the GNU General Public
pavone@468 143 License version 3 or higher. This gives you the right to redistribute and/or
pavone@468 144 modify the program as long as you follow the terms of the license. See the file
pavone@468 145 COPYING for full license details.
pavone@468 146
pavone@785 147 Binary releases of BlastEm are packaged with GLEW and SDL2 which have thier own
pavone@785 148 licenses. See GLEW-LICENSE and SDL-LICENSE for details.