Check comments, format and fix some typo.
[mirror_edk2.git] / MdeModulePkg / Universal / DebugSupportDxe / Ia32 / DebugSupport.h
CommitLineData
6e8a984e 1/** @file\r
2 Generic debug support macros, typedefs and prototypes for IA32/x64.\r
3\r
4Copyright (c) 2006 - 2008, Intel Corporation \r
5All rights reserved. This program and the accompanying materials \r
6are licensed and made available under the terms and conditions of the BSD License \r
7which accompanies this distribution. The full text of the license may be found at \r
8http://opensource.org/licenses/bsd-license.php \r
9 \r
10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
11WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
12\r
13**/\r
14\r
15#ifndef _DEBUG_SUPPORT_H_\r
16#define _DEBUG_SUPPORT_H_\r
17\r
6e8a984e 18#include <Uefi.h>\r
19\r
20#include <Protocol/DebugSupport.h>\r
21#include <Protocol/LoadedImage.h>\r
22\r
23#include <Library/DebugLib.h>\r
24#include <Library/UefiDriverEntryPoint.h>\r
25#include <Library/BaseMemoryLib.h>\r
26#include <Library/MemoryAllocationLib.h>\r
27#include <Library/UefiBootServicesTableLib.h>\r
28#include <Library/BaseLib.h>\r
29#include <Library/PcdLib.h>\r
30\r
31#define NUM_IDT_ENTRIES 0x78\r
32#define SYSTEM_TIMER_VECTOR 0x68\r
6e8a984e 33\r
34typedef\r
35VOID\r
36(*DEBUG_PROC) (\r
37 VOID\r
38 );\r
39\r
40typedef struct {\r
41 IA32_IDT_GATE_DESCRIPTOR OrigDesc;\r
42 DEBUG_PROC OrigVector;\r
43 IA32_IDT_GATE_DESCRIPTOR NewDesc;\r
44 DEBUG_PROC StubEntry;\r
45 VOID (*RegisteredCallback) ();\r
46} IDT_ENTRY;\r
47\r
c84507ab 48extern UINT8 InterruptEntryStub[];\r
49extern UINT32 StubSize;\r
50extern VOID (*OrigVector) (VOID);\r
51extern IDT_ENTRY *IdtEntryTable;\r
6e8a984e 52extern IA32_IDT_GATE_DESCRIPTOR NullDesc;\r
53\r
54/**\r
55 Generic IDT entry.\r
56\r
57**/\r
58VOID\r
59CommonIdtEntry (\r
60 VOID\r
61 );\r
62\r
63/**\r
64 Check whether FXSTOR is supported\r
65\r
66 @retval TRUE FXSTOR is supported.\r
67 @retval FALSE FXSTOR is not supported.\r
68\r
69**/\r
70BOOLEAN\r
71FxStorSupport (\r
72 VOID\r
73 );\r
74\r
75/**\r
76 Encodes an IDT descriptor with the given physical address.\r
77\r
78 @param DestDesc The IDT descriptor address.\r
79 @param Vecotr The interrupt vector entry.\r
80\r
81**/\r
82VOID\r
83Vect2Desc (\r
84 IA32_IDT_GATE_DESCRIPTOR * DestDesc,\r
85 VOID (*Vector) (VOID)\r
86 );\r
87\r
6e8a984e 88/**\r
7601dbe7 89 Initializes driver's handler registration database. \r
6e8a984e 90 \r
91 This code executes in boot services context\r
92 Must be public because it's referenced from DebugSupport.c\r
93\r
94 @retval EFI_UNSUPPORTED If IA32 processor does not support FXSTOR/FXRSTOR instructions,\r
95 the context save will fail, so these processor's are not supported.\r
96 @retval EFI_OUT_OF_RESOURCES Fails to allocate memory.\r
97 @retval EFI_SUCCESS Initializes successfully.\r
98\r
99**/\r
100EFI_STATUS\r
101PlInitializeDebugSupportDriver (\r
102 VOID\r
103 );\r
104\r
105/**\r
106 This is the callback that is written to the LoadedImage protocol instance\r
107 on the image handle. It uninstalls all registered handlers and frees all entry\r
108 stub memory.\r
109\r
110 @param ImageHandle The firmware allocated handle for the EFI image.\r
111\r
112 @retval EFI_SUCCESS Always.\r
113\r
114**/\r
115EFI_STATUS\r
116EFIAPI\r
117PlUnloadDebugSupportDriver (\r
118 IN EFI_HANDLE ImageHandle\r
119 );\r
120\r
121/**\r
c84507ab 122 Returns the maximum value that may be used for the ProcessorIndex parameter in\r
123 RegisterPeriodicCallback() and RegisterExceptionCallback(). \r
124 \r
125 Hard coded to support only 1 processor for now.\r
6e8a984e 126\r
c84507ab 127 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.\r
128 @param MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported\r
129 processor index is returned. Always 0 returned. \r
130 \r
131 @retval EFI_SUCCESS Always returned with **MaxProcessorIndex set to 0.\r
6e8a984e 132\r
133**/\r
134EFI_STATUS\r
135EFIAPI\r
136GetMaximumProcessorIndex (\r
137 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,\r
138 OUT UINTN *MaxProcessorIndex\r
139 );\r
140\r
141/**\r
c84507ab 142 Registers a function to be called back periodically in interrupt context.\r
143 \r
144 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.\r
145 @param ProcessorIndex Specifies which processor the callback function applies to.\r
146 @param PeriodicCallback A pointer to a function of type PERIODIC_CALLBACK that is the main\r
147 periodic entry point of the debug agent.\r
148 \r
149 @retval EFI_SUCCESS The function completed successfully. \r
150 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback\r
151 function was previously registered. \r
152 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback \r
153 function. \r
6e8a984e 154**/\r
155EFI_STATUS\r
156EFIAPI\r
157RegisterPeriodicCallback (\r
158 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,\r
159 IN UINTN ProcessorIndex,\r
160 IN EFI_PERIODIC_CALLBACK PeriodicCallback\r
161 );\r
162\r
163/**\r
c84507ab 164 Registers a function to be called when a given processor exception occurs.\r
6e8a984e 165\r
166 This code executes in boot services context.\r
c84507ab 167 \r
168 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.\r
169 @param ProcessorIndex Specifies which processor the callback function applies to.\r
170 @param ExceptionCallback A pointer to a function of type EXCEPTION_CALLBACK that is called\r
171 when the processor exception specified by ExceptionType occurs. \r
172 @param ExceptionType Specifies which processor exception to hook. \r
173 \r
174 @retval EFI_SUCCESS The function completed successfully. \r
175 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback\r
176 function was previously registered. \r
177 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback \r
178 function.\r
6e8a984e 179**/\r
180EFI_STATUS\r
181EFIAPI\r
182RegisterExceptionCallback (\r
183 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,\r
184 IN UINTN ProcessorIndex,\r
c84507ab 185 IN EFI_EXCEPTION_CALLBACK ExceptionCallback,\r
6e8a984e 186 IN EFI_EXCEPTION_TYPE ExceptionType\r
187 );\r
188\r
189/**\r
c84507ab 190 Invalidates processor instruction cache for a memory range. Subsequent execution in this range\r
191 causes a fresh memory fetch to retrieve code to be executed. \r
192 \r
193 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.\r
194 @param ProcessorIndex Specifies which processor's instruction cache is to be invalidated.\r
195 @param Start Specifies the physical base of the memory range to be invalidated. \r
196 @param Length Specifies the minimum number of bytes in the processor's instruction\r
197 cache to invalidate. \r
198 \r
199 @retval EFI_SUCCESS Always returned.\r
6e8a984e 200\r
201**/\r
202EFI_STATUS\r
203EFIAPI\r
204InvalidateInstructionCache (\r
205 IN EFI_DEBUG_SUPPORT_PROTOCOL *This,\r
206 IN UINTN ProcessorIndex,\r
207 IN VOID *Start,\r
208 IN UINT64 Length\r
209 );\r
210\r
211/**\r
212 Allocate pool for a new IDT entry stub.\r
213\r
214 Copy the generic stub into the new buffer and fixup the vector number\r
215 and jump target address.\r
216\r
217 @param ExceptionType This is the exception type that the new stub will be created\r
218 for.\r
219 @param Stub On successful exit, *Stub contains the newly allocated entry stub.\r
220\r
6e8a984e 221**/\r
c84507ab 222VOID\r
6e8a984e 223CreateEntryStub (\r
224 IN EFI_EXCEPTION_TYPE ExceptionType,\r
225 OUT VOID **Stub\r
226 );\r
227\r
228/**\r
c84507ab 229 Get Interrupt Handle from IDT Gate Descriptor.\r
6e8a984e 230\r
231 @param IdtGateDecriptor IDT Gate Descriptor.\r
232\r
c84507ab 233 @return Interrupt Handle stored in IDT Gate Descriptor.\r
6e8a984e 234\r
235**/\r
c84507ab 236UINTN\r
237GetInterruptHandleFromIdt (\r
6e8a984e 238 IN IA32_IDT_GATE_DESCRIPTOR *IdtGateDecriptor\r
239 );\r
240\r
241/**\r
242 This is the main worker function that manages the state of the interrupt\r
243 handlers. It both installs and uninstalls interrupt handlers based on the\r
244 value of NewCallback. If NewCallback is NULL, then uninstall is indicated.\r
245 If NewCallback is non-NULL, then install is indicated.\r
246\r
247 @param NewCallback If non-NULL, NewCallback specifies the new handler to register.\r
248 If NULL, specifies that the previously registered handler should\r
249 be uninstalled.\r
250 @param ExceptionType Indicates which entry to manage.\r
251\r
252 @retval EFI_SUCCESS Process is ok.\r
253 @retval EFI_INVALID_PARAMETER Requested uninstalling a handler from a vector that has\r
254 no handler registered for it\r
255 @retval EFI_ALREADY_STARTED Requested install to a vector that already has a handler registered.\r
256 @retval others Possible return values are passed through from UnHookEntry and HookEntry.\r
257\r
258**/\r
259EFI_STATUS\r
260ManageIdtEntryTable (\r
c84507ab 261 VOID (*NewCallback)(),\r
6e8a984e 262 EFI_EXCEPTION_TYPE ExceptionType\r
263 );\r
264\r
265/**\r
266 Creates a nes entry stub. Then saves the current IDT entry and replaces it\r
267 with an interrupt gate for the new entry point. The IdtEntryTable is updated\r
268 with the new registered function.\r
269\r
270 This code executes in boot services context. The stub entry executes in interrupt\r
271 context.\r
272\r
273 @param ExceptionType Specifies which vector to hook.\r
274 @param NewCallback A pointer to the new function to be registered.\r
275\r
6e8a984e 276**/\r
c84507ab 277VOID\r
6e8a984e 278HookEntry (\r
279 IN EFI_EXCEPTION_TYPE ExceptionType,\r
280 IN VOID (*NewCallback) ()\r
281 );\r
282\r
283/**\r
284 Undoes HookEntry. This code executes in boot services context.\r
285\r
286 @param ExceptionType Specifies which entry to unhook\r
287\r
6e8a984e 288**/\r
c84507ab 289VOID\r
6e8a984e 290UnhookEntry (\r
291 IN EFI_EXCEPTION_TYPE ExceptionType\r
292 );\r
293\r
294#endif\r