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

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

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

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
Values

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

as-remote-pointer Generic function
Signature

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

Parameters
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 notifaction 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