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.

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
- 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, thearguments:
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 callrestart
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 ofapplication:
,arguments:
, orcore-file:
may be supplied. In this case, the application’s initial state is running; you must callstop
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
- Init-Keywords
-
<access-path-creation-error>
Class¶ - Superclasses
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
object – An instance of
<access-path>
.
- Values
value – An instance of
<object>
.
-
access-path-abstract-handle-setter
Generic function¶ - Signature
access-path-abstract-handle-setter (value object) => (value)
- Parameters
value – An instance of
<object>
.object – An instance of
<access-path>
.
- Values
value – An instance of
<object>
.
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 theaccess-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
object – An instance of
<access-path>
.
- Values
value – An instance of
<object>
.
-
access-path-application
Generic function¶ - Signature
access-path-application (object) => (application)
- Parameters
object – An instance of
<object>
.
- 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 theapplication:
init keyword was not supplied when the access path was created.
-
access-path-arguments
Generic function¶ - Signature
access-path-arguments (object) => (value)
- Parameters
object – An instance of
<application-access-path>
.
- Values
value – An instance of
<string>
.
-
access-path-process
Generic function¶ - Signature
access-path-process (object) => (#rest results)
- Parameters
object – An instance of
<object>
.
- Values
process – An instance of
<remote-process>
, or#f
.
Returns the process associated with the access path, as a
<remote-process>
object. This may return#f
if one of theapplication:
orprocess:
init keywords was not supplied when the access path was created.
-
access-path-core-file
Generic function¶
-
$max-spy-function-arguments
Constant¶
-
spy-function-argument-remote-vector
Generic function¶ - Signature
spy-function-argument-remote-vector (object) => (value)
- Parameters
object – An instance of
<access-path>
.
- Values
value – An instance of
<object>
.
-
spy-function-argument-remote-vector-setter
Generic function¶ - Signature
spy-function-argument-remote-vector-setter (value object) => (value)
- Parameters
value – An instance of
<object>
.object – An instance of
<access-path>
.
- Values
value – An instance of
<object>
.
-
$max-stepping-locations
Constant¶
-
stepping-locations-remote-vector
Generic function¶ - Signature
stepping-locations-remote-vector (object) => (value)
- Parameters
object – An instance of
<access-path>
.
- Values
value – An instance of
<object>
.
-
stepping-locations-remote-vector-setter
Generic function¶ - Signature
stepping-locations-remote-vector-setter (value object) => (value)
- Parameters
value – An instance of
<object>
.object – An instance of
<access-path>
.
- Values
value – An instance of
<object>
.
-
$access-ok
Constant¶
Modeling Remote Objects¶
Debugger Connections¶
-
<debugger-connection>
Abstract Instantiable Class¶ - Superclasses
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
object – An instance of
<debugger-connection>
.
- Values
value – An instance of
<string>
.
-
connection-hostname-setter
Generic function¶ - Signature
connection-hostname-setter (value object) => (value)
- Parameters
value – An instance of
<string>
.object – An instance of
<debugger-connection>
.
- Values
value – An instance of
<string>
.
-
connection-open?
Generic function¶ - Signature
connection-open? (object) => (value)
- Parameters
object – An instance of
<remote-debugger-connection>
.
- Values
value – An instance of
<boolean>
.
-
connection-open?-setter
Generic function¶
-
connection-password
Generic function¶ - Signature
connection-password (object) => (value)
- Parameters
object – An instance of
<remote-debugger-connection>
.
- Values
value – An instance of
<string>
.
-
describe-debugger-connection
Generic function¶
-
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
- 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
ap – An instance of
<access-path>
.conn – An instance of
<debugger-connection>
.
- Values
conn – An instance of
<access-connection>
.
-
do-open-access-connections
Function¶ - Signature
do-open-access-connections (f server) => ()
- Parameters
f – An instance of
<function>
.server – An instance of
<debugger-connection>
.
-
connection-open-tethers
Generic function¶ - Signature
connection-open-tethers (object) => (value)
- Parameters
object – An instance of
<debugger-connection>
.
- Values
value – An instance of
<stretchy-vector>
.
-
connection-process
Generic function¶ - Signature
connection-process (object) => (value)
- Parameters
object – An instance of
<access-connection>
.
- Values
value – An instance of
<nub>
.
-
connection-process-list
Generic function¶ - Signature
connection-process-list (object) => (value)
- Parameters
object – An instance of
<debugger-connection>
.
- Values
value – An instance of
<stretchy-vector>
.
-
connection-process-list-setter
Generic function¶ - Signature
connection-process-list-setter (value object) => (value)
- Parameters
value – An instance of
<stretchy-vector>
.object – An instance of
<debugger-connection>
.
- Values
value – An instance of
<stretchy-vector>
.
-
connection-process-setter
Generic function¶ - Signature
connection-process-setter (value object) => (value)
- Parameters
value – An instance of
<nub>
.object – An instance of
<access-connection>
.
- 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
value – An instance of
<string>
.
-
host-machine
Function¶ - Signature
host-machine () => (connection)
- Values
connection – An instance of
<debugger-connection>
.
Returns an instance of
<debugger-connection>
that represents the machine on whichhost-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
ap – An instance of
<access-path>
.
- Values
count – An instance of
<integer>
.
Remote Processes¶
-
<remote-process>
Abstract Class¶
-
remote-process-name
Generic function¶ - Signature
remote-process-name (object) => (value)
- Parameters
object – An instance of
<remote-process>
.
- Values
value – An instance of
<string>
.
-
remote-process-system-identifier
Generic function¶ - Signature
remote-process-system-identifier (object) => (value)
- Parameters
object – An instance of
<remote-process>
.
- Values
value – An instance of
<string>
.
-
remote-process-actual-identifier
Generic function¶ - Signature
remote-process-actual-identifier (object) => (value)
- Parameters
object – An instance of
<remote-process>
.
- Values
value – An instance of
<abstract-integer>
.
Remote Threads¶
-
<remote-thread>
Abstract Class¶ - Superclasses
- 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
function – An instance of
<function>
.ap – An instance of
<access-path>
.
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
object – An instance of
<active-remote-register>
.
- Values
value – An instance of
<remote-thread>
.
-
thread-name
Generic function¶ - Signature
thread-name (object) => (value)
- Parameters
object – An instance of
<remote-thread>
.
- Values
value – An instance of
<string>
.
Returns the name of the thread as a string.
-
thread-access-path
Generic function¶ - Signature
thread-access-path (object) => (value)
- Parameters
object – An instance of
<remote-thread>
.
- Values
value – An instance of
<access-path>
.
-
get-thread-cpu-time
Generic function¶ - Signature
get-thread-cpu-time (ap thread) => (timer)
- Parameters
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
timer – An instance of
<integer>
.
-
get-process-wall-clock-time
Generic function¶ - Signature
get-process-wall-clock-time (ap) => (timer)
- Parameters
ap – An instance of
<access-path>
.
- Values
timer – An instance of
<integer>
.
-
number-of-active-threads
Generic function¶ - Signature
number-of-active-threads (ap) => (count)
- Parameters
ap – An instance of
<access-path>
.
- Values
count – An instance of
<integer>
.
-
thread-state
Generic function¶ - Signature
thread-state (object) => (value)
- Parameters
object – An instance of
<remote-thread>
.
- Values
value – An instance of
<string>
.
Returns the state of the thread as a string.
-
thread-priority
Generic function¶ - Signature
thread-priority (t #key normalize?) => (p)
- Parameters
t – An instance of
<remote-thread>
.normalize? (#key) – An instance of
<object>
.
- Values
p – An instance of
<number>
.
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
object – An instance of
<remote-thread>
.
- Values
value – An instance of
<boolean>
.
Returns
#t
if the given thread has been suspended, else returns#f
. Note that “suspended” means “suspended by the debugger”, via a call tosuspend-thread
. So, even with the application in the stopped state, this function might return#f
. A good interpretation ofthread-suspended?
is: will this thread not resume execution upon a call tocontinue
, or will it continue unhandled?
-
thread-permanently-suspended?
Generic function¶ - Signature
thread-permanently-suspended? (ap thread) => (suspended?)
- Parameters
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
suspended? – An instance of
<boolean>
.
-
thread-permanently-suspended?-setter
Generic function¶ - Signature
thread-permanently-suspended?-setter (suspend? ap thread) => (suspend?)
- Parameters
suspend? – An instance of
<boolean>
.ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
suspend? – An instance of
<boolean>
.
-
stack-size
Generic function¶ - Signature
stack-size (object) => (value)
- Parameters
object – An instance of
<remote-thread>
.
- Values
value – An instance of
<integer>
.
-
stack-size-setter
Generic function¶ - Signature
stack-size-setter (value object) => (value)
- Parameters
value – An instance of
<integer>
.object – An instance of
<remote-thread>
.
- Values
value – An instance of
<integer>
.
-
stack-size-valid?
Generic function¶ - Signature
stack-size-valid? (object) => (value)
- Parameters
object – An instance of
<remote-thread>
.
- Values
value – An instance of
<boolean>
.
-
stack-size-valid?-setter
Generic function¶ - Signature
stack-size-valid?-setter (value object) => (value)
- Parameters
value – An instance of
<boolean>
.object – An instance of
<remote-thread>
.
- Values
value – An instance of
<boolean>
.
-
stack-trace-valid?
Generic function¶ - Signature
stack-trace-valid? (object) => (value)
- Parameters
object – An instance of
<remote-thread>
.
- Values
value – An instance of
<boolean>
.
-
stack-trace-valid?-setter
Generic function¶ - Signature
stack-trace-valid?-setter (value object) => (value)
- Parameters
value – An instance of
<boolean>
.object – An instance of
<remote-thread>
.
- Values
value – An instance of
<boolean>
.
-
thread-stack
Generic function¶ - Signature
thread-stack (object) => (value)
- Parameters
object – An instance of
<remote-thread>
.
- Values
value – An instance of
<stack-frame>
, or#f
.
-
thread-stack-setter
Generic function¶ - Signature
thread-stack-setter (value object) => (value)
- Parameters
value – An instance of
<stack-frame>
, or#f
.object – An instance of
<remote-thread>
.
- Values
value – An instance of
<stack-frame>
, or#f
.
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
- 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
function – An instance of
<function>
.application – An instance of
<access-path>
.
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
Returns the version of the shared library as a string.
-
library-base-address
Generic function¶ - Signature
library-base-address (object) => (value)
- Parameters
object – An instance of
<remote-library>
.
- Values
value – An instance of
<remote-value>
.
-
library-image-name
Generic function¶ - Signature
library-image-name (object) => (value)
- Parameters
object – An instance of
<remote-library>
.
- Values
value – An instance of
<string>
.
Returns a
<string>
that indicates where the library was loaded from.
-
library-core-name
Generic function¶ - Signature
library-core-name (object) => (value)
- Parameters
object – An instance of
<remote-library>
.
- Values
value – An instance of
<string>
.
-
library-object-files
Generic function¶ - Signature
library-object-files (object) => (value)
- Parameters
object – An instance of
<remote-library>
.
- Values
value – An instance of
<sequence>
.
-
extend-remote-library
Generic function¶ - Signature
extend-remote-library (path library file) => ()
- Parameters
path – An instance of
<access-path>
.library – An instance of
<remote-library>
.file – An instance of
<remote-object-file>
.
-
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
lib – An instance of
<remote-library>
.
-
self-contained-component?
Generic function¶ - Signature
self-contained-component? (object) => (value)
- Parameters
object – An instance of
<remote-library>
.
- Values
value – An instance of
<boolean>
.
-
self-contained-component?-setter
Generic function¶ - Signature
self-contained-component?-setter (value object) => (value)
- Parameters
value – An instance of
<boolean>
.object – An instance of
<remote-library>
.
- Values
value – An instance of
<boolean>
.
Remote Object Files¶
-
<remote-object-file>
Class¶ - Superclasses
- Init-Keywords
client-data – An instance of
<object>
.language – An instance of
<integer>
.library (required) – An instance of
<remote-library>
.name (required) – An instance of
<byte-string>
.object-extension – An instance of
<byte-string>
.path – An instance of
<byte-string>
.source-extension – An instance of
<byte-string>
.
-
remote-object-file-core-name
Generic function¶ - Signature
remote-object-file-core-name (object) => (value)
- Parameters
object – An instance of
<remote-object-file>
.
- Values
value – An instance of
<byte-string>
.
-
remote-object-file-source-extension
Generic function¶ - Signature
remote-object-file-source-extension (object) => (value)
- Parameters
object – An instance of
<remote-object-file>
.
- Values
value – An instance of
<byte-string>
.
-
remote-object-file-object-extension
Generic function¶ - Signature
remote-object-file-object-extension (object) => (value)
- Parameters
object – An instance of
<remote-object-file>
.
- Values
value – An instance of
<byte-string>
.
-
remote-object-file-path
Generic function¶ - Signature
remote-object-file-path (object) => (value)
- Parameters
object – An instance of
<remote-object-file>
.
- Values
value – An instance of
<byte-string>
.
-
remote-object-file-library
Generic function¶ - Signature
remote-object-file-library (object) => (value)
- Parameters
object – An instance of
<remote-object-file>
.
- Values
value – An instance of
<remote-library>
.
-
remote-object-file-language
Generic function¶ - Signature
remote-object-file-language (object) => (value)
- Parameters
object – An instance of
<remote-object-file>
.
- Values
value – An instance of
<integer>
.
-
remote-object-file-client-data
Generic function¶ - Signature
remote-object-file-client-data (object) => (value)
- Parameters
object – An instance of
<remote-object-file>
.
- Values
value – An instance of
<object>
.
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
x – An instance of
<object>
.
- 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: theas
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
x – An instance of
<remote-value>
.
- Values
i – An instance of
<integer>
.
-
as-remote-value
Generic function¶ - Signature
as-remote-value (x) => (ptr)
- Parameters
x – An instance of
<abstract-integer>
.
- Values
ptr – An instance of
<remote-value>
.
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
x – An instance of
<remote-value>
.i – An instance of
<integer>
.
- Values
ptr – An instance of
<remote-value>
.
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
x – An instance of
<remote-value>
.i – An instance of
<integer>
.
- Values
ptr – An instance of
<remote-value>
.
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
ap – An instance of
<access-path>
.
- Values
value-size – An instance of
<integer>
.
-
tagged-remote-value-as-integer
Generic function¶ - Signature
tagged-remote-value-as-integer (x) => (i)
- Parameters
x – An instance of
<remote-value>
.
- Values
i – An instance of
<integer>
.
-
tagged-remote-value-as-character
Generic function¶ - Signature
tagged-remote-value-as-character (x) => (c)
- Parameters
x – An instance of
<remote-value>
.
- Values
c – An instance of
<character>
.
-
integer-as-tagged-remote-value
Generic function¶ - Signature
integer-as-tagged-remote-value (i) => (x)
- Parameters
i – An instance of
<integer>
.
- Values
x – An instance of
<remote-value>
.
-
character-as-tagged-remote-value
Generic function¶ - Signature
character-as-tagged-remote-value (c) => (x)
- Parameters
c – An instance of
<character>
.
- Values
x – An instance of
<remote-value>
.
-
remote-value-<
Generic function¶ - Signature
remote-value-< (x y) => (answer)
- Parameters
x – An instance of
<remote-value>
.y – An instance of
<remote-value>
.
- Values
answer – An instance of
<boolean>
.
-
remote-value-<=
Generic function¶ - Signature
remote-value-<= (x y) => (answer)
- Parameters
x – An instance of
<remote-value>
.y – An instance of
<remote-value>
.
- Values
answer – An instance of
<boolean>
.
-
remote-value-=
Generic function¶ - Signature
remote-value-= (x y) => (answer)
- Parameters
x – An instance of
<remote-value>
.y – An instance of
<remote-value>
.
- Values
answer – An instance of
<boolean>
.
-
remote-value-as-string
Generic function¶ - Signature
remote-value-as-string (ap val radix) => (str)
- Parameters
ap – An instance of
<access-path>
.val – An instance of
<remote-value>
.radix – An instance of
<integer>
.
- Values
str – An instance of
<string>
.
-
string-as-remote-value
Generic function¶ - Signature
string-as-remote-value (ap str radix) => (val)
- Parameters
ap – An instance of
<access-path>
.str – An instance of
<string>
.radix – An instance of
<integer>
.
- Values
val – An instance of
<remote-value>
.
-
remote-value-low-order-bits
Generic function¶ - Signature
remote-value-low-order-bits (x bit-count) => (value)
- Parameters
x – An instance of
<remote-value>
.bit-count – An instance of
<integer>
.
- Values
value – An instance of
<integer>
.
-
<remote-register>
Abstract Class¶ - Superclasses
- 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
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
- Init-Keywords
thread (required) – An instance of
<remote-thread>
.
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
r – An instance of
<remote-register>
.
- Values
sym – An instance of
<string>
.
Returns the name of the remote register as a symbol.
-
do-registers
Generic function¶ - Signature
do-registers (function ap #key type) => ()
- Parameters
function – An instance of
<function>
.ap – An instance of
<access-path>
.type (#key) – An instance of
<object>
.
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
ap – An instance of
<access-path>
.nub-register – An instance of
<integer>
.
- Values
descriptor – An instance of
<unassigned-remote-register>
.
-
active-register
Generic function¶ - Signature
active-register (ap thread register) => (reg)
- Parameters
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.register – An instance of
<unassigned-remote-register>
.
- Values
reg – An instance of
<active-remote-register>
.
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>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
ans – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
ans – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
ans – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.
- Values
page-size – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.addr – An instance of
<remote-value>
.
- Values
id – An instance of
<integer>
.
Turns an address into an integer-enumerated memory page ID.
-
page-relative-address
Generic function¶ - Signature
page-relative-address (ap addr) => (id offset)
- Parameters
ap – An instance of
<access-path>
.addr – An instance of
<remote-value>
.
- 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
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.offset – An instance of
<integer>
.
- Values
addr – An instance of
<remote-value>
.
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
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.stack-frame (#key) – An instance of
<object>
.
- Values
val – An instance of
<remote-value>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.value – An instance of
<remote-value>
.
- Values
val – An instance of
<remote-value>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.
- Values
val – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.value – An instance of
<integer>
.
- Values
val – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.
- Values
val – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.value – An instance of
<integer>
.
- Values
val – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.
- Values
val – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.value – An instance of
<integer>
.
- Values
val – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.
- Values
val – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.value – An instance of
<integer>
.
- Values
val – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.
- Values
val – An instance of
<single-float>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.value – An instance of
<single-float>
.
- Values
val – An instance of
<single-float>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.
- Values
val – An instance of
<double-float>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-location>
.value – An instance of
<double-float>
.
- Values
val – An instance of
<double-float>
.
-
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.length – An instance of
<integer>
.
- Values
val – An instance of
<byte-string>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.value – An instance of
<byte-string>
.ending-index (#key) – An instance of
<object>
.
- Values
val – An instance of
<byte-string>
.
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
ap – An instance of
<access-path>
.
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
ap – An instance of
<access-path>
.
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
ap – An instance of
<access-path>
.resume (#key) – An instance of
<object>
.
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
ap – An instance of
<access-path>
.resume (#key) – An instance of
<object>
.
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
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
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
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
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
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
-
step
Generic function¶ - Signature
step (ap n) => ()
- Parameters
ap – An instance of
<access-path>
.n – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.n – An instance of
<integer>
.
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
ap – An instance of
<access-path>
.
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
ap – An instance of
<access-path>
.
- Values
running? – An instance of
<boolean>
.
Returns
#t
if the remote-application is in the running state.
-
application-state-stopped?
Generic function¶ - Signature
application-state-stopped? (ap) => (stopped?)
- Parameters
ap – An instance of
<access-path>
.
- Values
stopped? – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.
- Values
unstarted? – An instance of
<boolean>
.
Returns
#t
if the remote-application is in the unstarted state, because it has never been started with a call torestart
orcontinue
.
-
application-state-post-mortem?
Generic function¶ - Signature
application-state-post-mortem? (ap) => (post-mortem?)
- Parameters
ap – An instance of
<access-path>
.
- Values
post-mortem? – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.do-cleanups? (#key) – An instance of
<object>
.
- Values
success? – An instance of
<boolean>
.
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. Ifdo-cleanups?
is false, the application will be put into the dead state. Ifdo-cleanups?
is true, the application will be put into the running state.
-
close-application
Generic function¶ - Signature
close-application (ap) => ()
- Parameters
ap – An instance of
<access-path>
.
-
register-exit-process-function
Generic function¶ - Signature
register-exit-process-function (ap exit-process) => ()
- Parameters
ap – An instance of
<access-path>
.exit-process – An instance of
<remote-symbol>
.
Remote Function Calling¶
-
remote-call
Generic function¶ - Signature
remote-call (access-path thread function #rest arguments) => (ret-addr cookie)
- Parameters
access-path – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.function – An instance of
<remote-value>
.arguments (#rest) – An instance of
<object>
.
- Values
ret-addr – An instance of
<remote-value>
.cookie – An instance of
<object>
.
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 callremote-call
if the application is not in the stopped stateThis 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
ap – An instance of
<access-path>
.thr – An instance of
<remote-thread>
.
- Values
result – An instance of
<remote-value>
.
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 toremote-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. Callingremote-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
ap – An instance of
<access-path>
.thr – An instance of
<remote-thread>
.ctx – An instance of
<thread-context>
.
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
. Likeremote-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
andremote-restore-context
should be called at the same time, in either order. The justification for having two separate functions,remote-call-result
andremote-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 ofremote-call-result
andremote-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
ap – An instance of
<access-path>
.thr – An instance of
<remote-thread>
.function – An instance of
<remote-value>
.arguments (#rest) – An instance of
<object>
.
- Values
result – An instance of
<remote-value>
.aborted? – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
success – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
success – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
success – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.size – An instance of
<integer>
.
- Values
success – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
success – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
success – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.size – An instance of
<integer>
.
- Values
success – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
success – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
success – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
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
access-path – An instance of
<access-path>
.timeout (#key) – An instance of
<object>
.profile-interval (#key) – An instance of
<object>
.
- Values
maybe-sr – An instance of
<stop-reason>
, or#f
.
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
ap – An instance of
<access-path>
.
-
inform-profiling-stopped
Generic function¶ - Signature
inform-profiling-stopped (ap) => ()
- Parameters
ap – An instance of
<access-path>
.
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
access-path – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.locations – An instance of
<sequence>
.operation – An instance of
<integer>
.stack-frame (#key) – An instance of
<object>
.
-
remove-all-stepping-control-for-thread
Generic function¶ - Signature
remove-all-stepping-control-for-thread (path thread) => ()
- Parameters
path – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
The Class Hierarchy of Stop Reasons¶
-
<internal-stop-reason>
Abstract Class¶ The base class of all stop-reasons that are signaled by the application.
- Superclasses
- Init-Keywords
process (required) – An instance of
<remote-process>
.thread (required) – An instance of
<remote-thread>
.
-
<basic-stop-reason>
Abstract Class¶ - Superclasses
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
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
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
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
-
<profiler-unhandled-stop-reason>
Class¶ - Superclasses
-
<timeout-stop-reason>
Class¶ - Superclasses
-
stop-reason-process
Generic function¶ - Signature
stop-reason-process (object) => (value)
- Parameters
object – An instance of
<internal-stop-reason>
.
- Values
value – An instance of
<remote-process>
.
Specifies the remote process in which the internal stop-reason occurred.
-
stop-reason-thread
Generic function¶ - Signature
stop-reason-thread (object) => (value)
- Parameters
object – An instance of
<internal-stop-reason>
.
- Values
value – An instance of
<remote-thread>
.
Specifies the remote thread in which the internal stop-reason occurred.
-
<process-stop-reason>
Abstract Class¶ - Superclasses
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
- Init-Keywords
executable (required) – An instance of
<remote-library>
.
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
object – An instance of
<create-process-stop-reason>
.
- Values
value – An instance of
<remote-library>
.
-
<exit-process-stop-reason>
Class¶ - Superclasses
- 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
object – An instance of
<exit-process-stop-reason>
.
- Values
value – An instance of
<integer>
.
Specifies the exit code for the process.
-
<thread-stop-reason>
Abstract Class¶ - Superclasses
The superclass of all thread-related stop-reasons.
-
<create-thread-stop-reason>
Class¶ - Superclasses
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
stop-reason – An instance of
<stop-reason>
.
-
create-thread-event-handler(<access-path>)
Method¶ - Signature
interactive-thread-break-event-handler (application) => (stop-reason)
- Parameters
application – An instance of
<object>
.
- Values
stop-reason – An instance of
<stop-reason>
.
-
interactive-thread-break-event-handler(<access-path>)
Method¶
-
<exit-thread-stop-reason>
Class¶ - Superclasses
- 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
object – An instance of
<exit-thread-stop-reason>
.
- Values
value – An instance of
<integer>
.
Specifies the exit code for the thread.
-
<library-stop-reason>
Abstract Class¶ - Superclasses
- Init-Keywords
library (required) – An instance of
<remote-library>
.
The superclass of all library-related stop-reasons.
-
stop-reason-library
Generic function¶ - Signature
stop-reason-library (object) => (value)
- Parameters
object – An instance of
<library-stop-reason>
.
- Values
value – An instance of
<remote-library>
.
Specifies the library to which the stop-reason corresponds.
-
<load-library-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a shared library is loaded.
-
<unload-library-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a shared library is unloaded.
-
<rip-stop-reason>
Class¶ - Superclasses
- 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
object – An instance of
<RIP-stop-reason>
.
- Values
value – An instance of
<integer>
.
Specifies the exit code for the application.
-
<debug-point-stop-reason>
Abstract Class¶ - Superclasses
- Init-Keywords
address (required) – An instance of
<remote-value>
.
The superclass of all debug point stop reasons.
-
stop-reason-debug-point-address
Generic function¶ - Signature
stop-reason-debug-point-address (object) => (value)
- Parameters
object – An instance of
<debug-point-stop-reason>
.
- Values
value – An instance of
<remote-value>
.
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
The class that represents the stop reason signaled when a breakpoint is hit.
-
<single-step-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a single-step “virtual breakpoint” is hit.
-
<source-step-stop-reason>
Class¶ - Superclasses
-
<source-step-into-stop-reason>
Class¶ - Superclasses
-
<source-step-out-stop-reason>
Class¶ - Superclasses
-
<source-step-over-stop-reason>
Class¶ - Superclasses
-
<watchpoint-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a watchpoint is hit.
-
<read-watchpoint-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a watchpoint is hit.
-
<write-watchpoint-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a watchpoint is hit.
-
<exception-stop-reason>
Abstract Class¶ - Superclasses
- Init-Keywords
exception-address (required) – An instance of
<remote-value>
.first-chance? – An instance of
<boolean>
.
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
object – An instance of
<exception-stop-reason>
.
- Values
value – An instance of
<remote-value>
.
-
stop-reason-exception-first-chance?
Generic function¶ - Signature
stop-reason-exception-first-chance? (object) => (value)
- Parameters
object – An instance of
<exception-stop-reason>
.
- Values
value – An instance of
<boolean>
.
-
<invoke-debugger-stop-reason>
Abstract Class¶ - Superclasses
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
-
<system-invoke-debugger-stop-reason>
Class¶ - Superclasses
-
<memory-exception-stop-reason>
Abstract Class¶ - Superclasses
The class that represents the stop reason signaled when a memory exception occurs.
-
<access-violation-stop-reason>
Class¶ - Superclasses
- 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
object – An instance of
<access-violation-stop-reason>
.
- Values
value – An instance of
<remote-value>
.
-
stop-reason-access-violation-operation
Generic function¶ - Signature
stop-reason-access-violation-operation (object) => (value)
- Parameters
object – An instance of
<access-violation-stop-reason>
.
- Values
value – An instance of
<integer>
.
-
$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
The class that represents the stop reason signaled when an out-of-bounds array references occurs.
-
<instruction-exception-stop-reason>
Abstract Class¶ - Superclasses
The class that represents the stop reason signaled when an instruction exception occurs.
-
<illegal-instruction-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when an illegal instruction exception occurs.
-
<privileged-instruction-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a privileged instruction exception occurs.
-
<arithmetic-exception-stop-reason>
Abstract Class¶ - Superclasses
The class that represents the stop reason signaled when an arithmetic exception occurs.
-
<float-exception-stop-reason>
Abstract Class¶ - Superclasses
The class that represents the stop reason signaled when a floating point exception occurs.
-
<denormal-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a floating point exception occurs.
-
<float-divide-by-zero-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a floating divide-by-zero exception occurs.
-
<inexact-result-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when an inexact result exception occurs.
-
<invalid-float-operation-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when an invalid floating point operation exception occurs.
-
<float-overflow-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a floating point overflow exception occurs.
-
<float-underflow-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when a floating point underflow exception occurs.
-
<float-stack-check-exception-stop-reason>
Class¶ - Superclasses
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
The class that represents the stop reason signaled when an integer exception occurs.
-
<integer-divide-by-zero-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when an integer divide-by-zero exception occurs.
-
<integer-overflow-exception-stop-reason>
Class¶ - Superclasses
-
<noncontinuable-exception-stop-reason>
Class¶ - Superclasses
The class that represents the stop reason signaled when some kind on non-continuable exception occurs.
-
<stack-overflow-exception-stop-reason>
Class¶ - Superclasses
-
<unclassified-exception-stop-reason>
Class¶ - Superclasses
-
<output-debug-string-stop-reason>
Class¶ - Superclasses
- Init-Keywords
debug-string (required) – An instance of
<string>
.
-
stop-reason-debug-string
Generic function¶ - Signature
stop-reason-debug-string (object) => (value)
- Parameters
object – An instance of
<output-debug-string-stop-reason>
.
- Values
value – An instance of
<string>
.
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
app – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
b – An instance of
<boolean>
.
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
ap – An instance of
<access-path>
.
- Values
seq – An instance of
<sequence>
.
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
yes-or-no – An instance of
<boolean>
.
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 byreceivable-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
name – An instance of
<string>
.
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
- Init-Keywords
index (required) – An instance of
<integer>
.link-next – An instance of
<stack-frame>
, or#f
.link-previous – An instance of
<stack-frame>
, or#f
.next-instruction (required) – An instance of
<remote-value>
.pointer (required) – An instance of
<remote-value>
.return-address (required) – An instance of
<remote-value>
.thread (required) – An instance of
<remote-thread>
.
-
link-next
Generic function¶ - Signature
link-next (object) => (value)
- Parameters
object – An instance of
<stack-frame>
.
- Values
value – An instance of
<stack-frame>
, or#f
.
-
link-next-setter
Generic function¶ - Signature
link-next-setter (value object) => (value)
- Parameters
value – An instance of
<stack-frame>
, or#f
.object – An instance of
<stack-frame>
.
- Values
value – An instance of
<stack-frame>
, or#f
.
-
link-previous
Generic function¶ - Signature
link-previous (object) => (value)
- Parameters
object – An instance of
<stack-frame>
.
- Values
value – An instance of
<stack-frame>
, or#f
.
-
link-previous-setter
Generic function¶ - Signature
link-previous-setter (value object) => (value)
- Parameters
value – An instance of
<stack-frame>
, or#f
.object – An instance of
<stack-frame>
.
- Values
value – An instance of
<stack-frame>
, or#f
.
-
<function-frame>
Class¶ A class that represents a function-call frame in the control stack.
- Superclasses
-
initialize-stack-trace
Generic function¶ - Signature
initialize-stack-trace (path thread) => (top-frame)
- Parameters
path – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
top-frame – An instance of
<function-frame>
.
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
path – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
count – An instance of
<integer>
.
-
next-frame
Generic function¶ - Signature
next-frame (path frame) => (maybe-frame)
- Parameters
path – An instance of
<access-path>
.frame – An instance of
<function-frame>
.
- Values
maybe-frame – An instance of
<function-frame>
, or#f
.
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
path – An instance of
<access-path>
.frame – An instance of
<function-frame>
.
- Values
maybe-frame – An instance of
<function-frame>
, or#f
.
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
path – An instance of
<access-path>
.frame – An instance of
<function-frame>
.
- Values
fp – An instance of
<remote-value>
.
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
path – An instance of
<access-path>
.frame – An instance of
<function-frame>
.
- Values
ret-addr – An instance of
<remote-value>
.
Returns the return address for the frame as a
<remote-value>
.
-
frame-instruction-address
Generic function¶ - Signature
frame-instruction-address (path frame) => (ip)
- Parameters
path – An instance of
<access-path>
.frame – An instance of
<function-frame>
.
- Values
ip – An instance of
<remote-value>
.
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
ap – An instance of
<access-path>
.this-one – An instance of
<remote-value>
.than-this-one – An instance of
<remote-value>
.
- Values
answer – An instance of
<boolean>
.
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
path – An instance of
<access-path>
.from – An instance of
<remote-value>
.to – An instance of
<remote-value>
.
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
object – An instance of
<function-frame>
.
- Values
value – An instance of
<vector>
.
-
lexicals-setter
Generic function¶ - Signature
lexicals-setter (value object) => (value)
- Parameters
value – An instance of
<vector>
.object – An instance of
<function-frame>
.
- Values
value – An instance of
<vector>
.
-
stack-frame-pointer
Generic function¶ - Signature
stack-frame-pointer (object) => (value)
- Parameters
object – An instance of
<stack-frame>
.
- Values
value – An instance of
<remote-value>
.
-
frame-thread
Generic function¶ - Signature
frame-thread (object) => (value)
- Parameters
object – An instance of
<stack-frame>
.
- Values
value – An instance of
<remote-thread>
.
-
full-lexicals-read?
Generic function¶ - Signature
full-lexicals-read? (object) => (value)
- Parameters
object – An instance of
<function-frame>
.
- Values
value – An instance of
<boolean>
.
-
full-lexicals-read?-setter
Generic function¶ - Signature
full-lexicals-read?-setter (value object) => (value)
- Parameters
value – An instance of
<boolean>
.object – An instance of
<function-frame>
.
- Values
value – An instance of
<boolean>
.
-
partial-lexicals-read?
Generic function¶ - Signature
partial-lexicals-read? (object) => (value)
- Parameters
object – An instance of
<function-frame>
.
- Values
value – An instance of
<boolean>
.
-
partial-lexicals-read?-setter
Generic function¶ - Signature
partial-lexicals-read?-setter (value object) => (value)
- Parameters
value – An instance of
<boolean>
.object – An instance of
<function-frame>
.
- Values
value – An instance of
<boolean>
.
-
lexicals-count
Generic function¶ - Signature
lexicals-count (object) => (value)
- Parameters
object – An instance of
<function-frame>
.
- Values
value – An instance of
<integer>
.
-
lexicals-count-setter
Generic function¶ - Signature
lexicals-count-setter (value object) => (value)
- Parameters
value – An instance of
<integer>
.object – An instance of
<function-frame>
.
- Values
value – An instance of
<integer>
.
-
lexicals-nub-table
Generic function¶ - Signature
lexicals-nub-table (object) => (value)
- Parameters
object – An instance of
<function-frame>
.
- 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
object – An instance of
<stack-frame>
.
- Values
value – An instance of
<remote-value>
.
Frame Arguments and Lexicals¶
-
<lexical-variable>
Abstract Class¶ - Superclasses
- Init-Keywords
address (required) – An instance of
<remote-location>
.argument? (required) – An instance of
<boolean>
.name (required) – An instance of
<byte-string>
.
A class representing a lexical variable in a stack frame.
-
lexical-variable-name
Generic function¶ - Signature
lexical-variable-name (v) => (name)
- Parameters
v – An instance of
<lexical-variable>
.
- Values
name – An instance of
<string>
.
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
object – An instance of
<lexical-variable>
.
- Values
value – An instance of
<remote-location>
.
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 asread-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
function – An instance of
<function>
.ap – An instance of
<access-path>
.frame – An instance of
<function-frame>
.
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
function – An instance of
<function>
.ap – An instance of
<access-path>
.frame – An instance of
<function-frame>
.
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
ap – An instance of
<access-path>
.frame – An instance of
<function-frame>
.name – An instance of
<string>
.
- Values
lx – An instance of
<lexical-variable>
, or#f
.
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
- 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
- Init-Keywords
absolute-end (required) – An instance of
<remote-value>
.debug-end (required) – An instance of
<remote-value>
.debug-start (required) – An instance of
<remote-value>
.
-
remote-function-debug-start
Generic function¶ - Signature
remote-function-debug-start (object) => (value)
- Parameters
object – An instance of
<remote-function>
.
- Values
value – An instance of
<remote-value>
.
-
remote-function-debug-end
Generic function¶ - Signature
remote-function-debug-end (object) => (value)
- Parameters
object – An instance of
<remote-function>
.
- Values
value – An instance of
<remote-value>
.
-
remote-function-end
Generic function¶ - Signature
remote-function-end (object) => (value)
- Parameters
object – An instance of
<remote-function>
.
- Values
value – An instance of
<remote-value>
.
-
first-frame-breakable-address
Generic function¶
-
first-frame-breakable-address(<remote-symbol>)
Method¶
-
first-frame-breakable-address(<remote-function>)
Method¶
-
last-frame-breakable-address
Generic function¶
-
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
object – An instance of
<remote-symbol>
.
- Values
value – An instance of
<string>
.
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
object – An instance of
<remote-symbol>
.
- Values
value – An instance of
<remote-value>
.
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 asread-value
) on the address of the remote symbol.
-
remote-symbol-language
Generic function¶ - Signature
remote-symbol-language (object) => (value)
- Parameters
object – An instance of
<remote-symbol>
.
- Values
value – An instance of
<integer>
.
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
object – An instance of
<remote-symbol>
.
- Values
value – An instance of
<remote-library>
, or#f
.
Returns the library to which the given
<remote-symbol>
belongs.
-
remote-symbol-object-file
Generic function¶ - Signature
remote-symbol-object-file (object) => (value)
- Parameters
object – An instance of
<remote-symbol>
.
- Values
value – An instance of
<remote-object-file>
, or#f
.
-
remote-symbol-storage-status
Generic function¶ - Signature
remote-symbol-storage-status (object) => (value)
- Parameters
object – An instance of
<remote-symbol>
.
- 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
object – An instance of
<remote-symbol>
.
- Values
value – An instance of
<source-location-map>
, or#f
.
-
remote-symbol-source-location-map-setter
Generic function¶ - Signature
remote-symbol-source-location-map-setter (value object) => (value)
- Parameters
value – An instance of
<source-location-map>
, or#f
.object – An instance of
<remote-symbol>
.
- Values
value – An instance of
<source-location-map>
, or#f
.
-
definitely-no-source-locations
Generic function¶ - Signature
definitely-no-source-locations (object) => (value)
- Parameters
object – An instance of
<remote-symbol>
.
- Values
value – An instance of
<boolean>
.
-
definitely-no-source-locations-setter
Generic function¶ - Signature
definitely-no-source-locations-setter (value object) => (value)
- Parameters
value – An instance of
<boolean>
.object – An instance of
<remote-symbol>
.
- Values
value – An instance of
<boolean>
.
-
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
symbol – An instance of
<remote-symbol>
, or#f
.previous – An instance of
<remote-symbol>
, or#f
.next – An instance of
<remote-symbol>
, or#f
.
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
ap – An instance of
<access-path>
.name – An instance of
<string>
.library (#key) – An instance of
<object>
.type (#key) – An instance of
<object>
.
- Values
maybe-sym – An instance of
<remote-symbol>
, or#f
.
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
sym-if-found – An instance of
<remote-symbol>
, or#f
.offset – An instance of
<integer>
.
-
address-within-definition?
Generic function¶
-
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
ap – An instance of
<access-path>
.address – An instance of
<remote-value>
.
- Values
lowerbound – An instance of
<remote-value>
.upperbound – An instance of
<remote-value>
.
Disassembly¶
-
interpret-instruction-at-current-location
Generic function¶ - Signature
interpret-instruction-at-current-location (ap thread) => (flow destination length)
- Parameters
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
flow – An instance of
<object>
.destination – An instance of
<remote-value>
, or#f
.length – An instance of
<integer>
, or#f
.
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:$flowLinear
means that this instruction will just flow to the next one when it has executed$flowCallDirect
and$flowCallIndirect
both mean that the instruction will invoke a subroutine$flowJumpDirect
and$flowJumpIndirect
both mean that the instruction will cause a jump to another location,$flowReturn
means that the instruction will return from the current subroutine$flowInterrupt
means that the instruction is definitely going to generate a<stop-reason>
$flowIllegal
means that the instruction could not be interpreted.
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
- Init-Keywords
base-address (required) – An instance of
<remote-value>
.base-linenumber (required) – An instance of
<integer>
.filename (required) – An instance of
<byte-string>
.function-symbol (required) – An instance of
<remote-symbol>
.location-count (required) – An instance of
<integer>
.pairs (required) – An instance of
<vector>
.
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
ap – An instance of
<access-path>
.sym – An instance of
<remote-symbol>
.
- Values
slm – An instance of
<source-location-map>
, or#f
.
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
object – An instance of
<source-location-map>
.
- Values
value – An instance of
<byte-string>
.
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
object – An instance of
<source-location-map>
.
- Values
value – An instance of
<integer>
.
The
<source-location-map>
contains a list of line number/address pairs, which can be individually accessed bysource-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
object – An instance of
<source-location-map>
.
- Values
value – An instance of
<integer>
.
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
object – An instance of
<source-location-map>
.
- Values
value – An instance of
<remote-value>
.
-
source-location-description
Generic function¶ - Signature
source-location-description (slm i) => (function-relative-linenumber address)
- Parameters
slm – An instance of
<source-location-map>
.i – An instance of
<integer>
.
- Values
function-relative-linenumber – An instance of
<integer>
.address – An instance of
<remote-value>
.
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
ap – An instance of
<access-path>
.slm – An instance of
<source-location-map>
.ip – An instance of
<remote-value>
.
- Values
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
code-location – An instance of
<remote-value>
, or#f
.exact? – An instance of
<boolean>
.
-
function-recorded-source-locations
Generic function¶ - Signature
function-recorded-source-locations (ap sym) => (filename base-linenumber base-address line-positions code-offsets)
- Parameters
ap – An instance of
<access-path>
.sym – An instance of
<remote-symbol>
.
- Values
filename – An instance of
<byte-string>
, or#f
.base-linenumber – An instance of
<integer>
.base-address – An instance of
<remote-value>
.line-positions – An instance of
<sequence>
.code-offsets – An instance of
<sequence>
.
Dylan-specific Extensions¶
-
dylan-thread-environment-block-address
Generic function¶ - Signature
dylan-thread-environment-block-address (ap thread) => (teb)
- Parameters
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
teb – An instance of
<remote-value>
.
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
path – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
well? – An instance of
<boolean>
.
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
path – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
address – An instance of
<remote-value>
.use-function-register? – An instance of
<boolean>
.success? – An instance of
<boolean>
.
-
dylan-current-function
Generic function¶ - Signature
dylan-current-function (ap thread) => (remote-lambda)
- Parameters
ap – An instance of
<access-path>
.thread – An instance of
<remote-thread>
.
- Values
remote-lambda – An instance of
<remote-value>
.