xref: /illumos-gate/usr/src/boot/efi/include/Protocol/Cpu.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
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 - 2018, Intel Corporation. All rights reserved.<BR>
7   SPDX-License-Identifier: BSD-2-Clause-Patent
8 
9 **/
10 
11 #ifndef __ARCH_PROTOCOL_CPU_H__
12 #define __ARCH_PROTOCOL_CPU_H__
13 
14 #include <Protocol/DebugSupport.h>
15 
16 #define EFI_CPU_ARCH_PROTOCOL_GUID \
17   { 0x26baccb1, 0x6f42, 0x11d4, {0xbc, 0xe7, 0x0, 0x80, 0xc7, 0x3c, 0x88, 0x81 } }
18 
19 typedef struct _EFI_CPU_ARCH_PROTOCOL EFI_CPU_ARCH_PROTOCOL;
20 
21 ///
22 /// The type of flush operation
23 ///
24 typedef enum {
25   EfiCpuFlushTypeWriteBackInvalidate,
26   EfiCpuFlushTypeWriteBack,
27   EfiCpuFlushTypeInvalidate,
28   EfiCpuMaxFlushType
29 } EFI_CPU_FLUSH_TYPE;
30 
31 ///
32 /// The type of processor INIT.
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_UNSUPPORTED       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   This function enables interrupt processing by the processor.
95 
96   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
97 
98   @retval EFI_SUCCESS           Interrupts are enabled on the processor.
99   @retval EFI_DEVICE_ERROR      Interrupts could not be enabled on the processor.
100 
101 **/
102 typedef
103 EFI_STATUS
104 (EFIAPI *EFI_CPU_ENABLE_INTERRUPT)(
105   IN EFI_CPU_ARCH_PROTOCOL              *This
106   );
107 
108 /**
109   This function disables interrupt processing by the processor.
110 
111   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
112 
113   @retval EFI_SUCCESS           Interrupts are disabled on the processor.
114   @retval EFI_DEVICE_ERROR      Interrupts could not be disabled on the processor.
115 
116 **/
117 typedef
118 EFI_STATUS
119 (EFIAPI *EFI_CPU_DISABLE_INTERRUPT)(
120   IN EFI_CPU_ARCH_PROTOCOL              *This
121   );
122 
123 /**
124   This function retrieves the processor's current interrupt state a returns it in
125   State. If interrupts are currently enabled, then TRUE is returned. If interrupts
126   are currently disabled, then FALSE is returned.
127 
128   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
129   @param  State            A pointer to the processor's current interrupt state. Set to TRUE if
130                            interrupts are enabled and FALSE if interrupts are disabled.
131 
132   @retval EFI_SUCCESS           The processor's current interrupt state was returned in State.
133   @retval EFI_INVALID_PARAMETER State is NULL.
134 
135 **/
136 typedef
137 EFI_STATUS
138 (EFIAPI *EFI_CPU_GET_INTERRUPT_STATE)(
139   IN EFI_CPU_ARCH_PROTOCOL              *This,
140   OUT BOOLEAN                           *State
141   );
142 
143 /**
144   This function generates an INIT on the processor. If this function succeeds, then the
145   processor will be reset, and control will not be returned to the caller. If InitType is
146   not supported by this processor, or the processor cannot programmatically generate an
147   INIT without help from external hardware, then EFI_UNSUPPORTED is returned. If an error
148   occurs attempting to generate an INIT, then EFI_DEVICE_ERROR is returned.
149 
150   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
151   @param  InitType         The type of processor INIT to perform.
152 
153   @retval EFI_SUCCESS           The processor INIT was performed. This return code should never be seen.
154   @retval EFI_UNSUPPORTED       The processor INIT operation specified by InitType is not supported
155                                 by this processor.
156   @retval EFI_DEVICE_ERROR      The processor INIT failed.
157 
158 **/
159 typedef
160 EFI_STATUS
161 (EFIAPI *EFI_CPU_INIT)(
162   IN EFI_CPU_ARCH_PROTOCOL              *This,
163   IN EFI_CPU_INIT_TYPE                  InitType
164   );
165 
166 /**
167   This function registers and enables the handler specified by InterruptHandler for a processor
168   interrupt or exception type specified by InterruptType. If InterruptHandler is NULL, then the
169   handler for the processor interrupt or exception type specified by InterruptType is uninstalled.
170   The installed handler is called once for each processor interrupt or exception.
171 
172   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
173   @param  InterruptType    A pointer to the processor's current interrupt state. Set to TRUE if interrupts
174                            are enabled and FALSE if interrupts are disabled.
175   @param  InterruptHandler A pointer to a function of type EFI_CPU_INTERRUPT_HANDLER that is called
176                            when a processor interrupt occurs. If this parameter is NULL, then the handler
177                            will be uninstalled.
178 
179   @retval EFI_SUCCESS           The handler for the processor interrupt was successfully installed or uninstalled.
180   @retval EFI_ALREADY_STARTED   InterruptHandler is not NULL, and a handler for InterruptType was
181                                 previously installed.
182   @retval EFI_INVALID_PARAMETER InterruptHandler is NULL, and a handler for InterruptType was not
183                                 previously installed.
184   @retval EFI_UNSUPPORTED       The interrupt specified by InterruptType is not supported.
185 
186 **/
187 typedef
188 EFI_STATUS
189 (EFIAPI *EFI_CPU_REGISTER_INTERRUPT_HANDLER)(
190   IN EFI_CPU_ARCH_PROTOCOL              *This,
191   IN EFI_EXCEPTION_TYPE                 InterruptType,
192   IN EFI_CPU_INTERRUPT_HANDLER          InterruptHandler
193   );
194 
195 /**
196   This function reads the processor timer specified by TimerIndex and returns it in TimerValue.
197 
198   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
199   @param  TimerIndex       Specifies which processor timer is to be returned in TimerValue. This parameter
200                            must be between 0 and NumberOfTimers-1.
201   @param  TimerValue       Pointer to the returned timer value.
202   @param  TimerPeriod      A pointer to the amount of time that passes in femtoseconds for each increment
203                            of TimerValue. If TimerValue does not increment at a predictable rate, then 0 is
204                            returned. This parameter is optional and may be NULL.
205 
206   @retval EFI_SUCCESS           The processor timer value specified by TimerIndex was returned in TimerValue.
207   @retval EFI_DEVICE_ERROR      An error occurred attempting to read one of the processor's timers.
208   @retval EFI_INVALID_PARAMETER TimerValue is NULL or TimerIndex is not valid.
209   @retval EFI_UNSUPPORTED       The processor does not have any readable timers.
210 
211 **/
212 typedef
213 EFI_STATUS
214 (EFIAPI *EFI_CPU_GET_TIMER_VALUE)(
215   IN EFI_CPU_ARCH_PROTOCOL              *This,
216   IN UINT32                             TimerIndex,
217   OUT UINT64                            *TimerValue,
218   OUT UINT64                            *TimerPeriod OPTIONAL
219   );
220 
221 /**
222   This function modifies the attributes for the memory region specified by BaseAddress and
223   Length from their current attributes to the attributes specified by Attributes.
224 
225   @param  This             The EFI_CPU_ARCH_PROTOCOL instance.
226   @param  BaseAddress      The physical address that is the start address of a memory region.
227   @param  Length           The size in bytes of the memory region.
228   @param  Attributes       The bit mask of attributes to set for the memory region.
229 
230   @retval EFI_SUCCESS           The attributes were set for the memory region.
231   @retval EFI_ACCESS_DENIED     The attributes for the memory resource range specified by
232                                 BaseAddress and Length cannot be modified.
233   @retval EFI_INVALID_PARAMETER Length is zero.
234                                 Attributes specified an illegal combination of attributes that
235                                 cannot be set together.
236   @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to modify the attributes of
237                                 the memory resource range.
238   @retval EFI_UNSUPPORTED       The processor does not support one or more bytes of the memory
239                                 resource range specified by BaseAddress and Length.
240                                 The bit mask of attributes is not support for the memory resource
241                                 range specified by BaseAddress and Length.
242 
243 **/
244 typedef
245 EFI_STATUS
246 (EFIAPI *EFI_CPU_SET_MEMORY_ATTRIBUTES)(
247   IN EFI_CPU_ARCH_PROTOCOL              *This,
248   IN  EFI_PHYSICAL_ADDRESS              BaseAddress,
249   IN  UINT64                            Length,
250   IN  UINT64                            Attributes
251   );
252 
253 ///
254 /// The EFI_CPU_ARCH_PROTOCOL is used to abstract processor-specific functions from the DXE
255 /// Foundation. This includes flushing caches, enabling and disabling interrupts, hooking interrupt
256 /// vectors and exception vectors, reading internal processor timers, resetting the processor, and
257 /// determining the processor frequency.
258 ///
259 struct _EFI_CPU_ARCH_PROTOCOL {
260   EFI_CPU_FLUSH_DATA_CACHE              FlushDataCache;
261   EFI_CPU_ENABLE_INTERRUPT              EnableInterrupt;
262   EFI_CPU_DISABLE_INTERRUPT             DisableInterrupt;
263   EFI_CPU_GET_INTERRUPT_STATE           GetInterruptState;
264   EFI_CPU_INIT                          Init;
265   EFI_CPU_REGISTER_INTERRUPT_HANDLER    RegisterInterruptHandler;
266   EFI_CPU_GET_TIMER_VALUE               GetTimerValue;
267   EFI_CPU_SET_MEMORY_ATTRIBUTES         SetMemoryAttributes;
268   ///
269   /// The number of timers that are available in a processor. The value in this
270   /// field is a constant that must not be modified after the CPU Architectural
271   /// Protocol is installed. All consumers must treat this as a read-only field.
272   ///
273   UINT32                                NumberOfTimers;
274   ///
275   /// The size, in bytes, of the alignment required for DMA buffer allocations.
276   /// This is typically the size of the largest data cache line in the platform.
277   /// The value in this field is a constant that must not be modified after the
278   /// CPU Architectural Protocol is installed. All consumers must treat this as
279   /// a read-only field.
280   ///
281   UINT32                                DmaBufferAlignment;
282 };
283 
284 extern EFI_GUID  gEfiCpuArchProtocolGuid;
285 
286 #endif
287