SourceLevelDebugPkg/Include/TransferProtocol.h

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