Docs: Update debugger documentation (new features + add some missing information)

Docs/content/apireference/Changelog.md

@@ -5,12 +5,23 @@ pre: ""
 chapter: false
 ---
 
+## Changes between 0.9.7 and 0.9.8 ##
+
+### New Features ###
+
+* New function to get a label's current CPU address: <kbd>[getLabelAddress](/apireference/memoryaccess.html#getlabeladdress)</kbd>
+
+## Changes between 0.9.6 and 0.9.7 ##
+
+*No changes.*
+
 ## Changes between 0.9.5 and 0.9.6 ##
 
 ### New Features ###
 
 * New event callback: <kbd>[scriptEnded](/apireference/enums.html#eventtype)</kbd>.
 * New functions to get PRG/CHR ROM offsets based on a CPU/PPU address: <kbd>[getPrgRomOffset](/apireference/memoryaccess.html#getprgromoffset)</kbd> and <kbd>[getChrRomOffset](/apireference/memoryaccess.html#getchrromoffset)</kbd>.
+* New function for use with the [test runner mode](/apireference.html#test-runner-mode): <kbd>[stop](/apireference/emulation.html#stop)</kbd>
 
 ### Changes ###
 

Docs/content/apireference/Emulation.md

@@ -236,6 +236,22 @@ Runs the emulator for the specified number of cycles/instructions and then break
 **Description**  
 Resets the current game.  
 
+## stop ##
+
+**Syntax**  
+
+    emu.stop(exitCode)
+
+**Parameters**  
+exitCode - *Integer* The exit code that the Mesen process will return when exiting (when used in [test runner mode](/apireference.html#test-runner-mode))
+
+**Return value**  
+*None*
+
+**Description**  
+Stops and unloads the current game.  When in [test runner mode](/apireference.html#test-runner-mode), this will also exit Mesen itself and the Mesen process will return the specified exit code.  
+
+
 ## resume ##
 
 **Syntax**  

Docs/content/apireference/MemoryAccess.md

@@ -104,11 +104,11 @@ Returns an integer representing the byte offset of the specified PPU address in
     emu.getLabelAddress(label)
 
 **Parameters**  
-label - *String* A label to look up.
+label - *String* The label to look up
 
 **Return value**  
-*Integer* The corresponding integer address.
+*Integer* The corresponding CPU address
 
 **Description**  
-Returns an integer representing the address of the specified label. The return value can be passed directly to `read()` and `readWord()`.
+Returns the address of the specified label. This address can be used with the memory read/write functions (`read()`, `readWord()`, `write()`, `writeWord()`) using the `emu.memType.cpu` or `emu.memType.cpuDebug` memory types.
 

Docs/content/apireference/_index.md

@@ -21,3 +21,15 @@ Lua scripting is still a relatively recent feature and the API is not quite stab
 * [Memory Access](/apireference/memoryaccess.html)
 * [Miscellaneous](/apireference/misc.html)
 * [Enums](/apireference/enums.html)
+
+
+## Test Runner Mode ##
+
+Mesen can be started in a headless test runner mode that can be used to implement automated testing by using Lua scripts.  
+
+To start Mesen in headless mode, use the `--testrunner` command line option and specify both a game and a Lua script to run:
+```
+Mesen.exe --testrunner MyGame.nes MyTest.lua
+```
+
+This will start Mesen (headless), load the game and the Lua script and start executing the game at maximum speed until the Lua script calls the <kbd>[emu.stop()](/apireference/emulation.html#stop)</kbd> function. The <kbd>[emu.stop()](/apireference/emulation.html#stop)</kbd> function can specify an exit code, which will be returned by the Mesen process, which can be used to validate whether the test passed or failed.

Docs/content/configuration/Emulation.md

@@ -40,7 +40,7 @@ Several options in this section should NOT be enabled to avoid issues in some ga
 
 **Use alternative MMC3 IRQ behavior**: The MMC3 has a number of different variants (A, B and C).  By default, Mesen uses the IRQ behavior for versions B and C.  By turning this option on, Mesen will default to using the MMC3A's IRQ behavior instead. There is usually no reason to enable this.
 
-**Enable OAM RAM decay**: On all models, OAM RAM decays whenever rendering is disabled. This causes the values in OAM RAM to randomly change, which may cause sprite-related glitches on the screen. No known game relies on this -- the option is offered here mostly for the sake of homebrew software testing.
+**Enable OAM RAM decay**: On all models, OAM RAM decays whenever rendering is disabled. This causes the values in OAM RAM to decay to a specific value after a certain amount of time has elapsed since the last time the value was read or written (which may cause sprite-related glitches to appear on the screen). No known game relies on this -- the option is offered here mostly for the sake of homebrew software testing. There is a corresponding option to break on decayed OAM reads available in the debugger to help find and debug OAM decay-related bugs.
 
 **Do not reset PPU when resetting console**: On the Famicom and top loader NES, the PPU does not reset when pressing the reset button (only the CPU is reset). When enabled, only the CPU resets when the reset button is pressed.
 

Docs/content/debugging/Debugger.md

@@ -19,6 +19,20 @@ Most elements in the debugger's interface have right-click menu options - make s
 Watch expressions, breakpoints and labels are automatically saved on a per-rom basis in a **Workspace**.  
 You can completely reset the workspace for a specific rom by using the **<kbd>File&rarr;Workspace&rarr;Reset Workspace</kbd>** command.
 
+## Search Tools ##
+
+There are a number of different tools that can be used to search/navigate the code:
+
+<div class="imgBox"><div>
+	<img src="/images/GoToAll.png" />
+	<span>Go To All</span>
+</div></div>
+
+* **Go To All**: The *Go To All* feature allows you to search for any label by its name and navigate to it. It also works with CA/CC65 and displays the location of the labels in the original source code. (**<kbd>Ctrl+,</kbd>**)
+* **Find/Find Next/Find Previous**: Incremental search that can be used to search through any text shown in the code window (**<kbd>Ctrl+F</kbd>**)
+* **Find All Occurrences**: Search the code for a specific string or label and return all the results in a list. (**<kbd>Ctrl+Shift+F</kbd>**)
+* **Go To...**: These options allow you to quickly reach the NMI, IRQ or Reset handlers or a specific address (**<kbd>Ctrl+G</kbd>**)
+
 
 ## Customizing the debugger ##
 
@@ -185,7 +199,10 @@ Select which address or address range this breakpoint should apply to.
 It is also possible to specify no address at all by selecting **Any** - in this case, breakpoints will be evaluated on every CPU cycle.  
 
 **Condition** (optional)  
-Conditions allow you to use the same expression syntax as the one used in the [Watch Window](#watch-window) to cause a breakpoint to trigger under very specific conditions.
+Conditions allow you to use the same expression syntax as the one used in the [Watch Window](#watch-window) to cause a breakpoint to trigger under specific conditions.
+
+**Process breakpoint on dummy reads/writes**  
+When enabled, the breakpoint will be processed for dummy reads and writes (only available for read or write breakpoints). When disabled, the debugger will never break on a dummy read or write for this breakpoint.
 
 **Mark on Event Viewer**  
 When enabled, a mark will be visible on the [Event Viewer](/debugging/eventviewer.html) whenever this breakpoint's conditions are met. This can be used to add marks to the event viewer based on a variety of conditions by using conditional breakpoints.
@@ -321,6 +338,8 @@ The `Break Options` submenu contains a number of options to configure under whic
 * **Break on Init (NSF)**: Break when the NSF's Init routine is called.
 * **Break on Play (NSF)**: Break when the NSF's Play routine is called.
 
+**Enable sub-instruction breakpoints**: This option allow Mesen to process breakpoints in the middle of CPU instructions.  This was the default up to version 0.9.7.  When this option is disabled, the debugger will break at the beginning of CPU instructions only (and will only break once per instruction). This is the new default as of 0.9.8.
+
 Additionally, you can configure whether or not the debugger window gets focused when a break or pause occurs.
 
 ### Copy Options ###
@@ -339,11 +358,13 @@ These options configure which portions of the code is copied into the clipboard
 <div></div>
 
 * **Hide Pause Icon**: When enabled, the pause icon that is normally shown whenever execution is paused will be hidden.
+* **Draw Partial Frame**: When enabled, the emulator's main window will display the current partially-drawn frame instead of the last complete frame.
+* **Show previous frame behind current**: When enabled along with `Draw Partial Frame`, the previous frame's data will be shown behind the current frame.
 
 <div></div>
 
-* **Draw Partial Frame**: When enabled, the emulator's main window will display the current partially-drawn frame instead of the last complete frame.
-* **Show previous frame behind current**: When enabled along with `Draw Partial Frame`, the previous frame's data will be shown behind the current frame.
+* **Show break notifications**: When enabled, a "notification" will be shown over the disassembly window indicating what caused the debugger to break the execution (e.g: a CPU/PPU read/write, a decayed OAM read, etc.)
+* **Show instruction progression**: When enabled, the code window will display an indicator showing how far along into the current instruction the execution is. This also shows an estimate of how many cycles the instruction will take to complete (this estimate may increase for various reasons such as a page being crossed, etc.)
 
 <div></div>
 
@@ -353,6 +374,26 @@ These options configure which portions of the code is copied into the clipboard
 
 * **Refresh UI while running**: When enabled, the watch window and the CPU/PPU status will be updated continuously while the emulation is running (instead of only updating when the execution breaks)
 
+## Workspaces ##
+
+Debugger "workspaces" are used to store information specific to each ROM you debug. This includes watch expressions, breakpoints and labels.
+
+### Default Workspace Labels ###
+
+By default, Mesen setups labels for the NES' PPU and APU registers. These can be enabling the `Disable default labels` option.  
+  
+Additionally, it's possible to setup your own set of default labels by creating a file called `DefaultLabels.Global.mlb` in the `Debugger` folder (where the workspace and CDL files are stored). When Mesen finds this file, it will ignore the its own default labels and use the ones contained in that file instead, for all ROMs.  
+
+You can also setup default labels for specific mappers by creating a file called `DefaultLabels.[mapper number].mlb` (e.g, for MMC3 games: `DefaultLabels.4.mlb`).  
+For FDS and NSF ROMs, `DefaultLabels.FDS.mlb` and `DefaultLabels.NSF.mlb` can be used, respectively.  
+
+If both a global and mapper-specific `mlb` is found, both of them will be used (with the mapper-specific file having priority in case of conflicting labels).
+
+{{% notice tip %}}
+`.mlb` files are a Mesen-specific file format to define labels/comments in the code. They are written in a simple text format and can also be created by using the debugger's `Export Labels` feature.
+{{% /notice %}}
+
+
 ## How To: Edit Code ##
 
 <div class="imgBox"><div>

Docs/content/debugging/DebuggerIntegration.md

@@ -1,5 +1,5 @@
 ---
-title: Integration with CC65/ASM6
+title: Integration with compilers
 weight: 18
 pre: ""
 chapter: false
@@ -7,7 +7,9 @@ chapter: false
 
 When building homebrew software in assembly or C, it is possible to export the labels used in your code and import them into Mesen to simplify the debugging process.  This allows the debugger to know which portions of the ROM correspond to which functions in your code, as well as display your code's comments inside the debugger itself.
 
-## CC65 / CA65 ##
+## Integration with compilers ##
+
+### CC65 / CA65 ###
 
 CC65/CA65 are able to produce .DBG files which can be imported into Mesen's debugger.  
 To make CC65/CA65 create a .DBG file during the compilation, use the `--dbgfile` command line option.
@@ -17,7 +19,12 @@ To import the .DBG file, use the **<kbd>File&rarr;Workspace&rarr;Import Labels</
 You can also enable the `Auto-load DBG/MLB files` to make Mesen load any .DBG file it finds next to the ROM whenever the debugger is opened or the power cycle button is used.  
 **Note:** For this option to work, the ROM file must have the same name as the DBG file (e.g `MyRom.nes` and `MyRom.dbg`) and be inside the same folder.
 
-### Source View ###
+#### Source View ####
+
+<div class="imgBox"><div>
+	<img src="/images/SourceView.png" />
+	<span>Source View</span>
+</div></div>
 
 When a .DBG file is loaded, 2 additional options appear in the code window's right-click menu:
 
@@ -25,7 +32,7 @@ When a .DBG file is loaded, 2 additional options appear in the code window's rig
 * **Show source code as comments**: When enabled, the debugger will show the original source code to the right of the disassembly, as comments.
 
 
-## ASM6f ##
+### ASM6f ###
 
 Integration with ASM6 is possible by using freem's branch of ASM6 named [ASM6f](https://github.com/freem/asm6f).  
 This fork contains 2 additional command line options that are useful when using Mesen: `-m` and `-c`
@@ -36,6 +43,27 @@ This fork contains 2 additional command line options that are useful when using
 Additionally, you can use the `Auto-load DBG/MLB files` and `Auto-load CDL files` options in the **<kbd>File&rarr;Workspace</kbd>** menu to automatically load MLB and CDL files present in the same folder as the current ROM, with the same filename (e.g `MyRom.nes`, `MyRom.mlb`, `MyRom.cdl`). 
 
 
-## NESASM ##
+### NESASM ###
 
-Mesen can also import the `.fns` symbol files that NESASM produces. However, due to limitations in the `.fns` format, these labels can only be reliably imported for games containing exactly 32kB of PRG ROM.  If you are creating a larger game, CC65/CA65 offers the best integration features at the moment.
+Mesen can also import the `.fns` symbol files that NESASM produces. However, due to limitations in the `.fns` format, these labels can only be reliably imported for games containing exactly 32kB of PRG ROM.  If you are creating a larger game, CC65/CA65 offers the best integration features at the moment.
+
+## Importing and exporting labels ##
+
+<div class="imgBox"><div>
+	<img src="/images/WorkspaceMenu.png" />
+	<span>Workspace Menu</span>
+</div></div>
+
+Mesen can also import and export labels in `.mlb` format. This is the same format as the label files produced by ASM6f. The ability to import labels can be used to integrate the debugger with your own workflow (e.g by creating your own scripts that produce `.mlb` files)
+
+<div style="clear:both"></div>
+
+### Import Settings ###
+
+<div class="imgBox"><div>
+	<img src="/images/ImportSettings.png" />
+	<span>Import Settings</span>
+</div></div>
+
+For fine-grain control over the DBG/MLB file imports, the `Import Settings` window can be used.  
+This allows you to configure which types of labels/comments should be imported, as well as choosing whether or not Mesen should delete all existing labels before importing DBG/MLB files.

Docs/content/debugging/MemoryTools.md

@@ -15,17 +15,25 @@ The memory viewer offers read and write access to all types of ROM and RAM:
 
 * CPU Memory
 * PPU Memory
-* Palette RAM
-* OAM RAM
-* Secondary OAM RAM
+
+<div></div>
+
 * PRG ROM
-* CHR ROM
-* CHR RAM
 * Work RAM
 * Save RAM
 
+<div></div>
+
+* CHR ROM
+* CHR RAM
+* Palette RAM
+* Sprite / OAM RAM
+* Secondary OAM RAM
+
 **Note:** Only memory types that are available for the currently loaded ROM will be shown in the dropdown.
 
+<div style="clear:both"></div>
+
 {{% notice tip %}}
 PRG ROM and CHR ROM *are* writable from the memory viewer.  Any change will remain in effect until a power cycle. If you want to save your PRG/CHR ROM modifications to a .nes file, or as an IPS patch, you can use the **<kbd>File&rarr;Save</kbd>** or **<kbd>File&rarr;Save edits as IPS</kbd>** commands in the [debugger window](/debugging/debugger.html).
 {{% /notice %}}
@@ -36,7 +44,15 @@ There are a number of highlighting/coloring options in the memory viewer.
 
 <kbd>**View&rarr;Memory Access Highlighting**</kbd> has coloring options for addresses that were recently read, written or executed (colored in <span class="blue">blue</span>, <span class="red">red</span> and <span class="green">green</span>, respectively). A fade-out period can also be configured, after which the byte will revert to its normal black color.  
 
-<kbd>**View&rarr;Data Type Highlighting**</kbd> offers options to change the background color of specific bytes based on their type.</span>.
+<kbd>**View&rarr;Data Type Highlighting**</kbd> offers options to change the background color of specific bytes based on their type:</span>
+	
+* Labeled bytes
+* Breakpoints
+* Code bytes *(PRG ROM only)*
+* Data bytes *(PRG ROM only)**
+* DMC sample bytes *(PRG ROM only)*
+* Drawn bytes *(CHR ROM only)*
+* Read bytes *(CHR ROM only)*
 
 <kbd>**View&rarr;De-emphasize**</kbd> offers options to display bytes matching certain conditions (unused, read, written or executed) in <span class="gray">gray</span>.
 

Docs/content/debugging/TextHooker.md

@@ -26,4 +26,6 @@ To configure character mappings, see the `Character Mappings` section below.
 
 This tab allows you to configure the mappings between CHR tiles and text characters. These mappings are based on the shape of the tile and are shared between all games. A number of mappings are built into Mesen, so some characters may already be recognized automatically.  
 
-When you want to add new mappings, simply edit the textbox below the tile you want to configure.
+When you want to add new mappings, simply edit the textbox below the tile you want to configure.  
+
+For Japanese text, you can specify `dakuten` (濁点) and `handakuten` (半濁点) by typing `daku` and `han` in the textbox. Alternatively, you can also use the Unicode characters for them: `ﾞ` (U+3099) and `ﾟ` (U+309A), respectively.