MdePkg/Include/Protocol/ExtendedSalBootService.h

   1 /** @file
   2   Definition of Extended SAL Boot Service Protocol
   3
   4   The Extended SAL Boot Service Protocol provides a mechanisms for platform specific
   5   drivers to update the SAL System Table and register Extended SAL Procedures that are
   6   callable in physical or virtual mode using the SAL calling convention.
   7
   8   Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
   9   This program and the accompanying materials
  10   are licensed and made available under the terms and conditions of the BSD License
  11   which accompanies this distribution.  The full text of the license may be found at
  12   http://opensource.org/licenses/bsd-license.php
  13
  14   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  15   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16
  17   @par Revision Reference:
  18   This Protocol was introduced in PI Specification 1.2.
  19
  20 **/
  21
  22 #ifndef _EXTENDED_SAL_BOOT_SERVICE_PROTOCOL_H_
  23 #define _EXTENDED_SAL_BOOT_SERVICE_PROTOCOL_H_
  24
  25 #include <IndustryStandard/Sal.h>
  26
  27 #define EXTENDED_SAL_BOOT_SERVICE_PROTOCOL_GUID   \
  28   { 0xde0ee9a4, 0x3c7a, 0x44f2, {0xb7, 0x8b, 0xe3, 0xcc, 0xd6, 0x9c, 0x3a, 0xf7 } }
  29
  30 typedef struct _EXTENDED_SAL_BOOT_SERVICE_PROTOCOL EXTENDED_SAL_BOOT_SERVICE_PROTOCOL;
  31
  32 /**
  33   Adds platform specific information to the to the header of the SAL System Table.
  34
  35   @param  This                  A pointer to the EXTENDED_SAL_BOOT_SERVICE_PROTOCOL instance.
  36   @param  SalAVersion           Version of recovery SAL PEIM(s) in BCD format. Higher byte contains
  37                                 the major revision and the lower byte contains the minor revision.
  38   @param  SalBVersion           Version of DXE SAL Driver in BCD format. Higher byte contains
  39                                 the major revision and the lower byte contains the minor revision.
  40   @param  OemId                 A pointer to a Null-terminated ASCII string that contains OEM unique string.
  41                                 The string cannot be longer than 32 bytes in total length
  42   @param  ProductId             A pointer to a Null-terminated ASCII string that uniquely identifies a family of
  43                                 compatible products. The string cannot be longer than 32 bytes in total length.
  44
  45   @retval EFI_SUCCESS           The SAL System Table header was updated successfully.
  46   @retval EFI_INVALID_PARAMETER OemId is NULL.
  47   @retval EFI_INVALID_PARAMETER ProductId is NULL.
  48   @retval EFI_INVALID_PARAMETER The length of OemId is greater than 32 characters.
  49   @retval EFI_INVALID_PARAMETER The length of ProductId is greater than 32 characters.
  50
  51 **/
  52 typedef
  53 EFI_STATUS
  54 (EFIAPI *EXTENDED_SAL_ADD_SST_INFO)(
  55   IN EXTENDED_SAL_BOOT_SERVICE_PROTOCOL  *This,
  56   IN UINT16                              SalAVersion,
  57   IN UINT16                              SalBVersion,
  58   IN CHAR8                               *OemId,
  59   IN CHAR8                               *ProductId
  60   );
  61
  62 /**
  63   Adds an entry to the SAL System Table.
  64
  65   This function adds the SAL System Table Entry specified by TableEntry and EntrySize
  66   to the SAL System Table.
  67
  68   @param  This         A pointer to the EXTENDED_SAL_BOOT_SERVICE_PROTOCOL instance.
  69   @param  TableEntry   Pointer to a buffer containing a SAL System Table entry that is EntrySize bytes
  70                        in length. The first byte of the TableEntry describes the type of entry.
  71   @param  EntrySize    The size, in bytes, of TableEntry.
  72
  73   @retval EFI_SUCCESSThe        SAL System Table was updated successfully.
  74   @retval EFI_INVALID_PARAMETER TableEntry is NULL.
  75   @retval EFI_INVALID_PARAMETER TableEntry specifies an invalid entry type.
  76   @retval EFI_INVALID_PARAMETER EntrySize is not valid for this type of entry.
  77
  78 **/
  79 typedef
  80 EFI_STATUS
  81 (EFIAPI *EXTENDED_SAL_ADD_SST_ENTRY)(
  82   IN EXTENDED_SAL_BOOT_SERVICE_PROTOCOL  *This,
  83   IN UINT8                               *TableEntry,
  84   IN UINTN                               EntrySize
  85   );
  86
  87 /**
  88   Internal ESAL procedures.
  89
  90   This is prototype of internal Extended SAL procedures, which is registerd by
  91   EXTENDED_SAL_REGISTER_INTERNAL_PROC service.
  92
  93   @param  FunctionId         The Function ID associated with this Extended SAL Procedure.
  94   @param  Arg2               Second argument to the Extended SAL procedure.
  95   @param  Arg3               Third argument to the Extended SAL procedure.
  96   @param  Arg4               Fourth argument to the Extended SAL procedure.
  97   @param  Arg5               Fifth argument to the Extended SAL procedure.
  98   @param  Arg6               Sixth argument to the Extended SAL procedure.
  99   @param  Arg7               Seventh argument to the Extended SAL procedure.
 100   @param  Arg8               Eighth argument to the Extended SAL procedure.
 101   @param  VirtualMode        TRUE if the Extended SAL Procedure is being invoked in virtual mode.
 102                              FALSE if the Extended SAL Procedure is being invoked in physical mode.
 103   @param  ModuleGlobal       A pointer to the global context associated with this Extended SAL Procedure.
 104
 105   @return The result returned from the specified Extended SAL Procedure
 106
 107 **/
 108 typedef
 109 SAL_RETURN_REGS
 110 (EFIAPI *SAL_INTERNAL_EXTENDED_SAL_PROC)(
 111   IN  UINT64   FunctionId,
 112   IN  UINT64   Arg2,
 113   IN  UINT64   Arg3,
 114   IN  UINT64   Arg4,
 115   IN  UINT64   Arg5,
 116   IN  UINT64   Arg6,
 117   IN  UINT64   Arg7,
 118   IN  UINT64   Arg8,
 119   IN  BOOLEAN  VirtualMode,
 120   IN  VOID     *ModuleGlobal  OPTIONAL
 121   );
 122
 123 /**
 124   Registers an Extended SAL Procedure.
 125
 126   The Extended SAL Procedure specified by InternalSalProc and named by ClassGuidLo,
 127   ClassGuidHi, and FunctionId is added to the set of available Extended SAL Procedures.
 128
 129   @param  This                   A pointer to the EXTENDED_SAL_BOOT_SERVICE_PROTOCOL instance.
 130   @param  ClassGuidLo            The lower 64-bits of  the class GUID for the Extended SAL Procedure being added.
 131                                  Each class GUID contains one or more functions specified by a Function ID.
 132   @param  ClassGuidHi            The upper 64-bits of  the class GUID for the Extended SAL Procedure being added.
 133                                  Each class GUID contains one or more functions specified by a Function ID.
 134   @param  FunctionId             The Function ID for the Extended SAL Procedure that is being added.  This Function
 135                                  ID is a member of the Extended SAL Procedure class specified by ClassGuidLo
 136                                  and ClassGuidHi.
 137   @param  InternalSalProc        A pointer to the Extended SAL Procedure being added.
 138   @param  PhysicalModuleGlobal   Pointer to a  module global structure. This is a physical mode pointer.
 139                                  This pointer is passed to the Extended SAL Procedure specified by ClassGuidLo,
 140                                  ClassGuidHi, FunctionId, and InternalSalProc.  If the system is in physical mode,
 141                                  then this pointer is passed unmodified to InternalSalProc.  If the system is in
 142                                  virtual mode, then the virtual address associated with this pointer is passed to
 143                                  InternalSalProc.
 144
 145   @retval EFI_SUCCESS            The Extended SAL Procedure was added.
 146   @retval EFI_OUT_OF_RESOURCES   There are not enough resources available to add the Extended SAL Procedure.
 147
 148 **/
 149 typedef
 150 EFI_STATUS
 151 (EFIAPI *EXTENDED_SAL_REGISTER_INTERNAL_PROC)(
 152   IN EXTENDED_SAL_BOOT_SERVICE_PROTOCOL  *This,
 153   IN UINT64                              ClassGuidLo,
 154   IN UINT64                              ClassGuidHi,
 155   IN UINT64                              FunctionId,
 156   IN SAL_INTERNAL_EXTENDED_SAL_PROC      InternalSalProc,
 157   IN VOID                                *PhysicalModuleGlobal  OPTIONAL
 158   );
 159
 160 /**
 161   Calls a previously registered Extended SAL Procedure.
 162
 163   This function calls the Extended SAL Procedure specified by ClassGuidLo, ClassGuidHi,
 164   and FunctionId.  The set of previously registered Extended SAL Procedures is searched for a
 165   matching ClassGuidLo, ClassGuidHi, and FunctionId.  If a match is not found, then
 166   EFI_SAL_NOT_IMPLEMENTED is returned.
 167
 168   @param  ClassGuidLo        The lower 64-bits of the class GUID for the Extended SAL Procedure
 169                              that is being called.
 170   @param  ClassGuidHi        The upper 64-bits of the class GUID for the Extended SAL Procedure
 171                              that is being called.
 172   @param  FunctionId         Function ID for the Extended SAL Procedure being called.
 173   @param  Arg2               Second argument to the Extended SAL procedure.
 174   @param  Arg3               Third argument to the Extended SAL procedure.
 175   @param  Arg4               Fourth argument to the Extended SAL procedure.
 176   @param  Arg5               Fifth argument to the Extended SAL procedure.
 177   @param  Arg6               Sixth argument to the Extended SAL procedure.
 178   @param  Arg7               Seventh argument to the Extended SAL procedure.
 179   @param  Arg8               Eighth argument to the Extended SAL procedure.
 180
 181   @retval EFI_SAL_NOT_IMPLEMENTED        The Extended SAL Procedure specified by ClassGuidLo,
 182                                          ClassGuidHi, and FunctionId has not been registered.
 183   @retval EFI_SAL_VIRTUAL_ADDRESS_ERROR  This function was called in virtual mode before virtual mappings
 184                                          for the specified Extended SAL Procedure are available.
 185   @retval Other                          The result returned from the specified Extended SAL Procedure
 186
 187 **/
 188 typedef
 189 SAL_RETURN_REGS
 190 (EFIAPI *EXTENDED_SAL_PROC)(
 191   IN UINT64  ClassGuidLo,
 192   IN UINT64  ClassGuidHi,
 193   IN UINT64  FunctionId,
 194   IN UINT64  Arg2,
 195   IN UINT64  Arg3,
 196   IN UINT64  Arg4,
 197   IN UINT64  Arg5,
 198   IN UINT64  Arg6,
 199   IN UINT64  Arg7,
 200   IN UINT64  Arg8
 201   );
 202
 203 ///
 204 /// The EXTENDED_SAL_BOOT_SERVICE_PROTOCOL provides a mechanisms for platform specific
 205 /// drivers to update the SAL System Table and register Extended SAL Procedures that are
 206 /// callable in physical or virtual mode using the SAL calling convention.
 207 ///
 208 struct _EXTENDED_SAL_BOOT_SERVICE_PROTOCOL {
 209   EXTENDED_SAL_ADD_SST_INFO            AddSalSystemTableInfo;
 210   EXTENDED_SAL_ADD_SST_ENTRY           AddSalSystemTableEntry;
 211   EXTENDED_SAL_REGISTER_INTERNAL_PROC  RegisterExtendedSalProc;
 212   EXTENDED_SAL_PROC                    ExtendedSalProc;
 213 };
 214
 215 extern EFI_GUID  gEfiExtendedSalBootServiceProtocolGuid;
 216
 217 #endif