The ACCESS-PATH library

Original document by Jonathan Bachrach, Scott McKay, Tony Mann, Tucker Withington, and Paul Howard.

The purpose of this document is to describe the debugger access path, which is an interface that abstracts the operations which are performed over the “tether” between the Open Dylan development environment and the running (“remote”) application. The architecture of the tethered environment is given by the following diagram. This document describes the part of the diagram labelled “Access Path”. It is target-independent, and runs in the same address space as the rest of the Open Dylan environment.

../../_images/access-path.png

The “Debugger Nub” might be on the same machine as the development environment, or it might be on the same machine as the application (in which case it might or might not be in the same process as the application). It might even be split across more than one machine or more than one process. In any case, the Debugger Nub is the part that knows how to read and write from the runtime environment, set and clear breakpoints, and so on. This part of the architecture is target-specific. The access path is able to invoke debugger nubs on remote machines by means of a “Debugger Connection” to the remote machine. This connection can be thought of as a connection to a server process on that remote machine, which has the responsibility of invoking the debugger nub, on demand.

The “Spy” is a very lightweight component that is physically part of the application. It cooperates closely with the Debugger Nub and native debugging APIs (such as ptrace or /proc), which provide most of the debugging functionality. At minimum, this part preserves a mapping between static handles and objects that are subject to relocation by the garbage collector. (The access path exposes an interface to this mapping, which we call proxy objects, or just proxies.) Nearly all of the functionality described in this document is provided either in the development environment or by the Debugger Nub. The one exception to this in the main set of protocols is the Remote Object Registration, which is provided by the Spy. Other things, such as language-specific remote function call, will also be provided in the Spy. The running application contains Dylan code, and may also contain “foreign” code.

The Derived Database contains information about most or all of the Dylan code, but will contain no information about the foreign code. The Derived Database does not contain enough information to be able to look up the name of a variable from its address or get a source line number from a PC; this information is pinned down during linking, and so is stored in the “Debug Info” part of the application. Since applications may contain foreign code as well as Dylan code, this architecture supports debugging of both. The access path exposes all of the necessary functionality to make this work.

The ACCESS-PATH Module

The following sections describe the interface that attaches the development environment (the “local” side) to an application being debugger (the “remote” side).

Creating and Attaching Access Paths

The following functions are used to create an access path with a particular application running, or to attach a remote process to an access path.

<access-path> Abstract Instantiable Class
Superclasses:

<object>

Init-Keywords:

  • application

  • arguments

  • process

  • core-file

  • application-object (required) – An instance of <object>.

  • symbol-file-locations – An instance of <sequence>.

The class that represents a “path” to an application being debugged.

If application: is supplied, it must be a string which names the application to be run, along with any necessary relative path qualification. In this case, the arguments: init keyword may also be supplied; it must be a string giving optional command line arguments to the application. In this case, the application’s initial state is stopped; you must call restart in order to start it.

For example,

let path = make(<access-path>,
                application: "/bin/rm",
                arguments: "-rf /");
restart(path);

If process: is supplied, then the access path is attached to the application being run in the given <remote-process> object. In this case, none of application:, arguments:, or core-file: may be supplied. In this case, the application’s initial state is running; you must call stop in order to halt it. When an access path is created in this way, the access path will potentially instruct the debugger server (via the debugger connection) to create a new remote debugger process.

If core-file: is supplied, it must be a string which names a core file from an application that dumped core. Again, this string must include any relative path qualifications. In this case, the application’s initial state is post-mortem.

For example,

let path = make(<access-path>,
                core-file: as(<locator>, "/home/dilbert/core"));
<application-access-path> Class
Superclasses:

<access-path>

Init-Keywords:

  • application (required) – An instance of <string>.

  • arguments – An instance of <string>.

  • debugger-connection – An instance of <object>.

  • library-search-paths – An instance of <sequence>.

  • start-in-own-shell? – An instance of <boolean>.

  • working-directory – An instance of <string>, or #f.

<access-path-creation-error> Class
Superclasses:

<error>

An instance of this error will be signaled during the initialization of an <access-path> if the debugger nub was unable to create it. This might occur if the supplied application name did not exist, for example, or a temporary file system error made a path inaccessible.

Access Path Functions

In general, these functions only return a meaningful value if the corresponding init keyword was supplied in the call to make that created the access path. It may be possible in some cases to derive a meaningful value, but this is not always the case.

access-path-abstract-handle Generic function
Signature:

access-path-abstract-handle (object) => (value)

Parameters:
Values:
access-path-abstract-handle-setter Generic function
Signature:

access-path-abstract-handle-setter (value object) => (value)

Parameters:
Values:

Instances of <access-path> have a slot for an abstract handle. The access path library does not define its type, nor the mode of its use. It does, however, provide a means of accessing it and setting it. Clients of the access-path library may use this slot for their own purposes. (Note that <access-path> is a sealed class).

access-path-application-object Generic function
Signature:

access-path-application-object (object) => (value)

Parameters:
Values:
access-path-application Generic function
Signature:

access-path-application (object) => (application)

Parameters:
Values:

  • application – An instance of <string>, or #f.

Returns the locator that names the application associated with the access path. This may return #f if the application: init keyword was not supplied when the access path was created.

access-path-arguments Generic function
Signature:

access-path-arguments (object) => (value)

Parameters:
Values:
access-path-process Generic function
Signature:

