embedded debugger-based tools protocols user's...

EDBG-based Tools Protocols Embedded Debugger-Based Tools Protocols User's Guide

2017 Microchip Technology Inc. User Guide DS50002630A-page 1

Table of Contents

1. Preface...................................................................................................................... 7

2. Introduction................................................................................................................82.1. EDBG Interface Overview............................................................................................................ 82.2. EDBG-based Tool Implementations............................................................................................. 8

3. CMSIS-DAP.............................................................................................................103.1. CMSIS-DAP Protocol................................................................................................................. 103.2. CMSIS-DAP Vendor Commands................................................................................................10

3.2.1. AVR-target Specific Vendor Commands......................................................................103.2.2. ARM-target Specific Vendor Commands.....................................................................133.2.3. EDBG-specific Vendor Commands..............................................................................13

3.3. Serial Trace Commands.............................................................................................................153.3.1. Set Transport Mode..................................................................................................... 153.3.2. Set Capture Mode........................................................................................................153.3.3. Set Baud Rate............................................................................................................. 163.3.4. Start............................................................................................................................. 163.3.5. Stop............................................................................................................................. 173.3.6. Get Data...................................................................................................................... 173.3.7. Get Status....................................................................................................................183.3.8. Get Buffer Size............................................................................................................ 183.3.9. Signon..........................................................................................................................19

3.4. Data Polling Service...................................................................................................................193.4.1. Data Sampler Disable..................................................................................................203.4.2. SAM Data Sampler Enable..........................................................................................203.4.3. SAM Data Sampler Disable.........................................................................................213.4.4. SAM PC Sampler.........................................................................................................223.4.5. AVR OCD Message Sampler.......................................................................................223.4.6. SAM Printf Queue Sampler......................................................................................... 233.4.7. SAM DCC Sampler......................................................................................................243.4.8. AVR PC Sampler......................................................................................................... 253.4.9. AVR SP Sampler......................................................................................................... 253.4.10. AVR Data Sampler Enable.......................................................................................... 263.4.11. AVR Data Sampler Disable..........................................................................................273.4.12. AVR Printf Queue Sampler.......................................................................................... 28

4. EDBG Control Protocol............................................................................................304.1. Protocol Commands...................................................................................................................30

4.1.1. QUERY........................................................................................................................ 304.1.2. SET..............................................................................................................................304.1.3. GET............................................................................................................................. 31

4.2. Responses................................................................................................................................. 324.2.1. OK................................................................................................................................324.2.2. LIST............................................................................................................................. 324.2.3. DATA............................................................................................................................32

EDBG-based Tools Protocols


4.2.4. FAILED........................................................................................................................ 324.3. EDBGCTRL ID Definitions......................................................................................................... 33

5. AVR Communication Protocol................................................................................. 365.1. Overview.................................................................................................................................... 365.2. Framing...................................................................................................................................... 365.3. Protocol Sub-set Overview.........................................................................................................375.4. Discovery Protocol Definition..................................................................................................... 37

5.4.1. CMD: QUERY..............................................................................................................375.4.2. Discovery QUERY Contexts........................................................................................ 385.4.3. RSP: LIST....................................................................................................................385.4.4. RSP: FAILED...............................................................................................................385.4.5. Discovery Protocol ID Definitions................................................................................ 38

5.5. Housekeeping Protocol.............................................................................................................. 395.5.1. CMD: QUERY..............................................................................................................395.5.2. Housekeeping QUERY Contexts.................................................................................395.5.3. CMD: SET....................................................................................................................395.5.4. CMD: GET................................................................................................................... 405.5.5. Housekeeping SET/GET Parameters..........................................................................405.5.6. Housekeeping Commands.......................................................................................... 415.5.7. Housekeeping Responses...........................................................................................425.5.8. Events..........................................................................................................................435.5.9. Hints and Tips .............................................................................................................445.5.10. Housekeeping ID Definitions....................................................................................... 44

6. AVR32 Generic Protocol..........................................................................................476.1. Protocol Commands...................................................................................................................47

6.1.1. QUERY........................................................................................................................ 476.1.2. SET..............................................................................................................................476.1.3. GET............................................................................................................................. 486.1.4. Activate Physical..........................................................................................................506.1.5. Deactivate Physical..................................................................................................... 506.1.6. Get ID.......................................................................................................................... 506.1.7. Erase........................................................................................................................... 516.1.8. Halt.............................................................................................................................. 516.1.9. Reset........................................................................................................................... 516.1.10. Step............................................................................................................................. 526.1.11. Read............................................................................................................................ 526.1.12. Write............................................................................................................................ 526.1.13. TAP.............................................................................................................................. 536.1.14. Is Protected..................................................................................................................546.1.15. Erase Section.............................................................................................................. 54

6.2. Responses................................................................................................................................. 556.2.1. OK................................................................................................................................556.2.2. LIST............................................................................................................................. 556.2.3. ID................................................................................................................................. 556.2.4. PC................................................................................................................................556.2.5. DATA............................................................................................................................566.2.6. FAILED........................................................................................................................ 56



6.3. Hints and Tips.............................................................................................................................566.3.1. Configuration............................................................................................................... 566.3.2. Activate and Deactivate Physical.................................................................................576.3.3. Programming and Debugging Commands.................................................................. 57

6.4. AVR32GENERIC ID Definitions................................................................................................. 57

7. AVR8 Generic Protocol............................................................................................607.1. Protocol Commands...................................................................................................................60

7.1.1. QUERY........................................................................................................................ 607.1.2. SET..............................................................................................................................607.1.3. GET............................................................................................................................. 617.1.4. Activate Physical..........................................................................................................657.1.5. Deactivate Physical..................................................................................................... 667.1.6. Get ID.......................................................................................................................... 667.1.7. Attach...........................................................................................................................667.1.8. Detach......................................................................................................................... 677.1.9. Reset........................................................................................................................... 677.1.10. Stop............................................................................................................................. 677.1.11. Run.............................................................................................................................. 687.1.12. Run To......................................................................................................................... 687.1.13. Step............................................................................................................................. 687.1.14. PC Read...................................................................................................................... 697.1.15. PC Write...................................................................................................................... 697.1.16. Prog Mode Enter..........................................................................................................697.1.17. Prog Mode Leave........................................................................................................ 707.1.18. Disable debugWIRE.................................................................................................... 707.1.19. Erase........................................................................................................................... 707.1.20. CRC.............................................................................................................................717.1.21. Memory Read.............................................................................................................. 727.1.22. Memory Read Masked.................................................................................................727.1.23. Memory Write.............................................................................................................. 727.1.24. Page Erase..................................................................................................................737.1.25. Hardware Breakpoint Set.............................................................................................737.1.26. Hardware Breakpoint Clear......................................................................................... 747.1.27. Software Breakpoint Set..............................................................................................747.1.28. Software Breakpoint Clear...........................................................................................757.1.29. Software Breakpoint Clear All......................................................................................75

7.2. Responses................................................................................................................................. 757.2.1. OK................................................................................................................................757.2.2. LIST............................................................................................................................. 767.2.3. PC................................................................................................................................767.2.4. DATA............................................................................................................................767.2.5. FAILED........................................................................................................................ 76

7.3. Events........................................................................................................................................ 777.3.1. Event: Break................................................................................................................ 777.3.2. Event: IDR Message....................................................................................................77

7.4. Memory Types............................................................................................................................777.4.1. debugWIRE memtypes................................................................................................777.4.2. megaAVR (JTAG) OCD memtypes..............................................................................79



7.4.3. AVR XMEGA memtypes.............................................................................................. 817.4.4. AVR devices with UPDI memtypes..............................................................................84

