summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/luascript/ref-debugger.rst
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2023-07-06 09:52:10 +1000
committer Vas Crabb <vas@vastheman.com>2023-07-06 09:52:10 +1000
commit12623c3fd35984f75e31144126689986af657a30 (patch)
tree8b8b01669ab168705148152e3f4a3622945dd04c /docs/source/luascript/ref-debugger.rst
parent737af4b6655d1de338895272bfeeec8bb7b7b17f (diff)
docs: Moved Lua API reference to its own section - the page was far too long.
Diffstat (limited to 'docs/source/luascript/ref-debugger.rst')
-rw-r--r--docs/source/luascript/ref-debugger.rst451
1 files changed, 451 insertions, 0 deletions
diff --git a/docs/source/luascript/ref-debugger.rst b/docs/source/luascript/ref-debugger.rst
new file mode 100644
index 00000000000..e347b7303ff
--- /dev/null
+++ b/docs/source/luascript/ref-debugger.rst
@@ -0,0 +1,451 @@
+.. _luascript-ref-debugger:
+
+Lua Debugger Classes
+====================
+
+Some of MAME’s core debugging features can be controlled from Lua script. The
+debugger must be enabled to use the debugger features (usually by passing
+``-debug`` on the command line).
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-debugsymtable:
+
+Symbol table
+------------
+
+Wrap’s MAME’s ``symbol_table`` class, providing named symbols that can be used
+in expressions. Note that symbol tables can be created and used even when the
+debugger is not enabled.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.symbol_table(machine)
+ Creates a new symbol table in the context of the specified machine,
+emu.symbol_table(parent, [device])
+ Creates a new symbol table with the specified parent symbol table. If a
+ device is specified and it implements ``device_memory_interface``, it will
+ be used as the base for looking up address spaces and memory regions. Note
+ that if a device that does not implement ``device_memory_interface`` is
+ supplied, it will not be used (address spaces and memory regions will be
+ looked up relative to the root device).
+emu.symbol_table(device)
+ Creates a new symbol table in the context of the specified device. If the
+ device implements ``device_memory_interface``, it will be used as the base
+ for looking up address spaces and memory regions. Note that if a device
+ that does not implement ``device_memory_interface`` is supplied, it will
+ only be used to determine the machine context (address spaces and memory
+ regions will be looked up relative to the root device).
+
+Methods
+~~~~~~~
+
+symbols:set_memory_modified_func(cb)
+ Set a function to call when memory is modified via the symbol table. No
+ arguments are passed to the function and any return values are ignored.
+ Call with ``nil`` to remove the callback.
+symbols:add(name, [value])
+ Adds a named integer symbol. The name must be a string. If a value is
+ supplied, it must be an integer. If a value is supplied, a read-only symbol
+ is added with the supplied value. If no value is supplied, a read/write
+ symbol is created with and initial value of zero. If a symbol entry with
+ the specified name already exists in the symbol table, it will be replaced.
+
+ Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
+symbols:add(name, getter, [setter], [format])
+ Adds a named integer symbol using getter and optional setter callbacks. The
+ name must be a string. The getter must be a function returning an integer
+ for the symbol value. If supplied, the setter must be a function that
+ accepts a single integer argument for the new value of the symbol. A format
+ string for displaying the symbol value may optionally be supplied. If a
+ symbol entry with the specified name already exists in the symbol table, it
+ will be replaced.
+
+ Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
+symbols:add(name, minparams, maxparams, execute)
+ Adds a named function symbol. The name must be a string. The minimum and
+ maximum numbers of parameters must be integers. If a symbol entry with the
+ specified name already exists in the symbol table, it will be replaced.
+
+ Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
+symbols:find(name)
+ Returns the :ref:`symbol entry <luascript-ref-debugsymentry>` with the
+ specified name, or ``nil`` if there is no symbol with the specified name in
+ the symbol table.
+symbols:find_deep(name)
+ Returns the :ref:`symbol entry <luascript-ref-debugsymentry>` with the
+ specified name, or ``nil`` if there is no symbol with the specified name in
+ the symbol table or any of its parent symbol tables.
+symbols:value(name)
+ Returns the integer value of the symbol with the specified name, or zero if
+ there is no symbol with the specified name in the symbol table or any of its
+ parent symbol tables. Raises an error if the symbol with specified name is
+ a function symbol.
+symbols:set_value(name, value)
+ Sets the value of the symbol with the specified name. Raises an error if
+ the symbol with the specified name is a read-only integer symbol or if it is
+ a function symbol. Has no effect if there is no symbol with the specified
+ name in the symbol table or any of its parent symbol tables.
+symbols:memory_value(name, space, offset, size, disable_se)
+ Read a value from memory. Supply the name or tag of the address space or
+ memory region to read from, or ``nil`` to use the address space or memory
+ region implied by the ``space`` argument. See
+ :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
+ access type specifications that can be used for the ``space`` argument.
+ The access size is specified in bytes, and must be 1, 2, 4 or 8. The
+ ``disable_se`` argument specifies whether memory access side effects should
+ be disabled.
+symbols:set_memory_value(name, space, offset, value, size, disable_se)
+ Write a value to memory. Supply the name or tag of the address space or
+ memory region to write to, or ``nil`` to use the address space or memory
+ region implied by the ``space`` argument. See
+ :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
+ access type specifications that can be used for the ``space`` argument.
+ The access size is specified in bytes, and must be 1, 2, 4 or 8. The
+ ``disable_se`` argument specifies whether memory access side effects should
+ be disabled.
+symbols:read_memory(space, address, size, apply_translation)
+ Read a value from an address space. The access size is specified in bytes,
+ and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
+ the address will be translated with debug read intention. Returns a value
+ of the requested size with all bits set if address translation fails.
+symbols:write_memory(space, address, data, size, apply_translation)
+ Write a value to an address space. The access size is specified in bytes,
+ and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
+ the address will be translated with debug write intention. The symbol
+ table’s memory modified function will be called after the value is written.
+ The value will not be written and the symbol table’s memory modified
+ function will not be called if address translation fails.
+
+Properties
+~~~~~~~~~~
+
+symbols.entries[]
+ The :ref:`symbol entries <luascript-ref-debugsymentry>` in the symbol table,
+ indexed by name. The ``at`` and ``index_of`` methods have O(n) complexity;
+ all other supported operations have O(1) complexity.
+symbols.parent (read-only)
+ The parent symbol table, or ``nil`` if the symbol table has no parent.
+
+
+.. _luascript-ref-debugexpression:
+
+Parsed expression
+-----------------
+
+Wraps MAME’s ``parsed_expression`` class, which represents a tokenised debugger
+expression. Note that parsed expressions can be created and used even when the
+debugger is not enabled.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.parsed_expression(symbols)
+ Creates an empty expression that will use the supplied
+ :ref:`symbol table <luascript-ref-debugsymtable>` to look up symbols.
+emu.parsed_expression(symbols, string, [default_base])
+ Creates an expression by parsing the supplied string, looking up symbols in
+ the supplied :ref:`symbol table <luascript-ref-debugsymtable>`. If the
+ default base for interpreting integer literals is not supplied, 16 is used
+ (hexadecimal). Raises an :ref:`expression error
+ <luascript-ref-debugexpressionerror>` if the string contains syntax errors
+ or uses undefined symbols.
+
+Methods
+~~~~~~~
+
+expression:set_default_base(base)
+ Set the default base for interpreting numeric literals. The base must be a
+ positive integer.
+expression:parse(string)
+ Parse a debugger expression string. Replaces the current contents of the
+ expression if it is not empty. Raises an :ref:`expression error
+ <luascript-ref-debugexpressionerror>` if the string contains syntax errors
+ or uses undefined symbols. The previous content of the expression is not
+ preserved when attempting to parse an invalid expression string.
+expression:execute()
+ Evaluates the expression, returning an unsigned integer result. Raises an
+ :ref:`expression error <luascript-ref-debugexpressionerror>` if the
+ expression cannot be evaluated (e.g. attempting to call a function with an
+ invalid number of arguments).
+
+Properties
+~~~~~~~~~~
+
+expression.is_empty (read-only)
+ A Boolean indicating whether the expression contains no tokens.
+expression.original_string (read-only)
+ The original string that was parsed to create the expression.
+expression.symbols (read/write)
+ The :ref:`symbol table <luascript-ref-debugsymtable>` used for to look up
+ symbols in the expression.
+
+
+.. _luascript-ref-debugsymentry:
+
+Symbol entry
+------------
+
+Wraps MAME’s ``symbol_entry`` class, which represents an entry in a
+:ref:`symbol table <luascript-ref-debugsymtable>`. Note that symbol entries
+must not be used after the symbol table they belong to is destroyed.
+
+Instantiation
+~~~~~~~~~~~~~
+
+symbols:add(name, [value])
+ Adds an integer symbol to a
+ :ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
+ entry.
+symbols:add(name, getter, [setter], [format])
+ Adds an integer symbol to a
+ :ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
+ entry.
+symbols:add(name, minparams, maxparams, execute)
+ Adds function symbol to a
+ :ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
+ entry.
+
+Properties
+~~~~~~~~~~
+
+entry.name (read-only)
+ The name of the symbol entry.
+entry.format (read-only)
+ The format string used to convert the symbol entry to text for display.
+entry.is_function (read-only)
+ A Boolean indicating whether the symbol entry is a callable function.
+entry.is_lval (read-only)
+ A Boolean indicating whether the symbol entry is an integer symbol that can
+ be set (i.e. whether it can be used on the left-hand side of assignment
+ expressions).
+entry.value (read/write)
+ The integer value of the symbol entry. Attempting to set the value raises
+ an error if the symbol entry is read-only. Attempting to get or set the
+ value of a function symbol raises an error.
+
+
+.. _luascript-ref-debugman:
+
+Debugger manager
+----------------
+
+Wraps MAME’s ``debugger_manager`` class, providing the main interface to control
+the debugger.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.debugger
+ Returns the global debugger manager instance, or ``nil`` if the debugger is
+ not enabled.
+
+Methods
+~~~~~~~
+
+debugger:command(str)
+ Execute a debugger console command. The argument is the command string.
+ The output is sent to both the debugger console and the Lua console.
+
+Properties
+~~~~~~~~~~
+
+debugger.consolelog[] (read-only)
+ The lines in the console log (output from debugger commands). This
+ container only supports index and length operations.
+debugger.errorlog[] (read-only)
+ The lines in the error log (``logerror`` output). This container only
+ supports index and length operations.
+debugger.visible_cpu (read/write)
+ The CPU device with debugger focus. Changes become visible in the debugger
+ console after the next step. Setting to a device that is not a CPU has no
+ effect.
+debugger.execution_state (read/write)
+ Either ``"run"`` if the emulated system is running, or ``"stop"`` if it is
+ stopped in the debugger.
+
+
+.. _luascript-ref-devdebug:
+
+Device debugger interface
+-------------------------
+
+Wraps MAME’s ``device_debug`` class, providing the debugger interface to an
+emulated CPU device.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].debug
+ Returns the debugger interface for an emulated CPU device, or ``nil`` if the
+ device is not a CPU.
+
+Methods
+~~~~~~~
+
+debug:step([cnt])
+ Step by the specified number of instructions. If the instruction count is
+ not provided, it defaults to a single instruction.
+debug:go()
+ Run the emulated CPU.
+debug:bpset(addr, [cond], [act])
+ Set a breakpoint at the specified address, with an optional condition and
+ action. If the action is not specified, it defaults to just breaking into
+ the debugger. Returns the breakpoint number for the new breakpoint.
+
+ If specified, the condition must be a debugger expression that will be
+ evaluated each time the breakpoint is hit. Execution will only be stopped
+ if the expression evaluates to a non-zero value. If the condition is not
+ specified, it defaults to always active.
+debug:bpenable([bp])
+ Enable the specified breakpoint, or all breakpoints for the device if no
+ breakpoint number is specified. Returns whether the specified number
+ matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
+ breakpoint number is specified.
+debug:bpdisable([bp])
+ Disable the specified breakpoint, or all breakpoints for the device if no
+ breakpoint number is specified. Returns whether the specified number
+ matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
+ breakpoint number is specified.
+debug:bpclear([bp])
+ Clear the specified breakpoint, or all breakpoints for the device if no
+ breakpoint number is specified. Returns whether the specified number
+ matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
+ breakpoint number is specified.
+debug:bplist()
+ Returns a table of breakpoints for the device. The keys are the breakpoint
+ numbers, and the values are
+ :ref:`breakpoint objects <luascript-ref-breakpoint>`.
+debug:wpset(space, type, addr, len, [cond], [act])
+ Set a watchpoint over the specified address range, with an optional
+ condition and action. The type must be ``"r"``, ``"w"`` or ``"rw"`` for a
+ read, write or read/write breakpoint. If the action is not specified, it
+ defaults to just breaking into the debugger. Returns the watchpoint number
+ for the new watchpoint.
+
+ If specified, the condition must be a debugger expression that will be
+ evaluated each time the breakpoint is hit. Execution will only be stopped
+ if the expression evaluates to a non-zero value. The variable 'wpaddr' is
+ set to the address that actually triggered the watchpoint, the variable
+ 'wpdata' is set to the data that is being read or written, and the variable
+ 'wpsize' is set to the size of the data in bytes. If the condition is not
+ specified, it defaults to always active.
+debug:wpenable([wp])
+ Enable the specified watchpoint, or all watchpoints for the device if no
+ watchpoint number is specified. Returns whether the specified number
+ matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
+ watchpoint number is specified.
+debug:wpdisable([wp])
+ Disable the specified watchpoint, or all watchpoints for the device if no
+ watchpoint number is specified. Returns whether the specified number
+ matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
+ watchpoint number is specified.
+debug:wpclear([wp])
+ Clear the specified watchpoint, or all watchpoints for the device if no
+ watchpoint number is specified. Returns whether the specified number
+ matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
+ watchpoint number is specified.
+debug:wplist(space)
+ Returns a table of watchpoints for the specified address space of the
+ device. The keys are the watchpoint numbers, and the values are
+ :ref:`watchpoint objects <luascript-ref-watchpoint>`.
+
+
+.. _luascript-ref-breakpoint:
+
+Breakpoint
+----------
+
+Wraps MAME’s ``debug_breakpoint`` class, representing a breakpoint for an
+emulated CPU device.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].debug:bplist()[bp]
+ Gets the specified breakpoint for an emulated CPU device, or ``nil`` if no
+ breakpoint corresponds to the specified index.
+
+Properties
+~~~~~~~~~~
+
+breakpoint.index (read-only)
+ The breakpoint’s index. The can be used to enable, disable or clear the
+ breakpoint via the
+ :ref:`CPU debugger interface <luascript-ref-devdebug>`.
+breakpoint.enabled (read/write)
+ A Boolean indicating whether the breakpoint is currently enabled.
+breakpoint.address (read-only)
+ The breakpoint’s address.
+breakpoint.condition (read-only)
+ A debugger expression evaluated each time the breakpoint is hit. The action
+ will only be triggered if this expression evaluates to a non-zero value. An
+ empty string if no condition was specified.
+breakpoint.action (read-only)
+ An action the debugger will run when the breakpoint is hit and the condition
+ evaluates to a non-zero value. An empty string if no action was specified.
+
+
+.. _luascript-ref-watchpoint:
+
+Watchpoint
+----------
+
+Wraps MAME’s ``debug_watchpoint`` class, representing a watchpoint for an
+emulated CPU device.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].debug:wplist(space)[wp]
+ Gets the specified watchpoint for an address space of an emulated CPU
+ device, or ``nil`` if no watchpoint in the address space corresponds to the
+ specified index.
+
+Properties
+~~~~~~~~~~
+
+watchpoint.index (read-only)
+ The watchpoint’s index. The can be used to enable, disable or clear the
+ watchpoint via the
+ :ref:`CPU debugger interface <luascript-ref-devdebug>`.
+watchpoint.enabled (read/write)
+ A Boolean indicating whether the watchpoint is currently enabled.
+watchpoint.type (read-only)
+ Either ``"r"``, ``"w"`` or ``"rw"`` for a read, write or read/write
+ watchpoint.
+watchpoint.address (read-only)
+ The starting address of the watchpoint’s address range.
+watchpoint.length (read-only)
+ The length of the watchpoint’s address range.
+watchpoint.condition (read-only)
+ A debugger expression evaluated each time the watchpoint is hit. The action
+ will only be triggered if this expression evaluates to a non-zero value. An
+ empty string if no condition was specified.
+watchpoint.action (read-only)
+ An action the debugger will run when the watchpoint is hit and the condition
+ evaluates to a non-zero value. An empty string if no action was specified.
+
+
+.. _luascript-ref-debugexpressionerror:
+
+Expression error
+----------------
+
+Wraps MAME’s ``expression_error`` class, describing an error occurring while
+parsing or executing a debugger expression. Raised on errors when using
+:ref:`parsed expressions <luascript-ref-debugexpression>`. Can be converted to
+a string to provide a description of the error.
+
+Properties
+~~~~~~~~~~
+
+err.code (read-only)
+ An implementation-dependent number representing the category of error.
+ Should not be displayed to the user.
+err.offset (read-only)
+ The offset within the expression string where the error was encountered.