NAME

       ice-gdb - JTAG ICE frontend for avr-gdb
       ice-insight - JTAG ICE frontend for avr-insight

SYNOPSIS

       ice-gdb/ice-insight [--debugger debugger] [--capture] [--ignore-intr] [--external] [gdb_arguments]

DESCRIPTION

       ice-gdb  (respectively  ice-insight)  starts avr-gdb (respectively avr-insight) and avarice to do on-chip
       debugging on Atmel AVR processors using their JTAG-based on-chip debug facilities, via the Atmel JTAG ICE
       pod.

       The  executable for the program being debugged is downloaded to the processor unless the --capture option
       is specified. A number of extra commands are available within gdb when started, see their description  in
       NEW  GDB  COMMANDS below. Restrictions on debugging with the JTAG ICE pod are discussed in more detail in
       DEBUGGING WITH JTAG ICE below.

       The arguments passed to avarice include the value of  the  AVARICE_ARGS  environment  variable.  This  is
       typically  used to specify the serial port to which the JTAG ICE pod is connected by setting AVARICE_ARGS
       to "-j <serial port name>".

OPTIONS

       --debugger debugger_command
              Specify a different debugger than avr-gdb (or avr-insight).  This  other  debugger  should  behave
              similarly to gdb.

       --capture
              Don't  download  the executable being debugged to the mote, just interrupt the current program and
              assume that it matches the executable passed to ice-gdb.  This is  similar  to  "attaching"  to  a
              running program within gdb.

       --ignore-intr
              Pass  the --ignore-intr option to avarice.  The single-step commands in gdb (s, n) will then "step
              over" interrupt handlers (i.e., if an interrupt occurs, execution will resume for the duration  of
              the interrupt).

       --external
              Do  not  start avarice.  Instead, avr-gdb will attempt to connect to an already running avarice on
              port localhost:6423.

NEW GDB COMMANDS

       ice-restart
              Restart avarice.

       ice-load filename
              Download executable filename to the Atmel processor and start debugging it (this replaces the  gdb
              load command).

       target-ice
              Connect to a copy of avarice running on port localhost:6423.

DEBUGGING WITH JTAG ICE

       The JTAG ICE debugging environment has a few restrictions and changes:

       •   No  "soft"  breakpoints,  and  only  three  hardware  breakpoints.  The  break  command sets hardware
           breakpoints. The easiest way to deal with this restriction is to enable and  disable  breakpoints  as
           needed.

       •   Two 1-byte hardware watchpoints (but each hardware watchpoint takes away one hardware breakpoint). If
           you set a watchpoint on a variable which takes more than one byte, execution will be abysmally  slow.
           Instead it is better to do the following:

             watch *(char *)&myvariable

           which watches the least significant byte of myvariable.

       •   The  Atmel  AVR processors have a Harvard architecture (separate code and data buses). To distinguish
           data address 0 from code address 0, avr-gdb adds 0x800000 to all data addresses. Bear  this  in  mind
           when examining printed pointers, or when passing absolute addresses to gdb commands.

ENVIRONMENT

       AVARICE_ARGS
              Extra arguments to pass to avarice at startup.

SEE ALSO

       gdb(1), insight(1).

BUGS

       On  Windows,  the  ice-gdb and ice-insight commands only work in the cygwin environment. They do not work
       with the mingw environment.

                                                 August 22, 2003                                      ice-gdb(1)