SourceLevelDebugPkg/Include/TransferProtocol.h

/** @file
  Transfer protocol definitions used by debug agent and host. It is only
  intended to be used by Debug related module implementation.

  Copyright (c) 2010 - 2017, Intel Corporation. All rights reserved.<BR>
  SPDX-License-Identifier: BSD-2-Clause-Patent

**/

#ifndef __TRANSFER_PROTOCOL_H__
#define __TRANSFER_PROTOCOL_H__

#include "ProcessorContext.h"

//
// Current revision of transfer protocol
// 0.4: Packet compression and decompression.
//
#define DEBUG_AGENT_REVISION_03   ((0 << 16) | 03)
#define DEBUG_AGENT_REVISION_04   ((0 << 16) | 04)
#define DEBUG_AGENT_CAPABILITIES  0

//
// Definitions for the (A)ttach command
//
#define DEBUG_STARTING_SYMBOL_ATTACH  (0xFA)

//
// Definition for starting symbol of a normal debug packet. Choose a non-ASCII to avoid conflict with other serial output.
//
#define DEBUG_STARTING_SYMBOL_NORMAL  (0xFE)

//
// Definition for starting symbol of a (C)ompressed debug packet. Choose a non-ASCII to avoid conflict with other serial output.
//
#define DEBUG_STARTING_SYMBOL_COMPRESS  (0xFC)

#pragma pack(1)

//
// Definition for debug packet header for debug packets (not including attach command)
//
typedef struct {
  UINT8     StartSymbol;
  UINT8     Command;
  UINT8     Length;                     // Length of Debug Packet including header and payload in byte
  UINT8     SequenceNo;
  UINT16    Crc;
} DEBUG_PACKET_HEADER;

//
// Definition for Command field for debug packets
//
#define DEBUG_COMMAND_REQUEST   (0 << 7)
#define DEBUG_COMMAND_RESPONSE  (1 << 7)

#define IS_REQUEST(x)  (((x)->Command & DEBUG_COMMAND_RESPONSE) == 0)

//
// HOST initiated commands
//
#define DEBUG_COMMAND_RESET                (DEBUG_COMMAND_REQUEST | 0x00)
#define DEBUG_COMMAND_GO                   (DEBUG_COMMAND_REQUEST | 0x01)
#define DEBUG_COMMAND_BREAK_CAUSE          (DEBUG_COMMAND_REQUEST | 0x02)
#define DEBUG_COMMAND_SET_HW_BREAKPOINT    (DEBUG_COMMAND_REQUEST | 0x03)
#define DEBUG_COMMAND_CLEAR_HW_BREAKPOINT  (DEBUG_COMMAND_REQUEST | 0x04)
#define DEBUG_COMMAND_SINGLE_STEPPING      (DEBUG_COMMAND_REQUEST | 0x05)
#define DEBUG_COMMAND_SET_SW_BREAKPOINT    (DEBUG_COMMAND_REQUEST | 0x06)
#define DEBUG_COMMAND_READ_MEMORY          (DEBUG_COMMAND_REQUEST | 0x07)
#define DEBUG_COMMAND_WRITE_MEMORY         (DEBUG_COMMAND_REQUEST | 0x08)
#define DEBUG_COMMAND_READ_IO              (DEBUG_COMMAND_REQUEST | 0x09)
#define DEBUG_COMMAND_WRITE_IO             (DEBUG_COMMAND_REQUEST | 0x0A)
#define DEBUG_COMMAND_READ_REGISTER        (DEBUG_COMMAND_REQUEST | 0x0B)
#define DEBUG_COMMAND_WRITE_REGISTER       (DEBUG_COMMAND_REQUEST | 0x0C)
#define DEBUG_COMMAND_READ_ALL_REGISTERS   (DEBUG_COMMAND_REQUEST | 0x0D)
#define DEBUG_COMMAND_ARCH_MODE            (DEBUG_COMMAND_REQUEST | 0x0E)
#define DEBUG_COMMAND_READ_MSR             (DEBUG_COMMAND_REQUEST | 0x0F)
#define DEBUG_COMMAND_WRITE_MSR            (DEBUG_COMMAND_REQUEST | 0x10)
#define DEBUG_COMMAND_SET_DEBUG_SETTING    (DEBUG_COMMAND_REQUEST | 0x11)
#define DEBUG_COMMAND_GET_REVISION         (DEBUG_COMMAND_REQUEST | 0x12)
#define DEBUG_COMMAND_GET_EXCEPTION        (DEBUG_COMMAND_REQUEST | 0x13)
#define DEBUG_COMMAND_SET_VIEWPOINT        (DEBUG_COMMAND_REQUEST | 0x14)
#define DEBUG_COMMAND_GET_VIEWPOINT        (DEBUG_COMMAND_REQUEST | 0x15)
#define DEBUG_COMMAND_DETACH               (DEBUG_COMMAND_REQUEST | 0x16)
#define DEBUG_COMMAND_CPUID                (DEBUG_COMMAND_REQUEST | 0x17)
#define DEBUG_COMMAND_SEARCH_SIGNATURE     (DEBUG_COMMAND_REQUEST | 0x18)
#define DEBUG_COMMAND_HALT                 (DEBUG_COMMAND_REQUEST | 0x19)

