===============================================================
                   Introduction
===============================================================

DbgPlus plugin is a plugin that allows you to issue debugging commands through a command-line interface.

This plugin provides you:
- a command-line interface for debugging
- additional IDC debugging extensions
- an additional command scripting engine (backed by COMPEL)

The plugin should work with most of IDA's debugger plugins and remote debuggers.
However, there are some commands that are specific to Windows/x86.

Please report your comments, bug discoveries or suggestions to <lallousx86@yahoo.com>

===============================================================
                   Installation
===============================================================

- Copy "compel_lib.dll" to %windir%\system32\
- Copy "dbgplus.plw" to %ida%\plugins\

Use ALT+Z to show the plugin.
Type "help" or read this document to get started.


===============================================================
                   Command line dialog help
===============================================================

The command line dialog is made of two components:
- Display window
- Command combobox

The dialog saves its settings in the following location:
  HKEY_CURRENT_USER\Software\Datarescue\IDA\Plugins\DbgPlus

It stores:
 - The dialog's dimension and position
 - Color
 - Pass to IDA keys
 - Autoexec COMPEL script

When the plugin first initializes, it runs the autoexec script if specified in "AutoexecScript" key.

Display window
------------------
* You may double click on a string to have it selected.
When you right-click on a selected string you will have it copied to the clipboard and pasted in the command box.

* If you try to type in the display window the characters will be passed to the command window

* You may configure the display color.
To do so, you have to edit the "DisplayColors" key and adjust the values: 0,65280
These are the background and foreground colors comma separated.

Command combobox
-------------------
* You may type here any sort of registered commands and any other command accepted by COMPEL scripting engine
* There are keys when pressed, are passed to IDA.
The default set of keys passed to IDA are: F2,F4,F7,F8,F9.
To add more keys you have to adjust the registry string:
PassToKeys = 0x76,0x77,0x78,0x71,0x73
This string contain a list of comma separated VK_xxx values
* The last executed command is registered under $lastcmd variable

===============================================================
                   Command line commands reference
===============================================================

help
------
Display help for a command or all commands.

Syntax: help [cmd_name]

Note: The display will be of the form: CMD [N, M] where N is the least param and M is the most param value.
If M or N are ZERO then this means no min or max arguments.

cls
----
Clears the display screen

echo
-----
Displays a message.

You may use it to view COMPEL's variables.
Example:
echo "bp0 is @" $bp0

bl
----
Shows breakpoints list, breakpoint condition and hit count

?
---
Evaluates an expression and returns an EA

.
----
Sets the current view to the instruction pointer register.

fkey
--------
Binds a COMPEL command to a function key (F1..F12)

Syntax:
  FKEY
  FKEY F_KEY COMPEL_COMMAND

Example:
  fkey F1 idc Message("I love you all!"); <- uses the "idc" command to issue an IDC command when F1 is pressed
  fkey F3 echo "Hello from Compel" <- uses "echo" command to display a message

Example 2:
  :fkey <- we typed this command and we see the output below:
  
  F1: idc Message("Hello from IDC!");
  F3: echo Hello from Compel

Now when you're in command box, press any of the hotkeys and see what happens!


set
----
Sets the value of a COMPEL value from IDC expression

Syntax: 
  set &$VARNAME EXPR

Example:
  var $temp <- create a variable
  set &$temp EIP <- set the value of $temp to EIP
  echo "temp=" $temp

history
--------
Displays all the commands previously executed

bc
---
Clears a breakpoint or all breakpoints of '*' was passed

Syntax: bc [NUM|*] [NUM] [NUM] ...

be
---
Enable breakpoint or all breakpoints of '*' was passed
Syntax: be [NUM|*] [NUM] [NUM] ...

bd
---
Disable breakpoint(s) or all breakpoints of '*' was passed

Syntax: bd [NUM|*] [NUM] [NUM] ...

bpx
----

Creates a software execution breakpoint
When a breakpoint is registered, a COMPEL variable is registered as: $bp{bpno}

Syntax: bpx addr [idc condition]
Example:
  bpx addr <- suppose the index returned was 5
  bpx addr eax == 3 <- creates a bpt with a condition
