bsnes-plus Usage Documentation


bsnes-plus is a Super Nintendo / Super Famicom emulator which aims to provide powerful, easy-to-use tools for debugging SNES software, in addition to the highly accurate hardware emulation provided by the original bsnes/higan project.

bsnes-plus is forked from version 073 of bsnes, but features numerous emulation updates and other enhancements backported from later versions of bsnes and higan. There are a couple of rare corner cases where even the bsnes-plus "accuracy" builds exhibit slightly less hardware-accuracy than current versions of higan, but nearly all licensed games, homebrew, and hacks that run correctly on a real console will also run identically under bsnes-plus.

The "compatibility" (default) profile features slightly decreased emulation accuracy, but with lower system requirements. This profile is recommended for most users and is capable of emulating nearly all of the same software as the accuracy profile, with little to no issues. The "performance" profile (not currently included in official releases) features an even greater speed/accuracy tradeoff, as the name implies.

The debugging tools included with bsnes-plus are fully compatible with all three profiles. See below for more information about using bsnes-plus for debugging.

Modes of Operation


bsnes is capable of running both in its default multi-user mode, as well as in single-user mode.

In multi-user mode, configuration data is stored inside the user's home directory. On Windows, this is located at "%APPDATA%/.bsnes". On other operating systems, this is located at "~/.bsnes".

To enable single-user mode, create a blank "bsnes-qt.cfg" file inside the same folder as the bsnes executable. bsnes will then use this file to store configuration data.

Supported Filetypes


SFC: SNES cartridge — ROM image.
BS: Satellaview BS-X flash cartridge — EEPROM image.
ST: Sufami Turbo cartridge — ROM image.
SRM, PSR: non-volatile memory, often used to save game data — (P)SRAM image.
RTC: real-time clock non-volatile memory.
UPS, BPS, IPS: patch data, used to dynamically modify cartridge of same base filename upon load.
CHT: plain-text list of "Game Genie" / "Pro Action Replay" codes.

The "snesreader" plugin adds additional support for compressed archives and less-common ROM file extensions, and the "supergameboy" plugin adds support for Game Boy and Super Game Boy ROMs (a copy of the actual Super Game Boy BIOS is required).

Using the Debugger


The primary goal of bsnes-plus is to provide easy-to-use tools for homebrew developers and ROM hackers. These tools can be accessed by selecting "Debugger ..." from the Tools menu.

The main debug window allows you to pause/resume emulation, single-step the SNES CPU and/or any active coprocessors, and optionally keep a trace log of executed code saved to disk for long-term debugging.

When emulation is stopped, either by pressing the Break/Run button or after a breakpoint is triggered (see below), you can press the Step button to execute a single instruction, the Step Over button to execute a single instruction or entire subroutine, or the Step Out button to exit the current subroutine. The checkboxes underneath allow you to select which combination of processors to single-step; each processor's code appears with a different color in the disassembly window.

(Note: the Step Over and Step Out buttons are unavailable when stepping multiple processors, and when stepping the SuperFX due to its lack of traditional call/return instructions and processor stack).

The trace options allow you to log disassembled instructions to disk in real-time while the emulator is running. The log output will be located in the directory specified for "exported data" in the emulator options (by default, this is the same directory as the currently loaded ROM). When the trace mask is enabled, each instruction will only be logged the first time it is executed; disabling this provides more thorough and detailed logging, but with greatly increased file size and CPU usage.

At the bottom of the main debug window, you can view the current register values for all steppable processors, and edit register values for the processor currently being stepped.

Debugger Menu: Tools

Disassembler Window


When single-stepping code, the disassembler window allows you to see other code in the vicinity of the current instruction. Only memory within a certain range that is known to actually be code is shown here.

Breakpoint Editor


Breakpoints allow you to automatically pause execution when code at a given location is executed, or when specific data is read or modified. Each breakpoint contains these fields:

Address Range: The address or range of addresses for the breakpoint to monitor. The second column represents the end of an address range, and is optional. Note that address mirroring will be ignored if a range of multiple addresses is specified.
Data: (optional) If this is specified, read and write breakpoints will only trigger if the byte being read from or written to the given address equals this value.
R/W/X: Specify any combination of read (R), write (W), and execute (X) operations that will trigger this breakpoint.
Source: Select which address space this breakpoint applies to; the default is the SNES CPU. Change this when debugging a coprocessor or monitoring reads/writes involving VRAM or other PPU memory.