//
// TARGET initiated commands
//
#define DEBUG_COMMAND_INIT_BREAK     (DEBUG_COMMAND_REQUEST | 0x3F)
#define DEBUG_COMMAND_BREAK_POINT    (DEBUG_COMMAND_REQUEST | 0x3E)
#define DEBUG_COMMAND_MEMORY_READY   (DEBUG_COMMAND_REQUEST | 0x3D)
#define DEBUG_COMMAND_PRINT_MESSAGE  (DEBUG_COMMAND_REQUEST | 0x3C)
#define DEBUG_COMMAND_ATTACH_BREAK   (DEBUG_COMMAND_REQUEST | 0x3B)

//
// Response commands
//
#define DEBUG_COMMAND_OK      (DEBUG_COMMAND_RESPONSE | 0x00)
#define DEBUG_COMMAND_RESEND  (DEBUG_COMMAND_RESPONSE | 0x01)
#define DEBUG_COMMAND_ABORT   (DEBUG_COMMAND_RESPONSE | 0x02)
//
// The below 2 commands are used when transferring big data (like > ~250 bytes).
// The sequence is:
//   HOST                             TARGET
//   Request                =>
//                          <=        IN_PROGRESS with partial data
//   CONTINUE               =>
//   (could have multiple IN_PROGRESS and CONTINUE interactions)
//                          <=        OK with the last part of data
//   OK (no data as ACK)    =>
//
#define DEBUG_COMMAND_IN_PROGRESS  (DEBUG_COMMAND_RESPONSE | 0x03)
#define DEBUG_COMMAND_CONTINUE     (DEBUG_COMMAND_RESPONSE | 0x04)
//
// The below 2 commands are used to support deferred halt:
// TARGET returns HALT_DEFERRED when it receives a HALT request in inter-active mode.
// TARGET returns HALT_PROCESSED when it receives a GO request and has a pending HALT request.
//
#define DEBUG_COMMAND_HALT_DEFERRED   (DEBUG_COMMAND_RESPONSE | 0x05)
#define DEBUG_COMMAND_HALT_PROCESSED  (DEBUG_COMMAND_RESPONSE | 0x06)

#define DEBUG_COMMAND_TIMEOUT        (DEBUG_COMMAND_RESPONSE | 0x07)
#define DEBUG_COMMAND_NOT_SUPPORTED  (DEBUG_COMMAND_RESPONSE | 0x0F)

//
// Definition for data field for debug packets
//
#define DEBUG_DATA_UPPER_LIMIT  0xff                    // Upper limit for the data size, by the limit of the packet header definition.

#define DEBUG_DATA_MAXIMUM_REAL_DATA  (DEBUG_DATA_UPPER_LIMIT - sizeof (DEBUG_PACKET_HEADER))