Now we have a COMPEL variable $bp5 which can be used in other commands that accepts expressions, example:
  u $bp5
Or:
  ? $bp5 + $bp1 / $bp1

pinfo
------
Show process' information or modules if called with 'module' param

d
---
Hex dumps memory contents
Syntax: d [addr] [count_in_bytes]

Example:
  d start 16 <- displays 'start' 16 bytes
  d <- displays 'start'+16 16 bytes

e
---
Writes bytes to memory address
Syntax: e addr byte1 [byte2] [byte3] ... [byteN]

dbginfo
--------

Shows the active debugger's plugin information

seh
----
Shows SEH registrations records for current or a given thread id

Syntax: seh [tid]

thread
-------

Displays a list of avail threads

Syntax: thread [tid]

u
--
Sets IDA View to the passed address

Syntax: u addr

r
---
Get/Set register(s) value(s)

Syntax:
  r [regname] [regvalue]
  r -> shows all registers
  r regname -> displays register value
  r regname regvalue -> update register's value

gle
----
Returns the thread's GetLastError() value

Syntax: gle [tid]

clsmessages
------------

Clears IDA's messages window.

idc
----

Uses IDC scripting engine to execute a line.

Example:
  idc Message("Hello world");


compelscript
-------------
Loads and executes a COMPEL script

Syntax: compelscript [script_file_name]

Example:
  compelscript c:\myscript.compel <- loads a script from a file
  compelscript <- loads a script from lines

===============================================================
                   IDC scripts extensions
===============================================================

compel_eval(cmd)
---------------------------

When you use this command, it will be executed as if it was typed from the command line plugin

Example: 
  // IDC will use COMPEL to add a new BPT.
  compel_eval("bpx start");

  // Display a message
  compel_eval("echo hello world!");

compel_tok_init(str, delim)
------------------------------
Tokenizes a string and returns a tokenizer handle.
Use that handler in subsequent calls and make sure you free it.

compel_tok_free(tok_handle)
-----------------------------
Frees the tokenizer handle.
You better call this function or you will be leaking memory

compel_tok_get(tok_handle, idx)
--------------------------
Returns the string at the given index.

compel_tok_count(tok_handle)
------------------------------
Returns the count of tokenized strings


Example:
  auto tok, cnt, i, s;

  tok = compel_tok_init("hello world", " ");
  cnt = compel_tok_count(tok);
  for (i=0;i<cnt;i++)
  {
    s = compel_tok_get(tok, i);
    Message("%d = %s\n", i, s);
  }
  compel_tok_free(tok);


bpt_bpx(addr)
-------------

Adds a BPX at the given address and returns the bpt number or -1 if error

Example:
  auto n;
  n = bpt_bpx("start");

bpt_bc(bptno)
---------------
Deletes a bpt by number.

Returns boolean.

bpt_getea(bptno)
------------------
Returns the EA associated with the given bptno

Example:  
  Message("bp0 @ %08X\n", bpt_getea(0));


bpt_bd(bptno)
--------------

Disables the breakpoint by number

bpt_blist(start_no)
----------------------
Starts enumerating breakpoints.

You should pass it -1 when you start enumerating, it returns the next index.

Example:

  auto x;

  x = -1;
  for (;;)
  {
    x = bpt_blist(x);
    if (x == -1)
      break;
    Message("bp%d @ %x\n", x, bpt_getea(x));
  }

bpt_be(bptno)
---------------
Enable a breakpoint

dbg_gettid()
--------------
Returns the current thread id or ZERO

dbg_gettib(tid)
------------------
Returns the TIB address of the given TID

===============================================================
                   COMPEL - Basic Reference
===============================================================

COMPEL is a simple command based language.

variable creation
---------------------
var $varname "any value"
echo "var value is:" $varname

command aliasing
--------------------
alias help h

what can I put in autoexec script?
-------------------------------------
* You may put a series of aliasing commands, such as:
alias HELP H
alias skipins s

* You may put key bindings:
fkey F10 skipins

More help
------------

Refer to the distribution of console based version of the COMPEL scripting engine.
Reading the provided examples will give you a fast overview of what you can do and what you can't.