Memory Editor


The memory editor allows you to view and edit the current contents of CPU memory, APU memory, VRAM, and all other address spaces which are available via the breakpoint editor. The values can be updated automatically in near-real-time or manually at any time.

A useful feature of this memory editor is that memory is highlighted to indicate known code and data regions. Memory highlighted in red is code, memory in blue is data, and memory in purple has been both read or written and executed (for example, code which is being executed from RAM).

The seek and search buttons can be used to jump to nearby regions of code, data, or unmarked memory, and to search for strings of byte values or ASCII text. Memory can also be dumped to disk and reloaded at a later time.

Properties Viewer


This window displays a detailed list of hardware register values and other properties for the SNES CPU, PPU, SMP, DSP, and other coprocessors, when available. Use this window to verify that the system has been initialized correctly, and whenever you want to be sure that a particular hardware register has the value that you expect.

Debugger Menu: S-PPU

Video RAM viewer


This window displays a graphical view of the current contents of VRAM.

The view can be switched between all available bit depths/formats as appropriate. The current tile addresses for all four background layers are also shown, and allow you to quickly jump to the graphics used by a specific layer.

When enabled, the graphic display can also be colored based on the current contents of CGRAM. Clicking within the CGRAM display allows you to select the palette to use.

Tilemap Viewer


This view displays the current contents and properties of each background layer's tilemap.

The properties of each layer can also optionally be overridden with custom values, for instances when the screen mode or other background properties are changed mid-frame. At any time, the relevant values being used by a given background layer can be viewed via the S-PPU tab on the Properties Viewer window, under registers $2105 and $2107 through $210c.

Sprite Viewer


This view displays the current properties of all sprites, based on the contents of OAM. Clicking on any sprite listed will display its graphics in the upper right corner of the window. The sprites can also be sorted by any of their properties by clicking the respective column header in the table.

Palette Viewer


This window displays the current contents of CGRAM. The same information is also presented on the Video RAM Viewer window, but this window is useful if you aren't currently interested in the contents of VRAM.

Debugger Menu: Misc

Debugger Options


This window allows you to configure a couple of options related to the debug windows:

Cache memory usage table to disk: Causes logged information about SNES memory usage (code/data regions) to be saved to disk and restored the next time the ROM is loaded. This is useful for long-term debugging/exploring across multiple sessions, but is disabled by default to avoid excessive disk space usage.
Show H-position in clocks instead of dots: Normally, when single-stepping the CPU, the output log shows the CPU's vertical counter value (in scanlines) and horizontal counter value (in dots/pixels). Enabling this option shows a more precise horizontal counter value based on the number of master clock cycles per scanline.

Satellaview and BS-X Support


As of version 073+3, bsnes-plus features extensive Satellaview and BS-X support.

Before using the Satellaview, first make sure it is enabled as the expansion port device on the "Advanced" tab of the emulator config window.

To use the BS-X interactive menu and play games on BS-X Memory Packs, select "Load BS-X Cartridge" from the "Load Special" menu. The "base cartridge" is the BS-X ROM itself, and the "slot cartridge" is an optional Memory Pack containing one or more BS-X games.

The next option, "Load BS-X Slotted Cartridge", allows you to play one of several other standalone cartridges which use the Satellaview hardware and have their own Memory Pack slots. A complete list of these cartridges is as follows:

Some sample broadcast data is located in the bsxdat directory. If you have downloaded some additional data, you can point to it using the "Paths" tab of the config window.

For more BS-X information and downloads, visit the BS-X Project site.

Known Limitations


Netplay: internet multiplay is not currently supported nor planned.

Contributors


byuu is the original author of bsnes and higan.

This is a list of others who have contributed to bsnes-plus, either directly or indirectly:
• Alex W. Jackson
• Andreas Naive
• anomie
• David Lindecrantz
• _Demo_
• Derrick Sobodash
• Devin Acker
• DMV27
• FirebrandX
• FitzRoy
• Grieverheart
• GIGO
• Jonas Quinn
• kode54
• krom
• LuigiBlood
• Marcus Rowe
• Matthew Callis
• Maximilian Rehkopf
• Michal Ziabkowski
• Nach
• neviksti
• Overload
• RedDwarf
• Richard Bannister
• Shay Green
• tetsuo55
• TRAC
• zones