[efi] Add EFI image format and basic runtime environment
[people/sha0/gpxe.git] / src / include / gpxe / efi / Protocol / Cpu.h
1 /** @file
2   CPU Architectural Protocol as defined in PI spec Volume 2 DXE
3
4   This code abstracts the DXE core from processor implementation details.
5
6   Copyright (c) 2006 - 2008, Intel Corporation
7   All rights reserved. This program and the accompanying materials
8   are licensed and made available under the terms and conditions of the BSD License
9   which accompanies this distribution.  The full text of the license may be found at
10   http://opensource.org/licenses/bsd-license.php
11
12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
14
15 **/
16
17 #ifndef __ARCH_PROTOCOL_CPU_H__
18 #define __ARCH_PROTOCOL_CPU_H__
19
20 #include <gpxe/efi/Protocol/DebugSupport.h>
21
22 #define EFI_CPU_ARCH_PROTOCOL_GUID \
23   { 0x26baccb1, 0x6f42, 0x11d4, {0xbc, 0xe7, 0x0, 0x80, 0xc7, 0x3c, 0x88, 0x81 } }
24
25 typedef struct _EFI_CPU_ARCH_PROTOCOL   EFI_CPU_ARCH_PROTOCOL;
26
27 typedef enum {
28   EfiCpuFlushTypeWriteBackInvalidate,
29   EfiCpuFlushTypeWriteBack,
30   EfiCpuFlushTypeInvalidate,
31   EfiCpuMaxFlushType
32 } EFI_CPU_FLUSH_TYPE;
33
34 typedef enum {
35   EfiCpuInit,
36   EfiCpuMaxInitType
37 } EFI_CPU_INIT_TYPE;
38
39 /**
40   EFI_CPU_INTERRUPT_HANDLER that is called when a processor interrupt occurs.
41
42   @param  InterruptType    Defines the type of interrupt or exception that
43                            occurred on the processor.This parameter is processor architecture specific.
44   @param  SystemContext    A pointer to the processor context when
45                            the interrupt occurred on the processor.
46
47   @return None
48
49 **/
50 typedef
51 VOID
52 (EFIAPI *EFI_CPU_INTERRUPT_HANDLER)(
53   IN CONST  EFI_EXCEPTION_TYPE  InterruptType,
54   IN CONST  EFI_SYSTEM_CONTEXT  SystemContext
55   );
56
57 /**
58   This function flushes the range of addresses from Start to Start+Length
59   from the processor's data cache. If Start is not aligned to a cache line
60   boundary, then the bytes before Start to the preceding cache line boundary
61   are also flushed. If Start+Length is not aligned to a cache line boundary,
62   then the bytes past Start+Length to the end of the next cache line boundary
63   are also flushed. The FlushType of EfiCpuFlushTypeWriteBackInvalidate must be
64   supported. If the data cache is fully coherent with all DMA operations, then
65   this function can just return EFI_SUCCESS. If the processor does not support
66   flushing a range of the data cache, then the entire data cache can be flushed.
67
68   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
69   @param  Start            The beginning physical address to flush from the processor's data
70                            cache.
71   @param  Length           The number of bytes to flush from the processor's data cache. This
72                            function may flush more bytes than Length specifies depending upon
73                            the granularity of the flush operation that the processor supports.
74   @param  FlushType        Specifies the type of flush operation to perform.
75
76   @retval EFI_SUCCESS           The address range from Start to Start+Length was flushed from
77                                 the processor's data cache.
78   @retval EFI_UNSUPPORTEDT      The processor does not support the cache flush type specified
79                                 by FlushType.
80   @retval EFI_DEVICE_ERROR      The address range from Start to Start+Length could not be flushed
81                                 from the processor's data cache.
82
83 **/
84 typedef
85 EFI_STATUS
86 (EFIAPI *EFI_CPU_FLUSH_DATA_CACHE)(
87   IN EFI_CPU_ARCH_PROTOCOL              *This,
88   IN EFI_PHYSICAL_ADDRESS               Start,
89   IN UINT64                             Length,
90   IN EFI_CPU_FLUSH_TYPE                 FlushType
91   );
92
93
94 /**
95   This function enables interrupt processing by the processor.
96
97   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
98
99   @retval EFI_SUCCESS           Interrupts are enabled on the processor.
100   @retval EFI_DEVICE_ERROR      Interrupts could not be enabled on the processor.
101
102 **/
103 typedef
104 EFI_STATUS
105 (EFIAPI *EFI_CPU_ENABLE_INTERRUPT)(
106   IN EFI_CPU_ARCH_PROTOCOL              *This
107   );
108
109
110 /**
111   This function disables interrupt processing by the processor.
112
113   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
114
115   @retval EFI_SUCCESS           Interrupts are disabled on the processor.
116   @retval EFI_DEVICE_ERROR      Interrupts could not be disabled on the processor.
117
118 **/
119 typedef
120 EFI_STATUS
121 (EFIAPI *EFI_CPU_DISABLE_INTERRUPT)(
122   IN EFI_CPU_ARCH_PROTOCOL              *This
123   );
124
125
126 /**
127   This function retrieves the processor's current interrupt state a returns it in
128   State. If interrupts are currently enabled, then TRUE is returned. If interrupts
129   are currently disabled, then FALSE is returned.
130
131   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
132   @param  State            A pointer to the processor's current interrupt state. Set to TRUE if
133                            interrupts are enabled and FALSE if interrupts are disabled.
134
135   @retval EFI_SUCCESS           The processor's current interrupt state was returned in State.
136   @retval EFI_INVALID_PARAMETER State is NULL.
137
138 **/
139 typedef
140 EFI_STATUS
141 (EFIAPI *EFI_CPU_GET_INTERRUPT_STATE)(
142   IN EFI_CPU_ARCH_PROTOCOL              *This,
143   OUT BOOLEAN                           *State
144   );
145
146
147 /**
148   This function generates an INIT on the processor. If this function succeeds, then the
149   processor will be reset, and control will not be returned to the caller. If InitType is
150   not supported by this processor, or the processor cannot programmatically generate an
151   INIT without help from external hardware, then EFI_UNSUPPORTED is returned. If an error
152   occurs attempting to generate an INIT, then EFI_DEVICE_ERROR is returned.
153
154   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
155   @param  InitType         The type of processor INIT to perform.
156
157   @retval EFI_SUCCESS           The processor INIT was performed. This return code should never be seen.
158   @retval EFI_UNSUPPORTED       The processor INIT operation specified by InitType is not supported
159                                 by this processor.
160   @retval EFI_DEVICE_ERROR      The processor INIT failed.
161
162 **/
163 typedef
164 EFI_STATUS
165 (EFIAPI *EFI_CPU_INIT)(
166   IN EFI_CPU_ARCH_PROTOCOL              *This,
167   IN EFI_CPU_INIT_TYPE                  InitType
168   );
169
170
171 /**
172   This function registers and enables the handler specified by InterruptHandler for a processor
173   interrupt or exception type specified by InterruptType. If InterruptHandler is NULL, then the
174   handler for the processor interrupt or exception type specified by InterruptType is uninstalled.
175   The installed handler is called once for each processor interrupt or exception.
176
177   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
178   @param  InterruptType    A pointer to the processor's current interrupt state. Set to TRUE if interrupts
179                            are enabled and FALSE if interrupts are disabled.
180   @param  InterruptHandler A pointer to a function of type EFI_CPU_INTERRUPT_HANDLER that is called
181                            when a processor interrupt occurs. If this parameter is NULL, then the handler
182                            will be uninstalled.
183
184   @retval EFI_SUCCESS           The handler for the processor interrupt was successfully installed or uninstalled.
185   @retval EFI_ALREADY_STARTED   InterruptHandler is not NULL, and a handler for InterruptType was
186                                 previously installed.
187   @retval EFI_INVALID_PARAMETER InterruptHandler is NULL, and a handler for InterruptType was not
188                                 previously installed.
189   @retval EFI_UNSUPPORTED       The interrupt specified by InterruptType is not supported.
190
191 **/
192 typedef
193 EFI_STATUS
194 (EFIAPI *EFI_CPU_REGISTER_INTERRUPT_HANDLER)(
195   IN EFI_CPU_ARCH_PROTOCOL              *This,
196   IN EFI_EXCEPTION_TYPE                 InterruptType,
197   IN EFI_CPU_INTERRUPT_HANDLER          InterruptHandler
198   );
199
200
201 /**
202   This function reads the processor timer specified by TimerIndex and returns it in TimerValue.
203
204   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
205   @param  TimerIndex       Specifies which processor timer is to be returned in TimerValue. This parameter
206                            must be between 0 and NumberOfTimers-1.
207   @param  TimerValue       Pointer to the returned timer value.
208   @param  TimerPeriod      A pointer to the amount of time that passes in femtoseconds for each increment
209                            of TimerValue.
210
211   @retval EFI_SUCCESS           The processor timer value specified by TimerIndex was returned in TimerValue.
212   @retval EFI_DEVICE_ERROR      An error occurred attempting to read one of the processor's timers.
213   @retval EFI_INVALID_PARAMETER TimerValue is NULL or TimerIndex is not valid.
214   @retval EFI_UNSUPPORTED       The processor does not have any readable timers.
215
216 **/
217 typedef
218 EFI_STATUS
219 (EFIAPI *EFI_CPU_GET_TIMER_VALUE)(
220   IN EFI_CPU_ARCH_PROTOCOL              *This,
221   IN UINT32                             TimerIndex,
222   OUT UINT64                            *TimerValue,
223   OUT UINT64                            *TimerPeriod OPTIONAL
224   );
225
226
227 /**
228   This function modifies the attributes for the memory region specified by BaseAddress and
229   Length from their current attributes to the attributes specified by Attributes.
230
231   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
232   @param  BaseAddress      The physical address that is the start address of a memory region.
233   @param  Length           The size in bytes of the memory region.
234   @param  Attributes       The bit mask of attributes to set for the memory region.
235
236   @retval EFI_SUCCESS           The attributes were set for the memory region.
237   @retval EFI_ACCESS_DENIED     The attributes for the memory resource range specified by
238                                 BaseAddress and Length cannot be modified.
239   @retval EFI_INVALID_PARAMETER Length is zero.
240   @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to modify the attributes of
241                                 the memory resource range.
242   @retval EFI_UNSUPPORTED       The processor does not support one or more bytes of the memory
243                                 resource range specified by BaseAddress and Length.
244                                 The bit mask of attributes is not support for the memory resource
245                                 range specified by BaseAddress and Length.
246
247 **/
248 typedef
249 EFI_STATUS
250 (EFIAPI *EFI_CPU_SET_MEMORY_ATTRIBUTES)(
251   IN EFI_CPU_ARCH_PROTOCOL              *This,
252   IN  EFI_PHYSICAL_ADDRESS              BaseAddress,
253   IN  UINT64                            Length,
254   IN  UINT64                            Attributes
255   );
256
257
258 /**
259   @par Protocol Description:
260   The EFI_CPU_ARCH_PROTOCOL is used to abstract processor-specific functions from the DXE
261   Foundation. This includes flushing caches, enabling and disabling interrupts, hooking interrupt
262   vectors and exception vectors, reading internal processor timers, resetting the processor, and
263   determining the processor frequency.
264
265   @param FlushDataCache
266   Flushes a range of the processor's data cache. If the processor does
267   not contain a data cache, or the data cache is fully coherent, then this
268   function can just return EFI_SUCCESS. If the processor does not support
269   flushing a range of addresses from the data cache, then the entire data
270   cache must be flushed.
271
272   @param EnableInterrupt
273   Enables interrupt processing by the processor.
274
275   @param DisableInterrupt
276   Disables interrupt processing by the processor.
277
278   @param GetInterruptState
279   Retrieves the processor's current interrupt state.
280
281   @param Init
282   Generates an INIT on the processor. If a processor cannot programmatically
283   generate an INIT without help from external hardware, then this function
284   returns EFI_UNSUPPORTED.
285
286   @param RegisterInterruptHandler
287   Associates an interrupt service routine with one of the processor's interrupt
288   vectors. This function is typically used by the EFI_TIMER_ARCH_PROTOCOL to
289   hook the timer interrupt in a system. It can also be used by the debugger to
290   hook exception vectors.
291
292   @param GetTimerValue
293   Returns the value of one of the processor's internal timers.
294
295   @param SetMemoryAttributes
296   Attempts to set the attributes of a memory region.
297
298   @param NumberOfTimers
299   The number of timers that are available in a processor. The value in this
300   field is a constant that must not be modified after the CPU Architectural
301   Protocol is installed. All consumers must treat this as a read-only field.
302
303   @param DmaBufferAlignment
304   The size, in bytes, of the alignment required for DMA buffer allocations.
305   This is typically the size of the largest data cache line in the platform.
306   The value in this field is a constant that must not be modified after the
307   CPU Architectural Protocol is installed. All consumers must treat this as
308   a read-only field.
309
310 **/
311 struct _EFI_CPU_ARCH_PROTOCOL {
312   EFI_CPU_FLUSH_DATA_CACHE            FlushDataCache;
313   EFI_CPU_ENABLE_INTERRUPT            EnableInterrupt;
314   EFI_CPU_DISABLE_INTERRUPT           DisableInterrupt;
315   EFI_CPU_GET_INTERRUPT_STATE         GetInterruptState;
316   EFI_CPU_INIT                        Init;
317   EFI_CPU_REGISTER_INTERRUPT_HANDLER  RegisterInterruptHandler;
318   EFI_CPU_GET_TIMER_VALUE             GetTimerValue;
319   EFI_CPU_SET_MEMORY_ATTRIBUTES       SetMemoryAttributes;
320   UINT32                              NumberOfTimers;
321   UINT32                              DmaBufferAlignment;
322 };
323
324 extern EFI_GUID gEfiCpuArchProtocolGuid;
325
326 #endif