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 |
|
---|
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 definitions 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 definitions 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
|
---|