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