UefiCpuPkg/Include/Protocol/SmmCpuService.h

   1 /** @file
   2 SMM CPU Service protocol definition.
   3
   4 Copyright (c) 2013 - 2015, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _SMM_CPU_SERVICE_PROTOCOL_H_
  16 #define _SMM_CPU_SERVICE_PROTOCOL_H_
  17
  18 //
  19 // Share some definitions with MP Services and CPU Arch Protocol
  20 //
  21 #include <Protocol/MpService.h>
  22 #include <Protocol/Cpu.h>
  23
  24 #define EFI_SMM_CPU_SERVICE_PROTOCOL_GUID \
  25   { \
  26     0x1d202cab, 0xc8ab, 0x4d5c, { 0x94, 0xf7, 0x3c, 0xfc, 0xc0, 0xd3, 0xd3, 0x35 } \
  27   }
  28
  29 typedef struct _EFI_SMM_CPU_SERVICE_PROTOCOL EFI_SMM_CPU_SERVICE_PROTOCOL;
  30
  31 //
  32 // Protocol functions
  33 //
  34
  35 /**
  36   Gets processor information on the requested processor at the
  37   instant this call is made. This service may only be called from the BSP.
  38
  39   @param[in]  This                  A pointer to the EFI_SMM_CPU_SERVICE_PROTOCOL
  40                                     instance.
  41   @param[in]  ProcessorNumber       The handle number of processor.
  42   @param[out] ProcessorInfoBuffer   A pointer to the buffer where information for
  43                                     the requested processor is deposited.
  44
  45   @retval EFI_SUCCESS             Processor information was returned.
  46   @retval EFI_DEVICE_ERROR        The calling processor is an AP.
  47   @retval EFI_INVALID_PARAMETER   ProcessorInfoBuffer is NULL.
  48   @retval EFI_NOT_FOUND           The processor with the handle specified by
  49                                   ProcessorNumber does not exist in the platform.
  50 **/
  51 typedef
  52 EFI_STATUS
  53 (EFIAPI * EFI_SMM_GET_PROCESSOR_INFO) (
  54   IN CONST EFI_SMM_CPU_SERVICE_PROTOCOL *This,
  55   IN       UINTN                        ProcessorNumber,
  56   OUT      EFI_PROCESSOR_INFORMATION    *ProcessorInfoBuffer
  57   );
  58
  59 /**
  60   This service switches the requested AP to be the BSP from that point onward.
  61   This service changes the BSP for all purposes.   This call can only be performed
  62   by the current BSP.
  63
  64   This service switches the requested AP to be the BSP from that point onward.
  65   This service changes the BSP for all purposes. The new BSP can take over the
  66   execution of the old BSP and continue seamlessly from where the old one left
  67   off.
  68
  69   If the BSP cannot be switched prior to the return from this service, then
  70   EFI_UNSUPPORTED must be returned.
  71
  72   @param[in] This              A pointer to the EFI_SMM_CPU_SERVICE_PROTOCOL instance.
  73   @param[in] ProcessorNumber   The handle number of AP that is to become the new
  74                                BSP. The range is from 0 to the total number of
  75                                logical processors minus 1.
  76
  77   @retval EFI_SUCCESS             BSP successfully switched.
  78   @retval EFI_UNSUPPORTED         Switching the BSP cannot be completed prior to
  79                                   this service returning.
  80   @retval EFI_UNSUPPORTED         Switching the BSP is not supported.
  81   @retval EFI_SUCCESS             The calling processor is an AP.
  82   @retval EFI_NOT_FOUND           The processor with the handle specified by
  83                                   ProcessorNumber does not exist.
  84   @retval EFI_INVALID_PARAMETER   ProcessorNumber specifies the current BSP or
  85                                   a disabled AP.
  86   @retval EFI_NOT_READY           The specified AP is busy.
  87
  88 **/
  89 typedef
  90 EFI_STATUS
  91 (EFIAPI * EFI_SMM_SWITCH_BSP) (
  92   IN CONST EFI_SMM_CPU_SERVICE_PROTOCOL *This,
  93   IN       UINTN                        ProcessorNumber
  94   );
  95
  96 /**
  97   Notify that a new processor has been added to the system.
  98
  99   The SMM CPU driver should add the processor to the SMM CPU list.
 100
 101   If the processor is disabled it won't participate any SMI handler during subsequent SMIs.
 102
 103   @param  This                      A pointer to the EFI_SMM_CPU_SERVICE_PROTOCOL instance.
 104   @param  ProcessorId               The hardware ID of the processor.
 105   @param  ProcessorNumber           The handle number of processor.
 106   @param  ProcessorResource         A pointer to EFI_SMM_PROCESSOR_RESOURCE which holds the assigned resources.
 107
 108   @retval EFI_SUCCESS          The function completed successfully.
 109   @retval EFI_ALREADY_STARTED  Processor already present.
 110   @retval EFI_NOT_READY        Space for a new handle could not be allocated.
 111
 112 **/
 113 typedef
 114 EFI_STATUS
 115 (EFIAPI *EFI_SMM_ADD_PROCESSOR) (
 116   IN CONST EFI_SMM_CPU_SERVICE_PROTOCOL  *This,
 117   IN       UINT64                        ProcessorId,
 118   OUT      UINTN                         *ProcessorNumber
 119   );
 120
 121 /**
 122   Notify that a processor is hot-removed.
 123
 124   Remove a processor from the CPU list of the SMM CPU driver. After this API is called, the removed processor
 125   must not respond to SMIs in the coherence domain.
 126
 127   @param  This                 A pointer to the EFI_SMM_CPU_SERVICE_PROTOCOL instance.
 128   @param  ProcessorId          The hardware ID of the processor.
 129
 130   @retval EFI_SUCCESS          The function completed successfully.
 131   @retval EFI_NOT_FOUND        Processor with the hardware ID specified by ProcessorId does not exist.
 132   @retval EFI_NOT_READY        Specified AP is busy.
 133
 134 **/
 135 typedef
 136 EFI_STATUS
 137 (EFIAPI *EFI_SMM_REMOVE_PROCESSOR) (
 138   IN CONST EFI_SMM_CPU_SERVICE_PROTOCOL  *This,
 139   IN       UINTN                         ProcessorNumber
 140   );
 141
 142 /**
 143   This return the handle number for the calling processor.  This service may be
 144   called from the BSP and APs.
 145
 146   This service returns the processor handle number for the calling processor.
 147   The returned value is in the range from 0 to the total number of logical
 148   processors minus 1. This service may be called from the BSP and APs.
 149   If ProcessorNumber is NULL, then EFI_INVALID_PARAMETER
 150   is returned. Otherwise, the current processors handle number is returned in
 151   ProcessorNumber, and EFI_SUCCESS is returned.
 152
 153   @param[in] This              A pointer to the EFI_SMM_CPU_SERVICE_PROTOCOL instance.
 154   @param[in] ProcessorNumber   The handle number of AP that is to become the new
 155                                BSP. The range is from 0 to the total number of
 156                                logical processors minus 1.
 157
 158   @retval EFI_SUCCESS             The current processor handle number was returned
 159                                   in ProcessorNumber.
 160   @retval EFI_INVALID_PARAMETER   ProcessorNumber is NULL.
 161
 162 **/
 163 typedef
 164 EFI_STATUS
 165 (EFIAPI * EFI_SMM_WHOAMI) (
 166   IN CONST EFI_SMM_CPU_SERVICE_PROTOCOL *This,
 167   OUT      UINTN                        *ProcessorNumber
 168   );
 169
 170 /**
 171   Register exception handler.
 172
 173   @param  This                  A pointer to the SMM_CPU_SERVICE_PROTOCOL instance.
 174   @param  ExceptionType         Defines which interrupt or exception to hook. Type EFI_EXCEPTION_TYPE and
 175                                 the valid values for this parameter are defined in EFI_DEBUG_SUPPORT_PROTOCOL
 176                                 of the UEFI 2.0 specification.
 177   @param  InterruptHandler      A pointer to a function of type EFI_CPU_INTERRUPT_HANDLER
 178                                 that is called when a processor interrupt occurs.
 179                                 If this parameter is NULL, then the handler will be uninstalled.
 180
 181   @retval EFI_SUCCESS           The handler for the processor interrupt was successfully installed or uninstalled.
 182   @retval EFI_ALREADY_STARTED   InterruptHandler is not NULL, and a handler for InterruptType was previously installed.
 183   @retval EFI_INVALID_PARAMETER InterruptHandler is NULL, and a handler for InterruptType was not previously installed.
 184   @retval EFI_UNSUPPORTED       The interrupt specified by InterruptType is not supported.
 185
 186 **/
 187 typedef
 188 EFI_STATUS
 189 (EFIAPI *EFI_SMM_REGISTER_EXCEPTION_HANDLER) (
 190   IN EFI_SMM_CPU_SERVICE_PROTOCOL  *This,
 191   IN EFI_EXCEPTION_TYPE            ExceptionType,
 192   IN EFI_CPU_INTERRUPT_HANDLER     InterruptHandler
 193   );
 194
 195 //
 196 //  This protocol provides CPU services from SMM.
 197 //
 198 struct _EFI_SMM_CPU_SERVICE_PROTOCOL {
 199   EFI_SMM_GET_PROCESSOR_INFO          GetProcessorInfo;
 200   EFI_SMM_SWITCH_BSP                  SwitchBsp;
 201   EFI_SMM_ADD_PROCESSOR               AddProcessor;
 202   EFI_SMM_REMOVE_PROCESSOR            RemoveProcessor;
 203   EFI_SMM_WHOAMI                      WhoAmI;
 204   EFI_SMM_REGISTER_EXCEPTION_HANDLER  RegisterExceptionHandler;
 205 };
 206
 207 extern EFI_GUID gEfiSmmCpuServiceProtocolGuid;
 208
 209 #endif