debug

Overview

The debug function provides commands for setting the Smartbase engine switches and debugger trace settings.

Commands and arguments to the "debug" function:

• (debug compileoff:) Sets the Smartbase "compile" function NOT to generate debug information.
• (debug compileon:) Sets the Smartbase "compile" function to generate debug information.
• (debug erroroff:) Turns off the gTP->DebugErrorON switch.
• (debug erroron:) Turns on the gTP->DebugErrorON switch.
• (debug get:) Returns a Structure with the following attributes:
• JitON: value of Smartbase engine DebugJitON switch (true|false)
• NativeCode: value of Smartbase engine NativeCode switch (true|false)
• TraceON: value of Smartbase engine DebugTraceON switch (true|false)
• TraceSuspended: value of Smartbase engine DebugSuspended switch (true|false)
• ErrorON: value of Smartbase engine DebugErrorON switch (true|false)
• Lambda: value of Smartbase engine DebugTraceLambda (Lambda Object|*|!)
• CodeL: value of Smartbase engine DebugTraceCodeL (number|*|!)
• Recursion: value of Smartbase engine DebugTraceRecursion (number|*|!)
• Compile: value of Smartbase engine GenerateDebugInfo switch (true|false)
• Changed: value of Smartbase engine EngineStateChanged switch (true|false)
• (debug jitoff:) Turns off the gTP->DebugJitON switch.
• (debug jiton:) Turns on the gTP->DebugJitON switch.
• (debug command) Sets the current instruction trace rules using the command string which is parsed as follows:
• command = "Lambda:CodeL:Recursion"
• whereLambda = (name | * | !)
• where CodeL = (number | * | !)
• where Recursion = (number | * | !)
• Some examples follow:
• "!" sets Smartbase engine swiches as follows: DebugTraceLambda=!, DebugTraceCodeL=!, DebugTraceRecursion=!
• "*" sets Smartbase engine swiches as follows: DebugTraceLambda=*, DebugTraceCodeL=*, DebugTraceRecursion=*
• "name:*:*" sets Smartbase engine swiches as follows: DebugTraceLambda=(eval name), DebugTraceCodeL=*, DebugTraceRecursion=*
• "*:45:*" sets Smartbase engine swiches as follows: DebugTraceLambda=*, DebugTraceCodeL=45, DebugTraceRecursion=*
• "*:*:3" sets Smartbase engine swiches as follows: DebugTraceLambda=*, DebugTraceCodeL=45, DebugTraceRecursion=3
• "name:52:5" sets Smartbase engine swiches as follows: DebugTraceLambda=(eval name), DebugTraceCodeL=52, DebugTraceRecursion=5

The Smartbase engine has two major execution settings: JitON and JitOFF. In JitON mode, the Just-In-Time compiler generates actual machine register code for extremely fast execution. In JitOFF mode, the Virtual Machine Emulator is turned on allowing debugger tracing of instructions.

In JitOFF mode, the Smartbase engine allows tracing of VM Emulated instructions IF AND ONLY IF the instructions have been executed as a result of the debugEval function. For example, the following code

(debugEval "(foo testing:)")

will evaluate the phrase "(foo testing:)" with VM instruction tracing on under the following rules and guidelines.

JitON Rule:

If the Smartbase engine JIT is ON, then debugEval will evaluate the specified expression WITHOUT instruction tracing. Instruction tracing is ONLY available with JitOFF.

Trace Rule:

Once inside the debugEval function, with JitOFF, instruction execution will proceed normally until the current debug trace settings requests a trace break. A trace break is always requested under the following trace rules:

• DebugTraceLambda Setting:
• DebugTraceLambda = #<current Lambda> A trace break is requested IFF the Trace-CodeL-Setting requests.
• DebugTraceLambda = * A trace break is requested IFF the Trace-CodeL-Setting requests.
• DebugTraceLambda = ! A trace break is NEVER requested.
• DebugTraceCodeL Setting:
• DebugTraceCodeL = current IP A trace break is requested IFF the Trace-Recursion-Setting requests.
• DebugTraceCodeL = * A trace break is requested IFF the Trace-Recursion-Setting requests.
• DebugTraceCodeL = ! A trace break is NEVER requested.
• DebugTraceRecursion Setting:
• DebugRecursionCount = DebugTraceRecursion A trace break is requested.
• DebugDebugTraceRecursion = * A trace break is requested.
• DebugDebugTraceRecursion = ! A trace break is NEVER requested.

Break Rule:

Once inside the debugEval function, with JitOFF, if a trace break is requested, by the above trace rules, then the VM Emulator calls the "debugDetective" function, which has been supplied by the user. As soon as the debugDetective function returns control (or if debugDetective is VOID), the VM Emulator continues instruction evaluation normally, subject to the above trace rules.

debugDetective:

The user supplied debugDetective, in combination with the debugEval function, provide an enhancement to the standard Lisp debugging method, which is to insert writeln instructions at strategic locations in the code. Before the debugDectective function is called, the VM Emulator sets the gTP->DebugSuspended switch to ON so that instuction tracing is inactive until the debugDetective function returns control to the VM Emulator.

The activities of the debugDetective can include the traditional Lisp writeln instructions or they can be as complex and creative as the user supplied debugDetective function can manage.

Once the debugDetective function returns control to the VM Emulator, instruction tracing continues in the normal manner until the debugEval function retiurns control. Instruction tracing is ONLY active while inside the debugEval function when JitOFF is true.

The debugDetective function is called under three circumstances as follows:

;; Called by the debug & debugEval functions when the engine state is changed.

(debugDetective)

;; Called by the VM Emulator when a trace break has been requested.

(debugDetective Lambda CodeL Recursion Rv Av Tv Pv Cv Sv Iv void)

;; Called by the VM Emulator when an error has occured.

(debugDetective Lambda CodeL Recursion Rv Av Tv Pv Cv Sv Iv errMsg)

Usage

Syntax

Examples

Argument Types