//
// Response data for DEBUG_COMMAND_BREAK_CAUSE
//
typedef struct {
  UINT8     Cause;
  UINT64    StopAddress;
} DEBUG_DATA_RESPONSE_BREAK_CAUSE;
//
// Break type definitions for DEBUG_DATA_BREAK_CAUSE
//
#define DEBUG_DATA_BREAK_CAUSE_UNKNOWN        0
#define DEBUG_DATA_BREAK_CAUSE_HW_BREAKPOINT  1
#define DEBUG_DATA_BREAK_CAUSE_STEPPING       2
#define DEBUG_DATA_BREAK_CAUSE_SW_BREAKPOINT  3
#define DEBUG_DATA_BREAK_CAUSE_USER_HALT      4
#define DEBUG_DATA_BREAK_CAUSE_IMAGE_LOAD     5
#define DEBUG_DATA_BREAK_CAUSE_IMAGE_UNLOAD   6
#define DEBUG_DATA_BREAK_CAUSE_SYSTEM_RESET   7
#define DEBUG_DATA_BREAK_CAUSE_EXCEPTION      8
#define DEBUG_DATA_BREAK_CAUSE_MEMORY_READY   9

//
// Response data for DEBUG_COMMAND_ARCH_MODE, defined as SOFT_DEBUGGER_PROCESSOR_...
//
typedef struct {
  UINT8    CpuMode;
} DEBUG_DATA_RESPONSE_ARCH_MODE;
//
// Cpu architecture definitions for DEBUG_DATA_RESPONSE_ARCH_MODE
//
#define DEBUG_DATA_BREAK_CPU_ARCH_IA16  0
#define DEBUG_DATA_BREAK_CPU_ARCH_IA32  1
#define DEBUG_DATA_BREAK_CPU_ARCH_X64   2

typedef struct {
  UINT8    Length   : 2;             // Refer to below DEBUG_DATA_BREAKPOINT_LENGTH_XX macros
  UINT8    Access   : 2;             // Refer to below DEBUG_DATA_BREAKPOINT_ACCESS_XX macros
  UINT8    Index    : 2;             // Index of debug register
  UINT8    Reserved : 2;
} DEBUG_DATA_BREAKPOINT_TYPE;
#define DEBUG_DATA_BREAKPOINT_MEMORY_ACCESS   (0x3)
#define DEBUG_DATA_BREAKPOINT_IO_ACCESS       (0x2)
#define DEBUG_DATA_BREAKPOINT_MEMORY_WRITE    (0x1)
#define DEBUG_DATA_BREAKPOINT_MEMORY_EXECUTE  (0x0)
#define DEBUG_DATA_BREAKPOINT_LENGTH_32       (0x3)
#define DEBUG_DATA_BREAKPOINT_LENGTH_64       (0x2)
#define DEBUG_DATA_BREAKPOINT_LENGTH_16       (0x1)
#define DEBUG_DATA_BREAKPOINT_LENGTH_8        (0x0)

//
// Request data for DEBUG_COMMAND_SET_HW_BREAKPOINT
//
typedef struct {
  DEBUG_DATA_BREAKPOINT_TYPE    Type;
  UINT64                        Address;
} DEBUG_DATA_SET_HW_BREAKPOINT;

//
// Request data for DEBUG_COMMAND_CLEAR_HW_BREAKPOINT
//
typedef struct {
  UINT8    IndexMask;                    // 0x0f will clear all hw breakpoints
} DEBUG_DATA_CLEAR_HW_BREAKPOINT;

//
// Request and response data for DEBUG_COMMAND_SET_SW_BREAKPOINT
//
typedef struct {
  UINT64    Address;
} DEBUG_DATA_SET_SW_BREAKPOINT;

typedef struct {
  UINT8    OriginalData;
} DEBUG_DATA_RESPONSE_SET_SW_BREAKPOINT;

//
// Request data for DEBUG_COMMAND_READ_MEMORY
//
typedef struct {
  UINT64    Address;
  UINT8     Width;
  UINT16    Count;
} DEBUG_DATA_READ_MEMORY;

//
// Request data for DEBUG_COMMAND_WRITE_MEMORY
//
typedef struct {
  UINT64    Address;
  UINT8     Width;
  UINT16    Count;
  UINT8     Data[1];                   // The actual length is (Width * Count)
} DEBUG_DATA_WRITE_MEMORY;

//
// Request and response data for DEBUG_COMMAND_READ_IO
//
typedef struct {
  UINT64    Port;
  UINT8     Width;
} DEBUG_DATA_READ_IO;

typedef struct {
  UINT8    Data[1];                    // The actual length depends on the packet header
} DEBUG_DATA_RESPONSE_READ_IO;

