Upload
vantu
View
265
Download
2
Embed Size (px)
Citation preview
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
2017 Microchip Technology Inc. User Guide DS50002630A-page 2
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 3
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 4
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 5
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 6
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.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 7
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 8
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.
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.
PowerDebugger
0x2144 Programming of all AVR devices using SPI, TPI, PDI,UPDI, JTAG, and aWire.
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 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.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 9
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.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 10
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
Field Size Description
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
Field Size Description
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
Field Size Description
ERASE_PIN 1 byte 0x86
Response:
Table 3-12.Custom Erase Response
Field Size Description
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
Field Size Description
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:
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 13
Table 3-14.Get Configuration Response
Field Size Description
GET_CONFIG 1 byte 0x83
Status 1 byte 0x00: success
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)
Field Size Description
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
Field Size Description
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
Field Size Description
SET_CONFIG 1 byte 0x84
Status 1 byte 0x00: success
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.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 14
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
Field Size Description
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
Field Size Description
SERIAL_TRACE 1 byte 0x87
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
Field Size Description
SERIAL_TRACE 1 byte 0x87
SET_CAPTURE_MODE 1 byte 0x01
Mode 1 byte Capture mode for incoming data
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 15
Field Size Description
0x00: OFF (default)
0x02: UART
Response:
Table 3-21.Set Capture Mode Response
Field Size Description
SERIAL_TRACE 1 byte 0x87
SET_CAPTURE_MODE 1 byte 0x01
Status 1 byte Status code
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
Field Size Description
SERIAL_TRACE 1 byte 0x87
SET_BAUD 1 byte 0x02
Baud 4 bytes, MSB first Requested baud rate
Response:
Table 3-23.Set Baud Rate Response
Field Size Description
SERIAL_TRACE 1 byte 0x87
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
Field Size Description
SERIAL_TRACE 1 byte 0x87
START 1 byte 0x03
Response:
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 16
Table 3-25.Start Response
Field Size Description
SERIAL_TRACE 1 byte 0x87
START 1 byte 0x03
Status 1 byte Status code
0x00: OK
0xFF: Error
3.3.5 StopStops the data capture.
Table 3-26.Stop
Field Size Description
SERIAL_TRACE 1 byte 0x87
STOP 1 byte 0x04
Response:
Table 3-27.Stop Response
Field Size Description
SERIAL_TRACE 1 byte 0x87
STOP 1 byte 0x04
Status 1 byte Status code
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
Field Size Description
SERIAL_TRACE 1 byte 0x87
GET_DATA 1 byte 0x08
Response:
Table 3-29.Get Data Response
Field Size Description
SERIAL_TRACE 1 byte 0x87
GET_DATA 1 byte 0x08
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 17
Field Size Description
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
Field Size Description
SERIAL_TRACE 1 byte 0x87
GET_STATUS 1 byte 0x09
Response:
Table 3-31.Get Status Response
Field Size Description
SERIAL_TRACE 1 byte 0x87
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
Field Size Description
SERIAL_TRACE 1 byte 0x87
GET_BUFFER_SIZE 1 byte 0x0A
Response:
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 18
Table 3-33.Get Buffer Size Response
Field Size Description
SERIAL_TRACE 1 byte 0x87
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
Field Size Description
SERIAL_TRACE 1 byte 0x87
SIGNON 1 byte 0x0F
Response:
Table 3-35.Signon Response
Field Size Description
SERIAL_TRACE 1 byte 0x87
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).
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 19
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
DISABLE_ALL 1 byte 0x00
Response:
Table 3-37.Data Sampler Disable Response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
DISABLE_ALL 1 byte 0x00
Status 1 byte Status code
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
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:
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 20
Table 3-39.SAM Data Sampler Response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAM_DATA_ENABLE 1 byte 0x01
Status 1 byte Status code
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAM_DATA_DISABLE 1 byte 0x11
Status 1 byte Status code
0x00: OK
0x:90 Handle not found
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 21
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
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
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-44.SAM PC Sampler response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_SAM_PC 1 byte 0x02
Status 1 byte Status code
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_AVR_OCD_MSG 1 byte 0x03
ENABLE 1 byte 0x00: disable
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 22
Field Size Description
0x01: enable
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-46.AVR OCD Message Sampler Response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_AVR_OCD_MSG 1 byte 0x03
Status 1 byte Status code
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_PRINTF_QUEUE 1 byte 0x04
ENABLE 1 byte 0x00: disable
0x01: enable
ADDRESS 4 byte Start address of queue structure to poll, MSB first
FLAGS 4 byte Bits 1:0: destination:
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 23
Field Size Description
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_PRINTF_QUEUE 1 byte 0x04
Status 1 byte Status code
0x00: OK
0xFF: Error
Note: This feature is in a beta stage and should be used with caution.
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_DCC 1 byte 0x05
ENABLE 1 byte 0x00: disable
0x01: enable
ADDRESS 4 byte Start address of DSU module (containing DCC), 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:
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 24
Table 3-50.SAM DCC Sampler Response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_DCC 1 byte 0x05
Status 1 byte Status code
0x00: OK
0xFF: Error
Note: This feature is in a beta stage and should be used with caution.
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_AVR_PC 1 byte 0x09
ENABLE 1 byte 0x00: disable
0x01: enable
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-52.AVR PC Sampler Response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_AVR_PC 1 byte 0x09
Status 1 byte Status code
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.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 25
Table 3-53.AVR PC Sampler
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_AVR_SP 1 byte 0x0A
ENABLE 1 byte 0x00: disable
0x01: enable
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-54.AVR PC Sampler Response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_AVR_SP 1 byte 0x0A
Status 1 byte Status code
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 26
Field Size Description
b01: send to HID (reserved) b10: send to DGI as print b11: reserved
Response:
Table 3-56.AVR Data Sampler Response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
AVR_DATA_ENABLE 1 byte 0x0B
Status 1 byte Status code
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
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:
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 27
Table 3-59.AVR Data Sampler Disable Response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
AVR_DATA_DISABLE 1 byte 0x0C
Status 1 byte Status code
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
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_PRINTF_QUEUE_AVR 1 byte 0x0D
ENABLE 1 byte 0x00: disable
0x01: enable
ADDRESS 2 bytes 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-61.AVR Printf Queue Sampler Response
Field Size Description
DATA_SAMPLER 1 byte 0x8A
SAMPLE_PRINTF_QUEUE_AVR 1 byte 0x0D
Status 1 byte Status code
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 28
Field Size Description
0x00: OK
0xFF: Error
Note: This feature is in a beta stage and should be used with caution.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 29
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
Field Size Description
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
Field Size Description
SET (0x01) 1 byte Command ID
Version (0x00) 1 byte Command version
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 30
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
Field Size Description
GET (0x02) 1 byte Command ID
Version (0x00) 1 byte Command version
Get context 1 byte Context of the parameter to get
Address 1 byte Parameter ID/start address
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 31
4.2 Responses
4.2.1 OKThe command was executed successfully.
Table 4-6.OK Response Format
Field Size Description
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
Field Size Description
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
Field Size Description
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
Field Size Description
EDBG_RSP_FAILED 1 byte Response ID
Version (0x00) 1 byte Response version
Failure Code 1 byte Instance code for failure; 0xFF = unknown
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 32
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-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 33
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 34
};
enum SerialTraceErrorBits { ERROR_OVERFLOW = 15, ERROR_RECEIVER = 14, RECEIVER_DISABLED = 9};
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 35
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
Payload N bytes Data
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
Payload N bytes Data
The protocol handler ID field identifies which sub-protocol to decode the packet by, and then whichcommand handler to forward the packet to.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 36
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.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 37
Table 5-5.Query
Field Size Description
QUERY (0x00) 1 byte Command ID
Version (0x00) 1 byte Command version
Query context 1 byte Type of query to execute
Responses:
RSP: LIST RSP: FAILED
5.4.2 Discovery QUERY ContextsTable 5-6.Discovery QUERY Contexts
ID Description Response
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.
Table 5-7.LIST Response Format
Field Size Description
RSP_LIST 1 byte Response ID
Version (0x00) 1 byte Response version
Data n bytes Data returned
5.4.4 RSP: FAILEDThe command failed to execute.
Table 5-8.FAILED Response Format
Field Size Description
RSP_FAILED 1 byte Response ID
Version (0x00) 1 byte Response version
Failure Code 1 byte Instance code for failure; 0xFF = unknown
5.4.5 Discovery Protocol ID Definitionsenum Jtagice3DiscoveryCommands { CMD_QUERY = 0x00, //! Capability discovery };
enum Jtagice3DiscoveryResponses {
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 38
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
Field Size Description
QUERY (0x00) 1 byte Command ID
Version (0x00) 1 byte Command version
Query context 1 byte Type of query to execute
Responses:
LIST FAILED
5.5.2 Housekeeping QUERY ContextsTable 5-10.Housekeeping QUERY Contexts
ID Description Response
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.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 39
Table 5-11.Set
Field Size Description
SET (0x01) 1 byte Command ID
Version (0x00) 1 byte Command version
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.
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
Field Size Description
GET (0x02) 1 byte Command ID
Version (0x00) 1 byte Command version
Get context 1 byte Context of the parameter to get
Address 1 byte Parameter ID/start address
Bytes 1 byte Number of bytes to read
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 40
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
Field Size Description
CMD_HOUSEKEEPING_START_SESSION 1 byte Command ID
Version (0x00) 1 byte Command version
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
Field Size Description
CMD_HOUSEKEEPING_END_SESSION Version Command ID
Version (0x00) 1 byte Command version
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
Field Size Description
CMD_HOUSEKEEPING_FW_UPGRADE 1 byte Command ID
Version (0x00) 1 byte Command version
Upgrade key 4 bytes Key for enabling upgrade mode
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 41
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
Field Size Description
CMD_HOUSEKEEPING_JTAG_DETECT 1 byte Command ID
Version (0x00) 1 byte Command version
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
Field Size Description
CMD_HOUSEKEEPING_CAL_OSC 1 byte Command ID
Version (0x00) 1 byte Command version
Responses:
OK FAILED
5.5.7 Housekeeping Responses
5.5.7.1 OKThe command was executed successfully.
Table 5-19.OK Response Format
Field Size Description
RSP_HOUSEKEEPING_OK 1 byte Response ID
Version (0x00) 1 byte Response version
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 42
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.
Table 5-20.LIST Response Format
Field Size Description
RSP_HOUSEKEEPING_LIST 1 byte Response ID
Version (0x00) 1 byte Response version
Data n bytes Data returned
5.5.7.3 DATAData is returned.
Table 5-21.DATA Response Format Version 0
Field Size Description
RSP_HOUSEKEEPING_DATA 1 byte Response ID
Version (0x01) 1 byte Response version
Data n bytes Data returned
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.
Table 5-22.FAILED Response Format
Field Size Description
RSP_HOUSEKEEPING_FAILED 1 byte Response ID
Version (0x00) 1 byte Response version
Failure Code 1 byte Instance code for failure; 0xFF = unknown
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
Field Size Description
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 43
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
Field Size Description
EVT_HOUSEKEEPING_SLEEP 1 byte Event ID
Version (0x00) 1 byte Event version
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
Field Size Description
EVT_HOUSEKEEPING_EXT_RESET 1 byte Event ID
Version (0x00) 1 byte Event version
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
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 44
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};
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 45
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};
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 46
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
Field Size Description
QUERY (0x00) 1 byte Command ID
Version (0x00) 1 byte Command version
Query context 1 byte Type of query toexecute
Responses:
LIST FAILED
6.1.1.1 AVR32 QUERY ContextsTable 6-2.AVR32 QUERY Contexts
ID Description Response
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.
EDBG-based Tools Protocols
2017 Microchip Technology Inc. User Guide DS50002630A-page 47
Table 6-3.Set
Field Size Description
SET (0x01) 1 byte Command ID
Version (0x00) 1 byte Command version
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.
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
Field Size Description
GET (0x02) 1 byte Command ID
Version (0x00) 1 byte Command version
Get context 1 byte Context of the parameter to get
Address 1 byte Parameter ID/start address
Bytes 1 byte Number of bytes to read