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)