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