access-path-process (object) => (#rest results)

Parameters:
Values:

Returns the process associated with the access path, as a <remote-process> object. This may return #f if one of the application: or process: init keywords was not supplied when the access path was created.

access-path-core-file Generic function
Signature:

access-path-core-file (object) => (#rest results)

Parameters:
Values:

  • core-file – An instance of <string>, or #f.

$max-spy-function-arguments Constant
spy-function-argument-remote-vector Generic function
Signature:

spy-function-argument-remote-vector (object) => (value)

Parameters:
Values:
spy-function-argument-remote-vector-setter Generic function
Signature:

spy-function-argument-remote-vector-setter (value object) => (value)

Parameters:
Values:
$max-stepping-locations Constant
stepping-locations-remote-vector Generic function
Signature:

stepping-locations-remote-vector (object) => (value)

Parameters:
Values:
stepping-locations-remote-vector-setter Generic function
Signature:

stepping-locations-remote-vector-setter (value object) => (value)

Parameters:
Values:
$access-ok Constant

Modeling Remote Objects

Debugger Connections

<debugger-connection> Abstract Instantiable Class
Superclasses:

<object>

The class that models a debugger connection to a (potentially remote) machine. This connection might be implicit (for the local machine), or it might be a network connection to a server process (for a remote machine).

*open-debugger-connections* Variable
connection-hostname Generic function
Signature:

connection-hostname (object) => (value)

Parameters:
Values:
connection-hostname-setter Generic function
Signature:

connection-hostname-setter (value object) => (value)

Parameters:
Values:
connection-open? Generic function
Signature:

connection-open? (object) => (value)

Parameters:

  • object – An instance of <remote-debugger-connection>.

Values:
connection-open?-setter Generic function
Signature:

connection-open?-setter (value object) => (value)

Parameters:

  • value – An instance of <boolean>.

  • object – An instance of <remote-debugger-connection>.

Values:
connection-password Generic function
Signature:

connection-password (object) => (value)

Parameters:

  • object – An instance of <remote-debugger-connection>.

Values:
describe-debugger-connection Generic function
Signature:

describe-debugger-connection (connection) => (#rest results)

Parameters:

  • connection – An instance of <object>.

Values:

  • #rest results – An instance of <object>.

describe-debugger-connection(<local-debugger-connection>) Method
describe-debugger-connection(<remote-debugger-connection>) Method
do-open-debugger-connections Function
Signature:

do-open-debugger-connections (f) => ()

Parameters:

  • f – An instance of <function>.

<access-connection> Open Abstract Class
Superclasses:

<object>

Init-Keywords:

  • debugger-connection (required) – An instance of <debugger-connection>.

  • description – An instance of <string>.

  • process – An instance of <nub>.

make-access-connection Open Generic function
Signature:

make-access-connection (ap conn) => (conn)

Parameters:
Values:
do-open-access-connections Function
Signature:

do-open-access-connections (f server) => ()

Parameters:
connection-open-tethers Generic function
Signature:

connection-open-tethers (object) => (value)

Parameters:
Values:
connection-process Generic function
Signature:

connection-process (object) => (value)

Parameters:
Values:

  • value – An instance of <nub>.

connection-process-list Generic function
Signature:

connection-process-list (object) => (value)

Parameters:
Values:
connection-process-list-setter Generic function
Signature:

connection-process-list-setter (value object) => (value)

Parameters:
Values:
connection-process-setter Generic function
Signature:

connection-process-setter (value object) => (value)

Parameters:
Values:

  • value – An instance of <nub>.

connection-network-address Generic function
Signature:

connection-network-address (object) => (value)

Parameters:

  • object – An instance of <remote-debugger-connection>.

Values:
host-machine Function
Signature:

host-machine () => (connection)

Values:

Returns an instance of <debugger-connection> that represents the machine on which host-machine was called.

$local-hostname Constant
do-processes Open Generic function
Signature:

do-processes (function dc) => ()

Parameters:

  • function – An instance of <function>.

  • dc –

    An instance of <debugger-connection>.

    Applies function to each of the <remote-process> objects which are potentially debuggable on the machine corresponding to dc. This will involve a communication with the server process running on that machine. The server process is expected to filter out those processes which are not amenable to debugging.

get-process-page-fault-count Generic function
Signature:

get-process-page-fault-count (ap) => (count)

Parameters:
Values:

Remote Processes

<remote-process> Abstract Class
Superclasses:

<object>

Init-Keywords:

  • nub-descriptor – An instance of <nubprocess>.

  • remote-process-actual-identifier – An instance of <abstract-integer>.

  • remote-process-name – An instance of <string>.

  • remote-process-system-identifier – An instance of <string>.

remote-process-name Generic function
Signature:

remote-process-name (object) => (value)

Parameters:
Values:
remote-process-system-identifier Generic function
Signature:

remote-process-system-identifier (object) => (value)

Parameters:
Values:
remote-process-actual-identifier Generic function
Signature:

remote-process-actual-identifier (object) => (value)

Parameters:
Values:

  • value – An instance of <abstract-integer>.

Remote Threads

<remote-thread> Abstract Class
Superclasses:

<object>

Init-Keywords:

  • access-path (required) – An instance of <access-path>.

  • name – An instance of <string>.

  • nub-descriptor (required) – An instance of <nubthread>.

  • os-priority – An instance of <integer>.

  • rnub-descriptor (required) – An instance of <abstract-integer>.

  • state – An instance of <string>.

The class that models a thread in an application process. Instances of <remote-thread> are guaranteed to be unique. It is not possible for more than one instance of <remote-thread> to refer to the same application thread. This remains true for the entire lifetime of the thread.

do-threads Generic function
Signature:

do-threads (function ap) => ()

Parameters:

Applies function to each of the <remote-thread> objects corresponding to the threads of the application’s process.

register-thread Generic function
Signature:

register-thread (object) => (value)

Parameters:
Values:
thread-name Generic function
Signature:

thread-name (object) => (value)

Parameters:
Values:

Returns the name of the thread as a string.

thread-access-path Generic function
Signature:

thread-access-path (object) => (value)

Parameters:
Values:
get-thread-cpu-time Generic function
Signature:

get-thread-cpu-time (ap thread) => (timer)

Parameters:
Values:
get-process-wall-clock-time Generic function
Signature:

get-process-wall-clock-time (ap) => (timer)

Parameters:
Values:
number-of-active-threads Generic function
Signature:

number-of-active-threads (ap) => (count)

Parameters:
Values:
thread-state Generic function
Signature:

thread-state (object) => (value)

Parameters:
Values:

Returns the state of the thread as a string.

thread-priority Generic function
Signature:

thread-priority (t #key normalize?) => (p)

Parameters:
Values:

Returns the priority of the thread as a real number. If normalize is true (the default) then the priority will be normalized to the scale used by the Dylan threads library. Otherwise the priority corresponds to a scale which is dependent on the remote machine.

thread-suspended? Generic function
Signature:

thread-suspended? (object) => (value)

Parameters:
Values:

Returns #t if the given thread has been suspended, else returns #f. Note that “suspended” means “suspended by the debugger”, via a call to suspend-thread. So, even with the application in the stopped state, this function might return #f. A good interpretation of thread-suspended? is: will this thread not resume execution upon a call to continue, or will it continue unhandled?

thread-permanently-suspended? Generic function
Signature:

thread-permanently-suspended? (ap thread) => (suspended?)

Parameters:
Values:
thread-permanently-suspended?-setter Generic function
Signature:

thread-permanently-suspended?-setter (suspend? ap thread) => (suspend?)

Parameters:
Values:
stack-size Generic function
Signature:

stack-size (object) => (value)

Parameters:
Values:
stack-size-setter Generic function
Signature:

stack-size-setter (value object) => (value)

Parameters:
Values:
stack-size-valid? Generic function
Signature:

stack-size-valid? (object) => (value)

Parameters:
Values:
stack-size-valid?-setter Generic function
Signature:

stack-size-valid?-setter (value object) => (value)

Parameters:
Values:
stack-trace-valid? Generic function
Signature:

stack-trace-valid? (object) => (value)

Parameters:
Values:
stack-trace-valid?-setter Generic function
Signature:

stack-trace-valid?-setter (value object) => (value)

Parameters:
Values:
thread-stack Generic function
Signature:

thread-stack (object) => (value)

Parameters:
Values:
thread-stack-setter Generic function
Signature:

thread-stack-setter (value object) => (value)

Parameters:
Values:

Remote Libraries

In this section, we use the term “library” to mean a traditional shared library, such as a DLL under Windows.

<remote-library> Abstract Class
Superclasses:

<object>

Init-Keywords:

  • base-address – An instance of <remote-value>.

  • core-name – An instance of <string>.

  • locator – An instance of <string>.

  • nub-descriptor – An instance of <nublibrary>.

  • rnub-descriptor – An instance of <abstract-integer>.

  • version-major – An instance of <integer>.

  • version-minor – An instance of <integer>.

The class that models a library in the remote application. Like <remote-thread>, instances of <remote-library> are unique, and always refer to the same loaded library.

do-libraries Generic function
Signature:

do-libraries (function application) => ()

Parameters:

Applies function to each of the <remote-library> objects corresponding to the libraries of the application.

library-version Generic function
Signature:

library-version (lib) => (major-version-number minor-version-number)

Parameters:

  • lib – An instance of <simple-remote-library>.

Values:

  • major-version-number – An instance of <integer>.

  • minor-version-number – An instance of <integer>.

Returns the version of the shared library as a string.

library-base-address Generic function
Signature:

library-base-address (object) => (value)

Parameters:
Values:
library-image-name Generic function
Signature:

library-image-name (object) => (value)

Parameters:
Values:

Returns a <string> that indicates where the library was loaded from.

library-core-name Generic function
Signature:

library-core-name (object) => (value)

Parameters:
Values:
library-object-files Generic function
Signature:

library-object-files (object) => (value)

Parameters:
Values:
extend-remote-library Generic function
Signature:

extend-remote-library (path library file) => ()

Parameters:
find-or-make-library Generic function
Signature:

find-or-make-library (ap lib) => (lib)

Parameters:

  • ap – An instance of <access-path>.

  • lib – An instance of <nublibrary>.

Values:
self-contained-component? Generic function
Signature:

self-contained-component? (object) => (value)

Parameters:
Values:
self-contained-component?-setter Generic function
Signature:

self-contained-component?-setter (value object) => (value)

Parameters:
Values:

Remote Object Files

<remote-object-file> Class
Superclasses:

<object>

Init-Keywords:
remote-object-file-core-name Generic function
Signature:

remote-object-file-core-name (object) => (value)

Parameters:
Values:
remote-object-file-source-extension Generic function
Signature:

remote-object-file-source-extension (object) => (value)

Parameters:
Values:
remote-object-file-object-extension Generic function
Signature:

remote-object-file-object-extension (object) => (value)

Parameters:
Values:
remote-object-file-path Generic function
Signature:

remote-object-file-path (object) => (value)

Parameters:
Values:
remote-object-file-library Generic function
Signature:

remote-object-file-library (object) => (value)

Parameters:
Values:
remote-object-file-language Generic function
Signature:

remote-object-file-language (object) => (value)

Parameters:
Values:
remote-object-file-client-data Generic function
Signature:

remote-object-file-client-data (object) => (value)

Parameters:
Values:

Reading and Writing Memory

The following functions can be used to do “raw” reads and writes on memory and registers in the remote application. Note that, since this is not intended to be a kernel debugger, the memory functions always operate in terms of the virtual memory of the application.

<remote-value> Type

The type that is used to contain remote values and addresses. Instances of this type hold values that are the size of a machine object or pointer. This type serves to hide any precision problems that might be encountered when modeling a 32-bit machine if the local Dylan implementation supports only 30-bit integers, or for allowing modeling of 64-bit applications on 32-bit machines. The type is guaranteed to be disjoint from any of the classes defined in this document. However, it is permitted for instances of <remote-value> to be instances of <real>, as defined in the Dylan library.

=(<remote-value>, <remote-value>) Method

Tests two remote-values for equality. Two remote values are equal if they represent the same bit pattern (of whatever size that may be).

as-integer Generic function
Signature:

as-integer (x) => (i)

Parameters:
Values:

  • i – An instance of <abstract-integer>.

Converts the remote value to an <abstract-integer> (NB the concrete representation may be a big integer as defined in the big-integers library.) This function might be a NOP. Note: the as function cannot be used for the same purpose, because of the possibility of <remote-value> being derived from a class defined in the Dylan library.

as-integer(<remote-value>) Method
as-integer(<descriptor-pointer>) Method
as-integer-losing-precision Generic function
Signature:

as-integer-losing-precision (x) => (i)

Parameters:
Values:
as-remote-value Generic function
Signature:

as-remote-value (x) => (ptr)

Parameters:

  • x – An instance of <abstract-integer>.

Values:

Converts the given abstract integer to a <remote-value>.

as-remote-pointer Generic function
Signature:

as-remote-pointer (x) => (ptr)

Parameters:

  • x – An instance of <abstract-integer>.

Values:

  • ptr – An instance of <descriptor-pointer>.

indexed-remote-value Generic function
Signature:

indexed-remote-value (x i) => (ptr)

Parameters:
Values:

Given a <remote-value> base and an integer offset, returns the result of adding the offset (measured in remote-value-sized units) to the base.

byte-indexed-remote-value Generic function
Signature:

byte-indexed-remote-value (x i) => (ptr)

Parameters:
Values:

Identical to indexed-remote-value, except that the offset is added in bytes rather than in remote-value-sized units.

remote-value-byte-size Generic function
Signature:

remote-value-byte-size (ap) => (value-size)

Parameters:
Values:
tagged-remote-value-as-integer Generic function
Signature:

tagged-remote-value-as-integer (x) => (i)

Parameters:
Values:
tagged-remote-value-as-character Generic function
Signature:

tagged-remote-value-as-character (x) => (c)

Parameters:
Values:
integer-as-tagged-remote-value Generic function
Signature:

integer-as-tagged-remote-value (i) => (x)

Parameters:
Values:
character-as-tagged-remote-value Generic function
Signature:

character-as-tagged-remote-value (c) => (x)

Parameters:
Values:
remote-value-< Generic function
Signature:

remote-value-< (x y) => (answer)

Parameters:
Values:
remote-value-<= Generic function
Signature:

remote-value-<= (x y) => (answer)

Parameters:
Values:
remote-value-= Generic function
Signature:

remote-value-= (x y) => (answer)

Parameters:
Values:
remote-value-as-string Generic function
Signature:

remote-value-as-string (ap val radix) => (str)

Parameters:
Values:
string-as-remote-value Generic function
Signature:

string-as-remote-value (ap str radix) => (val)

Parameters:
Values:
remote-value-low-order-bits Generic function
Signature:

remote-value-low-order-bits (x bit-count) => (value)

Parameters:
Values:
<remote-register> Abstract Class
Superclasses:

<object>

Init-Keywords:

  • category (required) – An instance of <symbol>.

  • code (required) – An instance of <integer>.

  • descriptor (required) – An instance of <integer>.

  • name (required) – An instance of <byte-string>.

The class that is used to “name” a remote register.

<unassigned-remote-register> Class
Superclasses:

<remote-register>

The class that is used to designate a register that is not considered to be within the context of a thread in the application. A subclass of <remote-register>. Read/write operations cannot be performed on instances of <unassigned-remote-register>.

<active-remote-register> Class
Superclasses:

<remote-register>

Init-Keywords:

The class that is used to designate a register within the context of a thread inside the running application. Note that read/write operations can only be performed on instances of <active-remote-register>.

register-name Generic function
Signature:

register-name (r) => (sym)

Parameters:
Values:

Returns the name of the remote register as a symbol.

do-registers Generic function
Signature:

do-registers (function ap #key type) => ()

Parameters:

Applies function to each of the registers in the given register set. function is called with one argument, an <unassigned-remote-register> object. type can be one of #f, #"general", #"float", or #"special". If it is #f, function is called on all the registers. If it is #"general", function is called only on the general-purpose registers. If it is #"float", function is called only on the floating-point registers. If it is #"special", function is called only on the special-purpose registers.

find-register Generic function
Signature:

find-register (ap nub-register) => (descriptor)

Parameters:
Values:
active-register Generic function
Signature:

active-register (ap thread register) => (reg)

Parameters:
Values:

Returns an <active-remote-register> whose attributes are identical to the given <unassigned-remote-register>. The returned instance can then be used to refer to that register within the specified remote-thread of the running application.

<remote-location> Type

The type used to represent a remote address. It is the union of <remote-value> and <active-remote-register>.

Note that some operations can only be sensibly performed on memory addresses and not registers, notable examples being the setting of breakpoints and querying page protection. In these cases the address is actually required to be of type <remote-value> rather than the more general <remote-location>.

<remote-type> Abstract Class
Superclasses:

<object>

The type used to represent a remote type.

Functions for Querying Page Protection

The debugger manager is required to check the page protection on an address before attempting to obtain a <remote-value> from that location (or write one to it). This is because the garbage collector may have placed a read barrier or write barrier, meaning that the objects at that address are invalid pending further GC activity. If the page is protected, then the read/write must be done within the context of the application, via the spy, and not via the debugger nub. These functions may not be called if the application is in the running state.

page-read-permission? Generic function
Signature:

page-read-permission? (ap address) => (ans)

Parameters:
Values:

Returns #t if read permissions are enabled at the given address in the application, else returns #f.

page-write-permission? Generic function
Signature:

page-write-permission? (ap address) => (ans)

Parameters:
Values:

Returns #t if write permissions are enabled at the given address in the application, else returns #f.

page-execute-permission? Generic function
Signature:

page-execute-permission? (ap address) => (ans)

Parameters:
Values:

Returns #t if execute permissions are enabled at the given address in the application, else returns #f.

remote-virtual-page-size Generic function
Signature:

remote-virtual-page-size (ap) => (page-size)

Parameters:
Values:

Returns the the size of a memory page on the remote machine, in <remote-value> units, as an integer.

remote-address-page-number Generic function
Signature:

remote-address-page-number (ap addr) => (id)

Parameters:
Values:

Turns an address into an integer-enumerated memory page ID.

page-relative-address Generic function
Signature:

page-relative-address (ap addr) => (id offset)

Parameters:
Values:

Turns an address into an integer-enumerated memory page ID, and an offset into the page.

calculate-stack-address Generic function
Signature:

calculate-stack-address (ap thread offset) => (addr)

Parameters:
Values:

Returns the address of a position on the stack of the application’s thread. Offset 0 is the top of the stack. Offset 1 is the position 1 remote-value below the top of the stack, and so on.

Functions for Reading and Writing

Note that, for all the functions described in this section, it is an error to call them if the application is in the running state. Furthermore, any of these functions might signal a <remote-access-violation-error> if a read or write is to an illegal address or causes an access violation. Note also that <remote-value> instances read from an application are likely to become “stale” once the application has been made runnable or has been single-stepped. For example, the garbage collector in the application might discard an object. Longer-lived objects must be registered via the Spy’s object registration facility.

<remote-access-violation-error> Class
Superclasses:

<error>

The condition signaled if some sort of an access error occurs while reading or writing remote memory.

read-value Generic function
Signature:

read-value (ap address #key stack-frame) => (val)

Parameters:
Values:

Reads a memory word from the location given by address, and returns its contents as a <remote-value>.

read-value(<access-path>, <active-remote-register>) Method
read-value(<access-path>, <remote-value>) Method
write-value Generic function
Signature:

write-value (ap address value) => (val)

Parameters:
Values:

Writes remote-value into the memory location given by address, and returns the value.

write-value(<access-path>, <active-remote-register>, <remote-value>) Method
write-value(<access-path>, <remote-value>, <remote-value>) Method
read-8b Generic function
Signature:

read-8b (ap address) => (val)

Parameters:
Values:

Reads an 8-bit byte from the location given by address, and returns its contents as an <integer>.

write-8b Generic function
Signature:

write-8b (ap address value) => (val)

Parameters:
Values:

Writes an 8-bit byte, as an integer, into the memory location at address, and returns the value.

read-16b Generic function
Signature:

read-16b (ap address) => (val)

Parameters:
Values:

Reads a 16-bit word from the location given by remote-location, and returns its contents as an <integer>.

write-16b Generic function
Signature:

write-16b (ap address value) => (val)

Parameters:
Values:

Writes a 16-bit word, as an integer, into the memory location at address, and returns the value.

read-32b Generic function
Signature:

read-32b (ap address) => (val)

Parameters:
Values:

Reads a 32-bit w ord from the location given by address, and returns its contents as an <integer>.

write-32b Generic function
Signature:

write-32b (ap address value) => (val)

Parameters:
Values:

Writes a 32-bit word, as an integer, into the memory location at address, and returns the value.

read-64b Generic function
Signature:

read-64b (ap address) => (val)

Parameters:
Values:

Reads a 64-bit word from the location given by address, and returns its contents as an <integer>.

write-64b Generic function
Signature:

write-64b (ap address value) => (val)

Parameters:
Values:

Writes a 64-bit word, as an integer, into the memory location at address, and returns the value.

read-single-float Generic function
Signature:

read-single-float (ap address) => (val)

Parameters:
Values:

Reads a single-precision floating-point number from the location given by remote-location, and returns its contents as a <single-float>.

read-single-float(<access-path>, <active-remote-register>) Method
read-single-float(<access-path>, <remote-value>) Method
write-single-float Generic function
Signature:

write-single-float (ap address value) => (val)

Parameters:
Values:

Writes a single-precision floating-point number, into the memory location at address, and returns the value.

write-single-float(<access-path>, <active-remote-register>, <single-float>) Method
write-single-float(<access-path>, <remote-value>, <single-float>) Method
read-double-float Generic function
Signature:

read-double-float (ap address) => (val)

Parameters:
Values:

Reads a double-precision floating-point number from the location given by remote-location, and returns its contents as a <double-float>.

read-double-float(<access-path>, <active-remote-register>) Method
read-double-float(<access-path>, <remote-value>) Method
write-double-float Generic function
Signature:

write-double-float (ap address value) => (val)

Parameters:
Values:
write-double-float(<access-path>, <active-remote-register>, <double-float>) Method
write-double-float(<access-path>, <remote-value>, <double-float>) Method

Writes a double-precision floating-point number, into the memory location at address, and returns the value.

read-byte-string Generic function
Signature:

read-byte-string (ap address length) => (val)

Parameters:
Values:

Reads a byte string starting from the location given by address, and returns its contents as a <byte-string>. length is the number of bytes to read.

write-byte-string Generic function
Signature:

write-byte-string (ap address value #key ending-index) => (val)

Parameters:
Values:

Writes a byte string into the memory starting at address, and returns the value.

Controlling the Application

The control functions described in this section are asynchronous and may return immediately, even though the remote application might not yet have entered the desired state. When the application’s state changes, an appropriate stop reason is sent. See wait-for-stop-reason.

restart Generic function
Signature:

restart (ap) => ()

Parameters:

Starts (or restarts) the application from the beginning. After making a new access path with the application: init keyword, restart is used to start up the application. restart may be called with the application in any state, and will put the application into the running state. Note that not all access paths will be able to restart an application that is in the post-mortem state.

stop Generic function
Signature:

stop (ap) => ()

Parameters:

Stops the application. This stops all of the threads in the application’s process. After starting or continuing an application or making a new access path with the process: init keyword, stop is used to stop the application. stop may be called only when the application is in the running state, and will put the application into the stopped state.

continue Generic function
Signature:

continue (ap #key resume) => ()

Parameters:

Continues the application from where it was stopped. This continues all of the threads in the application’s process.

If the application was stopped due to a first-chance exception, the exception will be ignored (ie. considered “handled”) when it resumes, thus bypassing any structured handling system that might exist. For a second-chance exception, the application simply continues. continue may be called only when the application is in the stopped state, and will put the application into the running state.

continue-unhandled Generic function
Signature:

continue-unhandled (ap #key resume) => ()

Parameters:

Continues the application from where it was stopped. This continues all of the threads in the application’s process.

If the application was stopped due to a first-chance exception, it will be given the chance to handle that exception itself (which will result in the exception occurring a second time if the application provides no handler for it). If the application was stopped due to a second-chance exception, it will abort. continue-unhandled may be called only when the application is in the stopped state, and will put the application into the running state.

suspend-thread Generic function
Signature:

suspend-thread (ap thread) => ()

Parameters:

Suspends the given thread in the application. This function may only be called when the application is in the stopped state — the thread in question will not resume execution when the application continues.

This function has no effect if the thread has already been suspended.

resume-thread Generic function
Signature:

resume-thread (ap thread) => ()

Parameters:

Resumes the given thread in the application. This function may only be called when the application is in the stopped state, and will only have an effect if the thread was previously suspended by a call to suspend-thread. The thread will resume its execution when the application continues.

dylan-resume-thread Generic function
Signature:

dylan-resume-thread (ap thread) => ()

Parameters:
step Generic function
Signature:

step (ap n) => ()

Parameters:

Single-steps the application over n instructions. This steps only the current thread. step may be called only when the application is in the stopped state, and will put the application into the running state. The application will run only for as long as it takes to step, and then a <single-step-stop-reason> event will be queued.

step-over Generic function
Signature:

step-over (ap n) => ()

Parameters:

Single-steps the application over n instructions, stepping over function calls. This steps only the current thread. step-over may be called only when the application is in the stopped state, and will put the application into the running state. The application will run only for as long as it takes to step, and then a <single-step-stop-reason> event will be queued.

step-out Generic function
Signature:

step-out (ap) => ()

Parameters:

Steps the application out of its current function frame, stopping at the next instruction in the calling frame.

step-out may be called only when the application is in the stopped state, and will put the application into the running state. The application will run only for as long as it takes to step, and then a <single-step-stop-reason> event will be queued.

application-state-running? Generic function
Signature:

application-state-running? (ap) => (running?)

Parameters:
Values:

Returns #t if the remote-application is in the running state.

application-state-stopped? Generic function
Signature:

application-state-stopped? (ap) => (stopped?)

Parameters:
Values:

Returns #t if the remote-application is in the stopped state, because it has been halted.

application-state-unstarted? Generic function
Signature:

application-state-unstarted? (ap) => (unstarted?)

Parameters:
Values:

Returns #t if the remote-application is in the unstarted state, because it has never been started with a call to restart or continue.

application-state-post-mortem? Generic function
Signature:

application-state-post-mortem? (ap) => (post-mortem?)

Parameters:
Values:

Returns #t if the remote-application is in the post-mortem state, because the access path is attached to a post-mortem dump.

kill-application Generic function
Signature:

kill-application (ap #key do-cleanups?) => (success?)

Parameters:
Values:

Kill the application’s process.

If do-cleanups? is true, all of the cleanups for the application are run before it is killed. The default is #f.

kill-application may be called only when the application is in the stopped state. If do-cleanups? is false, the application will be put into the dead state. If do-cleanups? is true, the application will be put into the running state.

close-application Generic function
Signature:

close-application (ap) => ()

Parameters:
register-exit-process-function Generic function
Signature:

register-exit-process-function (ap exit-process) => ()

Parameters:

Remote Function Calling

remote-call Generic function
Signature:

remote-call (access-path thread function #rest arguments) => (ret-addr cookie)

Parameters:
Values:

Prepares the given thread to perform a specific function call once the application is resumed. function is a <remote-value>, arguments is zero or more <remote-value> objects. The call is made using the C calling-conventions on the remote machine. (It is expected that a higher level will deal with language-specific calling conventions and language-specific return results).

return-address is a <remote-value> representing the point at which control in the application will resume when the called function returns. A breakpoint should be placed on this address before allowing the remote call to proceed in order to obtain notification of the remote function’s return and restore the thread’s dynamic context if necessary.

context is a cookie that will be required by remote-restore-context in order to ensure that the dynamic state of the thread will be restored back to what it was before the remote call. It is an error to call remote-call if the application is not in the stopped state

This function does not put the application into the running state, but the specified thread will make the remote call as soon as the application is resumed by continue or continue-handled.

remote-call-result Generic function
Signature:

remote-call-result (ap thr) => (result)

Parameters:
Values:

Obtains the result of a remote call (assuming the C calling convention). result is a <remote-value> that contains the return value of the function. In order to obtain a sensible result at the correct time, this function must be called when the breakpoint (that should have been set up after a call to remote-call) is actually encountered by the application. But note also that this is only true when the breakpoint is encountered by the thread that made the remote call, and when the thread is in the same stack frame as it was when the remote call was made. Calling remote-call-result when these conditions do not hold will have unpredictable results.

remote-restore-context Generic function
Signature:

remote-restore-context (ap thr ctx) => ()

Parameters:

Restores the dynamic context (register set) of a remote-thread that was previously instructed to do a remote call. The context argument is that received as a returned result from remote-call. Like remote-call-result, this should be called when the breakpoint (set on the remote function’s return address) is encountered, and in the relevant context as described above. Basically, remote-call-result and remote-restore-context should be called at the same time, in either order. The justification for having two separate functions, remote-call-result and remote-restore-context, is that the function result may sometimes be known not to be of interest. It also allows the possibility of not restoring the context if desired. Having called one or both of remote-call-result and remote-restore-context, it will be necessary to remove the breakpoint that was set in order to trap the return of the remote function.

remote-call-spy Generic function
Signature:

remote-call-spy (ap thr function #rest arguments) => (result aborted?)

Parameters:
Values:

A restricted remote calling protocol specifically for calling functions in the spy. The arguments are the same as those for remote-call, and once again the C calling convention is assumed. The function argument should be a <remote-value>, and must be the entry point of a known spy function in the remote application.

This function actually makes the spy call and returns its result (as a <remote-value>). Although this obviously causes the application to run, it does not “officially” enter the running state. Clients of the access path can assume that once this function has returned, the application is still in the stopped state, and that all threads and their stacks are in precisely the same state as before the call. While the call is made, all threads are suspended except for the one making the call.

Clearly, the strictness of this protocol places restrictions on what spy functions are allowed to do. They may not unwind the stack or take non-local exits, and they must not be capable of generating stop-reasons!

Breakpoints and Watchpoints

The following functions are used to set and clear breakpoints and watchpoints in the remote application. Hitting a breakpoint or a watchpoint in the application causes the corresponding stop reason to be signaled. Breakpoints and watchpoints are visible to all the threads in the remote application.

Note

Watchpoints are not currently implemented or used.

enable-breakpoint Generic function
Signature:

enable-breakpoint (ap address) => (success)

Parameters:
Values:

Sets a breakpoint at the given address (which must be a :type`<remote-value>`) in the remote application. Returns true if the operation succeeds, or #f if it fails.

disable-breakpoint Generic function
Signature:

disable-breakpoint (ap address) => (success)

Parameters:
Values:

Clears a breakpoint at the given address (which must be a <remote-value>) in the remote application. Returns true if the operation succeeds, or #f if it fails.

query-breakpoint? Generic function
Signature:

query-breakpoint? (ap address) => (success)

Parameters:
Values:

Returns true if a breakpoint has been set at the given address (which must be a <remote-value>) in the application, otherwise returns #f.

enable-read-watchpoint Generic function
Signature:

enable-read-watchpoint (ap address size) => (success)

Parameters:
Values:

Sets a “read” watchpoint at the given address (which must be a <remote-value>) in the application. size is an integer dictating the number of words that the watchpoint will cover. Returns true if the watchpoint is set successfully, and #f otherwise.

disable-read-watchpoint Generic function
Signature:

disable-read-watchpoint (ap address) => (success)

Parameters:
Values:

Clears a previously-set “read” watchpoint at the given address (which must be a <remote-value>) in the application. Returns true if the operation is successful, and #f otherwise.

query-read-watchpoint? Generic function
Signature:

query-read-watchpoint? (ap address) => (success)

Parameters:
Values:

Returns true if a “read” watchpoint has been set at the given address (which must be a <remote-value>) in the application, otherwise returns #f.

enable-write-watchpoint Generic function
Signature:

enable-write-watchpoint (ap address size) => (success)

Parameters:
Values:

Sets a “write” watchpoint at the given address (which must be a <remote-value>) in the application. size is an integer dictating the number of words that the watchpoint will cover. Returns true if the watchpoint is set successfully, and #f otherwise.

disable-write-watchpoint Generic function
Signature:

disable-write-watchpoint (ap address) => (success)

Parameters:
Values:

Clears a previously-set “write” watchpoint at the given address (which must be a <remote-value>) in the application. Returns true if the operation is successful, and #f otherwise.

query-write-watchpoint? Generic function
Signature:

query-write-watchpoint? (ap address) => (success)

Parameters:
Values:

Returns true if a “write” watchpoint has been set at the given address (which must be a <remote-value>) in the application, otherwise returns #f.

recover-breakpoint Generic function
Signature:

recover-breakpoint (ap thread) => ()

Parameters:

Stop Reasons

The debugger gets notified of state changes in the application via stop reasons.

Receiving and Processing Stop Reasons

wait-for-stop-reason Generic function
Signature:

wait-for-stop-reason (access-path #key timeout profile-interval) => (maybe-sr)

Parameters:
Values:

Waits for some kind of stop reason to occur on access-path. When the function returns, it returns a <stop-reason> object. The stop reason is recorded on a queue asynchronously to the caller of this function, so stop reasons are never lost.

If timeout is supplied, it is a real number specifying the number of seconds to wait for a stop reason. If the timer expires before a stop reason comes in, wait-for-stop-reason will return #f.

inform-profiling-started Generic function
Signature:

inform-profiling-started (ap) => ()

Parameters:
inform-profiling-stopped Generic function
Signature:

inform-profiling-stopped (ap) => ()

Parameters:

Stepping at Source Code Level

$step-operation-step-into Constant
$step-operation-step-out Constant
$step-operation-step-over Constant
apply-thread-stepping-control Generic function
Signature:

apply-thread-stepping-control (access-path thread locations operation #key stack-frame) => ()

Parameters:
remove-all-stepping-control-for-thread Generic function
Signature:

remove-all-stepping-control-for-thread (path thread) => ()

Parameters:

The Class Hierarchy of Stop Reasons

<stop-reason> Abstract Class

The base class for all stop reasons.

Superclasses:

<object>

<internal-stop-reason> Abstract Class

The base class of all stop-reasons that are signaled by the application.

Superclasses:

<stop-reason>

Init-Keywords:
<basic-stop-reason> Abstract Class
Superclasses:

<internal-stop-reason>

This is the root class of all stop-reasons that are signaled by the application and defined within the confines of the access-path layer. These stop-reasons are, by definition of this layer, language-independent.

<language-level-stop-reason> Open Abstract Class
Superclasses:

<internal-stop-reason>

This is the root class of all stop-reasons that are signaled by the application but not defined within the access-path library. It is intended that access-path clients should create a subtree of stop reasons under this class, and synthesize them by interpreting the context of <basic-stop-reason> objects as they are signaled.

<unhandled-stop-reason> Open Abstract Class
Superclasses:

<stop-reason>

The application can now timeout on an incoming debug event (e.g. page faults), for which the debugger needs to pass back an unhandled exception; this stop-reason models those special circumstances.

<external-stop-reason> Open Abstract Class
Superclasses:

<stop-reason>

The base class of all stop-reasons that were caused by behaviour outside of the application (for example, the debugger stopped the application explicitly). The access-path could not and does not define these stop-reasons, hence the class is left open.

<profiler-stop-reason> Class
Superclasses:

<external-stop-reason>

<profiler-unhandled-stop-reason> Class
Superclasses:

<profiler-stop-reason>, <unhandled-stop-reason>

<timeout-stop-reason> Class
Superclasses:

<external-stop-reason>

stop-reason-process Generic function
Signature:

stop-reason-process (object) => (value)

Parameters:
Values:

Specifies the remote process in which the internal stop-reason occurred.

stop-reason-thread Generic function
Signature:

stop-reason-thread (object) => (value)

Parameters:
Values:

Specifies the remote thread in which the internal stop-reason occurred.

<process-stop-reason> Abstract Class
Superclasses:

<basic-stop-reason>

The superclass of all stop-reasons that have something to do with the running process. At the moment, only two such stop-reasons (creation and exiting of the running process) are defined.

<create-process-stop-reason> Class
Superclasses:

<process-stop-reason>

Init-Keywords:

The class that represents the stop reason signaled when a process is created.

stop-reason-executable-component Generic function
Signature:

stop-reason-executable-component (object) => (value)

Parameters:
Values:
<exit-process-stop-reason> Class
Superclasses:

<process-stop-reason>

Init-Keywords:

  • exit-code (required) – An instance of <integer>.

The class that represents the stop reason signaled when a process is destroyed.

stop-reason-process-exit-code Generic function
Signature:

stop-reason-process-exit-code (object) => (value)

Parameters:
Values:

Specifies the exit code for the process.

<thread-stop-reason> Abstract Class
Superclasses:

<basic-stop-reason>

The superclass of all thread-related stop-reasons.

<create-thread-stop-reason> Class
Superclasses:

<thread-stop-reason>

The class that represents the stop reason signaled when a thread is created.

create-thread-event-handler Open Generic function
Signature:

create-thread-event-handler (application) => (stop-reason)

Parameters:

  • application – An instance of <object>.

Values:
create-thread-event-handler(<access-path>) Method
Signature:

interactive-thread-break-event-handler (application) => (stop-reason)

Parameters:

  • application – An instance of <object>.

Values:
interactive-thread-break-event-handler(<access-path>) Method
<exit-thread-stop-reason> Class
Superclasses:

<thread-stop-reason>

Init-Keywords:

  • exit-code (required) – An instance of <integer>.

The class that represents the stop reason signaled when a thread is created.

interactive-thread-break-event-handler Open Generic function
stop-reason-thread-exit-code Generic function
Signature:

stop-reason-thread-exit-code (object) => (value)

Parameters:
Values:

Specifies the exit code for the thread.

<library-stop-reason> Abstract Class
Superclasses:

<basic-stop-reason>

Init-Keywords:

The superclass of all library-related stop-reasons.

stop-reason-library Generic function
Signature:

stop-reason-library (object) => (value)

Parameters:
Values:

Specifies the library to which the stop-reason corresponds.

<load-library-stop-reason> Class
Superclasses:

<library-stop-reason>

The class that represents the stop reason signaled when a shared library is loaded.

<unload-library-stop-reason> Class
Superclasses:

<library-stop-reason>

The class that represents the stop reason signaled when a shared library is unloaded.

<rip-stop-reason> Class
Superclasses:

<basic-stop-reason>

Init-Keywords:

  • exit-code (required) – An instance of <integer>.

The class that represents the stop reason signaled when the remote application dies completely.

stop-reason-exit-code Generic function
Signature:

stop-reason-exit-code (object) => (value)

Parameters:
Values:

Specifies the exit code for the application.

<debug-point-stop-reason> Abstract Class
Superclasses:

<basic-stop-reason>

Init-Keywords:

The superclass of all debug point stop reasons.

stop-reason-debug-point-address Generic function
Signature:

stop-reason-debug-point-address (object) => (value)

Parameters:
Values:

Specifies the debug-point address corresponding to the stop-reason, e.g. the address at which a breakpoint was hit, as a <remote-value>.

<breakpoint-stop-reason> Class
Superclasses:

<debug-point-stop-reason>

The class that represents the stop reason signaled when a breakpoint is hit.

<single-step-stop-reason> Class
Superclasses:

<breakpoint-stop-reason>

The class that represents the stop reason signaled when a single-step “virtual breakpoint” is hit.

<source-step-stop-reason> Class
Superclasses:

<breakpoint-stop-reason>

<source-step-into-stop-reason> Class
Superclasses:

<source-step-stop-reason>

<source-step-out-stop-reason> Class
Superclasses:

<source-step-stop-reason>

<source-step-over-stop-reason> Class
Superclasses:

<source-step-stop-reason>

<watchpoint-stop-reason> Class
Superclasses:

<debug-point-stop-reason>

The class that represents the stop reason signaled when a watchpoint is hit.

<read-watchpoint-stop-reason> Class
Superclasses:

<watchpoint-stop-reason>

The class that represents the stop reason signaled when a watchpoint is hit.

<write-watchpoint-stop-reason> Class
Superclasses:

<watchpoint-stop-reason>

The class that represents the stop reason signaled when a watchpoint is hit.

<exception-stop-reason> Abstract Class
Superclasses:

<basic-stop-reason>

Init-Keywords:

The abstract class upon which all other exception stop reasons are based.

stop-reason-exception-address Generic function
Signature:

stop-reason-exception-address (object) => (value)

Parameters:
Values:
stop-reason-exception-first-chance? Generic function
Signature:

stop-reason-exception-first-chance? (object) => (value)

Parameters:
Values:
<invoke-debugger-stop-reason> Abstract Class
Superclasses:

<exception-stop-reason>

The class that represents a programmatic entry to the debugger, such as an unhandled condition being signaled by the application.

<system-initialized-stop-reason> Class
Superclasses:

<invoke-debugger-stop-reason>

<system-invoke-debugger-stop-reason> Class
Superclasses:

<invoke-debugger-stop-reason>

<memory-exception-stop-reason> Abstract Class
Superclasses:

<exception-stop-reason>

The class that represents the stop reason signaled when a memory exception occurs.

<access-violation-stop-reason> Class
Superclasses:

<memory-exception-stop-reason>

Init-Keywords:

  • violation-address (required) – An instance of <remote-value>.

  • violation-operation (required) – An instance of <integer>.

The class that represents the stop reason signaled when a memory access violation occurs.

stop-reason-access-violation-address Generic function
Signature:

stop-reason-access-violation-address (object) => (value)

Parameters:
Values:
stop-reason-access-violation-operation Generic function
Signature:

stop-reason-access-violation-operation (object) => (value)

Parameters:
Values:
$access-violation-on-execute Constant
$access-violation-on-read Constant
$access-violation-on-write Constant
$access-violation-undecidable Constant
<array-bounds-exception-stop-reason> Class
Superclasses:

<memory-exception-stop-reason>

The class that represents the stop reason signaled when an out-of-bounds array references occurs.

<instruction-exception-stop-reason> Abstract Class
Superclasses:

<exception-stop-reason>

The class that represents the stop reason signaled when an instruction exception occurs.

<illegal-instruction-exception-stop-reason> Class
Superclasses:

<instruction-exception-stop-reason>

The class that represents the stop reason signaled when an illegal instruction exception occurs.

<privileged-instruction-exception-stop-reason> Class
Superclasses:

<instruction-exception-stop-reason>

The class that represents the stop reason signaled when a privileged instruction exception occurs.

<arithmetic-exception-stop-reason> Abstract Class
Superclasses:

<exception-stop-reason>

The class that represents the stop reason signaled when an arithmetic exception occurs.

<float-exception-stop-reason> Abstract Class
Superclasses:

<arithmetic-exception-stop-reason>

The class that represents the stop reason signaled when a floating point exception occurs.

<denormal-exception-stop-reason> Class
Superclasses:

<float-exception-stop-reason>

The class that represents the stop reason signaled when a floating point exception occurs.

<float-divide-by-zero-exception-stop-reason> Class
Superclasses:

<float-exception-stop-reason>

The class that represents the stop reason signaled when a floating divide-by-zero exception occurs.

<inexact-result-exception-stop-reason> Class
Superclasses:

<float-exception-stop-reason>

The class that represents the stop reason signaled when an inexact result exception occurs.

<invalid-float-operation-exception-stop-reason> Class
Superclasses:

<float-exception-stop-reason>

The class that represents the stop reason signaled when an invalid floating point operation exception occurs.

<float-overflow-exception-stop-reason> Class
Superclasses:

<float-exception-stop-reason>

The class that represents the stop reason signaled when a floating point overflow exception occurs.

<float-underflow-exception-stop-reason> Class
Superclasses:

<float-exception-stop-reason>

The class that represents the stop reason signaled when a floating point underflow exception occurs.

<float-stack-check-exception-stop-reason> Class
Superclasses:

<float-exception-stop-reason>

The class that represents the stop reason signaled when a floating point stack check exception occurs. Note that this exception will only occur on Intel hardware.

<integer-exception-stop-reason> Abstract Class
Superclasses:

<exception-stop-reason>

The class that represents the stop reason signaled when an integer exception occurs.

<integer-divide-by-zero-exception-stop-reason> Class
Superclasses:

<integer-exception-stop-reason>

The class that represents the stop reason signaled when an integer divide-by-zero exception occurs.

<integer-overflow-exception-stop-reason> Class
Superclasses:

<integer-exception-stop-reason>

<noncontinuable-exception-stop-reason> Class
Superclasses:

<exception-stop-reason>

The class that represents the stop reason signaled when some kind on non-continuable exception occurs.

<stack-overflow-exception-stop-reason> Class
Superclasses:

<exception-stop-reason>

<unclassified-exception-stop-reason> Class
Superclasses:

<exception-stop-reason>

<output-debug-string-stop-reason> Class
Superclasses:

<basic-stop-reason>

Init-Keywords:

  • debug-string (required) – An instance of <string>.

stop-reason-debug-string Generic function
Signature:

stop-reason-debug-string (object) => (value)

Parameters:
Values:

First-Chance Exceptions

The underlying implementation of the debugger access path (the debugger nub and the operating system APIs that it uses) may support the notion of first- and second-chance exceptions. A first-chance exception is one that is signaled to the debugger as soon as it is raised/thrown in the application. At the point of signaling a first-chance exception to the debugger, the application may or may not have its own handler in scope to deal with it. Therefore the debugger must decide, having performed its own processing of the first-chance exception, whether the application should resume by attempting to handle it, or whether it should resume by ignoring it. For example, if the exception is a breakpoint interrupt, due to a breakpoint that was set by the debugger (an instance of <breakpoint-stop-reason>), it is likely that the debugger would want the application to ignore it. The opposite may be true of, say, an <array-bounds-exception-stop-reason>. If a first-chance exception is “given back” to the application to handle, and no handler is installed to deal with it, the debugger may receive notification of the exception again, as a second-chance exception. Some systems, however, do not provide this second notification, in which case first-chance would be the default (and only) case.

first-chance-exception? Generic function
Signature:

first-chance-exception? (app thread) => (b)

Parameters:
Values:

This can be called (only) when the application is in the stopped state. If the application stopped due to the specified thread reporting a first-chance exception, this returns true, otherwise it returns #f.

receivable-first-chance-exceptions Generic function
Signature:

receivable-first-chance-exceptions (ap) => (seq)

Parameters:
Values:

Returns a sequence of exception classes (subclasses of <exception-stop-reason>). For instances of these classes, the given access-path is capable of differentiating between first- and second-chance occurrences. If this sequence is empty, then the implementation has no notion of first/second chance occurrences at all. (In this special case, first-chance-exception? will invariably return #f, and continue-unhandled will have identical behaviour to continue).

receiving-first-chance? Generic function
Signature:

receiving-first-chance? (ap etype) => (yes-or-no)

Parameters:

  • ap – An instance of <access-path>.

  • etype – An instance of <class>.

Values:

Returns true if the given <access-path> is currently reporting first-chance occurrences of the given exception class, otherwise returns #f. This function is guaranteed to return #f for exception classes that are not members of the sequence returned by receivable-first-chance-exceptions for the same <access-path>.

receiving-first-chance?-setter Generic function
Signature:

receiving-first-chance?-setter (set ap etype) => (#rest results)

Parameters:
Values:

  • #rest results – An instance of <object>.

Allows the given <access-path> to receive (or prevents it from receiving) first-chance occurrences of the given exception class. This function is allowed to silently fail if the exception class is not a member of the sequence returned by receivable-first-chance-exceptions for the same <access-path>.

exception-name Generic function
Signature:

exception-name (ap ex) => (name)

Parameters:

  • ap – An instance of <access-path>.

  • ex – An instance of <class>.

Values:

Generates a printable name for the given exception class. Valid names are only guaranteed for classes that are members of the sequence returned by receivable-first-chance-exceptions for the same <access-path>.

Stack Backtraces

Note that, for all the functions described in this section and its subsections, it is an error to call them if the application is not in the stopped state.

Stack Frames

<stack-frame> Abstract Class

A class that represents a frame in the control stack.

Superclasses:

<object>

Init-Keywords:
Signature:

link-next (object) => (value)

Parameters:
Values:
Signature:

link-next-setter (value object) => (value)

Parameters:
Values:
Signature:

link-previous (object) => (value)

Parameters:
Values:
Signature:

link-previous-setter (value object) => (value)

Parameters:
Values:
<function-frame> Class

A class that represents a function-call frame in the control stack.

Superclasses:

<stack-frame>

initialize-stack-trace Generic function
Signature:

initialize-stack-trace (path thread) => (top-frame)

Parameters:
Values:

Informs the debugger nub to perform any initializations necessary on the given thread to enable doing further stack backtrace operations. The returned value is the initial frame for the thread.

number-of-frames-on-stack Generic function
Signature:

number-of-frames-on-stack (path thread) => (count)

Parameters:
Values:
next-frame Generic function
Signature:

next-frame (path frame) => (maybe-frame)

Parameters:
Values:

Returns the “next” function frame in the backtrace as a <function-frame>, where “next” means a more recently created call frame.

previous-frame Generic function
Signature:

previous-frame (path frame) => (maybe-frame)

Parameters:
Values:

Returns the “previous” function frame in the backtrace as a <function-frame>, where “previous” means a less recently created call frame. If frame is the bottom of the stack, this returns #f.

frame-pointer Generic function
Signature:

frame-pointer (path frame) => (fp)

Parameters:
Values:

Returns the address of the frame pointer for the frame as a <remote-value>.

frame-return-address Generic function
Signature:

frame-return-address (path frame) => (ret-addr)

Parameters:
Values:

Returns the return address for the frame as a <remote-value>.

frame-instruction-address Generic function
Signature:

frame-instruction-address (path frame) => (ip)

Parameters:
Values:

Returns the address of the next instruction to be executed for the frame as a <remote-value>. In the case of the topmost frame, this is the value of the thread’s program counter. In the case of an arbitrary frame, this should be equal to the return address of the called frame.

older-stack-frame? Generic function
Signature:

older-stack-frame? (ap this-one than-this-one) => (answer)

Parameters:
Values:

Decides whether one stack frame is older than another, purely by considering their frame pointers. Note that this decision has to be made by the debugger nub, because that is the only component that “knows” the direction of stack growth.

register-interactive-code-segment Generic function
Signature:

register-interactive-code-segment (path from to) => ()

Parameters:

A function via which the stack tracer can be informed that a region of code has been dynamically created, and was not present in any executable or library when the target application was started up. This enables the debugger nub to do whatever is necessary to ensure that the stack can still be reliably traced, given that there may be no debug tables for this code.

lexicals Generic function
Signature:

lexicals (object) => (value)

Parameters:
Values:
lexicals-setter Generic function
Signature:

lexicals-setter (value object) => (value)

Parameters:
Values:
stack-frame-pointer Generic function
Signature:

stack-frame-pointer (object) => (value)

Parameters:
Values:
frame-thread Generic function
Signature:

frame-thread (object) => (value)

Parameters:
Values:
full-lexicals-read? Generic function
Signature:

full-lexicals-read? (object) => (value)

Parameters:
Values:
full-lexicals-read?-setter Generic function
Signature:

full-lexicals-read?-setter (value object) => (value)

Parameters:
Values:
partial-lexicals-read? Generic function
Signature:

partial-lexicals-read? (object) => (value)

Parameters:
Values:
partial-lexicals-read?-setter Generic function
Signature:

partial-lexicals-read?-setter (value object) => (value)

Parameters:
Values:
lexicals-count Generic function
Signature:

lexicals-count (object) => (value)

Parameters:
Values:
lexicals-count-setter Generic function
Signature:

lexicals-count-setter (value object) => (value)

Parameters:
Values:
lexicals-nub-table Generic function
Signature:

lexicals-nub-table (object) => (value)

Parameters:
Values:

  • value – An instance of <nubhandle>, or #f.

lexicals-nub-table-setter Generic function
Signature:

lexicals-nub-table-setter (value object) => (value)

Parameters:

  • value – An instance of <nubhandle>, or #f.

  • object – An instance of <function-frame>.

Values:

  • value – An instance of <nubhandle>, or #f.

next-instruction Generic function
Signature:

next-instruction (object) => (value)

Parameters:
Values:

Frame Arguments and Lexicals

<lexical-variable> Abstract Class
Superclasses:

<object>

Init-Keywords:

A class representing a lexical variable in a stack frame.

lexical-variable-name Generic function
Signature:

lexical-variable-name (v) => (name)

Parameters:
Values:

Returns the name of the lexical variable as a <string> object. Note that the name may well be a “mangled” name.

lexical-variable-address Generic function
Signature:

lexical-variable-address (object) => (value)

Parameters:
Values:

Returns the address of the lexical variable as a <remote-value>. To get the value of a lexical variable, simply use one of the primitive read functions (such as read-value) on the address of the lexical variable. To set the value of a lexical variable, simply use one of the primitive write functions.

do-frame-arguments Generic function
Signature:

do-frame-arguments (function ap frame) => ()

Parameters:

Applies function to each of the arguments in the frame. The function is called with one argument, an argument that is represented as a <lexical-variable> object.

do-frame-lexicals Generic function
Signature:

do-frame-lexicals (function ap frame) => ()

Parameters:

Applies function to each of the arguments and lexicals in the frame. The function is called with one argument, a lexical variable that is represented as a <lexical-variable> object.

find-lexical-variable Generic function
Signature:

find-lexical-variable (ap frame name) => (lx)

Parameters:
Values:

Attempts to find a lexical variable, whose name is the same as the supplied string, within the lexicals of the given function frame. If such a lexical is found, it is returned as an instance of <lexical-variable>, otherwise #f is returned.

Continuing and Restarting Frames

Issue: Restart frame.

Issue: Return from frame.

Issue: Trap on exit.

Symbol Lookup

<remote-symbol> Class
Superclasses:

<object>

Init-Keywords:

  • address (required) – An instance of <remote-value>.

  • language (required) – An instance of <integer>.

  • library – An instance of <remote-library>, or #f.

  • name (required) – An instance of <string>.

  • object-file – An instance of <remote-object-file>, or #f.

  • storage-status – An instance of one-of(#"public", #"static", #"exported").

A class representing a global symbol in the executable or its libraries.

<remote-function> Class
Superclasses:

<remote-symbol>

Init-Keywords:
remote-function-debug-start Generic function
Signature:

remote-function-debug-start (object) => (value)

Parameters:
Values:
remote-function-debug-end Generic function
Signature:

remote-function-debug-end (object) => (value)

Parameters:
Values:
remote-function-end Generic function
Signature:

remote-function-end (object) => (value)

Parameters:
Values:
first-frame-breakable-address Generic function
Signature:

first-frame-breakable-address (symbol) => (#rest results)

Parameters:
Values:

  • #rest results – An instance of <object>.

first-frame-breakable-address(<remote-symbol>) Method
first-frame-breakable-address(<remote-function>) Method
last-frame-breakable-address Generic function
Signature:

last-frame-breakable-address (symbol) => (#rest results)

Parameters:
Values:

  • #rest results – An instance of <object>.

last-frame-breakable-address(<remote-symbol>) Method
last-frame-breakable-address(<remote-function>) Method
remote-symbol-name Generic function
Signature:

remote-symbol-name (object) => (value)

Parameters:
Values:

Returns the name of the remote symbol as a <string> object. Note that the name may well be a “mangled” name.

remote-symbol-address Generic function
Signature:

remote-symbol-address (object) => (value)

Parameters:
Values:

Returns the address of the remote symbol as a <remote-value>. To get the value of a remote symbol, simply use one of the primitive read functions (such as read-value) on the address of the remote symbol.

remote-symbol-language Generic function
Signature:

remote-symbol-language (object) => (value)

Parameters:
Values:

Attempts to determine which language defines the given symbol. The access-path library currently defines the following possible return values:

$symbol-language-basic Constant
$symbol-language-c Constant
$symbol-language-c++ Constant
$symbol-language-cobol Constant
$symbol-language-dylan Constant
$symbol-language-fortran Constant
$symbol-language-masm Constant
$symbol-language-pascal Constant
remote-symbol-library Generic function
Signature:

remote-symbol-library (object) => (value)

Parameters:
Values:

Returns the library to which the given <remote-symbol> belongs.

remote-symbol-object-file Generic function
Signature:

remote-symbol-object-file (object) => (value)

Parameters:
Values:
remote-symbol-storage-status Generic function
Signature:

remote-symbol-storage-status (object) => (value)

Parameters:
Values:

  • value – An instance of one-of(#"public", #"static", #"exported").

remote-symbol-source-location-map Generic function
Signature:

remote-symbol-source-location-map (object) => (value)

Parameters:
Values:
remote-symbol-source-location-map-setter Generic function
Signature:

remote-symbol-source-location-map-setter (value object) => (value)

Parameters:
Values:
definitely-no-source-locations Generic function
Signature:

definitely-no-source-locations (object) => (value)

Parameters:
Values:
definitely-no-source-locations-setter Generic function
Signature:

definitely-no-source-locations-setter (value object) => (value)

Parameters:
Values:
do-symbols Generic function
Signature:

do-symbols (function ap #key library matching type) => ()

Parameters:

  • function – An instance of <function>.

  • ap – An instance of <access-path>.

  • library (#key) – An instance of <object>.

  • matching (#key) – An instance of <object>.

  • type (#key) – An instance of <object>.

Applies function to each of the symbols in the executable or its libraries. The function is called with one argument, a <remote-symbol>.

If library is supplied, only the given <remote-library> is searched.

If matching is supplied, only those symbols whose names contain the matching substring are returned.

If type is supplied, only those symbols whose “types” match are returned. type can be one of #”static”, #”global”, or #”exported”.

nearest-symbols Generic function
Signature:

nearest-symbols (ap address) => (symbol previous next)

Parameters:
Values:

Returns three <remote-symbol> objects which represent the nearest symbol to address (or #f if there is no such symbol), the previous symbol (or #f if there is no previous symbol), and the next symbol (or #f if there is no next symbol).

find-symbol Generic function
Signature:

find-symbol (ap name #key library type) => (maybe-sym)

Parameters:
Values:

Attempts to find a symbol whose name is the same as the supplied string. If found, the symbol is returned as an instance of <remote-symbol>, otherwise #f is returned.

If the keyword library is supplied, it should be an instance of <remote-library>, and the lookup will be restricted to this library alone. Otherwise, all libraries in the application will be searched.

If type is supplied, it should be one of #”static”, #”global” or #”exported”, and the search will be restricted to symbols of this type. Otherwise, symbols of all types will be searched.

symbol-relative-address Generic function
Signature:

symbol-relative-address (ap address) => (sym-if-found offset)

Parameters:
Values:
address-within-definition? Generic function
Signature:

address-within-definition? (symbol addr) => (#rest results)

Parameters:
Values:

  • #rest results – An instance of <object>.

address-within-definition?(<remote-symbol>, <remote-value>) Method
address-within-definition?(<remote-function>, <remote-value>) Method
function-bounding-addresses Generic function
Signature:

function-bounding-addresses (ap address) => (lowerbound upperbound)

Parameters:
Values:
classify-symbolic-name Generic function
Signature:

classify-symbolic-name (path name) => (classification)

Parameters:
Values:

  • classification – An instance of <object>.

Disassembly

interpret-instruction-at-current-location Generic function
Signature:

interpret-instruction-at-current-location (ap thread) => (flow destination length)

Parameters:
Values:

A less user-interface-oriented function for disassembly. This describes what the code is going to do next by returning an abstraction over the current machine instruction about to be executed by the thread. (This instruction has been added to support stepping). flow is one of a set of values that describe what kind of flow of control the current instruction will cause. The access-path library defines these possible return values:

Regardless of the value of flow, destination always contains the address of the next instruction that will be executed after the current one. The access-path implementation will do all necessary calculations for PC-relativity, indirection and return addresses. The flow value is really just an indicator of what calculations were performed, not of what calculations need to be performed.

length will be an <integer> giving the size, in bytes, of the instruction that was examined, in case this is useful.

$flowcalldirect Constant
$flowcallindirect Constant
$flowillegal Constant
$flowinterrupt Constant
$flowjumpdirect Constant
$flowjumpindirect Constant
$flowlinear Constant
$flowreturn Constant

Source Code

It is the responsibility of the access-path layer to present any information that may be available within the application’s debugging information about source code location. In order to do this, it provides a simple abstraction called a <source-location-map>, which is associated with a <remote-symbol>.

<source-location-map> Class
Superclasses:

<object>

Init-Keywords:

A class abstracting over the available debugging information for known source code locations. These are created on a per-<remote-symbol> basis. Most commonly, this will be useful when the <remote-symbol> is known to denote a function.

function-source-location-map Generic function
Signature:

function-source-location-map (ap sym) => (slm)

Parameters:
Values:

Attempts to generate a <source-location-map> for the given <remote-symbol>. The given symbol is not required to denote a function, but it is assumed that this will be the normal usage of the API, hence the name. #f can be returned from this function if no map can be constructed, possibly due to an absence of debugging information for this symbol.

source-filename Generic function
Signature:

source-filename (object) => (value)

Parameters:
Values:

Returns a <string> naming the file associated with this <source-location-map>, the file in which the associated <remote-symbol> is defined. This will contain whatever path qualifications were provided in the debugging information format.

number-of-locations Generic function
Signature:

number-of-locations (object) => (value)

Parameters:
Values:

The <source-location-map> contains a list of line number/address pairs, which can be individually accessed by source-location-description (below). This function returns the number of source locations available inside the map.

base-linenumber Generic function
Signature:

base-linenumber (object) => (value)

Parameters:
Values:

All line numbers contained in the <source-location-map> are expressed relative to the base line number returned by this function. This base line number should be added to line numbers in the map in order to obtain an absolute line number within the file. The reason for this abstraction is to accommodate (and preserve the utility of) debugging information formats that express line numbers relative to the start of a function.

base-address Generic function
Signature:

base-address (object) => (value)

Parameters:
Values:
source-location-description Generic function
Signature:

source-location-description (slm i) => (function-relative-linenumber address)

Parameters:
Values:

Returns a particular line/address pair within the debug map. The value of index should be an integer within the range from zero below the value returned by number-of-locations for this map. The result of supplying an invalid index is undefined. The function-relative-linenumber is expressed relative to the base line number for this <source-location-map>. The address is an absolute code-location (PC) corresponding to the line number.

nearest-source-locations Generic function
Signature:

nearest-source-locations (ap slm ip) => (exact nearest-ahead nearest-behind)

Parameters:
Values:

  • exact – An instance of <integer>, or #f.

  • nearest-ahead – An instance of <integer>, or #f.

  • nearest-behind – An instance of <integer>, or #f.

Attempts to calculate the source locations within the map whose code-locations are nearest to the given address (a <remote-value>). Each of the return values will be a valid integer index into the map, or #f if there is no such index. exact indexes the source location that precisely corresponds to the given address, if one exists. nearest-ahead indexes the source location whose address is closest to but higher than the given address. nearest-behind indexes the source location whose address is closest to but lower than the given address.

resolve-source-location Generic function
Signature:

resolve-source-location (ap filename #key line column library paths) => (code-location exact?)

Parameters:
Values:
function-recorded-source-locations Generic function
Signature:

function-recorded-source-locations (ap sym) => (filename base-linenumber base-address line-positions code-offsets)

Parameters:
Values:

Dylan-specific Extensions

dylan-thread-environment-block-address Generic function
Signature:

dylan-thread-environment-block-address (ap thread) => (teb)

Parameters:
Values:

Gets the thread-local pointer to the Dylan-level thread environment block.

dylan-thread-mv-buffer-live? Generic function
Signature:

dylan-thread-mv-buffer-live? (path thread) => (well?)

Parameters:
Values:

Queries the necessary flags in the context of a dylan thread to decide whether the contents of the MV buffer are current.

dylan-calculate-destination-for-step-into Generic function
Signature:

dylan-calculate-destination-for-step-into (path thread) => (address use-function-register? success?)

Parameters:
Values:
dylan-current-function Generic function
Signature:

dylan-current-function (ap thread) => (remote-lambda)

Parameters:
Values: