2 Transfer protocol defintions used by debug agent and host. It is only
3 intended to be used by Debug related module implementation.
5 Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php.
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #ifndef __TRANSFER_PROTOCOL_H__
17 #define __TRANSFER_PROTOCOL_H__
19 #include "ProcessorContext.h"
20 #include "SoftDebuggerDefinitions.h"
23 // Definitions for break command.
25 #define DEBUG_STARTING_SYMBOL_BREAK (0x21) // '!'
26 #define DEBUG_STARTING_SYMBOL_BREAK_STRING ("!")
29 // Definition for starting symbol of a normal debug packet. Choose a non-ASCII to avoid conflict with other serial output.
31 #define DEBUG_STARTING_SYMBOL_NORMAL (0xFE)
37 // Definition for common header for normal debug packets (not including break command)
43 } DEBUG_COMMAND_HEADER
;
46 // Structure to facilitate debug packet header parsing or construction
51 } DEBUG_COMMAND_HEADER_NO_START_SYMBOL
;
55 // Definition for Command field for debug packets
57 #define DEBUG_COMMAND_REQUEST (0 << 7)
58 #define DEBUG_COMMAND_RESPONSE (1 << 7)
62 #define DEBUG_COMMAND_RESET (DEBUG_COMMAND_REQUEST | 0) // 0
64 #define DEBUG_COMMAND_GO (DEBUG_COMMAND_REQUEST | 1) // 1
66 #define DEBUG_COMMAND_BREAK_CAUSE (DEBUG_COMMAND_REQUEST | 2) // 2
68 #define DEBUG_COMMAND_SET_HW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 3) // 3
69 #define DEBUG_COMMAND_CLEAR_HW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 4) // 4
71 #define DEBUG_COMMAND_SINGLE_STEPPING (DEBUG_COMMAND_REQUEST | 5) // 5
73 #define DEBUG_COMMAND_SET_SW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 6) // 6
74 #define DEBUG_COMMAND_CLEAR_SW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 7) // 7
76 #define DEBUG_COMMAND_READ_MEMORY_8 (DEBUG_COMMAND_REQUEST | 8) // 8
77 #define DEBUG_COMMAND_READ_MEMORY_16 (DEBUG_COMMAND_REQUEST | 9) // 9
78 #define DEBUG_COMMAND_READ_MEMORY_32 (DEBUG_COMMAND_REQUEST | 10) // 10
79 #define DEBUG_COMMAND_READ_MEMORY_64 (DEBUG_COMMAND_REQUEST | 11) // 11
81 #define DEBUG_COMMAND_WRITE_MEMORY_8 (DEBUG_COMMAND_REQUEST | 12) // 12
82 #define DEBUG_COMMAND_WRITE_MEMORY_16 (DEBUG_COMMAND_REQUEST | 13) // 13
83 #define DEBUG_COMMAND_WRITE_MEMORY_32 (DEBUG_COMMAND_REQUEST | 14) // 14
84 #define DEBUG_COMMAND_WRITE_MEMORY_64 (DEBUG_COMMAND_REQUEST | 15) // 15
86 #define DEBUG_COMMAND_READ_IO (DEBUG_COMMAND_REQUEST | 16) // 16
87 #define DEBUG_COMMAND_WRITE_IO (DEBUG_COMMAND_REQUEST | 20) // 20
89 #define DEBUG_COMMAND_READ_REGISTER (DEBUG_COMMAND_REQUEST | 24) // 24
90 #define DEBUG_COMMAND_WRITE_REGISTER (DEBUG_COMMAND_REQUEST | 26) // 26
92 #define DEBUG_COMMAND_STEP_OVER (DEBUG_COMMAND_REQUEST | 28) // 28
93 #define DEBUG_COMMAND_STEP_OUT (DEBUG_COMMAND_REQUEST | 29) // 29
94 #define DEBUG_COMMAND_STEP_BRANCH (DEBUG_COMMAND_REQUEST | 30) // 30
96 #define DEBUG_COMMAND_ARCH_MODE (DEBUG_COMMAND_REQUEST | 34) // 34
98 #define DEBUG_COMMAND_READ_MSR (DEBUG_COMMAND_REQUEST | 35) // 35
99 #define DEBUG_COMMAND_WRITE_MSR (DEBUG_COMMAND_REQUEST | 36) // 36
101 #define DEBUG_COMMAND_READ_REGISTER_GROUP (DEBUG_COMMAND_REQUEST | 37) // 37
103 #define DEBUG_COMMAND_SET_DEBUG_FLAG (DEBUG_COMMAND_REQUEST | 38) // 38
105 #define DEBUG_COMMAND_GET_REVISION (DEBUG_COMMAND_REQUEST | 39) // 39
107 #define DEBUG_COMMAND_GET_EXCEPTION (DEBUG_COMMAND_REQUEST | 40) // 40
109 #define DEBUG_COMMAND_SET_VIEWPOINT (DEBUG_COMMAND_REQUEST | 41) // 41
111 #define DEBUG_COMMAND_GET_VIEWPOINT (DEBUG_COMMAND_REQUEST | 42) // 42
114 // The below are target side initiated commands.
116 #define DEBUG_COMMAND_INIT_BREAK (DEBUG_COMMAND_REQUEST | 63) // 63
117 #define DEBUG_COMMAND_BREAK_POINT (DEBUG_COMMAND_REQUEST | 62) // 62
118 #define DEBUG_COMMAND_MEMORY_READY (DEBUG_COMMAND_REQUEST | 61) // 61
120 #define DEBUG_COMMAND_OK (DEBUG_COMMAND_RESPONSE | 0)
121 #define DEBUG_COMMAND_RESEND (DEBUG_COMMAND_RESPONSE | 1)
122 #define DEBUG_COMMAND_ABORT (DEBUG_COMMAND_RESPONSE | 2)
125 // The below 2 commands are used when transferring big data (like > ~250 bytes). The sequence is:
126 // Host Macine Target Macine
128 // <= IN_PROGRESS with part of the data
130 // (could have multiple IN_PROGRESS and CONTINUE interactions)
131 // <= OK with the last part of data
132 // OK (no data as ACK) =>
134 #define DEBUG_COMMAND_IN_PROGRESS (DEBUG_COMMAND_RESPONSE | 3) // Used when trying to
135 #define DEBUG_COMMAND_CONTINUE (DEBUG_COMMAND_RESPONSE | 4) // Used when trying to transfer big data (like > ~250 bytes)
138 // The below 2 commands are used to support deferred halt. HALT_DEFERRED will be returned when a halt request received while target is already in inter-active mode.
139 // HALT_PROCESSED will be return as a possible return value for GO command, if target has a pending halt request.
141 #define DEBUG_COMMAND_HALT_DEFERRED (DEBUG_COMMAND_RESPONSE | 5)
142 #define DEBUG_COMMAND_HALT_PROCESSED (DEBUG_COMMAND_RESPONSE | 6)
144 #define DEBUG_COMMAND_TIMEOUT (DEBUG_COMMAND_RESPONSE | 7)
145 #define DEBUG_COMMAND_NOT_SUPPORTED (DEBUG_COMMAND_RESPONSE | 15)
148 // Definition for data field for debug packets
150 #define DEBUG_DATA_MAXIMUM_LENGTH_FOR_SMALL_COMMANDS 20
152 #define DEBUG_DATA_UPPER_LIMIT 0xff // This is the upper limit for the data size, by the limit of the packet header definition.
154 #define DEBUG_DATA_MAXIMUM_REAL_DATA 0xf8
156 #define DEBUG_DEFINITION_MAX_IO_LENGTH 4
159 // Response data for DEBUG_COMMAND_BREAK_CAUSE
164 } DEBUG_DATA_RESPONSE_BREAK_CAUSE
;
167 // Break type defintions for DEBUG_DATA_BREAK_CAUSE
169 #define DEBUG_DATA_BREAK_CAUSE_UNKNOWN 0
170 #define DEBUG_DATA_BREAK_CAUSE_HW_BREAKPOINT 1
171 #define DEBUG_DATA_BREAK_CAUSE_STEPPING 2
172 #define DEBUG_DATA_BREAK_CAUSE_SW_BREAKPOINT 3
173 #define DEBUG_DATA_BREAK_CAUSE_USER_HALT 4
174 #define DEBUG_DATA_BREAK_CAUSE_IMAGE_LOAD 5
175 #define DEBUG_DATA_BREAK_CAUSE_IMAGE_UNLOAD 6
176 #define DEBUG_DATA_BREAK_CAUSE_SYSTEM_RESET 7
177 #define DEBUG_DATA_BREAK_CAUSE_EXCEPTION 8
178 #define DEBUG_DATA_BREAK_CAUSE_MEMORY_READY 9
181 // Response data for DEBUG_COMMAND_ARCH_MODE, defined as SOFT_DEBUGGER_PROCESSOR_...
185 } DEBUG_DATA_RESPONSE_ARCH_MODE
;
188 // Cpu architecture defintions for DEBUG_DATA_RESPONSE_ARCH_MODE
190 #define DEBUG_DATA_BREAK_CPU_ARCH_IA16 0
191 #define DEBUG_DATA_BREAK_CPU_ARCH_IA32 1
192 #define DEBUG_DATA_BREAK_CPU_ARCH_X64 2
195 // Command and response data for DEBUG_COMMAND_XX_YY_BREAKPOINT
198 UINT8 Length
:2; // Refer to below DEBUG_DATA_BREAKPOINT_LENGTH_XX macros
199 UINT8 Access
:2; // Refer to below DEBUG_DATA_BREAKPOINT_ACCESS_XX macros
200 UINT8 Index
:2; // Index of debug register
202 } DEBUG_DATA_BREAKPOINT_TYPE
;
204 #define DEBUG_DATA_BREAKPOINT_MEMORY_ACCESS (0x11)
205 #define DEBUG_DATA_BREAKPOINT_IO_ACCESS (0x10)
206 #define DEBUG_DATA_BREAKPOINT_MEMORY_WRITE (0x01)
207 #define DEBUG_DATA_BREAKPOINT_MEMORY_EXECUTE (0x00)
209 #define DEBUG_DATA_BREAKPOINT_LENGTH_64 (0x11)
210 #define DEBUG_DATA_BREAKPOINT_LENGTH_32 (0x10)
211 #define DEBUG_DATA_BREAKPOINT_LENGTH_16 (0x01)
212 #define DEBUG_DATA_BREAKPOINT_LENGTH_8 (0x00)
215 // Command data for DEBUG_COMMAND_SET_HW_BREAKPOINT
218 DEBUG_DATA_BREAKPOINT_TYPE Type
;
220 } DEBUG_DATA_SET_HW_BREAKPOINT
;
223 // Command data for DEBUG_COMMAND_CLEAR_HW_BREAKPOINT
226 UINT8 IndexMask
; // 0x0f will clear all hw breakpoints
227 } DEBUG_DATA_CLEAR_HW_BREAKPOINT
;
230 // Command data for DEBUG_COMMAND_SET_SW_BREAKPOINT
234 } DEBUG_DATA_SET_SW_BREAKPOINT
;
237 // Response data for DEBUG_COMMAND_SET_SW_BREAKPOINT
241 } DEBUG_DATA_RESPONSE_SET_SW_BREAKPOINT
;
244 // Command data for DEBUG_COMMAND_CLEAR_SW_BREAKPOINT
246 typedef DEBUG_DATA_SET_SW_BREAKPOINT DEBUG_DATA_CLEAR_SW_BREAKPOINT
;
249 // Command data for DEBUG_COMMAND_READ_MEMORY_XX
254 } DEBUG_DATA_READ_MEMORY_8
;
256 typedef DEBUG_DATA_READ_MEMORY_8 DEBUG_DATA_READ_MEMORY_16
;
258 typedef DEBUG_DATA_READ_MEMORY_8 DEBUG_DATA_READ_MEMORY_32
;
260 typedef DEBUG_DATA_READ_MEMORY_8 DEBUG_DATA_READ_MEMORY_64
;
263 // Command data for DEBUG_COMMAND_WRITE_MEMORY_XX
268 UINT8 Data
; // The actual length for this field is decided by Width x Count
269 } DEBUG_DATA_WRITE_MEMORY_8
;
271 typedef DEBUG_DATA_WRITE_MEMORY_8 DEBUG_DATA_WRITE_MEMORY_16
;
273 typedef DEBUG_DATA_WRITE_MEMORY_8 DEBUG_DATA_WRITE_MEMORY_32
;
275 typedef DEBUG_DATA_WRITE_MEMORY_8 DEBUG_DATA_WRITE_MEMORY_64
;
278 // Command data for DEBUG_COMMAND_READ_IO
283 } DEBUG_DATA_READ_IO
;
286 // Response data for DEBUG_COMMAND_READ_IO
289 UINT8 Data
; // The actual length of this structure will be adjusted according to the Width field
290 } DEBUG_DATA_RESPONSE_READ_IO
;
293 // Command data for DEBUG_COMMAND_WRITE_IO
298 UINT8 Data
; // The actual length of this structure will be adjusted according to the Width field
299 } DEBUG_DATA_WRITE_IO
;
302 // Command data for DEBUG_COMMAND_READ_REGISTER
305 UINT8 Index
; // defined as DEBUG_DEFINITION_REGISTER_XX
308 } DEBUG_DATA_READ_REGISTER
;
311 // Command data for DEBUG_COMMAND_WRITE_REGISTER
314 UINT8 Index
; // defined as DEBUG_DEFINITION_REGISTER_XX
318 } DEBUG_DATA_WRITE_REGISTER
;
321 // Command data for DEBUG_COMMAND_READ_MSR
325 } DEBUG_DATA_READ_MSR
;
328 // Response data for DEBUG_COMMAND_READ_MSR
332 } DEBUG_DATA_RESPONSE_READ_MSR
;
335 // Command data for DEBUG_COMMAND_WRITE_MSR
340 } DEBUG_DATA_WRITE_MSR
;
343 // Command data for DEBUG_COMMAND_READ_REGISTER_GROUP
346 // For possible values, refer to the definition for DEBUG_DEFINITION_REGISTER_GROUP_XXX (in another .h file as it is architecture specific)
348 } DEBUG_DATA_READ_REGISTER_GROUP
;
351 // Response data for DEBUG_COMMAND_GET_REVISION
356 } DEBUG_DATA_RESPONSE_GET_REVISION
;
359 // Response data for DEBUG_COMMAND_GET_EXCEPTION
363 UINT64 ExceptionData
;
364 } DEBUG_DATA_RESPONSE_GET_EXCEPTION
;
367 UINT8 DRn
; // The index of DR register which to be used as temporary breakpoint
368 } DEBUG_DATA_STEP_OVER
;
371 // Command data for DEBUG_COMMAND_SET_DEBUG_FLAG
374 UINT32 DebugFlag
; // The index of DR register which to be used as temporary breakpoint
375 } DEBUG_DATA_SET_DEBUG_FLAG
;
378 // Command data for DEBUG_COMMAND_SET_VIEWPOINT
379 // If viewpoint is changed successfully, DEBUG_COMMAND_OK will be returned.
380 // If viewpoint is not availabe, DEBUG_COMMAND_NOT_SUPPORTED will be returned.
383 UINT32 ViewPoint
; // The index of viewpoint will be set
384 } DEBUG_DATA_SET_VIEWPOINT
;
387 // Response data for DEBUG_COMMAND_GET_VIEWPOINT
390 UINT32 ViewPoint
; // The index of viewpoint will be returned
391 } DEBUG_DATA_RESPONSE_GET_VIEWPOINT
;
395 #define DEBUG_PACKET_CONSTRUCTOR_WITH_NO_DATA(DebugPacket,ShortCommandType) \
396 ((DEBUG_COMMAND_HEADER *)DebugPacket)->StartSymbol = DEBUG_STARTING_SYMBOL_NORMAL; \
397 ((DEBUG_COMMAND_HEADER *)DebugPacket)->Command = DEBUG_COMMAND_##ShortCommandType; \
398 ((DEBUG_COMMAND_HEADER *)DebugPacket)->DataLength = 0;
400 #define DEBUG_PACKET_CONSTRUCTOR_WITH_DATA(DebugPacket,ShortCommandType, DebugPacketDataPointer, PacketLength) \
401 ((DEBUG_COMMAND_HEADER *)DebugPacket)->StartSymbol = DEBUG_STARTING_SYMBOL_NORMAL; \
402 ((DEBUG_COMMAND_HEADER *)DebugPacket)->Command = DEBUG_COMMAND_##ShortCommandType; \
403 ((DEBUG_COMMAND_HEADER *)DebugPacket)->DataLength = sizeof (DEBUG_DATA_##ShortCommandType); \
404 *DebugPacketDataPointer = (DEBUG_DATA_##ShortCommandType *)((DEBUG_COMMAND_HEADER *)DebugPacket+1); \
405 *PacketLength = sizeof (DEBUG_COMMAND_HEADER) + sizeof (DEBUG_DATA_##ShortCommandType);