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 - 2015, 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 21 // 22 // Current revision of transfer protocol 23 // 0.4: Packet compression and decompression. 24 // 25 #define DEBUG_AGENT_REVISION_03 ((0 << 16) | 03) 26 #define DEBUG_AGENT_REVISION_04 ((0 << 16) | 04) 27 #define DEBUG_AGENT_REVISION DEBUG_AGENT_REVISION_04 28 #define DEBUG_AGENT_CAPABILITIES 0 29 30 // 31 // Definitions for the (A)ttach command 32 // 33 #define DEBUG_STARTING_SYMBOL_ATTACH (0xFA) 34 35 // 36 // Definition for starting symbol of a normal debug packet. Choose a non-ASCII to avoid conflict with other serial output. 37 // 38 #define DEBUG_STARTING_SYMBOL_NORMAL (0xFE) 39 40 // 41 // Definition for starting symbol of a (C)ompressed debug packet. Choose a non-ASCII to avoid conflict with other serial output. 42 // 43 #define DEBUG_STARTING_SYMBOL_COMPRESS (0xFC) 44 45 #pragma pack(1) 46 47 // 48 // Definition for debug packet header for debug packets (not including attach command) 49 // 50 typedef struct { 51 UINT8 StartSymbol; 52 UINT8 Command; 53 UINT8 Length; // Length of Debug Packet including header and payload in byte 54 UINT8 SequenceNo; 55 UINT16 Crc; 56 } DEBUG_PACKET_HEADER; 57 58 // 59 // Definition for Command field for debug packets 60 // 61 #define DEBUG_COMMAND_REQUEST (0 << 7) 62 #define DEBUG_COMMAND_RESPONSE (1 << 7) 63 64 #define IS_REQUEST(x) (((x)->Command & DEBUG_COMMAND_RESPONSE) == 0) 65 66 // 67 // HOST initiated commands 68 // 69 #define DEBUG_COMMAND_RESET (DEBUG_COMMAND_REQUEST | 0x00) 70 #define DEBUG_COMMAND_GO (DEBUG_COMMAND_REQUEST | 0x01) 71 #define DEBUG_COMMAND_BREAK_CAUSE (DEBUG_COMMAND_REQUEST | 0x02) 72 #define DEBUG_COMMAND_SET_HW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 0x03) 73 #define DEBUG_COMMAND_CLEAR_HW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 0x04) 74 #define DEBUG_COMMAND_SINGLE_STEPPING (DEBUG_COMMAND_REQUEST | 0x05) 75 #define DEBUG_COMMAND_SET_SW_BREAKPOINT (DEBUG_COMMAND_REQUEST | 0x06) 76 #define DEBUG_COMMAND_READ_MEMORY (DEBUG_COMMAND_REQUEST | 0x07) 77 #define DEBUG_COMMAND_WRITE_MEMORY (DEBUG_COMMAND_REQUEST | 0x08) 78 #define DEBUG_COMMAND_READ_IO (DEBUG_COMMAND_REQUEST | 0x09) 79 #define DEBUG_COMMAND_WRITE_IO (DEBUG_COMMAND_REQUEST | 0x0A) 80 #define DEBUG_COMMAND_READ_REGISTER (DEBUG_COMMAND_REQUEST | 0x0B) 81 #define DEBUG_COMMAND_WRITE_REGISTER (DEBUG_COMMAND_REQUEST | 0x0C) 82 #define DEBUG_COMMAND_READ_ALL_REGISTERS (DEBUG_COMMAND_REQUEST | 0x0D) 83 #define DEBUG_COMMAND_ARCH_MODE (DEBUG_COMMAND_REQUEST | 0x0E) 84 #define DEBUG_COMMAND_READ_MSR (DEBUG_COMMAND_REQUEST | 0x0F) 85 #define DEBUG_COMMAND_WRITE_MSR (DEBUG_COMMAND_REQUEST | 0x10) 86 #define DEBUG_COMMAND_SET_DEBUG_SETTING (DEBUG_COMMAND_REQUEST | 0x11) 87 #define DEBUG_COMMAND_GET_REVISION (DEBUG_COMMAND_REQUEST | 0x12) 88 #define DEBUG_COMMAND_GET_EXCEPTION (DEBUG_COMMAND_REQUEST | 0x13) 89 #define DEBUG_COMMAND_SET_VIEWPOINT (DEBUG_COMMAND_REQUEST | 0x14) 90 #define DEBUG_COMMAND_GET_VIEWPOINT (DEBUG_COMMAND_REQUEST | 0x15) 91 #define DEBUG_COMMAND_DETACH (DEBUG_COMMAND_REQUEST | 0x16) 92 #define DEBUG_COMMAND_CPUID (DEBUG_COMMAND_REQUEST | 0x17) 93 #define DEBUG_COMMAND_SEARCH_SIGNATURE (DEBUG_COMMAND_REQUEST | 0x18) 94 #define DEBUG_COMMAND_HALT (DEBUG_COMMAND_REQUEST | 0x19) 95 96 // 97 // TARGET initiated commands 98 // 99 #define DEBUG_COMMAND_INIT_BREAK (DEBUG_COMMAND_REQUEST | 0x3F) 100 #define DEBUG_COMMAND_BREAK_POINT (DEBUG_COMMAND_REQUEST | 0x3E) 101 #define DEBUG_COMMAND_MEMORY_READY (DEBUG_COMMAND_REQUEST | 0x3D) 102 #define DEBUG_COMMAND_PRINT_MESSAGE (DEBUG_COMMAND_REQUEST | 0x3C) 103 #define DEBUG_COMMAND_ATTACH_BREAK (DEBUG_COMMAND_REQUEST | 0x3B) 104 105 // 106 // Response commands 107 // 108 #define DEBUG_COMMAND_OK (DEBUG_COMMAND_RESPONSE | 0x00) 109 #define DEBUG_COMMAND_RESEND (DEBUG_COMMAND_RESPONSE | 0x01) 110 #define DEBUG_COMMAND_ABORT (DEBUG_COMMAND_RESPONSE | 0x02) 111 // 112 // The below 2 commands are used when transferring big data (like > ~250 bytes). 113 // The sequence is: 114 // HOST TARGET 115 // Request => 116 // <= IN_PROGRESS with partial data 117 // CONTINUE => 118 // (could have multiple IN_PROGRESS and CONTINUE interactions) 119 // <= OK with the last part of data 120 // OK (no data as ACK) => 121 // 122 #define DEBUG_COMMAND_IN_PROGRESS (DEBUG_COMMAND_RESPONSE | 0x03) 123 #define DEBUG_COMMAND_CONTINUE (DEBUG_COMMAND_RESPONSE | 0x04) 124 // 125 // The below 2 commands are used to support deferred halt: 126 // TARGET returns HALT_DEFERRED when it receives a HALT request in inter-active mode. 127 // TARGET returns HALT_PROCESSED when it receives a GO request and has a pending HALT request. 128 // 129 #define DEBUG_COMMAND_HALT_DEFERRED (DEBUG_COMMAND_RESPONSE | 0x05) 130 #define DEBUG_COMMAND_HALT_PROCESSED (DEBUG_COMMAND_RESPONSE | 0x06) 131 132 #define DEBUG_COMMAND_TIMEOUT (DEBUG_COMMAND_RESPONSE | 0x07) 133 #define DEBUG_COMMAND_NOT_SUPPORTED (DEBUG_COMMAND_RESPONSE | 0x0F) 134 135 // 136 // Definition for data field for debug packets 137 // 138 #define DEBUG_DATA_UPPER_LIMIT 0xff // Upper limit for the data size, by the limit of the packet header definition. 139 140 #define DEBUG_DATA_MAXIMUM_REAL_DATA (DEBUG_DATA_UPPER_LIMIT - sizeof (DEBUG_PACKET_HEADER)) 141 142 // 143 // Response data for DEBUG_COMMAND_BREAK_CAUSE 144 // 145 typedef struct { 146 UINT8 Cause; 147 UINT64 StopAddress; 148 } DEBUG_DATA_RESPONSE_BREAK_CAUSE; 149 // 150 // Break type defintions for DEBUG_DATA_BREAK_CAUSE 151 // 152 #define DEBUG_DATA_BREAK_CAUSE_UNKNOWN 0 153 #define DEBUG_DATA_BREAK_CAUSE_HW_BREAKPOINT 1 154 #define DEBUG_DATA_BREAK_CAUSE_STEPPING 2 155 #define DEBUG_DATA_BREAK_CAUSE_SW_BREAKPOINT 3 156 #define DEBUG_DATA_BREAK_CAUSE_USER_HALT 4 157 #define DEBUG_DATA_BREAK_CAUSE_IMAGE_LOAD 5 158 #define DEBUG_DATA_BREAK_CAUSE_IMAGE_UNLOAD 6 159 #define DEBUG_DATA_BREAK_CAUSE_SYSTEM_RESET 7 160 #define DEBUG_DATA_BREAK_CAUSE_EXCEPTION 8 161 #define DEBUG_DATA_BREAK_CAUSE_MEMORY_READY 9 162 163 // 164 // Response data for DEBUG_COMMAND_ARCH_MODE, defined as SOFT_DEBUGGER_PROCESSOR_... 165 // 166 typedef struct { 167 UINT8 CpuMode; 168 } DEBUG_DATA_RESPONSE_ARCH_MODE; 169 // 170 // Cpu architecture defintions for DEBUG_DATA_RESPONSE_ARCH_MODE 171 // 172 #define DEBUG_DATA_BREAK_CPU_ARCH_IA16 0 173 #define DEBUG_DATA_BREAK_CPU_ARCH_IA32 1 174 #define DEBUG_DATA_BREAK_CPU_ARCH_X64 2 175 176 typedef struct { 177 UINT8 Length:2; // Refer to below DEBUG_DATA_BREAKPOINT_LENGTH_XX macros 178 UINT8 Access:2; // Refer to below DEBUG_DATA_BREAKPOINT_ACCESS_XX macros 179 UINT8 Index:2; // Index of debug register 180 UINT8 Reserved:2; 181 } DEBUG_DATA_BREAKPOINT_TYPE; 182 #define DEBUG_DATA_BREAKPOINT_MEMORY_ACCESS (0x3) 183 #define DEBUG_DATA_BREAKPOINT_IO_ACCESS (0x2) 184 #define DEBUG_DATA_BREAKPOINT_MEMORY_WRITE (0x1) 185 #define DEBUG_DATA_BREAKPOINT_MEMORY_EXECUTE (0x0) 186 #define DEBUG_DATA_BREAKPOINT_LENGTH_32 (0x3) 187 #define DEBUG_DATA_BREAKPOINT_LENGTH_64 (0x2) 188 #define DEBUG_DATA_BREAKPOINT_LENGTH_16 (0x1) 189 #define DEBUG_DATA_BREAKPOINT_LENGTH_8 (0x0) 190 191 // 192 // Request data for DEBUG_COMMAND_SET_HW_BREAKPOINT 193 // 194 typedef struct { 195 DEBUG_DATA_BREAKPOINT_TYPE Type; 196 UINT64 Address; 197 } DEBUG_DATA_SET_HW_BREAKPOINT; 198 199 // 200 // Request data for DEBUG_COMMAND_CLEAR_HW_BREAKPOINT 201 // 202 typedef struct { 203 UINT8 IndexMask; // 0x0f will clear all hw breakpoints 204 } DEBUG_DATA_CLEAR_HW_BREAKPOINT; 205 206 // 207 // Request and response data for DEBUG_COMMAND_SET_SW_BREAKPOINT 208 // 209 typedef struct { 210 UINT64 Address; 211 } DEBUG_DATA_SET_SW_BREAKPOINT; 212 213 typedef struct { 214 UINT8 OriginalData; 215 } DEBUG_DATA_RESPONSE_SET_SW_BREAKPOINT; 216 217 // 218 // Request data for DEBUG_COMMAND_READ_MEMORY 219 // 220 typedef struct { 221 UINT64 Address; 222 UINT8 Width; 223 UINT16 Count; 224 } DEBUG_DATA_READ_MEMORY; 225 226 // 227 // Request data for DEBUG_COMMAND_WRITE_MEMORY 228 // 229 typedef struct { 230 UINT64 Address; 231 UINT8 Width; 232 UINT16 Count; 233 UINT8 Data[1]; // The actual length is (Width * Count) 234 } DEBUG_DATA_WRITE_MEMORY; 235 236 // 237 // Request and response data for DEBUG_COMMAND_READ_IO 238 // 239 typedef struct { 240 UINT64 Port; 241 UINT8 Width; 242 } DEBUG_DATA_READ_IO; 243 244 typedef struct { 245 UINT8 Data[1]; // The actual length depends on the packet header 246 } DEBUG_DATA_RESPONSE_READ_IO; 247 248 // 249 // Request data for DEBUG_COMMAND_WRITE_IO 250 // 251 typedef struct { 252 UINT64 Port; 253 UINT8 Width; 254 UINT8 Data[1]; // The actual length is Width 255 } DEBUG_DATA_WRITE_IO; 256 257 // 258 // Request data for DEBUG_COMMAND_READ_REGISTER 259 // 260 typedef struct { 261 UINT8 Index; // defined as SOFT_DEBUGGER_REGISTER_XX 262 } DEBUG_DATA_READ_REGISTER; 263 264 // 265 // Request data for DEBUG_COMMAND_WRITE_REGISTER 266 // 267 typedef struct { 268 UINT8 Index; // defined as SOFT_DEBUGGER_REGISTER_XX 269 UINT8 Length; 270 UINT8 Data[1]; // The actual length is Length 271 } DEBUG_DATA_WRITE_REGISTER; 272 273 // 274 // Request and response data for DEBUG_COMMAND_READ_MSR 275 // 276 typedef struct { 277 UINT32 Index; 278 } DEBUG_DATA_READ_MSR; 279 280 typedef struct { 281 UINT64 Value; 282 } DEBUG_DATA_RESPONSE_READ_MSR; 283 284 // 285 // Request data for DEBUG_COMMAND_WRITE_MSR 286 // 287 typedef struct { 288 UINT32 Index; 289 UINT64 Value; 290 } DEBUG_DATA_WRITE_MSR; 291 292 // 293 // Response data for DEBUG_COMMAND_GET_REVISION 294 // 295 typedef struct { 296 UINT32 Revision; 297 UINT32 Capabilities; 298 } DEBUG_DATA_RESPONSE_GET_REVISION; 299 300 // 301 // Response data for DEBUG_COMMAND_GET_EXCEPTION 302 // 303 typedef struct { 304 UINT8 ExceptionNum; 305 UINT32 ExceptionData; 306 } DEBUG_DATA_RESPONSE_GET_EXCEPTION; 307 308 // 309 // Request data for DEBUG_DATA_SET_DEBUG_SETTING 310 // 311 typedef struct { 312 UINT8 Key; 313 UINT8 Value; 314 } DEBUG_DATA_SET_DEBUG_SETTING; 315 // 316 // Supported keys 317 // 318 #define DEBUG_AGENT_SETTING_SMM_ENTRY_BREAK 1 319 #define DEBUG_AGENT_SETTING_PRINT_ERROR_LEVEL 2 320 #define DEBUG_AGENT_SETTING_BOOT_SCRIPT_ENTRY_BREAK 3 321 // 322 // Bitmask of print error level for debug message 323 // 324 #define DEBUG_AGENT_ERROR BIT0 325 #define DEBUG_AGENT_WARNING BIT1 326 #define DEBUG_AGENT_INFO BIT2 327 #define DEBUG_AGENT_VERBOSE BIT3 328 329 // 330 // Request data for DEBUG_COMMAND_SET_VIEWPOINT 331 // 332 typedef struct { 333 UINT32 ViewPoint; // The index of viewpoint will be set 334 } DEBUG_DATA_SET_VIEWPOINT; 335 336 // 337 // Response data for DEBUG_COMMAND_GET_VIEWPOINT 338 // 339 typedef struct { 340 UINT32 ViewPoint; // The index of viewpoint will be returned 341 } DEBUG_DATA_RESPONSE_GET_VIEWPOINT; 342 343 // 344 // Request and response data for DEBUG_COMMAND_CPUID 345 // 346 typedef struct { 347 UINT32 Eax; // The value of EAX prior to invoking the CPUID instruction 348 UINT32 Ecx; // The value of ECX prior to invoking the CPUID instruction 349 } DEBUG_DATA_CPUID; 350 351 typedef struct { 352 UINT32 Eax; // The value of EAX returned by the CPUID instruction 353 UINT32 Ebx; // The value of EBX returned by the CPUID instruction 354 UINT32 Ecx; // The value of ECX returned by the CPUID instruction 355 UINT32 Edx; // The value of EDX returned by the CPUID instruction 356 } DEBUG_DATA_RESPONSE_CPUID; 357 358 // 359 // Request and response data for DEBUG_COMMAND_SEARCH_SIGNATURE 360 // 361 typedef struct { 362 UINT64 Start; 363 UINT32 Count; 364 UINT32 Alignment; 365 BOOLEAN Positive; // TRUE to search in higher address memory 366 UINT8 DataLength; 367 UINT8 Data[1]; 368 } DEBUG_DATA_SEARCH_SIGNATURE; 369 370 typedef struct { 371 UINT64 Address; // -1 indicates not found 372 } DEBUG_DATA_RESPONSE_SEARCH_SIGNATURE; 373 374 #pragma pack() 375 376 #endif 377 378