7.5. Hints and Tips.............................................................................................................................867.5.1. Configuration............................................................................................................... 867.5.2. Activate and Deactivate Physical.................................................................................877.5.3. Programming Session Control.....................................................................................877.5.4. Debug Session Control................................................................................................877.5.5. Flow Control.................................................................................................................887.5.6. Memory/OCD Access.................................................................................................. 88

7.6. AVR8GENERIC ID Definitions................................................................................................... 88

8. AVR ISP Protocol.....................................................................................................928.1. SPI Programming Protocol Commands..................................................................................... 92

8.1.1. SPI Load Address........................................................................................................928.1.2. SPI Set Baud............................................................................................................... 928.1.3. SPI Get Baud...............................................................................................................938.1.4. SPI Enter Programming Mode.....................................................................................938.1.5. SPI Leave Programming Mode....................................................................................948.1.6. SPI Chip Erase............................................................................................................ 948.1.7. SPI Program Flash...................................................................................................... 958.1.8. SPI Read Flash............................................................................................................968.1.9. SPI Program EEPROM................................................................................................978.1.10. SPI Read EEPROM.....................................................................................................978.1.11. SPI Program Fuse....................................................................................................... 978.1.12. SPI Read Fuse............................................................................................................ 978.1.13. SPI Program Lock........................................................................................................988.1.14. SPI Read Lock.............................................................................................................988.1.15. SPI Read Signature.....................................................................................................988.1.16. SPI Read OSCCAL......................................................................................................988.1.17. SPI Multi...................................................................................................................... 98

8.2. SPI Programming Protocol Responses......................................................................................998.3. ID Definitions..............................................................................................................................99

9. TPI Protocol...........................................................................................................1019.1. TPI Protocol Commands.......................................................................................................... 101

9.1.1. TPI Enter Programming Mode...................................................................................1019.1.2. TPI Leave Programming Mode..................................................................................1019.1.3. TPI Set Parameter.....................................................................................................1029.1.4. TPI Erase...................................................................................................................1029.1.5. TPI Write Memory......................................................................................................1039.1.6. TPI Read Memory......................................................................................................103

9.2. TPI Programming Protocol Responses....................................................................................1049.3. ID Definitions............................................................................................................................104

10. Document Revisions..............................................................................................106

The Microchip Web Site.............................................................................................. 107

Customer Change Notification Service........................................................................107



Customer Support....................................................................................................... 107

Microchip Devices Code Protection Feature............................................................... 107

Legal Notice.................................................................................................................108

Trademarks................................................................................................................. 108

Quality Management System Certified by DNV...........................................................109

Worldwide Sales and Service...................................................................................... 110



1. PrefaceThe Embedded Debugger (EDBG) offers on-board programming and debugging support to all Microchipkits in which it is embedded.

EDBG is supported natively in Atmel Studio.

This documentation provides details on the EDBG communication protocol, and is intended for advancedusers who want to develop their own software components, which interact with EDBG and otherMicrochip tools based on EDBG.

The protocol defined here is to be used at your own risk. Not all EDBG commands are documented here.Errors or questions can be addressed to [email protected].

Although efforts will be made to keep the contents of this document accurate, Microchip reserves the rightto change or extend the protocol without prior notice.



mailto:[email protected]

2. Introduction

2.1 EDBG Interface OverviewThe Embedded Debugger (EDBG) implements a composite USB device consisting of three interfaces:

Programming and debugging interface (HID) CDC Virtual COM port Atmel Data Gateway Interface

The programming and debugging interface is an implementation of the CMSIS-DAP interface defined byKeil. CMSIS-DAP supports access to any ARM Coresight Debug Access Port. CMSIS-DAP supports aset of "vendor" commands, which are used by EDBG for accessing special functions not nativelysupported by CMSIS-DAP, as well as for debugging and programming AVR device families.

The CDC Virtual COM port implementation provides a simple link between a COM port registered on thehost PC and a RX-TX pin pair on the EDBG. This pair is connected to a UART pin pair on the board onwhich the EDBG is embedded.

The DGI is a bidirectional interface for streaming data to and from the EDBG. It is a custom interface withinput and output BULK endpoints. The DGI protocol is specified in a separate document.

Note: mEDBG is a scaled-down EDBG implementation and does not support the DGI.

Note: EDBGC does not include DGI support.

2.2 EDBG-based Tool ImplementationsThe protocol-set described in this document is intended for use on EDBG platforms as well as standalonedebuggers. The JTAGICE3 firmware version 3 upgrades that tool to support Cortex-M based SAMdevices, and implements parts of the protocol-set described here. EDBG implementations are very limitedsubsets of this protocol, which support the particular Microchip controller mounted on that board.

Table 2-1.EDBG-based Tool Implementations

Tool USB PID Supports Notes

EDBG 0x2111 Only the Microchip device mounted on that board.

CDC Virtual COM port and Atmel Data Gateway Interfacesupport varies between different kits.

As used onXplained Proboards

EDBGC 0x216A Only the Microchip device mounted on that board.

CDC Virtual COM port

Commerciallyavailable EDBG forthird-party use.

mEDBG 0x2145 Only the Microchip device mounted on that board.

CDC Virtual COM port.

As used onXplained Miniboards

JTAGICE3 0x2140 Programming of all AVR devices using SPI, PDI, UPDI,JTAG, and aWire.

FW version 3 andlater



Tool USB PID Supports Notes

Debugging of all AVR devices with on-chip debugcapability using debugWIRE, PDI, UPDI, JTAG, andaWire.

Programming and debugging of all ARM Cortex-M basedSAM devices using SWD and JTAG.

Atmel-ICE 0x2141 Programming of all AVR devices using SPI, TPI, PDI,UPDI, JTAG, and aWire.



PowerDebugger

0x2144 Programming of all AVR devices using SPI, TPI, PDI,UPDI, JTAG, and aWire.



Atmel Data Gateway Interface support for Powermeasurements, SPI, USART, TWI, and GPIO.

CDC Virtual COM port.

Note: The capability of each implementation should be queried from the tool itself rather than basedupon the lists here.

JTAGICE3 (FW version 2 and earlier) implements a custom USB interface, which is no longer supported.



3. CMSIS-DAP

3.1 CMSIS-DAP ProtocolThe CMSIS-DAP protocol belongs to ARM. Further information can be found at Keil.

3.2 CMSIS-DAP Vendor CommandsThe CMSIS-DAP protocol contains a section of "vendor commands", which are free to use for performingspecial functions. This section defines the vendor commands used by EDBG-based tools.

A summary of vendor commands is given here:

Table 3-1.Vendor Command Summary

ID value Command Usage Description

0x80 AVR_CMD AVR Enveloped AVR protocol command

0x81 AVR_RSP AVR Enveloped AVR protocol response poll

0x82 AVR_EVT AVR Enveloped AVR protocol event poll

0x83 GET_CONFIG EDBG Retrieve EDBG board configuration

0x84 SET_CONFIG EDBG Set EDBG board configuration (only on HHB suffixed parts)

0x85 RESET ARM Perform custom reset sequence

0x86 ERASE_PIN ARM/EDBG Control the erase pin

0x87 SERIAL_TRACE ARM Serial trace capture commands

0x88 GET_REQUEST EDBG Enveloped EDBG GET command

0x89 SET_REQUEST EDBG Enveloped EDBG SET command

0x8A DATA_POLLING ALL Configure data polling service

3.2.1 AVR-target Specific Vendor CommandsTable 3-2.AVR Vendor-commands

Command ID value Description

AVR_CMD 0x80 Send enveloped AVR-specific protocol command

AVR_RSP 0x81 Retrieve (poll for) enveloped AVR-specific protocol response

