EdkCompatibilityPkg/Foundation/Core/Dxe/ArchProtocol/Cpu/Cpu.h

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