Module Linker.Trace

Call tracing.

Linker doesn't operate in terms of functions or subroutines, but rather in terms of executable chunks of code. It is convenient, though, to track called functions, i.e., there are names and arguments (data-flow). Since a code in Primus is an uniterpreted computation it is the responsibility of the code provider to make corresponding observations, when a subroutine is entered or left.

By default, the code is provided by the BIR Interpreter and Primus Interpreter. Both care to provide corresponding observations. However, the Primus Lisp Interpreter provides call observations only when an externally visible function is called, e.g., malloc, free.

val call : (string * value list) observation

occurs when a subroutine is called. Argument values are specified in the same order in which corresponding input arguments of a corresponding subroutine term are specified.

Example,

(call (malloc 4))

val return : (string * value list) observation

occurs just before a subroutine returns.

Context-wise, an observation is made when the interpreter is still in the subroutine. The argument list are in the same order as arguments of a corresponding subroutine. Values of all arguments are provided, including output and input arguments.

Example,

(call-return (malloc 4 0xDEADBEEF))

val lisp_call : (string * value list) observation

occurs when an externally linked primus stub is called. Arguments values are specified in the same order as in the call observation

val lisp_call_return : (string * value list) observation

occurs just before a lisp call from an external procedure returns. Arguments values are specified in the same order as in the return observation

Notification interface

Use Machine.Observation.make function, where Machine is a module implementing Machine.S interface, to provide observations.

val call_entered : (string * value list) statement

the statement that makes call observations.

val call_returned : (string * value list) statement

the statement that makes return observations

val lisp_call_entered : (string * value list) statement

the statement that makes lisp-call observations

val lisp_call_returned : (string * value list) statement

the statement that makes lisp-call-return observations