source-level debugging feature

(As described at PR #13444)

Author: dave-br

docs/source/commandline/commandline-all.rst

@@ -3856,6 +3856,81 @@ Core Communication Options
 
             mame arescue -comm_remotehost 192.168.1.3 -comm_remoteport 30100 -comm_framesync
 
+.. _mame-commandline-srcdbginfo:
+
+**-src_debug_info** *<path>*
+
+    Enable :ref:`source-level debugging <srcdbg>`.  *<path>* is a path to the :ref:`MAME Debugging Information File <srcdbg_mdi>`
+
+    By default, source-level debugging is disabled.
+
+    Example:
+        .. code-block:: bash
+
+            mame coco2 -src_debug_info c:\MyProject\MyProject.mdi
+
+.. _mame-commandline-srcdbgsearchpath:
+
+**-src_debug_search_path** *<path-list>*
+
+    If :ref:`source-level debugging <srcdbg>` is enabled, and
+    relative paths are present in the
+    :ref:`MAME Debugging Information File <srcdbg_mdi>`, this
+    specifies where MAME should look for those source files.
+
+    *<path-list>* is a semicolon-separated list of full paths
+    to directories on the MAME host system.
+    
+    By default, MAME expects to find full paths to source files in the
+    MAME Debugging Information File.
+
+    Example:
+        .. code-block:: bash
+
+            mame coco2 -src_debug_info c:\MyProject\MyProject.mdi -src_debug_search_path c:\MyProject\SourceDir1;c:\MyProject\SourceDir2
+
+.. _mame-commandline-srcdbgprefixmap:
+
+**-src_debug_prefix_map** *<prefix-map>*
+
+    If :ref:`source-level debugging <srcdbg>` is enabled, and the sources originally used
+    to build the debugged program are in a different location on the MAME
+    host system, this specifies how to map path prefixes from the originally
+    built source files to the source files currently present on the MAME
+    host system.  This is useful in cases where the debugged program was
+    built on a machine different from the MAME host system, or if the
+    build *environment* is different from the MAME run-time environment (such
+    as the use of cygwin while running the build tool).
+
+    *<prefix-map>* is a semicolon-separated list of semicolon-separated pairs of
+    paths, where each pair consists of a build environment's path prefix followed
+    by the MAME host system's path prefix it should be replaced with, of the form:
+
+        *build-path-prefix1*\ ;\ *runtime-path-prefix1*\ ;\ *build-path-prefix2*\ ;\ *runtime-path-prefix2*\ ;\ *etc.*
+
+    By default, source files are expected to be located at the same paths
+    present in the :ref:`MAME Debugging Information File <srcdbg_mdi>`
+
+    Example:
+        .. code-block:: bash
+
+            mame coco2 -src_debug_info c:\MyProject\MyProject.mdi -src_debug_prefix_map /cygdrive/c/;c:\;/cygdrive/d/;d:\
+
+.. _mame-commandline-srcdbgoffset:
+
+**-src_debug_offset** *<offset>*
+
+    If :ref:`source-level debugging <srcdbg>` is enabled, this causes *<offset>*
+    to be applied to all addresses encountered in the
+    :ref:`MAME Debugging Information File <srcdbg_mdi>`.  For more information,
+    see :ref:`srcdbg_offsets`.
+
+    The default is 0.
+
+    Example:
+        .. code-block:: bash
+
+            mame coco2 -src_debug_info c:\MyProject\MyProject.mdi -src_debug_offset 57344
 
 .. _mame-commandline-miscoptions:
 

docs/source/debugger/breakpoint.rst

@@ -29,7 +29,9 @@ Sets a new execution breakpoint at the specified **<address>**.  The
 **<address>** may optionally be followed by a colon and a tag or
 debugger CPU number to set a breakpoint for a specific CPU.  If no CPU
 is specified, the breakpoint will be set for the CPU currently visible
-in the debugger.
+in the debugger.  When :ref:`source-level debugging <srcdbg>` is
+enabled, :ref:`alternatives <srcdbg_bp>` to specifying **<address>**
+are allowed.
 
 The optional **<condition>** parameter lets you specify an expression
 that will be evaluated each time the breakpoint address is hit.  If the

docs/source/debugger/execution.rst

@@ -4,9 +4,13 @@ Execution Debugger Commands
 ===========================
 
 :ref:`debugger-command-step`
-    single step for <count> instructions (F11)
+    single step for <count> instructions (F11, when disassembly view is active)
+:ref:`debugger-command-steps`
+    single step one source line (F11, when source view is active)
 :ref:`debugger-command-over`
-    single step over <count> instructions (F10)
+    single step over <count> instructions (F10, when disassembly view is active)
+:ref:`debugger-command-overs`
+    single step over one source line (F10, when source view is active)
 :ref:`debugger-command-out`
     single step until the current subroutine/exception handler returns
     (Shift-F11)
@@ -63,6 +67,46 @@ Examples:
 Back to :ref:`debugger-execution-list`
 
 
+.. _debugger-command-steps:
+
+steps
+-----
+
+**steps**
+
+When :ref:`source-level debugging <srcdbg>` is enabled, this single-steps
+one *source* line on the currently executing CPU.  When the original
+source is assembly language, ``step`` and ``steps`` generally behave the same.
+But when the original source is in a higher level language like C or BASIC,
+``steps`` results in executing the remainder of a block of instructions
+associated with the current source line.
+
+If the current source line is a
+call instruction, ``steps`` stops at the first source line in the called
+function, but only if the called function has source associated with it.
+If neither the called function nor any of its callees have source associated
+with them, ``steps`` will continue execution until the call is complete, and
+the first instruction with source associated with it is encountered.
+
+If the current line returns from a recursive function, ``steps`` will stop
+at the same line, but in the prior call frame.  It will appear as if
+no stepping occurred, but the stack register will indicate a return
+has occurred.  Note that this logic can be fooled when stepping into a function
+without associated source, which makes further calls without proper
+matching returns (using direct manipulation of the stack pointer instead).
+
+
+
+Examples:
+
+``steps``
+    Steps forward to the next source line on the current CPU.
+``sts``
+    Steps forward to the next source line on the current CPU.
+
+Back to :ref:`debugger-execution-list`
+
+
 .. _debugger-command-over:
 
 over
@@ -93,6 +137,30 @@ Examples:
 Back to :ref:`debugger-execution-list`
 
 
+.. _debugger-command-overs:
+
+overs
+-----
+
+**overs**
+
+When :ref:`source-level debugging <srcdbg>` is enabled, this steps forward
+over one *source* line on the currently executing CPU.  When the original
+source is assembly language, ``over`` and ``overs`` generally behave the same.
+But when the original source is in a higher level language like C or BASIC,
+``overs`` results in executing the remainder of a block of instructions
+associated with the current source line.
+
+Examples:
+
+``overs``
+    Steps forward over the next source line on the current CPU.
+``os``
+    Steps forward over the next source line on the current CPU.
+
+Back to :ref:`debugger-execution-list`
+
+
 .. _debugger-command-out:
 
 out
@@ -118,6 +186,33 @@ Example:
 Back to :ref:`debugger-execution-list`
 
 
+.. _debugger-command-outs:
+
+outs
+----
+
+**outs**
+
+When :ref:`source-level debugging <srcdbg>` is enabled, this single-steps
+until the next return from subroutine or return from exception instruction
+lands the currently executing CPU to a *source* line.  When the original
+source is assembly language and source-level debugging information is provided
+for the current and calling subroutine, ``out`` and ``outs`` generally
+behave the same.  But when layers of functions or subroutines *without*
+source-level information exist between the current instruction and the
+most recent calling instruction *with* source-level information, ``outs``
+will skip over those "non source-level information" layers until it lands on
+calling code with source-level information.
+
+Examples:
+
+``outs``
+    Steps until a subroutine or exception handler returns to code with
+    source-level information.
+
+Back to :ref:`debugger-execution-list`
+
+
 .. _debugger-command-go:
 
 go

docs/source/debugger/general.rst

@@ -43,6 +43,8 @@ General Debugger Commands
     read commands from file and executes them one by one
 :ref:`debugger-command-time`
     prints the current machine time to the console
+:ref:`debugger-command-sdoffset`
+    sets the address offset to be used by source-level debugging
 :ref:`debugger-command-quit`
     exit the debugger and end the emulation session
 
@@ -100,8 +102,10 @@ symlist
 
 Lists registered symbols and their values.  If **<cpu>** is not
 specified, symbols in the global symbol table are displayed; otherwise,
-symbols specific to the device **<cpu>** are displayed.  Symbols are
-listed alphabetically.  Read-only symbols are noted.  See
+symbols specific to the device **<cpu>** are displayed. If a **<cpu>**
+is specified, and :ref:`Source-Level Debugging <srcdbg>` is enabled on that
+CPU, then :ref:`source-level symbols <srcdbg_symbols>` are listed as well.
+Symbols are listed alphabetically.  Read-only symbols are noted.  See
 :ref:`debugger-devicespec` for details on how to specify a CPU.
 
 Examples:
@@ -568,6 +572,23 @@ Examples:
 Back to :ref:`debugger-general-list`
 
 
+.. _debugger-command-sdoffset:
+
+sdoffset
+--------
+
+Sets the :ref:`address offset <srcdbg_offsets>` to be used by
+:ref:`source-level debugging <srcdbg>`
+
+Examples:
+
+``sdoffset E000``
+    Apply an offset of $E000 to all addresses present
+    in the :ref:`MAME Debugging Information File <srcdbg_mdi>`.
+
+Back to :ref:`debugger-general-list`
+
+
 .. _debugger-command-quit:
 
 quit