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