TransferProtocol.h revision 18b144ea424e476f14839e9d9d3b81fb4820a613
1/** @file 2 Transfer protocol defintions used by debug agent and host. It is only 3 intended to be used by Debug related module implementation. 4 5 Copyright (c) 2010, 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. 10 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. 13 14**/ 15 16#ifndef __TRANSFER_PROTOCOL_H__ 17#define __TRANSFER_PROTOCOL_H__ 18 19#include "ProcessorContext.h" 20#include "SoftDebuggerDefinitions.h" 21 22// 23// Definitions for break command. 24// 25#define DEBUG_STARTING_SYMBOL_BREAK (0x21) // '!' 26#define DEBUG_STARTING_SYMBOL_BREAK_STRING ("!") 27 28// 29// Definition for starting symbol of a normal debug packet. Choose a non-ASCII to avoid conflict with other serial output. 30// 31#define DEBUG_STARTING_SYMBOL_NORMAL (0xFE) 32 33 34#pragma pack(1) 35 36// 37// Definition for common header for normal debug packets (not including break command) 38// 39typedef struct { 40 UINT8 StartSymbol; 41 UINT8 Command; 42 UINT8 DataLength; 43} DEBUG_COMMAND_HEADER; 44 45// 46// Structure to facilitate debug packet header parsing or construction 47// 48typedef struct { 49 UINT8 Command; 50 UINT8 DataLength; 51} DEBUG_COMMAND_HEADER_NO_START_SYMBOL; 52 53 54// 55// Definition for Command field for debug packets 56// 57#define DEBUG_COMMAND_REQUEST (0 << 7) 58#define DEBUG_COMMAND_RESPONSE (1 << 7) 59 60 61 62#define DEBUG_COMMAND_RESET (DEBUG_COMMAND_REQUEST | 0) // 0 63 64#define DEBUG_COMMAND_GO (DEBUG_COMMAND_REQUEST | 1) // 1 65 66#define DEBUG_COMMAND_BREAK_CAUSE (DEBUG_COMMAND_REQUEST | 2) // 2 67 68#define DEBUG_COMMAND_SET_HW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 3) // 3 69#define DEBUG_COMMAND_CLEAR_HW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 4) // 4 70 71#define DEBUG_COMMAND_SINGLE_STEPPING (DEBUG_COMMAND_REQUEST | 5) // 5 72 73#define DEBUG_COMMAND_SET_SW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 6) // 6 74#define DEBUG_COMMAND_CLEAR_SW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 7) // 7 75 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 80 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 85 86#define DEBUG_COMMAND_READ_IO (DEBUG_COMMAND_REQUEST | 16) // 16 87#define DEBUG_COMMAND_WRITE_IO (DEBUG_COMMAND_REQUEST | 20) // 20 88 89#define DEBUG_COMMAND_READ_REGISTER (DEBUG_COMMAND_REQUEST | 24) // 24 90#define DEBUG_COMMAND_WRITE_REGISTER (DEBUG_COMMAND_REQUEST | 26) // 26 91 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 95 96#define DEBUG_COMMAND_ARCH_MODE (DEBUG_COMMAND_REQUEST | 34) // 34 97 98#define DEBUG_COMMAND_READ_MSR (DEBUG_COMMAND_REQUEST | 35) // 35 99#define DEBUG_COMMAND_WRITE_MSR (DEBUG_COMMAND_REQUEST | 36) // 36 100 101#define DEBUG_COMMAND_READ_REGISTER_GROUP (DEBUG_COMMAND_REQUEST | 37) // 37 102 103#define DEBUG_COMMAND_SET_DEBUG_FLAG (DEBUG_COMMAND_REQUEST | 38) // 38 104 105#define DEBUG_COMMAND_GET_REVISION (DEBUG_COMMAND_REQUEST | 39) // 30 106 107#define DEBUG_COMMAND_GET_EXCEPTION (DEBUG_COMMAND_REQUEST | 40) // 40 108 109#define DEBUG_COMMAND_SET_VIEWPOINT (DEBUG_COMMAND_REQUEST | 41) // 41 110 111#define DEBUG_COMMAND_GET_VIEWPOINT (DEBUG_COMMAND_REQUEST | 42) // 42 112 113// 114// The below are target side initiated commands. 115// 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 119 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) 123 124// 125// The below 2 commands are used when transferring big data (like > ~250 bytes). The sequence is: 126// Host Macine Target Macine 127// Request => 128// <= IN_PROGRESS with part of the data 129// CONTINUE => 130// (could have multiple IN_PROGRESS and CONTINUE interactions) 131// <= OK with the last part of data 132// OK (no data as ACK) => 133// 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) 136 137// 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. 140// 141#define DEBUG_COMMAND_HALT_DEFERRED (DEBUG_COMMAND_RESPONSE | 5) 142#define DEBUG_COMMAND_HALT_PROCESSED (DEBUG_COMMAND_RESPONSE | 6) 143 144#define DEBUG_COMMAND_NOT_SUPPORTED (DEBUG_COMMAND_RESPONSE | 15) 145 146// 147// Definition for data field for debug packets 148// 149#define DEBUG_DATA_MAXIMUM_LENGTH_FOR_SMALL_COMMANDS 20 150 151#define DEBUG_DATA_UPPER_LIMIT 0xff // This is the upper limit for the data size, by the limit of the packet header definition. 152 153#define DEBUG_DATA_MAXIMUM_REAL_DATA 0xf8 154 155#define DEBUG_DEFINITION_MAX_IO_LENGTH 4 156 157// 158// Response data for DEBUG_COMMAND_BREAK_CAUSE 159// 160typedef struct { 161 UINT8 Cause; 162 UINT64 StopAddress; 163} DEBUG_DATA_RESPONSE_BREAK_CAUSE; 164 165// 166// Break type defintions for DEBUG_DATA_BREAK_CAUSE 167// 168#define DEBUG_DATA_BREAK_CAUSE_UNKNOWN 0 169#define DEBUG_DATA_BREAK_CAUSE_HW_BREAKPOINT 1 170#define DEBUG_DATA_BREAK_CAUSE_STEPPING 2 171#define DEBUG_DATA_BREAK_CAUSE_SW_BREAKPOINT 3 172#define DEBUG_DATA_BREAK_CAUSE_USER_HALT 4 173#define DEBUG_DATA_BREAK_CAUSE_IMAGE_LOAD 5 174#define DEBUG_DATA_BREAK_CAUSE_IMAGE_UNLOAD 6 175#define DEBUG_DATA_BREAK_CAUSE_SYSTEM_RESET 7 176#define DEBUG_DATA_BREAK_CAUSE_EXCEPTION 8 177#define DEBUG_DATA_BREAK_CAUSE_MEMORY_READY 9 178 179// 180// Response data for DEBUG_COMMAND_ARCH_MODE, defined as SOFT_DEBUGGER_PROCESSOR_... 181// 182typedef struct { 183 UINT8 CpuMode; 184} DEBUG_DATA_RESPONSE_ARCH_MODE; 185 186// 187// Cpu architecture defintions for DEBUG_DATA_RESPONSE_ARCH_MODE 188// 189#define DEBUG_DATA_BREAK_CPU_ARCH_IA16 0 190#define DEBUG_DATA_BREAK_CPU_ARCH_IA32 1 191#define DEBUG_DATA_BREAK_CPU_ARCH_X64 2 192 193// 194// Command and response data for DEBUG_COMMAND_XX_YY_BREAKPOINT 195// 196typedef struct { 197 UINT8 Length:2; // Refer to below DEBUG_DATA_BREAKPOINT_LENGTH_XX macros 198 UINT8 Access:2; // Refer to below DEBUG_DATA_BREAKPOINT_ACCESS_XX macros 199 UINT8 Index:2; // Index of debug register 200 UINT8 Reserved:2; 201} DEBUG_DATA_BREAKPOINT_TYPE; 202 203#define DEBUG_DATA_BREAKPOINT_MEMORY_ACCESS (0x11) 204#define DEBUG_DATA_BREAKPOINT_IO_ACCESS (0x10) 205#define DEBUG_DATA_BREAKPOINT_MEMORY_WRITE (0x01) 206#define DEBUG_DATA_BREAKPOINT_MEMORY_EXECUTE (0x00) 207 208#define DEBUG_DATA_BREAKPOINT_LENGTH_64 (0x11) 209#define DEBUG_DATA_BREAKPOINT_LENGTH_32 (0x10) 210#define DEBUG_DATA_BREAKPOINT_LENGTH_16 (0x01) 211#define DEBUG_DATA_BREAKPOINT_LENGTH_8 (0x00) 212 213// 214// Command data for DEBUG_COMMAND_SET_HW_BREAKPOINT 215// 216typedef struct { 217 DEBUG_DATA_BREAKPOINT_TYPE Type; 218 UINT64 Address; 219} DEBUG_DATA_SET_HW_BREAKPOINT; 220 221// 222// Command data for DEBUG_COMMAND_CLEAR_HW_BREAKPOINT 223// 224typedef struct { 225 UINT8 IndexMask; // 0x0f will clear all hw breakpoints 226} DEBUG_DATA_CLEAR_HW_BREAKPOINT; 227 228// 229// Command data for DEBUG_COMMAND_SET_SW_BREAKPOINT 230// 231typedef struct { 232 UINT64 Address; 233} DEBUG_DATA_SET_SW_BREAKPOINT; 234 235// 236// Response data for DEBUG_COMMAND_SET_SW_BREAKPOINT 237// 238typedef struct { 239 UINT8 OriginalData; 240} DEBUG_DATA_RESPONSE_SET_SW_BREAKPOINT; 241 242// 243// Command data for DEBUG_COMMAND_CLEAR_SW_BREAKPOINT 244// 245typedef DEBUG_DATA_SET_SW_BREAKPOINT DEBUG_DATA_CLEAR_SW_BREAKPOINT; 246 247// 248// Command data for DEBUG_COMMAND_READ_MEMORY_XX 249// 250typedef struct { 251 UINT64 Address; 252 UINT16 Count; 253} DEBUG_DATA_READ_MEMORY_8; 254 255typedef DEBUG_DATA_READ_MEMORY_8 DEBUG_DATA_READ_MEMORY_16; 256 257typedef DEBUG_DATA_READ_MEMORY_8 DEBUG_DATA_READ_MEMORY_32; 258 259typedef DEBUG_DATA_READ_MEMORY_8 DEBUG_DATA_READ_MEMORY_64; 260 261// 262// Command data for DEBUG_COMMAND_WRITE_MEMORY_XX 263// 264typedef struct { 265 UINT64 Address; 266 UINT16 Count; 267 UINT8 Data; // The actual length for this field is decided by Width x Count 268} DEBUG_DATA_WRITE_MEMORY_8; 269 270typedef DEBUG_DATA_WRITE_MEMORY_8 DEBUG_DATA_WRITE_MEMORY_16; 271 272typedef DEBUG_DATA_WRITE_MEMORY_8 DEBUG_DATA_WRITE_MEMORY_32; 273 274typedef DEBUG_DATA_WRITE_MEMORY_8 DEBUG_DATA_WRITE_MEMORY_64; 275 276// 277// Command data for DEBUG_COMMAND_READ_IO 278// 279typedef struct { 280 UINT16 Port; 281 UINT8 Width; 282} DEBUG_DATA_READ_IO; 283 284// 285// Response data for DEBUG_COMMAND_READ_IO 286// 287typedef struct { 288 UINT8 Data; // The actual length of this structure will be adjusted according to the Width field 289} DEBUG_DATA_RESPONSE_READ_IO; 290 291// 292// Command data for DEBUG_COMMAND_WRITE_IO 293// 294typedef struct { 295 UINT16 Port; 296 UINT8 Width; 297 UINT8 Data; // The actual length of this structure will be adjusted according to the Width field 298} DEBUG_DATA_WRITE_IO; 299 300// 301// Command data for DEBUG_COMMAND_READ_REGISTER 302// 303typedef struct { 304 UINT8 Index; // defined as DEBUG_DEFINITION_REGISTER_XX 305 UINT8 Offset:4; 306 UINT8 Length:4; 307} DEBUG_DATA_READ_REGISTER; 308 309// 310// Command data for DEBUG_COMMAND_WRITE_REGISTER 311// 312typedef struct { 313 UINT8 Index; // defined as DEBUG_DEFINITION_REGISTER_XX 314 UINT8 Offset:4; 315 UINT8 Length:4; 316 UINT64 Value; 317} DEBUG_DATA_WRITE_REGISTER; 318 319// 320// Command data for DEBUG_COMMAND_READ_MSR 321// 322typedef struct { 323 UINT32 Index; 324} DEBUG_DATA_READ_MSR; 325 326// 327// Response data for DEBUG_COMMAND_READ_MSR 328// 329typedef struct { 330 UINT64 Value; 331} DEBUG_DATA_RESPONSE_READ_MSR; 332 333// 334// Command data for DEBUG_COMMAND_WRITE_MSR 335// 336typedef struct { 337 UINT32 Index; 338 UINT64 Value; 339} DEBUG_DATA_WRITE_MSR; 340 341// 342// Command data for DEBUG_COMMAND_READ_REGISTER_GROUP 343// 344typedef struct { 345 // For possible values, refer to the definition for DEBUG_DEFINITION_REGISTER_GROUP_XXX (in another .h file as it is architecture specific) 346 UINT8 Index; 347} DEBUG_DATA_READ_REGISTER_GROUP; 348 349// 350// Response data for DEBUG_COMMAND_GET_REVISION 351// 352typedef struct { 353 UINT32 Revision; 354 UINT32 Capabilities; 355} DEBUG_DATA_RESPONSE_GET_REVISION; 356 357// 358// Response data for DEBUG_COMMAND_GET_EXCEPTION 359// 360typedef struct { 361 UINT8 ExceptionNum; 362 UINT64 ExceptionData; 363} DEBUG_DATA_RESPONSE_GET_EXCEPTION; 364 365typedef struct { 366 UINT8 DRn; // The index of DR register which to be used as temporary breakpoint 367} DEBUG_DATA_STEP_OVER; 368 369// 370// Command data for DEBUG_COMMAND_SET_DEBUG_FLAG 371// 372typedef struct { 373 UINT32 DebugFlag; // The index of DR register which to be used as temporary breakpoint 374} DEBUG_DATA_SET_DEBUG_FLAG; 375 376// 377// Command data for DEBUG_COMMAND_SET_VIEWPOINT 378// If viewpoint is changed successfully, DEBUG_COMMAND_OK will be returned. 379// If viewpoint is not availabe, DEBUG_COMMAND_NOT_SUPPORTED will be returned. 380// 381typedef struct { 382 UINT32 ViewPoint; // The index of viewpoint will be set 383} DEBUG_DATA_SET_VIEWPOINT; 384 385// 386// Response data for DEBUG_COMMAND_GET_VIEWPOINT 387// 388typedef struct { 389 UINT32 ViewPoint; // The index of viewpoint will be returned 390} DEBUG_DATA_RESPONSE_GET_VIEWPOINT; 391 392#pragma pack() 393 394#define DEBUG_PACKET_CONSTRUCTOR_WITH_NO_DATA(DebugPacket,ShortCommandType) \ 395 ((DEBUG_COMMAND_HEADER *)DebugPacket)->StartSymbol = DEBUG_STARTING_SYMBOL_NORMAL; \ 396 ((DEBUG_COMMAND_HEADER *)DebugPacket)->Command = DEBUG_COMMAND_##ShortCommandType; \ 397 ((DEBUG_COMMAND_HEADER *)DebugPacket)->DataLength = 0; 398 399#define DEBUG_PACKET_CONSTRUCTOR_WITH_DATA(DebugPacket,ShortCommandType, DebugPacketDataPointer, PacketLength) \ 400 ((DEBUG_COMMAND_HEADER *)DebugPacket)->StartSymbol = DEBUG_STARTING_SYMBOL_NORMAL; \ 401 ((DEBUG_COMMAND_HEADER *)DebugPacket)->Command = DEBUG_COMMAND_##ShortCommandType; \ 402 ((DEBUG_COMMAND_HEADER *)DebugPacket)->DataLength = sizeof (DEBUG_DATA_##ShortCommandType); \ 403 *DebugPacketDataPointer = (DEBUG_DATA_##ShortCommandType *)((DEBUG_COMMAND_HEADER *)DebugPacket+1); \ 404 *PacketLength = sizeof (DEBUG_COMMAND_HEADER) + sizeof (DEBUG_DATA_##ShortCommandType); 405 406#endif 407 408