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