MdePkg/Include/Protocol/Cpu.h

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