==== Open On-Chip Debugger (openOCD) ====


=== Install openOCD ===


== Download Debian Package ==

First and recommended way to get openOCD is to install the debian package. 

<code>
sudo apt-get install openocd
</code>

== Build it yourself ==

If you need the newest version of openOCD you should build the source yourself.
Download Source from sourceforge page:

<code>
git clone git://git.code.sf.net/p/openocd/code openocd-code
</code>

Install the libusb-1.0 package

<code>
sudo apt-get install libusb-1.0-0-dev
./bootstrap
./configure --prefix=$HOME/site
make
make install
</code>

Add the file /etc/udev/rules.d/52-flyswatter.rules. This will make the usb device accessible without root permissions.

<code>
# Flyswatter JTAG Debugger
SUBSYSTEMS=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", MODE="0666"
</code>

later more....


=== How to use openOCD ===

First of all, you should download the official openOCD User's Guide:


[[http://openocd.sourceforge.net/doc/pdf/openocd.pdf]]

You can find there actually all information you need, but I will give you a quickstart guide here.

You can use openOCD with various hardware, so you have to tell openOCD which one you are actually using. This is done with some special Configuration Files. Overall you need three of these files:

  * interface config file: Descripes which hardware debugger you are using
  * board config file: Descripes which kind of board you are using
  * target config files: Descripes which microcontroller you are using

You can find a lot of configuration files for specific hardware there:


<code>
cd /usr/share/openocd/scripts
</code>

Here are the interface config files (e.g. jlink.cfg)

<code>
ls interface
</code>

Here are the board config files (e.g. pic-p32mx.cfg)

<code>
ls board
</code>

Here are the target config files (e.g. pic32mx.cfg)

<code>
ls target
</code>

Now you have to find the right config files for your devices.
If you don't find the config file for your device, you should have a look
into the official OpenOCD User's Guide. There are many design rules for these files.

If you had find suitable files for your hardware you can start programming the flash of your target.

<code>
openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg -c "program filename.elf verify reset"
</code>

If you get the error that there is no maximum adapter speed specified you can add to your interface config file the following statement.

<code>
adapter_khz 1000
</code>

verify and reset are optional parameters, for verifying the flash after programming and reseting the hardware.

filename.elf is the excecutable, which should be cross-compiled for the target hardware.

Now, the board should allready execute your program.


== Set up server for debugging ==

If you start the Open On-Chip Debugger without a "program" command, it generates a local server on port 4444 for telnet communication.

<code>
openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
</code>

Connect to localhost with telnet.

<code>
telnet localhost 4444
</code>


Now you can use JTAG Commands for Debugging your hardware.

Halt program:

<code>
halt
</code>

You can step through your program

<code>
step
</code>

and resume your program.

<code>
resume
</code>

You also can reset the hardware

<code>
reset
</code>

and halt the hardware after a reset.

<code>
reset halt
</code>


If CPU is halted you can show all available registers

<code>
reg
</code>

Show one specific register

<code>
reg [NAME]
</code>

and override the value of the register.

<code>
reg [NAME] [VALUE]
</code>



=== Debugging with gdb ===

If you want to debug your hardware more comfortable you are able to use gdb.
You should use the gdb provided by your Toolchain. For example mipsel-none-elf-gdb for a MIPS architecture.

<code>
mipsel-none-elf-gdb main.elf
</code>


Connect to the gdbserver on the local pc using port 3333.

<code>
(gdb) target remote localhost:3333
</code>

Send commands to gdbserver using the monitor command

<code>
(gdb) monitor reset halt
</code>

Now the hardware performs a reset and halts directly. You can use gdb as normal:

You can list the source code:

<code>
(gdb) list
</code>

Set breakpoints (e.g. at line 27)

<code>
(gdb) br 27
</code>

Run the program until the next breakpoint occurs.

<code>
(gdb) continue
</code>

Walk step by step through your source code

<code>
(gdb) next
</code>

or print variable content

<code>
(gdb) print [var]
</code>