MdePkg/Include/Protocol/LegacySpiController.h

   1 /** @file
   2   This file defines the Legacy SPI Controller Protocol.
   3
   4   Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Revision Reference:
   8     This Protocol was introduced in UEFI PI Specification 1.6.
   9
  10 **/
  11
  12 #ifndef __LEGACY_SPI_CONTROLLER_PROTOCOL_H__
  13 #define __LEGACY_SPI_CONTROLLER_PROTOCOL_H__
  14
  15 ///
  16 /// Note: The UEFI PI 1.6 specification uses the character 'l' in the GUID
  17 ///       definition. This definition assumes it was supposed to be '1'.
  18 ///
  19 /// Global ID for the Legacy SPI Controller Protocol
  20 ///
  21 #define EFI_LEGACY_SPI_CONTROLLER_GUID  \
  22   { 0x39136fc7, 0x1a11, 0x49de,         \
  23     { 0xbf, 0x35, 0x0e, 0x78, 0xdd, 0xb5, 0x24, 0xfc }}
  24
  25 typedef
  26 struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
  27 EFI_LEGACY_SPI_CONTROLLER_PROTOCOL;
  28
  29 /**
  30   Set the erase block opcode.
  31
  32   This routine must be called at or below TPL_NOTIFY.
  33   The menu table contains SPI transaction opcodes which are accessible after
  34   the legacy SPI flash controller's configuration is locked. The board layer
  35   specifies the erase block size for the SPI NOR flash part. The SPI NOR flash
  36   peripheral driver selects the erase block opcode which matches the erase
  37   block size and uses this API to load the opcode into the opcode menu table.
  38
  39   @param[in] This              Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
  40                                structure.
  41   @param[in] EraseBlockOpcode  Erase block opcode to be placed into the opcode
  42                                menu table.
  43
  44   @retval EFI_SUCCESS       The opcode menu table was updated
  45   @retval EFI_ACCESS_ERROR  The SPI controller is locked
  46
  47 **/
  48 typedef EFI_STATUS
  49 (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE) (
  50   IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This,
  51   IN UINT8                                     EraseBlockOpcode
  52   );
  53
  54 /**
  55   Set the write status prefix opcode.
  56
  57   This routine must be called at or below TPL_NOTIFY.
  58   The prefix table contains SPI transaction write prefix opcodes which are
  59   accessible after the legacy SPI flash controller's configuration is locked.
  60   The board layer specifies the write status prefix opcode for the SPI NOR
  61   flash part. The SPI NOR flash peripheral driver uses this API to load the
  62   opcode into the prefix table.
  63
  64   @param[in] This               Pointer to an
  65                                 EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.
  66   @param[in] WriteStatusPrefix  Prefix opcode for the write status command.
  67
  68   @retval EFI_SUCCESS       The prefix table was updated
  69   @retval EFI_ACCESS_ERROR  The SPI controller is locked
  70
  71 **/
  72 typedef
  73 EFI_STATUS
  74 (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX) (
  75   IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This,
  76   IN UINT8                                     WriteStatusPrefix
  77   );
  78
  79 /**
  80   Set the BIOS base address.
  81
  82   This routine must be called at or below TPL_NOTIFY.
  83   The BIOS base address works with the protect range registers to protect
  84   portions of the SPI NOR flash from erase and write operat ions. The BIOS
  85   calls this API prior to passing control to the OS loader.
  86
  87   @param[in] This             Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
  88                               structure.
  89   @param[in] BiosBaseAddress  The BIOS base address.
  90
  91   @retval EFI_SUCCESS            The BIOS base address was properly set
  92   @retval EFI_ACCESS_ERROR       The SPI controller is locked
  93   @retval EFI_INVALID_PARAMETER  The BIOS base address is greater than
  94                                  This->Maxi.mumOffset
  95   @retval EFI_UNSUPPORTED        The BIOS base address was already set
  96
  97 **/
  98 typedef EFI_STATUS
  99 (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS) (
 100   IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This,
 101   IN UINT32 BiosBaseAddress
 102   );
 103
 104 /**
 105   Clear the SPI protect range registers.
 106
 107   This routine must be called at or below TPL_NOTIFY.
 108   The BIOS uses this routine to set an initial condition on the SPI protect
 109   range registers.
 110
 111   @param[in] This  Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.
 112
 113   @retval EFI_SUCCESS       The registers were successfully cleared
 114   @retval EFI_ACCESS_ERROR  The SPI controller is locked
 115
 116 **/
 117 typedef
 118 EFI_STATUS
 119 (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT) (
 120   IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This
 121   );
 122
 123 /**
 124   Determine if the SPI range is protected.
 125
 126   This routine must be called at or below TPL_NOTIFY.
 127   The BIOS uses this routine to verify a range in the SPI is protected.
 128
 129   @param[in] This            Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
 130                              structure.
 131   @param[in] BiosAddress     Address within a 4 KiB block to start protecting.
 132   @param[in] BytesToProtect  The number of 4 KiB blocks to protect.
 133
 134   @retval TRUE   The range is protected
 135   @retval FALSE  The range is not protected
 136
 137 **/
 138 typedef
 139 BOOLEAN
 140 (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED) (
 141   IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This,
 142   IN UINT32                                    BiosAddress,
 143   IN UINT32                                    BlocksToProtect
 144   );
 145
 146 /**
 147   Set the next protect range register.
 148
 149   This routine must be called at or below TPL_NOTIFY.
 150   The BIOS sets the protect range register to prevent write and erase
 151   operations to a portion of the SPI NOR flash device.
 152
 153   @param[in] This             Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
 154                               structure.
 155   @param[in] BiosAddress      Address within a 4 KiB block to start protecting.
 156   @param[in] BlocksToProtect  The number of 4 KiB blocks to protect.
 157
 158   @retval EFI_SUCCESS            The register was successfully updated
 159   @retval EFI_ACCESS_ERROR       The SPI controller is locked
 160   @retval EFI_INVALID_PARAMETER  BiosAddress < This->BiosBaseAddress, or
 161                                  BlocksToProtect * 4 KiB
 162                                    > This->MaximumRangeBytes, or
 163                                  BiosAddress - This->BiosBaseAddress
 164                                    + (BlocksToProtect * 4 KiB)
 165                                      > This->MaximumRangeBytes
 166   @retval EFI_OUT_OF_RESOURCES  No protect range register available
 167   @retval EFI_UNSUPPORTED       Call This->SetBaseAddress because the BIOS base
 168                                 address is not set
 169
 170 **/
 171 typedef
 172 EFI_STATUS
 173 (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE) (
 174   IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This,
 175   IN UINT32                                    BiosAddress,
 176   IN UINT32                                    BlocksToProtect
 177   );
 178
 179 /**
 180   Lock the SPI controller configuration.
 181
 182   This routine must be called at or below TPL_NOTIFY.
 183   This routine locks the SPI controller's configuration so that the software
 184   is no longer able to update:
 185   * Prefix table
 186   * Opcode menu
 187   * Opcode type table
 188   * BIOS base address
 189   * Protect range registers
 190
 191   @param[in] This  Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.
 192
 193   @retval EFI_SUCCESS          The SPI controller was successfully locked
 194   @retval EFI_ALREADY_STARTED  The SPI controller was already locked
 195
 196 **/
 197 typedef EFI_STATUS
 198 (EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER) (
 199   IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This
 200   );
 201
 202 ///
 203 /// Support the extra features of the legacy SPI flash controller.
 204 ///
 205 struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL {
 206   ///
 207   /// Maximum offset from the BIOS base address that is able to be protected.
 208   ///
 209   UINT32                                                 MaximumOffset;
 210
 211   ///
 212   /// Maximum number of bytes that can be protected by one range register.
 213   ///
 214   UINT32                                                 MaximumRangeBytes;
 215
 216   ///
 217   /// The number of registers available for protecting the BIOS.
 218   ///
 219   UINT32                                                 RangeRegisterCount;
 220
 221   ///
 222   /// Set the erase block opcode.
 223   ///
 224   EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE  EraseBlockOpcode;
 225
 226   ///
 227   /// Set the write status prefix opcode.
 228   ///
 229   EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX WriteStatusPrefix;
 230
 231   ///
 232   /// Set the BIOS base address.
 233   ///
 234   EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS   BiosBaseAddress;
 235
 236   ///
 237   /// Clear the SPI protect range registers.
 238   ///
 239   EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT   ClearSpiProtect;
 240
 241   ///
 242   /// Determine if the SPI range is protected.
 243   ///
 244   EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED  IsRangeProtected;
 245
 246   ///
 247   /// Set the next protect range register.
 248   ///
 249   EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE  ProtectNextRange;
 250
 251   ///
 252   /// Lock the SPI controller configuration.
 253   ///
 254   EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER     LockController;
 255 };
 256
 257 extern EFI_GUID gEfiLegacySpiControllerProtocolGuid;
 258
 259 #endif // __LEGACY_SPI_CONTROLLER_PROTOCOL_H__