//
// Request data for DEBUG_COMMAND_WRITE_IO
//
typedef struct {
  UINT64    Port;
  UINT8     Width;
  UINT8     Data[1];                   // The actual length is Width
} DEBUG_DATA_WRITE_IO;

//
// Request data for DEBUG_COMMAND_READ_REGISTER
//
typedef struct {
  UINT8    Index;                     // defined as SOFT_DEBUGGER_REGISTER_XX
} DEBUG_DATA_READ_REGISTER;

//
// Request data for DEBUG_COMMAND_WRITE_REGISTER
//
typedef struct {
  UINT8    Index;                     // defined as SOFT_DEBUGGER_REGISTER_XX
  UINT8    Length;
  UINT8    Data[1];                   // The actual length is Length
} DEBUG_DATA_WRITE_REGISTER;

//
// Request and response data for DEBUG_COMMAND_READ_MSR
//
typedef struct {
  UINT32    Index;
} DEBUG_DATA_READ_MSR;

typedef struct {
  UINT64    Value;
} DEBUG_DATA_RESPONSE_READ_MSR;

//
// Request data for DEBUG_COMMAND_WRITE_MSR
//
typedef struct {
  UINT32    Index;
  UINT64    Value;
} DEBUG_DATA_WRITE_MSR;

//
// Response data for DEBUG_COMMAND_GET_REVISION
//
typedef struct {
  UINT32    Revision;
  UINT32    Capabilities;
} DEBUG_DATA_RESPONSE_GET_REVISION;

//
// Response data for DEBUG_COMMAND_GET_EXCEPTION
//
typedef struct {
  UINT8     ExceptionNum;
  UINT32    ExceptionData;
} DEBUG_DATA_RESPONSE_GET_EXCEPTION;

//
// Request data for DEBUG_DATA_SET_DEBUG_SETTING
//
typedef struct {
  UINT8    Key;
  UINT8    Value;
} DEBUG_DATA_SET_DEBUG_SETTING;
//
// Supported keys
//
#define DEBUG_AGENT_SETTING_SMM_ENTRY_BREAK          1
#define DEBUG_AGENT_SETTING_PRINT_ERROR_LEVEL        2
#define DEBUG_AGENT_SETTING_BOOT_SCRIPT_ENTRY_BREAK  3
//
// Bitmask of print error level for debug message
//
#define DEBUG_AGENT_ERROR    BIT0
#define DEBUG_AGENT_WARNING  BIT1
#define DEBUG_AGENT_INFO     BIT2
#define DEBUG_AGENT_VERBOSE  BIT3

//
// Request data for DEBUG_COMMAND_SET_VIEWPOINT
//
typedef struct {
  UINT32    ViewPoint;                     // The index of viewpoint will be set
} DEBUG_DATA_SET_VIEWPOINT;

//
// Response data for DEBUG_COMMAND_GET_VIEWPOINT
//
typedef struct {
  UINT32    ViewPoint;                     // The index of viewpoint will be returned
} DEBUG_DATA_RESPONSE_GET_VIEWPOINT;

//
// Request and response data for DEBUG_COMMAND_CPUID
//
typedef struct {
  UINT32    Eax;                           // The value of EAX prior to invoking the CPUID instruction
  UINT32    Ecx;                           // The value of ECX prior to invoking the CPUID instruction
} DEBUG_DATA_CPUID;

typedef struct {
  UINT32    Eax;                           // The value of EAX returned by the CPUID instruction
  UINT32    Ebx;                           // The value of EBX returned by the CPUID instruction
  UINT32    Ecx;                           // The value of ECX returned by the CPUID instruction
  UINT32    Edx;                           // The value of EDX returned by the CPUID instruction
} DEBUG_DATA_RESPONSE_CPUID;

//
// Request and response data for DEBUG_COMMAND_SEARCH_SIGNATURE
//
typedef struct {
  UINT64     Start;
  UINT32     Count;
  UINT32     Alignment;
  BOOLEAN    Positive;                     // TRUE to search in higher address memory
  UINT8      DataLength;
  UINT8      Data[1];
} DEBUG_DATA_SEARCH_SIGNATURE;

typedef struct {
  UINT64    Address;                       // -1 indicates not found
} DEBUG_DATA_RESPONSE_SEARCH_SIGNATURE;

#pragma pack()

#endif