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