AVR_EVT 0x82 Poll for enveloped AVR-specific protocol event

3.2.1.1 Enveloped AVR Commands, Responses, and EventsIn order to support programing and debugging AVR devices over the same interface as ARM-baseddevices, three vendor commands are used. Commands are send using the AVR_CMD vendor command.All commands are synchronous and result in one and only one response. The response is, however,buffered on the tool and must be polled for using the AVR_RSP vendor command. Events occurasynchronously to commands, and must be periodically polled for using the AVR_EVT vendor command.

The AVR command set is described in AVR Communication Protocol.



http://www.keil.com/support/man/docs/dapdebug/

Wrapping AVR CommandsSo to SEND an AVR command to the EDBG, it is wrapped as:

Table 3-3.AVR_CMD Command

Field Size Description

AVR_CMD 1 byte 0x80

FragmentInfo 1 byte Fragment number

Size 2 bytes, MSB first Number of bytes in the wrapped AVR packet

CommandPacket N bytes Enveloped AVR packet

Large packets must be chopped up according to the HID interfaces REPORT_SIZE. The fragmentnumber envelope field is two 4-bit nibbles indicating a "packet m of n packets" relationship:

(packet_number

Table 3-7.AVR_RSP Response


AVR_RSP 1 byte 0x81

FragmentInfo 1 byte Fragment number

Size 2 byte, MSB first Number of response bytes

Response N bytes Enveloped AVR response

FragmentNumber 0x00 indicates that no response data is available, and the rest of the packet is ignored.

Large packets must be chopped up according to the HID interfaces REPORT_SIZE. The fragmentnumber envelope field is two 4-bit nibbles indicating a "packet m of n packets" relationship:

(packet_number

Table 3-10.Unwrapping AVR_EVT


AVR_EVT 1 byte 0x82

Size 2 byte, MSB first Number of event bytes

Event N bytes Enveloped AVR event

Size of 0x0000 indicates that no event data is available, and the rest of the packet is ignored.

3.2.2 ARM-target Specific Vendor Commands

3.2.2.1 Erase PinPulses the ERASE pin high for about 300ms. Required by some SAM devices to gain access when thedevice is secured. EDBG only.

Table 3-11.Erase Pin Command


ERASE_PIN 1 byte 0x86

Response:

Table 3-12.Custom Erase Response


ERASE_PIN 1 byte 0x86

Status 1 byte 0x00: success

0x01: failed

3.2.2.2 Serial TraceProvides access to ITM trace output from an ARM device's SWO pin

For more details on the serial trace protocol API, see Serial Trace Commands.

3.2.3 EDBG-specific Vendor Commands

3.2.3.1 Get ConfigurationRetrieves board configuration information. EDBG only.

Table 3-13.Get Configuration Command


GET_CONFIG 1 byte 0x83

Count 1 byte Number of configuration packets to retrieve

ConfigID 1 byte Starting configuration packet ID

Parameter 1 byte Configuration packet dependent parameter

Response:



Table 3-14.Get Configuration Response


GET_CONFIG 1 byte 0x83


Other values: failed

NumBytes 2 byte, MSB first Number of bytes of configuration packet data

ConfigPackets N bytes Configuration data returned

Configuration packet format is described here:

Table 3-15.Configuration Packet Format (get)


ConfigID 1 byte Configuration ID

DataType 1 byte Data-type of the configuration parameter

Data N bytes Configuration data according to the data type

3.2.3.2 Set ConfigurationSets board configuration parameters. Will only work with devices with HHB suffix.

Table 3-16.Set Configuration Command


SET_CONFIG 1 byte 0x84

Count 1 byte Number of bytes to write

ConfigID 1 byte Configuration packet ID

Data N bytes Configuration data

Response:

Table 3-17.Set Configuration Response


SET_CONFIG 1 byte 0x84


Other values: failed

3.2.3.3 EDBG GET RequestMaps directly to EDBG_GET on the EDBGCTRL protocol.

3.2.3.4 EDBG SET RequestMaps directly to EDBG_SET on the EDBGCTRL protocol.



3.3 Serial Trace CommandsSome ARM-based devices implement a serial trace output using the SWO pin. This is available onlywhen using the SWD interface, and it uses the JTAG TDO pin on the tool to sample the signal. Thissection describes how to configure the tool for capturing serial trace and how to read the captured serialtrace data out of the tool.

Note that the hardware tool performs only raw data capture, storage, and forwarding.

All serial trace commands use vendor command 7 (0x87).

Note: The protocol described here is a custom implementation for SWO trace, which pre-dates thatdetails in the CMSIS-DAP specification. The implementation is thus similar, but not identical.

3.3.1 Set Transport ModeSets the transport mode for sending data from the hardware tool to the host computer. Currently only HIDtransport is supported.

Table 3-18.Set Transport Mode


SERIAL_TRACE 1 byte 0x87

SET_TRANSPORT_MODE 1 byte 0x00

Mode 1 byte Transport mode to transfer data to host PC

0x00: OFF (default)

0x01: HID

Response:

Table 3-19.Set Transport Mode Response



SET_TRANSPORT_MODE 1 byte 0x00

Status 1 byte Status code

0x00: OK

0xFF: Error

3.3.2 Set Capture ModeSets the capture mode for sampling data sent from the target. Currently only UART is supported.

Table 3-20.Set Capture Mode



SET_CAPTURE_MODE 1 byte 0x01

Mode 1 byte Capture mode for incoming data




0x00: OFF (default)

0x02: UART

Response:

Table 3-21.Set Capture Mode Response



SET_CAPTURE_MODE 1 byte 0x01


0x00: OK

0xFF: Error

3.3.3 Set Baud RateSets the baud rate for capturing data. Can be called iteratively to build a table of supported baud-rates,which can be sampled by the hardware.

Table 3-22.Set Baud Rate



SET_BAUD 1 byte 0x02

Baud 4 bytes, MSB first Requested baud rate

Response:

Table 3-23.Set Baud Rate Response



SET_BAUD 1 byte 0x02

Baud 4 bytes, MSB first Actual baud rate achievable

3.3.4 StartStarts the data capture.

Table 3-24.Start



START 1 byte 0x03

Response:



Table 3-25.Start Response



START 1 byte 0x03


0x00: OK

0xFF: Error

3.3.5 StopStops the data capture.

Table 3-26.Stop



STOP 1 byte 0x04

Response:

Table 3-27.Stop Response



STOP 1 byte 0x04


0x00: OK

0xFF: Error

3.3.6 Get DataRetrieves captured data along with status information. Note that up to 508 bytes can be retrieved at atime.

Table 3-28.Get Data



GET_DATA 1 byte 0x08

Response:

Table 3-29.Get Data Response



GET_DATA 1 byte 0x08




STATUS 2 bytes, MSB first Status encoding

Bit 15: overrun error (buffer not read fast enough)

Bit 14: receive error (framing or baud rate error)

Bit 9: receive disabled (receiver has been disabled)

Bits 8..0: number of data bytes received

DATA N bytes Data streamed from the target device

3.3.7 Get StatusReads out status information.

Table 3-30.Get Status



GET_STATUS 1 byte 0x09

Response:

Table 3-31.Get Status Response



GET_STATUS 1 byte 0x09

STATUS 1 byte Status encoding

Bit 7: overrun error (buffer not read fast enough)

Bit 6: receive error (framing or baud rate error)

Bit 1: receive disabled (receiver has been disabled)

BYTES 2 byte, MSB first Number of bytes available to read

3.3.8 Get Buffer SizeReads out the buffer size available on the hardware.

Table 3-32.Get Buffer Size



GET_BUFFER_SIZE 1 byte 0x0A

Response:



Table 3-33.Get Buffer Size Response



GET_BUFFER_SIZE 1 byte 0x0A

Buffer size 4 bytes, MSB first Total size of receive buffer

3.3.9 SignonUsed to check that serial trace is supported by the hardware.

Table 3-34.Signon



SIGNON 1 byte 0x0F

Response:

Table 3-35.Signon Response



SIGNON 1 byte 0x0F

Signon string 3 bytes "OK\0"

Note: Any other response than the signon string indicates that SWO trace is not supported on thathardware.

3.4 Data Polling ServiceDuring a debug session when the target device is running, the debugger usually only polls the target forits run/stopped state. The data polling service can make more use of this time by reading data sources onthe target at a faster rate than can be achieved from the software frontend. On ARM-based devices aswell as AVR UC3 devices, data can be read directly from memory during run mode, but on AVR 8-bitMCUs this data is transferred using the OCD Register, with the exception of AVR devices with UPDI,which can read some memory areas non-intrusively while in run mode. In addition, SAMD devices havetwo Debug Communication Channels (DCCn) available.

All polling functions are intended for use in RUN mode only. For AVR devices the polling service will bedisabled when the device halts. When using the SAM polling modes however, the user must be sure todisable the service when the device halts.

The hardware tool performs only raw data capture, storage, and forwarding. In most cases data can beforwarded to either the DGI or HID buffers, which must be polled by the host computer.Note: Currently only DGI transport is supported. Refer to DGI documentation for details.

The data polling service uses vendor command 'A' (0x8A).



3.4.1 Data Sampler DisableDisables all data sampling. Individual sources can be disabled using their respective commands, whilethe DISABLE command will disable all sources.

Table 3-36.Data Sampler Disable


DATA_SAMPLER 1 byte 0x8A

DISABLE_ALL 1 byte 0x00

Response:

Table 3-37.Data Sampler Disable Response



DISABLE_ALL 1 byte 0x00


0x00: OK

0xFF: Error

3.4.2 SAM Data Sampler EnableUsed to enable polling of locations in memory on an ARM-based target device. Up to 200 locations canbe added to the sampling service, but performance will of course degrade as more locations are added.

The command will return a handle, which should be used when disabling the polling function afterwards.

Table 3-38.SAM Data Sampler



SAM_DATA_ENABLE 1 byte 0x01

START_ADDRESS 4 byte Start address to poll, MSB first.

Must be >=0x20000000

LENGTH 4 byte Number of bytes to poll, MSB first.

Limited by internal EDBG-DGI buffer size.

See error codes section below.

FLAGS 4 byte Bits 1:0: destination: b00: send to DGI as data b01: send to HID (reserved) b10: send to DGI as print b11: reserved

Response:



Table 3-39.SAM Data Sampler Response



SAM_DATA_ENABLE 1 byte 0x01


0x00: OK

0xFF: Error

Handle/error code 1 byte Sampler handle is returned if Status is OK.

Error code is returned if Status is Error.

Error codes:

Table 3-40.SAM Data Sampler Error Codes

Error code Value Description

ERROR_FULL 0x92 Too many poll locations are enabled

ERROR_SIZE_EXCEEDED 0x94 Buffer memory is full.

Total buffer memory is 8MB for the Power Debugger and 64kB forall other EDBG-based tools supported.

ERROR_OUT_OF_RANGE 0x91 The poll location specified is not allowed

3.4.3 SAM Data Sampler DisableUsed to disable polling of locations in memory on an ARM-based target device.

Table 3-41.SAM Data Sampler Disable



SAM_DATA_DISABLE 1 byte 0x11

HANDLE 1 byte Handle ID of the location to stop polling. This valuewas returned when polling was enabled.

Response:

Table 3-42.SAM Data Sampler Disable Response



SAM_DATA_DISABLE 1 byte 0x11


0x00: OK

0x:90 Handle not found



3.4.4 SAM PC SamplerUsed to poll a single location (typically PC) in memory on an ARM-based target device. Generally fasterthan the DATA_SAMPLING function.

Table 3-43.SAM PC Sampler



SAMPLE_SAM_PC 1 byte 0x02

ENABLE 1 byte 0x00: disable

0x01: enable

BURST 1 byte Number of samples per loop (1 to 16)

ADDRESS 4 byte Address to poll, MSB first.

Must be >= 0x20000000


Response:

Table 3-44.SAM PC Sampler response



SAMPLE_SAM_PC 1 byte 0x02


0x00: OK

0xFF: Error

3.4.5 AVR OCD Message SamplerUsed to read out data from the OCD message register on some AVR devices. Only megaAVR devicesJTAG interface, XMEGA devices and AVR devices with UPDI have this capability.

Table 3-45.AVR OCD Message Sampler



SAMPLE_AVR_OCD_MSG 1 byte 0x03





0x01: enable


Response:

Table 3-46.AVR OCD Message Sampler Response



SAMPLE_AVR_OCD_MSG 1 byte 0x03


0x00: OK

0xFF: Error

Note: This feature is in a beta stage and should be used with caution.

3.4.6 SAM Printf Queue SamplerUsed to read out data from a queue on a SAM device.

The printf queue is a circular buffer stored in the SAM's SRAM space along with some administrativefunctions. It consists of:

1. 1 word token+size ("SAM"+size_bytes).2. 1 word write pointer.3. 1 word read pointer.4. (2^size)-12 bytes circular buffer.

The printf queue sampler reads available bytes from the read pointer and sends data to the hostcomputer.

Table 3-47.SAM Printf Queue Sampler



SAMPLE_PRINTF_QUEUE 1 byte 0x04


0x01: enable

ADDRESS 4 byte Start address of queue structure to poll, MSB first

FLAGS 4 byte Bits 1:0: destination:




b00: send to DGI as data b01: send to HID (reserved) b10: send to DGI as print b11: reserved

Response:

Table 3-48.SAM Printf Queue Sampler Response



SAMPLE_PRINTF_QUEUE 1 byte 0x04


0x00: OK

0xFF: Error


3.4.7 SAM DCC SamplerUsed to read out data from DCC0 on a SAMD or SAML device. User code running on the device canwrite characters to DCC0 to implement printf functionality. The debugger polls this location and forwardsdata received to the host computer.

Table 3-49.SAM DCC Sampler



SAMPLE_DCC 1 byte 0x05


0x01: enable

ADDRESS 4 byte Start address of DSU module (containing DCC), MSB first


Response:



Table 3-50.SAM DCC Sampler Response



SAMPLE_DCC 1 byte 0x05


0x00: OK

0xFF: Error


3.4.8 AVR PC SamplerUsed to poll the Program Counter on an AVR device. Only AVR devices with UPDI have this capability.

Table 3-51.AVR PC Sampler



SAMPLE_AVR_PC 1 byte 0x09


0x01: enable


Response:

Table 3-52.AVR PC Sampler Response



SAMPLE_AVR_PC 1 byte 0x09


0x00: OK

0xFF: Error

3.4.9 AVR SP SamplerUsed to poll the Stack Pointer on an AVR device. Only AVR devices UPDI have this capability.



Table 3-53.AVR PC Sampler



SAMPLE_AVR_SP 1 byte 0x0A


0x01: enable


Response:

Table 3-54.AVR PC Sampler Response



SAMPLE_AVR_SP 1 byte 0x0A


0x00: OK

0xFF: Error

3.4.10 AVR Data Sampler EnableUsed to enable polling of locations in memory on an AVR target device. Up to 200 locations can be addedto the sampling service, but performance will of course degrade as more locations are added. Only AVRdevices with UPDI have this capability.

The command will return a handle, which should be used when disabling the polling function afterwards.

Table 3-55.AVR Data Sampler



AVR_DATA_ENABLE 1 byte 0x0B

START_ADDRESS 4 byte Start address to poll, MSB first.

Must be in the range 0x2000 to 0x3FFF.

LENGTH 4 byte Number of bytes to poll, MSB first.

Must be set to 1.

FLAGS 4 byte Bits 1:0: destination: b00: send to DGI as data




b01: send to HID (reserved) b10: send to DGI as print b11: reserved

Response:

Table 3-56.AVR Data Sampler Response



AVR_DATA_ENABLE 1 byte 0x0B


0x00: OK

0xFF: Error

Handle / error code 1 byte Sampler handle is returned if Status is OK.

Error code is returned if Status is Error.

Error codes:

Table 3-57.AVR Data Sampler Error Codes

Error code Value Description

ERROR_FULL 0x92 Too many poll locations are enabled

ERROR_SIZE_EXCEEDED 0x94 Buffer memory is full

ERROR_OUT_OF_RANGE 0x91 The poll location specified is not allowed

3.4.11 AVR Data Sampler DisableUsed to disable polling of locations in memory on an AVR target device.

Table 3-58.AVR Data Sampler Disable



AVR_DATA_DISABLE 1 byte 0x0C

HANDLE 1 byte Handle ID of the location to stop polling. This value was returned whenpolling was enabled.

Response:



Table 3-59.AVR Data Sampler Disable Response



AVR_DATA_DISABLE 1 byte 0x0C


0x00: OK

0x:90 Handle not found

3.4.12 AVR Printf Queue SamplerUsed to read out data from a queue on a AVR device.

The printf queue is a circular buffer stored in the AVR device's SRAM space along with someadministrative functions. It consists of:

1. 1 byte token.2. 1 bytes size.3. 1 byte write index.4. 1 byte read index.5. (2^size)-4 bytes circular buffer.

The printf queue sampler reads available bytes from the read index and sends data to the host computer.

Table 3-60.AVR Printf Queue Sampler



SAMPLE_PRINTF_QUEUE_AVR 1 byte 0x0D


0x01: enable

ADDRESS 2 bytes Start address of queue structure to poll, MSB first


Response:

Table 3-61.AVR Printf Queue Sampler Response



SAMPLE_PRINTF_QUEUE_AVR 1 byte 0x0D





0x00: OK

0xFF: Error




4. EDBG Control ProtocolThe EDBG Control protocol is used to query and configure parameters relevant to EDBG and the boardin which EDBG is embedded.

4.1 Protocol Commands

4.1.1 QUERYUsed to discover the capabilities of the tool.

For lists of valid query types, see EDBG QUERY Contexts.

Table 4-1.Query


QUERY (0x00) 1 byte Command ID

Version (0x00) 1 byte Command version

Query context 1 byte Type of query to execute

Responses:

LIST FAILED

4.1.1.1 EDBG QUERY ContextsTable 4-2.EDBG QUERY Contexts

ID Description Response

EDBG_QUERY_COMMANDS Lists protocol commands supported List of n * [byte]

4.1.2 SETUsed to set parameters on the tool.

For lists of valid get/set parameters, see EDBGCTRL ID Definitions.

Table 4-3.Set


SET (0x01) 1 byte Command ID


Set context 1 byte Context of the parameter to set

Address 1 byte Parameter ID/start address

Bytes 1 byte Number of bytes to write

Data N bytes Data to write

Responses:

OK



FAILED

Note: Setting multiple parameters in one set call can only be done when all fields are in the samecontext.

4.1.3 GETUsed to get parameters on the tool.

For lists of valid get/set parameters, see EDBGCTRL ID Definitions.

Table 4-4.Get


GET (0x02) 1 byte Command ID


Get context 1 byte Context of the parameter to get


Bytes 1 byte Number of bytes to read

Responses:

DATA FAILED

Note: Getting multiple parameters in one get call can only be done when all fields are in the samecontext.

4.1.3.1 SET/GET ParametersTable 4-5.EDBG SET/GET Parameters

Context ID Description ACC Size

EDBG_CTXT_CTRL EDBG_CTRL_LED_USAGE Enables or disables LED usage(for power saving).

0x00: LEDs disabled

0x01: LEDs enabled

RW 1 byte

EDBG_CTRL_EXT_PROG Enables or disables the externaldebug interface, if present.

0x00: external interface disabled

0x01: external interface enabled

RW 1 byte

EDBG_CTRL_TARGET_POWER Enables or disables power fortarget device, if present.

0x00: power disabled

0x01: power enabled

RW 1 byte



4.2 Responses

4.2.1 OKThe command was executed successfully.

Table 4-6.OK Response Format


EDBG_RSP_OK 1 byte Response ID

Version (0x00) 1 byte Response version

4.2.2 LISTList of data returned.

Table 4-7.LIST Response Format


EDBG_RSP_LIST 1 byte Response ID

Version 1 byte Response version

Data (0x00) n bytes Data returned

4.2.3 DATAData is returned.

Table 4-8.DATA Response Format Version 0


EDBG_RSP_DATA 1 byte Response ID

Version 1 byte Response version

Data (0x01) n bytes Data returned

Status code 1 byte Trailing status of the read operation indicating whether the data returned isin fact valid. 0x00 = OK.

4.2.4 FAILEDThe command failed to execute.

Table 4-9.FAILED Response Format


EDBG_RSP_FAILED 1 byte Response ID


Failure Code 1 byte Instance code for failure; 0xFF = unknown



4.3 EDBGCTRL ID DefinitionsThis sections includes the header file defining the different command and response IDs for theEDBGCTRL protocol. It also defines the different possible failure codes.

enum EdbgCommands { //********************************************************** // Protocol commands //**********************************************************

// Basics CMD_EDBG_QUERY = 0x00, CMD_EDBG_SET = 0x01, CMD_EDBG_GET = 0x02,};

enum EdbgResponses { //********************************************************** // Protocol responses //**********************************************************

RSP_EDBG_OK = 0x80, RSP_EDBG_LIST = 0x81, RSP_EDBG_DATA = 0x84, RSP_EDBG_FAILED = 0xA0};

enum EdbgFailureCodes { //********************************************************** // Failure response codes (RSP_FAILED) //**********************************************************

EDBG_FAILED_OK = 0x00, EDBG_FAILED_NOT_SUPPORTED = 0x01, EDBG_FAILED_ILLEGAL_GPIO_PIN = 0x10, EDBG_FAILED_ILLEGAL_GPIO_MODE = 0x11, EDBG_FAILED_ILLEGAL_VOLTAGE_RANGE = 0x12, EDBG_FAILED_ILLEGAL_INTERVAL = 0x13, EDBG_FAILED_ILLEGAL_MAX_THRESHOLD = 0x14, EDBG_FAILED_ILLEGAL_MIN_THRESHOLD = 0x15, EDBG_FAILED_ILLEGAL_ACTION = 0x16, EDBG_FAILED_ILLEGAL_FREQUENCY = 0x17, EDBG_FAILED_ILLEGAL_MODE = 0x18, EDBG_FAILED_ILLEGAL_FLAGS = 0x19, EDBG_FAILED_FLASH_WRITE = 0x20, EDBG_FAILED_OVERFLOW = 0x30, EDBG_FAILED_UNKNOWN = 0xFF};

enum EdbgConfigTypes { EDBG_CONFIGTYPE_CHAR = 0x00, EDBG_CONFIGTYPE_SHORT = 0x01, EDBG_CONFIGTYPE_WORD = 0x02, EDBG_CONFIGTYPE_BIT = 0x03, EDBG_CONFIGTYPE_STRING = 0x10, EDBG_CONFIGTYPE_ARRAY = 0x20,};

enum EdbgConfigTags { //********************************************************** // EDBG Configuration Tags //**********************************************************

EDBG_CONFIG_VERSION = 0x00, EDBG_CONFIG_SERIAL_NUMBER = 0x01, EDBG_CONFIG_BOARD_NAME = 0x02, EDBG_CONFIG_MANUFACTURER_NAME = 0x03, EDBG_CONFIG_TARGET_NAME = 0x04, EDBG_CONFIG_TARGET_SIGNATURE = 0x05, EDBG_CONFIG_TARGET_JTAGID = 0x06, EDBG_CONFIG_TARGET_CHIPID = 0x07, EDBG_CONFIG_INTERFACES = 0x08, EDBG_CONFIG_DGI_GPIO_MAP = 0x09, EDBG_CONFIG_EXTENSION_MAP = 0x0A,



EDBG_CONFIG_EXTENSION_STATUS = 0x0B, EDBG_CONFIG_EXTENSION_MANUFACTURER = 0x0C, EDBG_CONFIG_EXTENSION_PRODUCT = 0x0D, EDBG_CONFIG_EXTENSION_REVISION = 0x0E, EDBG_CONFIG_EXTENSION_SERIAL = 0x0F, EDBG_CONFIG_EXTENSION_MIN_VOLTAGE = 0x10, EDBG_CONFIG_EXTENSION_MAX_VOLTAGE = 0x11, EDBG_CONFIG_EXTENSION_CURRENT = 0x12, EDBG_CONFIG_BOARD_TYPE = 0x13, EDBG_CONFIG_FAMILY_NAME = 0x14, EDBG_CONFIG_TVS = 0x15, EDBG_CONFIG_VERSION_MINOR = 0x16, EDBG_CONFIG_USB_ID = 0x17, EDBG_CONFIG_KIT_DATA = 0x20,};

enum EdbgInterfaces { //********************************************************** // EDBG Configuration Tags //********************************************************** // GPIO, USART, UART, TWI, SPI, CDC // SWD, ARMJTAG, AVRJTAG, aW, dW, PDI, ISP, DBG_EN

EDBG_IF_DBG_EN = 15, EDBG_IF_DBG_ISP = 14, EDBG_IF_DBG_PDI = 13, EDBG_IF_DBG_DW = 12, EDBG_IF_DBG_AW = 11, EDBG_IF_DBG_AVRJTAG = 10, EDBG_IF_DBG_ARMJTAG = 9, EDBG_IF_DBG_SWD = 8, EDBG_IF_DGI_SPI = 0, EDBG_IF_DGI_TWI = 1, EDBG_IF_DGI_UART = 2, EDBG_IF_DGI_USART = 3, EDBG_IF_DGI_GPIO = 4, EDBG_IF_CDC = 5, EDBG_IF_ERASE_PIN = 7,};enum EDBGQueryContexts { // QUERY types on this protocol EDBG_QUERY_COMMANDS = 0x00}; enum EDBGSetGetContexts { EDBG_CONTEXT_CONTROL = 0x00, EDBG_CONTEXT_CONFIG0 = 0x10, EDBG_CONTEXT_CONFIG1 = 0x11,};

enum EDBGControlContextParameters { EDBG_CONTROL_LED_USAGE = 0x00, EDBG_CONTROL_EXT_PROG = 0x01, EDBG_CONTROL_TARGET_POWER = 0x10};

enum SerialTraceCommands { ST_SET_TRANSPORT_MODE = 0x00, ST_SET_CAPTURE_MODE = 0x01, ST_SET_BAUD = 0x02, ST_START = 0x03, ST_STOP = 0x04, ST_GET_DATA = 0x08, ST_GET_STATUS = 0x09, ST_GET_BUFFER_SIZE = 0x0A, ST_SIGNON = 0x0F};

enum SerialTraceTransportModes { TRANSPORT_OFF = 0x00, TRANSPORT_HID = 0x01};

enum SerialTraceTransportModes { CAPTURE_OFF = 0x00, CAPTURE_UART = 0x02



};

enum SerialTraceErrorBits { ERROR_OVERFLOW = 15, ERROR_RECEIVER = 14, RECEIVER_DISABLED = 9};



5. AVR Communication Protocol

5.1 OverviewThe communication protocol of the AVR functionality of EDBG is based on sub-protocols, which may ormay not be available depending upon the physical capabilities of the tool.

5.2 FramingThis section outlines the general frame format used by all sub-protocols.

The protocol handler ID field identifies which sub-protocol to decode the packet by, and then whichcommand handler to forward the packet to.

In general, ID == 0x00 is used as a query function in order for the host to discover the feature set ofthe tool.

Table 5-1.Command Frame Format

Field Size Value

SOF 1 byte 0x0E

Protocol version 1 byte 0x00 in this version (all packets)

Sequence ID 2 bytes Incrementing from 0x00 (least significant byte sent first)

Protocol handler ID 1 byte Destination sub-protocol handler ID

Payload N bytes Data

Table 5-2.Response Frame Format

Field Size Value

SOF 1 byte 0x0E

Sequence ID 2 bytes Echo of incoming ID (least significant byte sent first)

Protocol handler ID 1 byte Source sub-protocol handler ID


Table 5-3.Event Frame Format

Field Size Value

SOF 1 byte 0x0E

Protocol version 1 byte 0x00 in this version (all packets)

Sequence ID 2 bytes Incrementing from 0x00 (least significant byte sent first)

Protocol handler ID 1 byte Source sub-protocol handler ID


The protocol handler ID field identifies which sub-protocol to decode the packet by, and then whichcommand handler to forward the packet to.



In general, ID == 0x00 is used as a query function in order for the host to discover the feature set ofthe tool.

If there is a condition where the EDBG AVR command handler expects more data for a command than isavailable, then the next incoming command will be rejected and an error response (RSP_FAILED withfailure code FAILURE_USB_PREVIOUS_UNDERRUN) will be returned . Note that such an underrunsituation will result in unknown values for the parameters of the failing command and the host will have todo the necessary cleanup to undo any undesired behavior. The underrun error reporting is done bytransport layer and is independent of the sub-protocol being used.

Note: Unless otherwise stated, all multi-byte fields in this section are sent with least significant byte first.

5.3 Protocol Sub-set OverviewOne or more of the sub-protocols listed in the table below may be implemented by EDBG. Each oneimplements its own command handler, and is self-contained in terms of configuration parameters. Whichprotocol to use is given by the ID being put into the "Protocol handler ID" field in the main frame format.Then the command or response follows as the "Payload" field in the main frame format.

Table 5-4.Protocol Sub-sets

ID Name Description

0x00 DISCOVERY For discovering the feature set of the tool

0x01 HOUSEKEEPING (HK) Housekeeping functions

0x11 AVRISP Programming of tinyAVR and megaAVR using AVRISP commands(SPI-based programming)

0x12 AVR8GENERIC Debugging of tinyAVR using debugWIRE Programming and debugging of megaAVR and XMEGA using

JTAG and PDI Programming and debugging of AVR devices using UPDI

0x13 AVR32GENERIC Programming and debugging of AVR UC3 32-bit microcontrollers usingJTAG and aWire

0x14 TPI Programming of tinyAVR devices using TPI

0x20 EDBG_CTRL Control and configuration of EDBG

5.4 Discovery Protocol DefinitionThe discovery handler only supports the QUERY command. It is used to interrogate the tool for itssupported functionality and other fixed information.

5.4.1 CMD: QUERYUsed to discover the capabilities of the tool.

For lists of valid query types, see Discovery QUERY Contexts.



Table 5-5.Query





Responses:

RSP: LIST RSP: FAILED

5.4.2 Discovery QUERY ContextsTable 5-6.Discovery QUERY Contexts


COMMAND_HANDLERS Lists protocol command handlerssupported

List of n * [byte]

TOOL_NAME Name of this tool String of n * [byte]

SERIAL_NUMBER Serial number String of n * [byte]

MNF_DATE Manufacture date String of form YYYYMMDDHHMMSS

5.4.3 RSP: LISTList of data returned.



RSP_LIST 1 byte Response ID


Data n bytes Data returned

5.4.4 RSP: FAILEDThe command failed to execute.



RSP_FAILED 1 byte Response ID



5.4.5 Discovery Protocol ID Definitionsenum Jtagice3DiscoveryCommands { CMD_QUERY = 0x00, //! Capability discovery };

enum Jtagice3DiscoveryResponses {



RSP_DISCOVERY_LIST = 0x81, //! List of items returned RSP_DISCOVERY_FAILED = 0xA0, //! Command failed to execute};

// Generic failure codesenum Jtagice3FailureCodes { FAILURE_OK = 0x00, //! No error FAILURE_USB_PREVIOUS_UNDERRUN = 0xE0, //! Previous command had too few bytes FAILURE_UNKNOWN = 0xFF //! Unknown failure};

enum Jtagice3Discovery { DISCOVERY_COMMAND_HANDLERS = 0x00, //! List available command handlers DISCOVERY_TOOL_NAME = 0x80, //! Query tool name DISCOVERY_SERIAL_NUMBER = 0x81, //! Query tool serial number DISCOVERY_MNF_DATE = 0x82 //! Query tool manufacturing date};

enum Jtagice3DiscoveryFailureCodes { DISCOVERY_FAILED_NOT_SUPPORTED = 0x10 //! Unsupported function};

5.5 Housekeeping Protocol

5.5.1 CMD: QUERYUsed to discover the capabilities of the tool.

For lists of valid query types, see Housekeeping QUERY Contexts.

Table 5-9.Query





Responses:

LIST FAILED

5.5.2 Housekeeping QUERY ContextsTable 5-10.Housekeeping QUERY Contexts


HK_QUERY_COMMANDS Lists protocol commands supported List of n * [byte]

5.5.3 CMD: SETUsed to set parameters on the tool.

For lists of valid get/set parameters, see Housekeeping SET/GET Parameters.



Table 5-11.Set








Responses:

OK FAILED


5.5.4 CMD: GETUsed to get parameters on the tool.

For lists of valid get/set parameters, see Housekeeping SET/GET Parameters.

Table 5-12.Get







Responses:

DATA FAILED

Note: Getting multiple parameters in one set call can only be done when all fields are in the samecontext.

5.5.5 Housekeeping SET/GET ParametersTable 5-13.Housekeeping SET/GET Parameters

Context ID Description Acc Size

HK_CONTEXT_CONFIG HWREV Hardware version R 1 byte

FWREV_MAJ Firmware major version R 1 byte

FWREV_MIN Firmware minor version R 1 byte



Context ID Description Acc Size

BUILD Firmware build number R 2 x [byte]

HK_CONTEXT_ANALOG VTG Target voltage reading R 2 bytes (mV value)

5.5.6 Housekeeping Commands

5.5.6.1 Start SessionStarts a session with the tool. The tool may now publish events to the host on the EVENT channel.

Table 5-14.Start Session Command Format


CMD_HOUSEKEEPING_START_SESSION 1 byte Command ID


Responses:

OK FAILED

5.5.6.2 End SessionEnds a session with the tool. The tool will cease to publish events.

Table 5-15.End Session Command Format


CMD_HOUSEKEEPING_END_SESSION Version Command ID


Reset 1 byte 0 = no action; 1 = reset tool

Responses:

OK FAILED

5.5.6.3 Firmware UpgradeInvokes upgrade mode. No further communication is required.

Upgrading firmware on EDBG-based tools is not a publicly documented mechanism. Calling this protocolcommand will cause a response to be sent before communication ceases and the tool re-enumerates intoits upgrade configuration. At this point atfw.exe (part of Atmel Studio) can be used to upgrade thefirmware on the tool. Toggling power without upgrading will put the tool back into application mode.

Note: Not all EDBG-based tools have the same bootloader mechanism.

Table 5-16.Firmware Upgrade Command Format


CMD_HOUSEKEEPING_FW_UPGRADE 1 byte Command ID


Upgrade key 4 bytes Key for enabling upgrade mode



Responses:

OK FAILED

5.5.6.4 JTAG Scan-chain DetectionPerforms an auto detection of JTAG devices. If no devices are found, JTAG enable sequences for variousfamilies are applied and the detection retried. If any device on the scan chain does not have JTAGenabled, the "use reset" parameter can help to enable JTAG. (This will not necessarily work with devicesnot manufactured by Microchip.)

Table 5-17.JTAG Scan-chain Detection Command Format


CMD_HOUSEKEEPING_JTAG_DETECT 1 byte Command ID


Use reset 1 byte 0 = External reset will NOT be applied

1 = External reset will be applied

Responses:

LIST of 32-bit JTAG IDs FAILED

5.5.6.5 Calibrate OscillatorPerforms oscillator calibration on the target. Protocol and target code is described in application notes AVR053 (megaAVR and tinyAVR) and AVR1606 (AVR XMEGA). Note that this command must be calledwithout any physical activated, or else an error will be returned. The reference clock for the calibration isrunning at 32.120kHz.

Table 5-18.Calibrate Oscillator Command Format


CMD_HOUSEKEEPING_CAL_OSC 1 byte Command ID


Responses:

OK FAILED

5.5.7 Housekeeping Responses

5.5.7.1 OKThe command was executed successfully.

Table 5-19.OK Response Format


RSP_HOUSEKEEPING_OK 1 byte Response ID




http://ww1.microchip.com/downloads/en/appnotes/atmel-2555-internal-rc-oscillator-calibration-for-tinyavr-and-megaavr-devices_applicationnote_avr053.pdfhttp://ww1.microchip.com/downloads/en/appnotes/doc8277.pdf

5.5.7.2 LISTList of data returned.



RSP_HOUSEKEEPING_LIST 1 byte Response ID



5.5.7.3 DATAData is returned.

Table 5-21.DATA Response Format Version 0


RSP_HOUSEKEEPING_DATA 1 byte Response ID



Status code 1 byte Trailing status of the read operation indicating whether thedata returned is in fact valid. 0x00 = OK.

Note: RSP_HOUSEKEEPING_DATA version 0 does not have the trailing status code.

5.5.7.4 FAILEDThe command failed to execute.



RSP_HOUSEKEEPING_FAILED 1 byte Response ID



5.5.8 Events

5.5.8.1 Event: PowerIndicates a target power event has occurred.

Note: Debouncing is implemented, but several alternating events could still appear in some cases.

Table 5-23.POWER Event Format


EVT_HOUSEKEEPING_POWER 1 byte Event ID

Version (0x00) 1 byte Event version

State 1 byte 0x00 = Power has gone OFF

0x01 = Power has been restored



5.5.8.2 Event: SleepIndicates target sleep status.

Note: This value is polled from the target at a fixed frequency.

Entering and exiting SLEEP states rapidly will not generate the same number of event messages as theactual state transitions.

Table 5-24.SLEEP Event Format


EVT_HOUSEKEEPING_SLEEP 1 byte Event ID


State 1 byte 0x00 = Target is now AWAKE

0x01 = Target is now ASLEEP

5.5.8.3 Event: External ResetIndicates target external reset status.

Table 5-25.EXTERNAL RESET Event Format


EVT_HOUSEKEEPING_EXT_RESET 1 byte Event ID


State 1 byte 0x00 = External reset has been released (rising edge)

0x01 = External reset has been applied (falling edge)

5.5.9 Hints and TipsUsing the housekeeping protocol:

Housekeeping functions are performed using the Housekeeping protocol handler. All housekeepingfunctions are independent of any target functionality. This includes VTref reading, version checking, etc.

Session control is done on the housekeeping interface using CMD_START_SESSION andCMD_END_SESSION, (aka: sign on and sign off).

JTAG scan-chain auto-detection is supported on the housekeeping interface, but is restricted exclusivelyto JTAG detection. All other interfaces must be detected manually by trial and error, or selected by theuser directly. Scan-chain auto-detection must be executed before activating the JTAG physical using anyprotocol.

5.5.10 Housekeeping ID Definitionsenum Jtagice3HousekeepingCommands { // Basics CMD_HOUSEKEEPING_QUERY = 0x00, //! Capability discovery CMD_HOUSEKEEPING_SET = 0x01, //! Set parameters CMD_HOUSEKEEPING_GET = 0x02, //! Get parameters // Session CMD_HOUSEKEEPING_START_SESSION = 0x10, //! Start a session CMD_HOUSEKEEPING_END_SESSION = 0x11, //! Terminate a session // Misc target-related CMD_HOUSEKEEPING_JTAG_DETECT = 0x30, //! Scan for JTAG devices



CMD_HOUSEKEEPING_CAL_OSC = 0x31, //! Oscillator calibration // Internal commands CMD_HOUSEKEEPING_FW_UPGRADE = 0x50, //! Enter upgrade mode};

enum Jtagice3HousekeepingResponses { RSP_HOUSEKEEPING_OK = 0x80, //! All OK RSP_HOUSEKEEPING_LIST = 0x81, //! List of items returned RSP_HOUSEKEEPING_DATA = 0x84, //! Data returned RSP_HOUSEKEEPING_FAILED = 0xA0, //! Command failed to execute RSP_HOUSEKEEPING_FAILED_WITH_DATA = 0xA1 //! Failed with more info

};

enum Jtagice3HousekeepingEvents { EVT_HOUSEKEEPING_POWER = 0x10, //! Power event occurred EVT_HOUSEKEEPING_SLEEP = 0x11, //! Sleep event detected EVT_HOUSEKEEPING_EXT_RESET = 0x12, //! External reset event};

enum Jtagice3HousekeepingFailureCodes { HOUSEKEEPING_FAILED_OK = 0x00, //! All OK HOUSEKEEPING_FAILED_NOT_SUPPORTED = 0x10, //! Not supported HOUSEKEEPING_FAILED_INVALID_KEY = 0x11, //! Wrong key HOUSEKEEPING_FAILED_INVALID_PARAMETER = 0x12, //! Wrong parameter HOUSEKEEPING_FAILED_INVALID_PARAMETER_VALUE = 0x13, //! Wrong value

HOUSEKEEPING_FAILED_JTAG_DETECT_NO_DEVICES = 0x30, //! No devices HOUSEKEEPING_FAILED_JTAG_DETECT_TOO_MANY_DEVICES = 0x31, //! Too many devices HOUSEKEEPING_FAILED_JTAG_DETECT_JTAGM_INIT_ERROR = 0x32, //! Init failed HOUSEKEEPING_FAILED_JTAG_DETECT_JTAGM_ERROR = 0x33, //! JTAGM error HOUSEKEEPING_FAILED_NO_TARGET_POWER = 0x38, //! Apply power HOUSEKEEPING_FAILED_OSCCAL_INVALID_MODE = 0x40, //! Wrong mode HOUSEKEEPING_FAILED_OSCCAL_INVALID_PHYSICAL = 0x41, //! Wrong phy HOUSEKEEPING_FAILED_OSCCAL_FW_ERROR = 0x42, //! Firmware error HOUSEKEEPING_FAILED_OSCCAL_FAILED = 0x43, //! OSCCAL error};

enum Jtagice3SetGetFailureCodes { SETGET_FAILURE_OK = 0x00, //! All OK SETGET_FAILURE_NOT_IMPLEMENTED = 0x10, //! Command not implented SETGET_FAILURE_NOT_SUPPORTED = 0x11, //! Parameter not supported SETGET_FAILURE_INVALID_CLOCK_SPEED = 0x20, //! Clock out of range SETGET_FAILURE_ILLEGAL_STATE = 0x21, //! Wrong state to access the parameter SETGET_FAILURE_JTAGM_INIT_ERROR = 0x22, //! JTAG initialisation error SETGET_FAILURE_INVALID_VALUE = 0x23 //! Value out of range};

enum Jtagice3HousekeepingQueryContexts { HK_QUERY_COMMANDS = 0x00 //! Supported command list};

enum Jtagice3HousekeepingSetGetContexts { HK_CONTEXT_CONFIG = 0x00, //! Config parameter HK_CONTEXT_ANALOG = 0x01, //! Analog parameters};

enum Jtagice3HousekeepingConfigContextParameters { HOUSEKEEPING_CONFIG_HWREV = 0x00, //! Hardware revision HOUSEKEEPING_CONFIG_FWREV_MAJ = 0x01, //! Firmware revision high HOUSEKEEPING_CONFIG_FWREV_MIN = 0x02, //! Firmware revision low HOUSEKEEPING_CONFIG_BUILD = 0x03, //! Firmware build number};

enum Jtagice3HousekeepingAnalogContextParameters { HOUSEKEEPING_ANALOG_VTREF = 0x00 //! Target reference voltage};

enum Jtagice3HousekeepingPowerEvents { HOUSEKEEPING_POWER_OFF = 0x00, //! Power went off HOUSEKEEPING_POWER_ON = 0x01 //! Power went on};



enum Jtagice3HousekeepingSleepEvents { HOUSEKEEPING_AWAKE = 0x00, //! Target woke up HOUSEKEEPING_SLEEP = 0x01 //! Target fell asleep};

enum Jtagice3HousekeepingResetEvents { HOUSEKEEPING_RESET_RELEASED = 0x00, //! External reset released HOUSEKEEPING_RESET_APPLIED = 0x01 //! External reset applied};



6. AVR32 Generic ProtocolThe AVR32GENERIC protocol is the single protocol for programming and debugging AVR UC3 32-bitmicrocontrollers using all relevant tools.

UC3 devices are big endian meaning that byte address 0 is the most significant byte. TheAVR32GENERIC protocol is little endian, i.e. least significant byte is sent first. Words are sent inascending order, i.e. lowest word address first.

6.1 Protocol Commands

6.1.1 QUERYUsed to discover the capabilities of the tool.

For lists of valid query types, see AVR32 QUERY Contexts.

Table 6-1.Query




Query context 1 byte Type of query toexecute

Responses:

LIST FAILED

6.1.1.1 AVR32 QUERY ContextsTable 6-2.AVR32 QUERY Contexts


AVR32_QUERY_COMMANDS Lists protocol commands supported List of n * [byte]

AVR32_QUERY_CONFIGURATION Lists configuration parameterssupported

List of n * [byte]

AVR32_QUERY_READ_MEMTYPES Lists readable memtypes List of n * [byte]

AVR32_QUERY_WRITE_MEMTYPES Lists writeable memtypes List of n * [byte]

6.1.2 SETUsed to set parameters on the tool.

For lists of valid get/set parameters, see SET/GET Parameters.



Table 6-3.Set








Responses:

OK FAILED


6.1.3 GETUsed to get parameters on the tool.

For lists of valid get/set parameters, see SET/GET Parameters.

Table 6-4.Get







embedded debugger-based tools protocols user's...

Documents