jtag.h

avrrice软件用于AVR单片机的JTAG调试.

// A generic error message when nothing good comes to mind
#define JTAG_CAUSE "JTAG ICE communication failed"

// The file descriptor used while talking to the JTAG ICE
extern int jtagBox;

// Whether we are in "programming mode" (changes how program memory
// is written, apparently)
extern bool programmingEnabled;

// Name of the device controlled by the JTAG ICE
extern char *device_name;

// Basic JTAG I/O
// -------------

/** If status < 0: Report JTAG ICE communication error & exit **/
void jtagCheck(int status);

/** Initialise the serial port specified by jtagDeviceName for JTAG ICE access
 **/
void initJtagPort(char *jtagDeviceName);

/** A timed-out read from file descriptor 'fd'.

    'timeout' is in microseconds, it is the maximum interval within which
    the read must make progress (i.e., it's a per-byte timeout)

    Returns the number of bytes read or -1 for errors other than timeout.

    Note: EOF and timeout cannot be distinguished
**/
int timeout_read(int fd, void *buf, size_t count, unsigned long timeout);

/** Decode 3-byte big-endian address **/
unsigned long decodeAddress(uchar *buffer);

/** Encode 3-byte big-endian address **/
void encodeAddress(uchar *buffer, unsigned long x);

/** Send a command to the jtag, with retries, and return the 'responseSize' 
    byte response. Aborts avarice in case of to many failed retries.

    Returns a dynamically allocated buffer containing the reponse (caller
    must free)
**/
uchar *doJtagCommand(uchar *command, int  commandSize, int responseSize);

/** Simplified form of doJtagCommand:
    Send 1-byte command 'cmd' to JTAG ICE, with retries, expecting a 
    'responseSize' byte reponse.

    Return true if responseSize is 0 or if last response byte is
    JTAG_R_OK
**/
bool doSimpleJtagCommand(uchar cmd, int responseSize);

/** Send initial configuration to setup the JTAG box itself. 
 **/
void initJtagBox(void);

/**
    Send initial configuration to the JTAG box when starting a new
    debug session.  (Note: when attaching to a running target, fuse
    bits cannot be set so debugging must have been enabled earlier)

    The bitrate sets the JTAG bitrate. The bitrate must be less than
    1/4 that of the target avr frequency or the jtagice will have
    problems reading from the target. The problems are usually
    manifested as failed calls to jtagRead().
**/
void initJtagOnChipDebugging(uchar bitrate);


// Breakpoints
// -----------

enum bpType
{
    NONE,           // disabled.
    CODE,           // normal code space breakpoint.
    WRITE_DATA,     // write data space breakpoint (ie "watch").
    READ_DATA,      // read data space breakpoint (ie "watch").
    ACCESS_DATA,    // read/write data space breakpoint (ie "watch").
};

/** Clear out the breakpoints. */
void deleteAllBreakpoints(void);

/** Delete breakpoint at the specified address. */
bool deleteBreakpoint(unsigned int address, bpType type, unsigned int length);

/** Add a code breakpoint at the specified address. */
bool addBreakpoint(unsigned int address, bpType type, unsigned int length);

/** Send the breakpoint details down to the JTAG box. */
void updateBreakpoints(bool setCodeBreakpoints);

/** True if there is a breakpoint at address */
bool codeBreakpointAt(unsigned int address);

/** True if there is a breakpoint between start (inclusive) and 
    end (exclusive) */
bool codeBreakpointBetween(unsigned int start, unsigned int end);

bool stopAt(unsigned int address);

// Miscellaneous
// -------------

/** Set JTAG ICE parameter 'item' to 'newValue' **/
void setJtagParameter(uchar item, uchar newValue);

/** Return value of JTAG ICE parameter 'item' **/
uchar getJtagParameter(uchar item);

// Writing to program memory
// -------------------------

/** Switch to faster programming mode, allows chip erase */
void enableProgramming(void);

/** Switch back to normal programming mode **/
void disableProgramming(void);

/** Erase all chip memory **/
void eraseProgramMemory(void);

/** Download an image contained in the specified file. */
void downloadToTarget(const char* filename, bool program, bool verify);

// Running, single stepping, etc
// -----------------------------

/** Retrieve the current Program Counter value, or PC_INVALID if fails */
unsigned long getProgramCounter(void);

/** Set program counter to 'pc'. Return true iff successful **/
bool setProgramCounter(unsigned long pc);

/** Reset AVR. Return true iff successful **/
bool resetProgram(void);

/** Interrupt AVR. Return true iff successful **/
bool interruptProgram(void);

/** Resume program execution. Return true iff successful.
    Note: the gdb 'continue' command is handled by jtagContinue,
    this is just the low level command to resume after interruptProgram
**/
bool resumeProgram(void);

/** Issue a "single step" command to the JTAG box. 
    Return true iff successful **/
bool jtagSingleStep(void);

/** Send the program on it's merry way, and wait for a breakpoint or
    input from gdb.
    Return true for a breakpoint, false for gdb input. **/
bool jtagContinue(bool setCodeBreakpoints);

// R/W memory
// ----------

/** Read 'numBytes' from target memory address 'addr'.

    The memory space is selected by the high order bits of 'addr' (see
    above).

    Returns a dynamically allocated buffer with the requested bytes if
    successful (caller must free), or NULL if the read failed.
 **/
uchar *jtagRead(unsigned long addr, unsigned int numBytes);

/** Write 'numBytes' bytes from 'buffer' to target memory address 'addr'

    The memory space is selected by the high order bits of 'addr' (see
    above).

    Returns true for a successful write, false for a failed one.

    Note: The current behaviour for program-space writes is pretty
    weird (does not match jtagRead). See comments in jtagrw.cc.
**/
bool jtagWrite(unsigned long addr, unsigned int numBytes, uchar buffer[]);


/** Write fuses to target.

    The input parameter is a string from command-line, as produced by
    printf("%x", 0xaabbcc );
**/
void jtagWriteFuses(char *fuses);


/** Read fuses from target.

    Shows extended, high and low fuse byte.
*/
void jtagReadFuses(void);


/** Display fuses.

    Shows extended, high and low fuse byte.
*/
void jtagDisplayFuses(uchar *fuseBits);


/** Write lockbits to target.

    The input parameter is a string from command-line, as produced by
    printf("%x", 0xaa);
**/
void jtagWriteLockBits(char *lock);


/** Read the lock bits from the target and display them.
**/
void jtagReadLockBits(void);


/** Display lockbits.

    Shows raw value and individual bits.
**/
void jtagDisplayLockBits(uchar *lockBits);


#endif