general
memory
execution
breakpoint
watchpoint
registerpoints
exceptionpoint
annotation
cheats
image

Literal numbers are prefixed according to their bases:

* Hexadecimal (base-16) with ``$`` or ``0x``
* Decimal (base-10) with ``#``
* Octal (base-8) with ``0o``
* Binary (base-2) with ``0b``
* Unprefixed numbers are hexadecimal (base-16).

Examples:

* ``123`` is 123 hexadecimal (291 decimal)
* ``$123`` is 123 hexadecimal (291 decimal)
* ``0x123`` is 123 hexadecimal (291 decimal)
* ``#123`` is 123 decimal
* ``0o123`` is 123 octal (83 decimal)
* ``0b1001`` is 1001 binary (9 decimal)
* ``0b123`` is invalid


.. _debugger-express-bool:

Boolean values

The memory access prefix operators allow reading from and writing to
emulated address spaces.  The memory prefix operators specify the
access size and whether side effects are disabled, and may optionally be
preceded by an address space specification.  The supported access sizes
and side effect modes are as follows:

* ``b`` specifies an 8-bit access (byte)
* ``w`` specifies a 16-bit access (word)
* ``d`` specifies a 32-bit access (double word)
* ``q`` specifies a 64-bit access (quadruple word)
* ``@`` suppress side effects
* ``!`` do not suppress side effects

Suppressing side effects of a read access yields the value reading from
address would, with no further effects.  For example reading a mailbox
with side effects disabled will not clear the pending flag, and reading
a FIFO with side effects disabled will not remove an item.

For write accesses, suppressing side effects doesn’t change behaviour in
most cases – you want to see the effects of writing to a location.
However, there are some exceptions where it is useful to separate
multiple effects of a write access.  For example:

* Some registers need to be written in sequence to avoid race
  conditions.  The debugger can issue multiple writes at the same point
  in emulated time, so these race conditions can be avoided trivially.
  For example writing to the MC68HC05 output compare register high byte
  (OCRH) inhibits compare until the output compare register low byte
  (OCRL) is written to prevent race conditions.  Since the debugger can
  write to both locations at the same instant from the emulated
  machine’s point of view, the race condition is not usually relevant.
  It’s more error-prone if you can accidentally set hidden state when
  all you really want to do is change the value, so writing to OCRH with
  side effects suppressed does not inhibit compare, it just changes the
  value in the output compare register.
* Writing to some registers has multiple effects that may be useful to
  separate for debugging purposes.  Using the MC68HC05 as an example
  again, writing to OCRL changes the value in the output compare
  register, and also clears the output compare flag (OCF) and enables
  compare if it was previously inhibited by writing to OCRH.  Writing to
  OCRL with side effects disabled just changes the value in the register
  without clearing OCF or enabling compare, since it’s useful for
  debugging purposes.  Writing to OCRL with side effects enabled has the
  additional effects.

The size may optionally be preceded by an access type specification:

* ``p`` or ``lp`` specifies a logical address defaulting to space 0
  (program)
* ``d`` or ``ld`` specifies a logical address defaulting to space 1
  (data)
* ``i`` or ``li`` specifies a logical address defaulting to space 2
  (I/O)
* ``3`` or ``l3`` specifies a logical address defaulting to space 3
  (opcodes)
* ``pp`` specifies a physical address defaulting to space 0 (program)
* ``pd`` specifies a physical address defaulting to space 1 (data)
* ``pi`` specifies a physical address defaulting to space 2 (I/O)
* ``p3`` specifies a physical address defaulting to space 3 (opcodes)
* ``r`` specifies direct read/write pointer access defaulting to space 0
  (program)
* ``o`` specifies direct read/write pointer access defaulting to space 3
  (opcodes)
* ``m`` specifies a memory region
* ``s`` specifies a memory share

Finally, this may be preceded by a tag and/or address space name
followed by a dot (``.``).

