1/** @file
2  IPF specific types, macros, and definitions for Debug Support Driver.
3
4Copyright (c) 2004 - 2010, Intel Corporation. All rights reserved.<BR>
5This program and the accompanying materials
6are licensed and made available under the terms and conditions of the BSD License
7which accompanies this distribution.  The full text of the license may be found at
8http://opensource.org/licenses/bsd-license.php
9
10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13**/
14
15#ifndef _PLDEBUG_SUPPORT_H_
16#define _PLDEBUG_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
29#define DISABLE_INTERRUPTS  0UL
30
31#define EFI_ISA IsaIpf
32
33typedef struct {
34  UINT64  Low;
35  UINT64  High;
36} BUNDLE;
37
38typedef
39VOID
40(*CALLBACK_FUNC) (
41  );
42
43/**
44  IPF specific DebugSupport driver initialization.
45
46  Must be public because it's referenced from DebugSupport.c
47
48  @retval  EFI_SUCCESS     Always.
49
50**/
51EFI_STATUS
52PlInitializeDebugSupportDriver (
53  VOID
54  );
55
56/**
57  Unload handler that is called during UnloadImage() - deallocates pool memory
58  used by the driver.
59
60  Must be public because it's referenced from DebugSuport.c
61
62  @param  ImageHandle    The firmware allocated handle for the EFI image.
63
64  @retval EFI_SUCCESS    Always.
65
66**/
67EFI_STATUS
68EFIAPI
69PlUnloadDebugSupportDriver (
70  IN EFI_HANDLE                   ImageHandle
71  );
72
73/**
74  C callable function to obtain the current value of IVA.
75
76  @return Current value of IVA.
77
78**/
79VOID  *
80GetIva (
81  VOID
82  );
83
84/**
85  C callable function that HookStub will be copied from it's loaded location into the IVT when
86  an IVT entry is hooked.
87
88**/
89VOID
90HookStub (
91  VOID
92  );
93
94/**
95  C callable function to chain an interrupt handler.
96
97**/
98VOID
99ChainHandler (
100  VOID
101  );
102
103/**
104  C callable function to unchain an interrupt handler.
105
106**/
107VOID
108UnchainHandler (
109  VOID
110  );
111
112/**
113  C callable function to enable/disable interrupts.
114
115  @param  NewInterruptState   New Interrupt State.
116
117  @return Previous state of psr.ic.
118
119**/
120UINT64
121ProgramInterruptFlags (
122  IN UINT64                       NewInterruptState
123  );
124
125/**
126  Flushes instruction cache for specified number of bytes.
127
128  @param  StartAddress     Cache Start Address.
129  @param  SizeInBytes      Cache Size.
130
131**/
132VOID
133InstructionCacheFlush (
134  IN VOID    *StartAddress,
135  IN UINTN   SizeInBytes
136  );
137
138/**
139  Returns the maximum value that may be used for the ProcessorIndex parameter in
140  RegisterPeriodicCallback() and RegisterExceptionCallback().
141
142  Hard coded to support only 1 processor for now.
143
144  @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
145  @param  MaxProcessorIndex     Pointer to a caller-allocated UINTN in which the maximum supported
146                                processor index is returned. Always 0 returned.
147
148  @retval EFI_SUCCESS           Always returned with **MaxProcessorIndex set to 0.
149
150**/
151EFI_STATUS
152EFIAPI
153GetMaximumProcessorIndex (
154  IN EFI_DEBUG_SUPPORT_PROTOCOL   *This,
155  OUT UINTN                       *MaxProcessorIndex
156  );
157
158/**
159  Registers a function to be called back periodically in interrupt context.
160
161  @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
162  @param  ProcessorIndex        Specifies which processor the callback function applies to.
163  @param  PeriodicCallback      A pointer to a function of type PERIODIC_CALLBACK that is the main
164                                periodic entry point of the debug agent.
165
166  @retval EFI_SUCCESS           The function completed successfully.
167  @retval EFI_ALREADY_STARTED   Non-NULL PeriodicCallback parameter when a callback
168                                function was previously registered.
169  @retval EFI_OUT_OF_RESOURCES  System has insufficient memory resources to register new callback
170                                function.
171**/
172EFI_STATUS
173EFIAPI
174RegisterPeriodicCallback (
175  IN EFI_DEBUG_SUPPORT_PROTOCOL   *This,
176  IN UINTN                        ProcessorIndex,
177  IN EFI_PERIODIC_CALLBACK        PeriodicCallback
178  );
179
180/**
181  Registers a function to be called when a given processor exception occurs.
182
183  This code executes in boot services context.
184
185  @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
186  @param  ProcessorIndex        Specifies which processor the callback function applies to.
187  @param  ExceptionCallback     A pointer to a function of type EXCEPTION_CALLBACK that is called
188                                when the processor exception specified by ExceptionType occurs.
189  @param  ExceptionType         Specifies which processor exception to hook.
190
191  @retval EFI_SUCCESS           The function completed successfully.
192  @retval EFI_ALREADY_STARTED   Non-NULL PeriodicCallback parameter when a callback
193                                function was previously registered.
194  @retval EFI_OUT_OF_RESOURCES  System has insufficient memory resources to register new callback
195                                function.
196**/
197EFI_STATUS
198EFIAPI
199RegisterExceptionCallback (
200  IN EFI_DEBUG_SUPPORT_PROTOCOL   *This,
201  IN UINTN                        ProcessorIndex,
202  IN EFI_EXCEPTION_CALLBACK       ExceptionCallback,
203  IN EFI_EXCEPTION_TYPE           ExceptionType
204  );
205
206/**
207  Invalidates processor instruction cache for a memory range. Subsequent execution in this range
208  causes a fresh memory fetch to retrieve code to be executed.
209
210  @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
211  @param  ProcessorIndex        Specifies which processor's instruction cache is to be invalidated.
212  @param  Start                 Specifies the physical base of the memory range to be invalidated.
213  @param  Length                Specifies the minimum number of bytes in the processor's instruction
214                                cache to invalidate.
215
216  @retval EFI_SUCCESS           Always returned.
217
218**/
219EFI_STATUS
220EFIAPI
221InvalidateInstructionCache (
222  IN EFI_DEBUG_SUPPORT_PROTOCOL   *This,
223  IN UINTN                        ProcessorIndex,
224  IN VOID                         *Start,
225  IN UINTN                        Length
226  );
227
228/**
229  C routine that is called for all registered exceptions.  This is the main
230  exception dispatcher.
231
232  Must be public because it's referenced from AsmFuncs.s.
233
234  @param  ExceptionType        Specifies which processor exception.
235  @param  Context              System Context.
236**/
237VOID
238CommonHandler (
239  IN EFI_EXCEPTION_TYPE ExceptionType,
240  IN EFI_SYSTEM_CONTEXT Context
241  );
242
243/**
244  This is the worker function that uninstalls and removes all handlers.
245
246  @param  ExceptionType     Specifies which processor exception.
247  @param  NewBundles        New Boundles.
248  @param  NewCallback       A pointer to the new function to be registered.
249
250  @retval EFI_ALEADY_STARTED Ivt already hooked.
251  @retval EFI_SUCCESS        Successfully uninstalled.
252
253**/
254EFI_STATUS
255ManageIvtEntryTable (
256  IN  EFI_EXCEPTION_TYPE    ExceptionType,
257  IN  BUNDLE                NewBundles[4],
258  IN  CALLBACK_FUNC         NewCallback
259  );
260
261/**
262  Saves original IVT contents and inserts a few new bundles which are fixed up
263  to store the ExceptionType and then call the common handler.
264
265  @param  ExceptionType      Specifies which processor exception.
266  @param  NewBundles         New Boundles.
267  @param  NewCallback        A pointer to the new function to be hooked.
268
269**/
270VOID
271HookEntry (
272  IN  EFI_EXCEPTION_TYPE    ExceptionType,
273  IN  BUNDLE                NewBundles[4],
274  IN  CALLBACK_FUNC         NewCallback
275  );
276
277/**
278  Restores original IVT contents when unregistering a callback function.
279
280  @param  ExceptionType     Specifies which processor exception.
281
282**/
283VOID
284UnhookEntry (
285  IN  EFI_EXCEPTION_TYPE    ExceptionType
286  );
287
288/**
289  Sets up cache flush and calls assembly function to chain external interrupt.
290
291  Records new callback in IvtEntryTable.
292
293  @param  NewCallback     A pointer to the interrupt handle.
294
295**/
296VOID
297ChainExternalInterrupt (
298  IN  CALLBACK_FUNC         NewCallback
299  );
300
301/**
302  Sets up cache flush and calls assembly function to restore external interrupt.
303  Removes registered callback from IvtEntryTable.
304
305**/
306VOID
307UnchainExternalInterrupt (
308  VOID
309  );
310
311/**
312  Given an integer number, return the physical address of the entry point in the IFT.
313
314  @param  HandlerIndex       Index of the Handler
315  @param  EntryPoint         IFT Entrypoint
316
317**/
318VOID
319GetHandlerEntryPoint (
320  UINTN                     HandlerIndex,
321  VOID                      **EntryPoint
322  );
323
324#endif
325