pavone@808: BlastEm 0.3.1 pavone@468: ------------- pavone@468: pavone@468: Installation pavone@468: ------------ pavone@468: pavone@808: Extract this archive to a directory of your choosing. If you wish to change the pavone@808: configuration settings, copy default.cfg to $HOME/.config/blastem/blastem.cfg and pavone@468: modify the copy. You may also whish to add the blastem directory to your PATH pavone@468: environment variable. pavone@468: pavone@808: Usage pavone@808: ----- pavone@808: pavone@808: BlastEm does not have much of a GUI at the moment and expects a filename to be pavone@808: passed to it at startup. You can do this by either running it from the command pavone@808: line or associating it with a file type. To get a list of supported command pavone@808: line options on Linux or OSX type: pavone@808: pavone@808: ./blastem -h pavone@808: pavone@808: From within your BlastEm directory. On Windows type: pavone@808: pavone@808: blastem.exe -h pavone@808: pavone@468: Configuration pavone@468: ------------- pavone@468: pavone@808: Configuration is read from the file at $HOME/.config/blastem/blastem.cfg if it pavone@808: exists, othwerise it is read from default.cfg from the same directory as the pavone@808: BlastEm executable. Sections are denoted by a section name followed by an open pavone@468: curly bracket, the section's contents and a closing curly bracket. Individual pavone@468: configuration values are set by entering the value's name followed by a space pavone@468: or tab and followed by the desired value. pavone@468: pavone@468: Bindings pavone@468: -------- pavone@468: pavone@468: The keys subsection of bindings maps keyboard keys to gamepad buttons or UI pavone@468: actions. The key name goes on the left and the action is on the right. pavone@468: Most keys are named for the character they produce when pressed. Additionally, pavone@468: the arrow, enter and escape keys have the symbolic names up, down, left, right, pavone@468: enter and esc respectively. Other keys that do not produce characters are not pavone@468: yet supported. pavone@468: pavone@468: The pads subsection is used to map gamepads and joysticks. Analog axes are not pavone@468: currently supported. An example configuration is provided in default.cfg to map pavone@468: SDL joystick 0 to the second controller. pavone@468: pavone@468: Video pavone@468: ----- pavone@468: pavone@536: The video section currently has three settings: "width", "vertex_shader" and pavone@536: "fragment_shader". "width" sets the width of the window in pixels. Height is pavone@536: calculated from this value. Both width and height can be overridden from the pavone@536: command line. "vertex_shader" and "fragment_shader" control which GLSL shader pavone@536: files are used for rendering the display when in Open GL rendering mode. pavone@536: Shaders can be used to implement graphical filters and other effects. pavone@468: pavone@468: Audio pavone@468: ----- pavone@468: pavone@468: The audio section has two config values: rate and buffer. rate selects the pavone@468: sample rate and buffer sets the size of the output buffer in samples. 512 is pavone@468: generally a good value, but if you're experiencing audio dropouts you might pavone@468: want to increase it to 1024. pavone@468: pavone@468: Debugger pavone@468: -------- pavone@468: pavone@468: BlastEm has an integrated command-line debugger loosely based on GDB's pavone@468: interface. The interface is very rough at the moment. Available commands in the pavone@468: 68K debugger are: pavone@468: b ADDRESS - Set a breakpoint at ADDRESS pavone@536: d BREAKPOINT - Delete a 68K breakpoint pavone@468: a ADDRESS - Advance to address pavone@468: n - Advance to next instruction pavone@536: o - Advance to next instruction ignoring branches to pavone@536: lower addresses (good for breaking out of loops) pavone@536: s - Advance to next instruction (follows bsr/jsr) pavone@468: c - Continue pavone@808: bt - Print a backtrace pavone@468: p[/(x|X|d|c)] VALUE - Print a register or memory location pavone@468: vs - Print VDP sprite list pavone@468: vr - Print VDP register info pavone@536: zb ADDRESS - Set a Z80 breakpoint pavone@536: zp[/(x|X|d|c)] VALUE - Display a Z80 value pavone@468: q - Quit BlastEm pavone@468: Available commands in the Z80 debugger are: pavone@536: b ADDRESS - Set a breakpoint at ADDRESS pavone@536: de BREAKPOINT - Delete a Z80 breakpoint pavone@536: a ADDRESS - Advance to address pavone@468: n - Advance to next instruction pavone@468: c - Continue pavone@468: p[/(x|X|d|c)] VALUE - Print a register or memory location pavone@468: di[/(x|X|d|c)] VALUE - Print VALUE before every debugger prompt pavone@468: q - Quit BlastEm pavone@468: pavone@468: The -d flag can be used to cause BlastEm to start in the debugger. pavone@468: Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key pavone@808: by default) to enter the debugger while a game is running. pavone@468: pavone@536: GDB Remote Debugging pavone@536: -------------------- pavone@536: pavone@536: In addition to the native debugger, BlastEm can also act as a GDB remote pavone@536: debugging stub. To use this, you'll want to configure your Makefile to produce pavone@536: both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with pavone@536: the ELF file. Once inside the gdb session, type: pavone@536: pavone@536: target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D pavone@536: pavone@536: where BLASTEM_PATH is the relative or absolute path to your BlastEm pavone@536: installation and ROM_FILE.bin is the name of the raw binary for your program. pavone@536: BlastEm will halt at the beginning of your program's entry point and return pavone@536: control to GDB. This will allow you to set breakpoints before your code runs. pavone@536: pavone@808: On Windows, the procedure is slightly different. First run pavone@808: blastem.exe ROM_FILE.bin -D pavone@808: This will cause BlastEm to wait for a socket connection on port 1234. It will pavone@808: appear to be frozen until gdb connects to it. Now open the ELF file in gdb pavone@808: and type: pavone@808: pavone@808: target remote :1234 pavone@808: pavone@536: Trace points and watch points are not currently supported. pavone@536: pavone@810: Included Tools pavone@810: -------------- pavone@810: pavone@810: BlastEm ships with a few small utilities that leverage portions of the emulator pavone@810: code. pavone@810: pavone@810: dis - 68K disassembler pavone@810: zdis - Z80 disassembler pavone@810: vgmplay - Very basic VGM player pavone@810: stateview - GST save state viewer pavone@810: pavone@468: License pavone@468: ------- pavone@468: pavone@468: BlastEm is free software distributed under the terms of the GNU General Public pavone@468: License version 3 or higher. This gives you the right to redistribute and/or pavone@468: modify the program as long as you follow the terms of the license. See the file pavone@468: COPYING for full license details. pavone@468: pavone@785: Binary releases of BlastEm are packaged with GLEW and SDL2 which have thier own pavone@785: licenses. See GLEW-LICENSE and SDL-LICENSE for details.