summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/debugger/memory.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/debugger/memory.rst')
-rw-r--r--docs/source/debugger/memory.rst506
1 files changed, 373 insertions, 133 deletions
diff --git a/docs/source/debugger/memory.rst b/docs/source/debugger/memory.rst
index 7f9414e085f..da3645a6d1e 100644
--- a/docs/source/debugger/memory.rst
+++ b/docs/source/debugger/memory.rst
@@ -3,165 +3,405 @@
Memory Debugger Commands
========================
+:ref:`debugger-command-dasm`
+ disassemble code to a file
+:ref:`debugger-command-find`
+ search emulated memory for data
+:ref:`debugger-command-fill`
+ search emulated memory with specified pattern
+:ref:`debugger-command-dump`
+ dump emulated memory to a file as text
+:ref:`debugger-command-strdump`
+ dump delimited strings from emulated memory to a file
+:ref:`debugger-command-save`
+ save binary data from emulated memory to a file
+:ref:`debugger-command-saver`
+ save binary data from a memory region to a file
+:ref:`debugger-command-load`
+ load binary data from a file to emulated memory
+:ref:`debugger-command-loadr`
+ load binary data from a file to a memory region
+:ref:`debugger-command-map`
+ map a logical address to the corresponding physical address and
+ handler
+:ref:`debugger-command-memdump`
+ dump current memory maps to a file
-You can also type **help <command>** for further details on each command in the MAME Debugger interface.
-| :ref:`debugger-command-dasm` -- disassemble to the given file
-| :ref:`debugger-command-find` -- search program memory, data memory, or I/O memory for data
-| :ref:`debugger-command-dump` -- dump program memory, data memory, or I/O memory as text
-| :ref:`debugger-command-save` -- save binary program, data, or I/O memory to the given file
-| :ref:`debugger-command-load` -- load binary program memory, data memory, or I/O memory from the given file
-| :ref:`debugger-command-map` -- map logical program, data, or I/O address to physical address and bank
+.. _debugger-command-dasm:
+dasm
+----
+**dasm <filename>,<address>,<length>[,<opcodes>[,<CPU>]]**
+Disassembles program memory to the file specified by the **<filename>**
+parameter. The **<address>** parameter specifies the address to start
+disassembling from, and the **<length>** parameter specifies how much
+memory to disassemble. The range **<address>** through
+**<address>+<length>-1**, inclusive, will be disassembled to the file.
+By default, raw opcode data is output with each line. The optional
+**<opcodes>** parameter is a Boolean that enables disables this feature.
+By default, program memory for the visible CPU is disassembled. To
+disassemble program memory for a different CPU, specify it using the
+optional fifth parameter (see :ref:`debugger-devicespec` for details).
- .. _debugger-command-dasm:
+Examples:
-dasm
-----
+``dasm venture.asm,0,10000``
+ Disassembles addresses 0-ffff for the visible CPU, including raw
+ opcode data, to the file **venture.asm**.
+``dasm harddriv.asm,3000,1000,0,2``
+ Disassembles addresses 3000-3fff for the third CPU in the system
+ (zero-based index), without raw opcode data, to the file
+ **harddriv.asm**.
+
+Back to :ref:`debugger-memory-list`
-| **dasm <filename>,<address>,<length>[,<opcodes>[,<cpu>]]**
-|
-| The dasm command disassembles program memory to the file specified in the <filename> parameter. <address> indicates the address of the start of disassembly, and <length> indicates how much memory to disassemble. The range <address> through <address>+<length>-1 inclusive will be output to the file. By default, the raw opcode data is output with each line. The optional <opcodes> parameter can be used to enable (1) or disable (0) this feature. Finally, you can disassemble code from another CPU by specifying the <cpu> parameter.
-|
-| Examples:
-|
-| dasm venture.asm,0,10000
-|
-| Disassembles addresses 0-ffff in the current CPU, including raw opcode data, to the file 'venture.asm'.
-|
-| dasm harddriv.asm,3000,1000,0,2
-|
-| Disassembles addresses 3000-3fff from CPU #2, with no raw opcode data, to the file 'harddriv.asm'.
-|
-| Back to :ref:`debugger-memory-list`
-
-
- .. _debugger-command-find:
+
+.. _debugger-command-find:
find
----
-| **f[ind][{d|i}] <address>,<length>[,<data>[,...]]**
-|
-| The **find**/**findd**/**findi** commands search through memory for the specified sequence of data. 'find' will search program space memory, while 'findd' will search data space memory and 'findi' will search I/O space memory. <address> indicates the address to begin searching, and <length> indicates how much memory to search. <data> can either be a quoted string or a numeric value or expression or the wildcard character '?'. Strings by default imply a byte-sized search; non-string data is searched by default in the native word size of the CPU. To override the search size for non-strings, you can prefix the value with b. to force byte- sized search, w. for word-sized search, d. for dword-sized, and q. for qword-sized. Overrides are remembered, so if you want to search for a series of words, you need only to prefix the first value with a w. Note also that you can intermix sizes in order to perform more complex searches. The entire range <address> through <address>+<length>-1 inclusive will be searched for the sequence, and all occurrences will be displayed.
-|
-| Examples:
-|
-| find 0,10000,"HIGH SCORE",0
-|
-| Searches the address range 0-ffff in the current CPU for the string "HIGH SCORE" followed by a 0 byte.
-|
-| findd 3000,1000,w.abcd,4567
-|
-| Searches the data memory address range 3000-3fff for the word-sized value abcd followed by the word-sized value 4567.
-|
-| find 0,8000,"AAR",d.0,"BEN",w.0
-|
-| Searches the address range 0000-7fff for the string "AAR" followed by a dword-sized 0 followed by the string "BEN", followed by a word-sized 0.
-|
-| Back to :ref:`debugger-memory-list`
-
-
- .. _debugger-command-dump:
+**f[ind][{d|i|o}] <address>[:<space>],<length>[,<data>[,...]]**
+
+Search through memory for the specified sequence of data. The
+**<address>** is the address to begin searching from, optionally
+followed by a device and/or address space (see
+:ref:`debugger-devicespec` for details); the **<length>** specifies
+how much memory to search. If an address space is not specified, the
+command suffix sets the address space: ``find`` defaults to the first
+address space exposed by the device, ``findd`` defaults to the space
+with index 1 (data), ``findi`` default to the space with index 2 (I/O),
+and ``findo`` defaults to the space with index 3 (opcodes).
+
+The **<data>** can either be a quoted string, a numeric value or
+expression, or the wildcard character ``?``. By default, strings imply
+a byte-sized search; by default non-string data is searched using the
+native word size of the address space. To override the search size for
+non-string data, you can prefix values with ``b.`` to force byte-sized
+search, ``w.`` for word-sized search, ``d.`` for double word-sized
+search, and ``q.`` for quadruple word-sized search. Overrides propagate
+to subsequent values, so if you want to search for a sequence of words,
+you need only prefix the first value with ``w.``. Also note that you
+can intermix sizes to perform more complex searches.
+
+The entire range **<address>** through **<address>+<length>-1**,
+inclusive, will be searched for the sequence, and all occurrences will
+be displayed.
+
+Examples:
+
+``find 0,10000,"HIGH SCORE",0``
+ Searches the address range 0-ffff in the program space of the
+ visible CPU for the string “HIGH SCORE” followed by a 0 byte.
+``find 300:tms9918a,100,w.abcd,4567``
+ Searches the address range 300-3ff in the first address space
+ exposed by the device with the absolute tag ``:tms9918a`` for the
+ word-sized value abcd followed by the word-sized value 4567.
+``find 0,8000,"AAR",d.0,"BEN",w.0``
+ Searches the address range 0000-7fff for the string “AAR” followed
+ by a dword-sized 0 followed by the string “BEN”, followed by a
+ word-sized 0.
+
+Back to :ref:`debugger-memory-list`
+
+
+.. _debugger-command-fill:
+
+fill
+----
+
+**fill[{d|i|o}] <address>[:<space>],<length>[,<data>[,...]]**
+
+Overwrite a block of memory with copies of the supplied data sequence.
+The **<address>** specifies the address to begin writing at, optionally
+followed by a device and/or address space (see
+:ref:`debugger-devicespec` for details); the **<length>** specifies how
+much memory to fill. If an address space is not specified, the command
+suffix sets the address space: ``fill`` defaults to the first
+address space exposed by the device, ``filld`` defaults to the space
+with index 1 (data), ``filli`` default to the space with index 2 (I/O),
+and ``fillo`` defaults to the space with index 3 (opcodes).
+
+The **<data>** can either be a quoted string, or a numeric value or
+expression. By default, non-string data is written using the native
+word size of the address space. To override the data size for non-string
+data, you can prefix values with ``b.`` to force byte-sized fill, ``w.``
+for word-sized fill, ``d.`` for double word-sized fill, and ``q.`` for
+quadruple word-sized fill. Overrides propagate to subsequent values, so
+if you want to fill with a series of words, you need only prefix the
+first value with ``w.``. Also note that you can intermix sizes to
+perform more complex fills. The fill operation may be truncated if a
+page fault occurs or if part of the sequence or string would fall beyond
+**<address>+<length>-1**.
+
+Back to :ref:`debugger-memory-list`
+
+
+.. _debugger-command-dump:
dump
----
-| **dump[{d|i}] <filename>,<address>,<length>[,<size>[,<ascii>[,<cpu>]]]**
-|
-| The **dump**/**dumpd**/**dumpi** commands dump memory to the text file specified in the <filename> parameter.
-| 'dump' will dump program space memory, while 'dumpd' will dump data space memory and 'dumpi' will dump I/O space memory.
-| <address> indicates the address of the start of dumping, and <length> indicates how much memory to dump. The range <address> through <address>+<length>-1 inclusive will be output to the file.
-| By default, the data will be output in byte format, unless the underlying address space is word/dword/qword-only. You can override this by specifying the <size> parameter, which can be used to group the data in 1, 2, 4 or 8-byte chunks.
-| The optional <ascii> parameter can be used to enable (1) or disable (0) the output of ASCII characters to the right of each line; by default, this is enabled.
-| Finally, you can dump memory from another CPU by specifying the <cpu> parameter.
-|
-|
-| Examples:
-|
-| dump venture.dmp,0,10000
-|
-| Dumps addresses 0-ffff in the current CPU in 1-byte chunks, including ASCII data, to the file 'venture.dmp'.
-|
-| dumpd harddriv.dmp,3000,1000,4,0,3
-|
-| Dumps data memory addresses 3000-3fff from CPU #3 in 4-byte chunks, with no ASCII data, to the file 'harddriv.dmp'.
-|
-| Back to :ref:`debugger-memory-list`
-
-
- .. _debugger-command-save:
+**dump[{d|i|o}] <filename>,<address>[:<space>],<length>[,<group>[,<ascii>[,<rowsize>]]]**
+
+Dump memory to the text file specified by the **<filename>** parameter.
+The **<address>** specifies the address to start dumping from,
+optionally followed by a device and/or address space (see
+:ref:`debugger-devicespec` for details); the **<length>** specifies how
+much memory to dump. If an address space is not specified, the command
+suffix sets the address space: ``dump`` defaults to the first
+address space exposed by the device, ``dumpd`` defaults to the space
+with index 1 (data), ``dumpi`` default to the space with index 2 (I/O),
+and ``dumpo`` defaults to the space with index 3 (opcodes).
+
+The range **<address>** through **<address>+<length>-1**, inclusive,
+will be output to the file. By default, the data will be output using
+the native word size of the address space. You can override this by
+specifying the **<group>** parameter, which can be used to group the
+data in 1-, 2-, 4- or 8-byte chunks. The optional **<ascii>** parameter
+is a Boolean value used to enable or disable output of ASCII characters
+on the right of each line (enabled by default). The optional
+**<rowsize>** parameter specifies the amount of data on each line in
+address units (defaults to 16 bytes).
+
+Examples:
+
+``dump venture.dmp,0,10000``
+ Dumps addresses 0-ffff from the program space of the visible CPU in
+ 1-byte chunks, including ASCII data, to the file **venture.dmp**.
+``dumpd harddriv.dmp,3000:3,1000,4,0``
+ Dumps data memory addresses 3000-3fff from the fourth CPU in the
+ system (zero-based index) in 4-byte chunks, without ASCII data, to
+ the file **harddriv.dmp**.
+``dump vram.dmp,0:sms_vdp:videoram,4000,1,false,8``
+ Dumps ``videoram`` space addresses 0000-3fff from the device with
+ the absolute tag path ``:sms_vdp`` in 1-byte chunks, without ASCII
+ data, with 8 bytes per line, to the file **vram.dmp**.
+
+Back to :ref:`debugger-memory-list`
+
+
+.. _debugger-command-strdump:
+
+strdump
+-------
+
+**strdump[{d|i|o}] <filename>,<address>[:<space>],<length>[,<term>]**
+
+Dump memory to the text file specified by the **<filename>** parameter.
+The **<address>** specifies the address to start dumping from,
+optionally followed by a device and/or address space (see
+:ref:`debugger-devicespec` for details); the **<length>** specifies how
+much memory to dump. If an address space is not specified, the command
+suffix sets the address space: ``strdump`` defaults to the first
+address space exposed by the device, ``strdumpd`` defaults to the space
+with index 1 (data), ``strdumpi`` default to the space with index 2
+(I/O), and ``strdumpo`` defaults to the space with index 3 (opcodes).
+
+By default, the data will be interpreted as a series of NUL-terminated
+(ASCIIZ) strings, the dump will have one string per line, and C-style
+escapes sequences will be used for bytes that do not represent printable
+ASCII characters. The optional **<term>** parameter can be used to
+specify a different string terminator character.
+
+Back to :ref:`debugger-memory-list`
+
+
+.. _debugger-command-save:
save
----
-| **save[{d|i}] <filename>,<address>,<length>[,<cpu>]**
-|
-| The **save**/**saved**/**savei** commands save raw memory to the binary file specified in the <filename> parameter.
-| 'save' will save program space memory, while 'saved' will save data space memory and 'savei' will save I/O space memory.
-| <address> indicates the address of the start of saving, and <length> indicates how much memory to save. The range <address> through <address>+<length>-1 inclusive will be output to the file.
-| You can also save memory from another CPU by specifying the <cpu> parameter.
-|
-|
-| Examples:
-|
-| save venture.bin,0,10000
-|
-| Saves addresses 0-ffff in the current CPU to the binary file 'venture.bin'.
-|
-| saved harddriv.bin,3000,1000,3
-|
-| Saves data memory addresses 3000-3fff from CPU #3 to the binary file 'harddriv.bin'.
-|
-| Back to :ref:`debugger-memory-list`
-
-
- .. _debugger-command-load:
+**save[{d|i|o}] <filename>,<address>[:<space>],<length>**
+
+Save raw memory to the binary file specified by the **<filename>**
+parameter. The **<address>** specifies the address to start saving
+from, optionally followed by a device and/or address space (see
+:ref:`debugger-devicespec` for details); the **<length>** specifies how
+much memory to save. If an address space is not specified, the command
+suffix sets the address space: ``save`` defaults to the first address
+space exposed by the device, ``saved`` defaults to the space with index
+1 (data), ``savei`` default to the space with index 2 (I/O), and
+``saveo`` defaults to the space with index 3 (opcodes).
+
+The range **<address>** through **<address>+<length>-1**, inclusive,
+will be output to the file.
+
+Examples:
+
+``save venture.bin,0,10000``
+ Saves addresses 0-ffff from the program space of the current CPU to
+ the binary file **venture.bin**
+``saved harddriv.bin,3000:3,1000``
+ Saves data memory addresses 3000-3fff from the fourth CPU in the
+ system (zero-based index) to the binary file **harddriv.bin**.
+``save vram.bin,0:sms_vdp:videoram,4000``
+ Saves ``videoram`` space addresses 0000-3fff from the device with
+ the absolute tag path ``:sms_vdp`` to the binary file **vram.bin**.
+
+Back to :ref:`debugger-memory-list`
+
+
+.. _debugger-command-saver:
+
+saver
+-----
+
+**saver <filename>,<address>,<length>,<region>**
+
+Save raw content of memory region specified by the **<region>**
+parameter to the binary file specified by the **<filename>** parameter.
+Regions tags follow the same rules as device tags (see
+:ref:`debugger-devicespec`). The **<address>** specifies the address to
+start saving from, and the **<length>** specifies how much memory to
+save. The range **<address>** through **<address>+<length>-1**,
+inclusive, will be output to the file.
+
+Examples:
+
+``saver data.bin,200,100,:monitor``
+ Saves ``:monitor`` region addresses 200-2ff to the binary file
+ **data.bin**.
+``saver cpurom.bin,1000,400,.``
+ Saves addresses 1000-13ff from the memory region with the same tag
+ as the visible CPU to the binary file **cpurom.bin**.
+
+Back to :ref:`debugger-memory-list`
+
+
+.. _debugger-command-load:
load
----
-| **load[{d|i}] <filename>,<address>[,<length>,<cpu>]**
-|
-| The **load**/**loadd**/**loadi** commands load raw memory from the binary file specified in the <filename> parameter.
-| 'load' will load program space memory, while 'loadd' will load data space memory and 'loadi' will load I/O space memory.
-| <address> indicates the address of the start of saving, and <length> indicates how much memory to load. The range <address> through <address>+<length>-1 inclusive will be read in from the file.
-| If you specify <length> = 0 or a length greater than the total length of the file it will load the entire contents of the file and no more.
-| You can also load memory from another CPU by specifying the <cpu> parameter.
-|
-| NOTE: This will only actually write memory that is possible to overwrite in the Memory Window
-|
-|
-| Examples:
-|
-| load venture.bin,0,10000
-|
-| Loads addresses 0-ffff in the current CPU from the binary file 'venture.bin'.
-|
-| loadd harddriv.bin,3000,1000,3
-|
-| Loads data memory addresses 3000-3fff from CPU #3 from the binary file 'harddriv.bin'.
-|
-| Back to :ref:`debugger-memory-list`
-
-
- .. _debugger-command-map:
+**load[{d|i|o}] <filename>,<address>[:<space>][,<length>]**
+
+Load raw memory from the binary file specified by the **<filename>**
+parameter. The **<address>** specifies the address to start loading to,
+optionally followed by a device and/or address space (see
+:ref:`debugger-devicespec` for details); the **<length>** specifies how
+much memory to load. If an address space is not specified, the command
+suffix sets the address space: ``load`` defaults to the first address
+space exposed by the device, ``loadd`` defaults to the space with index
+1 (data), ``loadi`` default to the space with index 2 (I/O), and
+``loado`` defaults to the space with index 3 (opcodes).
+
+The range **<address>** through **<address>+<length>-1**, inclusive,
+will be read in from the file. If the **<length>** is omitted, if it is
+zero, or if it is greater than the total length of the file, the entire
+contents of the file will be loaded but no more.
+
+Note that this has the same effect as writing to the address space from
+a debugger memory view, or using the ``b@``, ``w@``, ``d@`` or ``q@``
+memory accessors in debugger expressions. Read-only memory will not be
+overwritten, and writing to I/O addresses may have effects beyond
+setting register values.
+
+Examples:
+
+``load venture.bin,0,10000``
+ Loads addresses 0-ffff in the program space for the visible CPU from
+ the binary file **venture.bin**.
+``loadd harddriv.bin,3000,1000,3``
+ Loads data memory addresses 3000-3fff in the program space for the
+ fourth CPU in the system (zero-based index) from the binary file
+ **harddriv.bin**.
+``load vram.bin,0:sms_vdp:videoram``
+ Loads the ``videoram`` space for the device with the absolute tag
+ path ``:sms_vdp`` starting at address 0000 with the entire content
+ of the binary file **vram.bin**.
+
+Back to :ref:`debugger-memory-list`
+
+
+.. _debugger-command-loadr:
+
+loadr
+-----
+
+**loadr <filename>,<address>,<length>,<region>**
+
+Load memory in the memory region specified by the **<region>** with raw
+data from the binary file specified by the **<filename>** parameter.
+Regions tags follow the same rules as device tags (see
+:ref:`debugger-devicespec`). The **<address>** specifies the address to
+start loading to, and the
+**<length>** specifies how much memory to load. The range **<address>**
+through **<address>+<length>-1**, inclusive, will be read in from the
+file. If the **<length>** is zero, or is greater than the total length
+of the file, the entire contents of the file will be loaded but no more.
+
+Examples:
+
+``loadr data.bin,200,100,:monitor``
+ Loads ``:monitor`` region addresses 200-2ff from the binary file
+ **data.bin**.
+``loadr cpurom.bin,1000,400,.``
+ Loads addresses 1000-13ff in the memory region with the same tag as
+ the visible CPU from the binary file **cpurom.bin**.
+
+Back to :ref:`debugger-memory-list`
+
+
+.. _debugger-command-map:
map
---
-| **map[{d|i}] <address>**
-|
-| The map/mapd/mapi commands map a logical address in memory to the correct physical address, as well as specifying the bank.
-| 'map' will map program space memory, while 'mapd' will map data space memory and 'mapi' will map I/O space memory.
-|
-| Example:
-|
-| map 152d0
-|
-| Gives physical address and bank for logical address 152d0 in program memory
-|
-| Back to :ref:`debugger-memory-list`
+**map[{d|i|o}] <address>[:<space>]**
+
+Map a logical memory address to the corresponding physical address, as
+well as reporting the handler name. The address may optionally be
+followed by a colon and device and/or address space (see
+:ref:`debugger-devicespec` for details). If an address space is not
+specified, the command suffix sets the address space: ``map`` defaults
+to the first address space exposed by the device, ``mapd`` defaults to
+the space with index 1 (data), ``mapi`` default to the space with index
+2 (I/O), and ``mapo`` defaults to the space with index 3 (opcodes).
+
+Examples:
+
+``map 152d0``
+ Gives the physical address and handler name for logical address
+ 152d0 in program memory for the visible CPU.
+``map 107:sms_vdp``
+ Gives the physical address and handler name for logical address 107
+ in the first address space for the device with the absolute tag path
+ ``:sms_vdp``.
+
+Back to :ref:`debugger-memory-list`
+
+
+.. _debugger-command-memdump:
+
+memdump
+-------
+
+**memdump [<filename>,[<device>]]**
+
+Dumps the current memory maps to the file specified by **<filename>**,
+or **memdump.log** if omitted. If **<device>** is specified (see
+:ref:`debugger-devicespec`), only memory maps for the part of the device
+tree rooted at this device will be dumped.
+
+Examples:
+
+``memdump mylog.log``
+ Dumps memory maps for all devices in the system to the file
+ **mylog.log**.
+``memdump``
+ Dumps memory maps for all devices in the system to the file
+ **memdump.log**.
+``memdump audiomaps.log,audiopcb``
+ Dumps memory maps for the device with the absolute tag path
+ ``:audiopcb`` and all its child devices to the file
+ **audiomaps.log**.
+``memdump mylog.log,1``
+ Dumps memory maps for the second CPU device in the system
+ (zero-based index) and all its child devices to the file
+ **mylog.log**.
+Back to :ref:`debugger-memory-list`