<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html; charset=ISO-8859-1"
 http-equiv="content-type">
  <title>PDA Debugger Protocol Reference</title>
</head>
<body>

<h2>PDA Debugger Protocol Reference</h2>

<h3>clear</h3>
Clears any breakpoint set on given line
<pre>
   C: clear {line}
   R: ok
</pre>


<h3>data</h3>
Retrieves data stack information 
<pre>
   C: data {thread_id}
   R: {value 1}|{value 2}|{value 3}|...|
    
Errors:
   error: invalid thread
</pre>


<h3>drop</h3>
Returns from the current frame without executing the rest of instructions.  

<pre>
If VM running:
   C: drop {thread_id}
   R: ok
   E: resumed {thread_id} drop
   E: suspended {thread_id} drop
   
If VM suspended:
   C: drop {thread_id}
   R: ok
   E: vmresumed drop
   E: vmsuspended {thread_id} drop

Errors:
   error: invalid thread
</pre>


<h3>eval</h3>
Sets what events cause the execution to stop.

<pre>
   C: eval {thread_id} {instruction}%20{parameter}|{instruction}%20{parameter}|...
   R: ok
   E: resumed {thread_id} client
   E: evalresult result
   E: suspended {thread_id} eval
   
Errors:
   error: invalid thread
   error: cannot evaluate while vm is suspended
   error: thread running        
</pre>


<h3>eventstop</h3>
Sets what events cause the execution to stop.

<pre>
   C: eventstop {event_name} {0|1}
   R: ok
   ...
   E: suspended event {event_name}
</pre>


<h3>exit</h3>
Instructs the debugger to exit.

<pre>
   C: exit
   R: ok
</pre>


<h3>popdata</h3>
Pops the top value from the data stack  

<pre>
   C: popdata {thread_id}
   R: ok
   
Errors:
   error: invalid thread
</pre>


<h3>pushdata</h3>
Pushes the given value on top of the data stack.

<pre>
   C: pushdata {thread_id} {value}
   R: ok
   
Errors:
   error: invalid thread
</pre>


<h3>resume</h3>
Resumes the execution of a single thread.  Can be issued only if the virtual 
machine is running.

<pre>
   C: resume {thread_id}
   R: ok
   E: resumed {thread_id} client
   
Errors:
   error: invalid thread
   error: cannot resume thread when vm is suspended
   error: thread already running
</pre>


<h3>set</h3>
Sets a breakpoint at given line

<pre>
Suspend a single thread:
   C: set {line_number} 0
   R: ok
   C: resume {thread_id}
   E: resumed {thread_id} client
   E: suspended {thread_id} breakpoint line_number
   
Suspend the VM:
   C: set {line_number} 1
   R: ok
   C: vmresume
   E: vmresumed client
   E: vmsuspended {thread_id} breakpoint line_number
</pre>


<h3>setdata</h3>
Sets a data value in the data stack at the given location

<pre>
   C: setdata {thread_id} {index} {value}
   R: ok
   
Errors:
   error: invalid thread
</pre>


<h3>setvar</h3>
Sets a variable value 

<pre>
   C: setvar {thread_id} {frame_number} {variable} {value}
   R: ok
   
Errors:
   error: invalid thread
</pre>


<h3>stack</h3>
Retrieves command stack information 

<pre>
   C: stack {thread_id}
   R: {file}|{line}|{function}|{var_1}|{var_2}|...#{file}|{line}|{function}|{var_1}|{var_2}|...#...
   
Errors:
   error: invalid thread
</pre>


<h3>step</h3>
Executes next instruction 

<pre>
If VM running:
   C: step {thread_id}
   R: ok
   E: resumed {thread_id} client
   E: suspended {thread_id} step
   
If VM suspended:
   C: step {thread_id}
   R: ok
   E: vmresumed client
   E: vmsuspended {thread_id} step
   
Errors:
   error: invalid thread
</pre>


<h3>stepreturn</h3>
Executes instructions until the current subroutine is finished 

<pre>
If VM running:
   C: stepreturn {thread_id}
   R: ok
   E: resumed {thread_id} client
   E: suspended {thread_id} step
   
If VM suspended:
   C: stepreturn {thread_id}
   R: ok
   E: vmresumed client
   E: vmsuspended {thread_id} step
   
Errors:
   error: invalid thread
</pre>


<h3>suspend</h3>
Suspends execution of a single thread.  Can be issued only if the virtual 
machine is running.

<pre>
   C: suspend {thread_id}
   R: ok
   E: suspended {thread_id} client
   
Errors:
   error: invalid thread
      error: vm already suspended
   error: thread already suspended
</pre>

<h3>threads</h3>
Retrieves the list of active threads 

<pre>
   C: threads
   R: {thread id} {thread id} ...
</pre>

<h3>var</h3>
Retrieves variable value 

<pre>
   C: var  {thread_id} {frame_number} {variable_name}
   R: {variable_value}
   
Errors:
   error: invalid thread
   error: variable undefined
</pre>


<h3>watch</h3>
Sets a watchpoint on a given variable

<pre>
   C: watch {function}::{variable_name} {watch_operation}
   R: ok
   C: resume
   R: resumed client
   E: suspended watch {watch_operation} {function}::{variable_name}
</pre>

The <code>watch_operation<code> value can be:
<ul>
  <li>0 - no watch</li>
  <li>1 - read watch</li>
  <li>2 - write watch</li>
  <li>3 - both, etc.</li>
</ul>


<h3>vmresume</h3>
Resumes the execution of the whole virtual machine  
 
<pre>
   C: vmresume
   R: ok
   E: vmresumed client
   
Errors:
   error: vm already running
</pre>

<h3>vmsuspend</h3>
Suspends the execution of the whole virtual machine 

<pre>
   C: vmsuspend
   R: ok
   E: vmsuspended client
   
Errors:
   error: thread already suspended
</pre>
</body>

</html>