That may seem like a lot to digest, so let’s look at the simplest
examples:

``b@<addr>``
    Refers to the byte at **<addr>** in the program space of the current
    CPU while suppressing side effects
``b!<addr>``
    Refers to the byte at **<addr>** in the program space of the current
    CPU, *not* suppressing side effects such as reading a mailbox
    clearing the pending flag, or reading a FIFO removing an item
``w@<addr>`` and ``w!<addr>``
    Refer to the word at **<addr>** in the program space of the current
    CPU, suppressing or not suppressing side effects, respectively.
``d@<addr>`` and ``d!<addr>``
    Refer to the double word at **<addr>** in the program space of the
    current CPU, suppressing or not suppressing side effects,
    respectively.
``q@<addr>`` and ``q!<addr>``
    Refer to the quadruple word at **<addr>** in the program space of
    the current CPU, suppressing or not suppressing side effects,
    respectively.

Adding access types gives additional possibilities:

``dw@300``
    Refers to the word at 300 in the data space of the current CPU while
    suppressing side effects
``id@400``
    Refers to the double word at 400 in the I/O space of the current CPU
    while suppressing side effects
``ppd!<addr>``
    Refers to the double word at physical address **<addr>** in the
    program space of the current CPU while not suppressing side effects
``rw@<addr>``
    Refers to the word at address **<addr>** in the program space of the
    current CPU using direct read/write pointer access

If we want to access an address space of a device other than the current
CPU, an address space beyond the first four indices, or a memory region,
we need to include a tag or name:

``ramport.b@<addr>``
    Refers to the byte at address **<addr>** in the ``ramport`` space of
    the current CPU
``audiocpu.dw@<addr>``
    Refers to the word at address **<addr>** in the data space of the
    CPU with absolute tag ``:audiocpu``
``maincpu:status.b@<addr>``
    Refers to the byte at address **<addr>** in the ``status`` space of
    the CPU with the absolute tag ``:maincpu``
``monitor.mb@78``
    Refers to the byte at 78 in the memory region with the absolute tag
    ``:monitor``
``..md@202``
    Refers to the double word at address 202 in the memory region with
    the same tag path as the current CPU.

Some combinations are not useful.  For example physical and logical
addresses are equivalent for some CPUs, and direct read/write pointer
accesses never have side effects.  Accessing a memory region (``m``
access type) requires a tag to be specified.

Memory accesses can be used as both lvalues and rvalues, so you can write
``b@100 = ff`` to store a byte in memory.


.. _debugger-express-func:

Functions
~~~~~~~~~

The debugger supports a number of useful utility functions in expressions.

min(<a>, <b>)
    Returns the lesser of the two arguments.
max(<a>, <b>)
    Returns the greater of the two arguments.
if(<cond>, <trueval>, <falseval>)
    Returns **<trueval>** if **<cond>** is true (non-zero), or
    **<falseval>** otherwise.  Note that the expressions for
    **<trueval>** and **<falseval>** are both evaluated irrespective of
    whether **<cond>** is true or false.
abs(<x>)
    Reinterprets the argument as a 64-bit signed integer and returns the
    absolute value.
bit(<x>, <n>[, <w>])
    Extracts and right-aligns a bit field **<w>** bits wide from **<x>**
    with least significant bit position **<n>**, counting from the
    least significant bit.  If **<w>** is omitted, a single bit is
    extracted.
s8(<x>)
    Sign-extends the argument from 8 bits to 64 bits (overwrites bits 8
    through 63, inclusive, with the value of bit 7, counting from the
    least significant bit).
s16(<x>)
    Sign-extends the argument from 16 bits to 64 bits (overwrites bits
    16 through 63, inclusive, with the value of bit 15, counting from
    the least significant bit).
s32(<x>)
    Sign-extends the argument from 32 bits to 64 bits (overwrites bits
    32 through 63, inclusive, with the value of bit 31, counting from
    the least significant bit).