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)