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