TransferProtocol.h 12 KB

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