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