MdePkg/Include/Protocol/LegacySpiFlash.h

   1 /** @file
   2   This file defines the Legacy SPI Flash 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_FLASH_PROTOCOL_H__
  13 #define __LEGACY_SPI_FLASH_PROTOCOL_H__
  14
  15 #include <Protocol/SpiNorFlash.h>
  16
  17 ///
  18 /// Global ID for the Legacy SPI Flash Protocol
  19 ///
  20 #define EFI_LEGACY_SPI_FLASH_PROTOCOL_GUID  \
  21   { 0xf01bed57, 0x04bc, 0x4f3f,             \
  22     { 0x96, 0x60, 0xd6, 0xf2, 0xea, 0x22, 0x82, 0x59 }}
  23
  24 typedef struct _EFI_LEGACY_SPI_FLASH_PROTOCOL EFI_LEGACY_SPI_FLASH_PROTOCOL;
  25
  26 /**
  27   Set the BIOS base address.
  28
  29   This routine must be called at or below TPL_NOTIFY.
  30   The BIOS base address works with the protect range registers to protect
  31   portions of the SPI NOR flash from erase and write operat ions.
  32   The BIOS calls this API prior to passing control to the OS loader.
  33
  34   @param[in] This             Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data
  35                               structure.
  36   @param[in] BiosBaseAddress  The BIOS base address.
  37
  38   @retval EFI_SUCCESS            The BIOS base address was properly set
  39   @retval EFI_ACCESS_ERROR       The SPI controller is locked
  40   @retval EFI_INVALID_PARAMETER  BiosBaseAddress > This->MaximumOffset
  41   @retval EFI_UNSUPPORTED        The BIOS base address was already set or not a
  42                                  legacy SPI host controller
  43
  44 **/
  45 typedef
  46 EFI_STATUS
  47 (EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS) (
  48   IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This,
  49   IN UINT32                               BiosBaseAddress
  50   );
  51
  52 /**
  53   Clear the SPI protect range registers.
  54
  55   This routine must be called at or below TPL_NOTIFY.
  56   The BIOS uses this routine to set an initial condition on the SPI protect
  57   range registers.
  58
  59   @param[in] This  Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.
  60
  61   @retval EFI_SUCCESS       The registers were successfully cleared
  62   @retval EFI_ACCESS_ERROR  The SPI controller is locked
  63   @retval EFI_UNSUPPORTED   Not a legacy SPI host controller
  64
  65 **/
  66 typedef EFI_STATUS
  67 (EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT) (
  68   IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This
  69   );
  70
  71 /**
  72   Determine if the SPI range is protected.
  73
  74   This routine must be called at or below TPL_NOTIFY.
  75   The BIOS uses this routine to verify a range in the SPI is protected.
  76
  77   @param[in] This             Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data
  78                               structure.
  79   @param[in] BiosAddress      Address within a 4 KiB block to start protecting.
  80   @param[in] BlocksToProtect  The number of 4 KiB blocks to protect.
  81
  82   @retval TRUE   The range is protected
  83   @retval FALSE  The range is not protected
  84
  85 **/
  86 typedef
  87 BOOLEAN
  88 (EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED) (
  89   IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This,
  90   IN UINT32                               BiosAddress,
  91   IN UINT32                               BlocksToProtect
  92   );
  93
  94 /**
  95   Set the next protect range register.
  96
  97   This routine must be called at or below TPL_NOTIFY.
  98   The BIOS sets the protect range register to prevent write and erase
  99   operations to a portion of the SPI NOR flash device.
 100
 101   @param[in] This             Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data
 102                               structure.
 103   @param[in] BiosAddress      Address within a 4 KiB block to start protecting.
 104   @param[in] BlocksToProtect  The number of 4 KiB blocks to protect.
 105
 106   @retval EFI_SUCCESS            The register was successfully updated
 107   @retval EFI_ACCESS_ERROR       The SPI controller is locked
 108   @retval EFI_INVALID_PARAMETER  BiosAddress < This->BiosBaseAddress, or
 109   @retval EFI_INVALID_PARAMETER  BlocksToProtect * 4 KiB
 110                                    > This->MaximumRangeBytes, or
 111                                  BiosAddress - This->BiosBaseAddress
 112                                    + (BlocksToProtect * 4 KiB)
 113                                      > This->MaximumRangeBytes
 114   @retval EFI_OUT_OF_RESOURCES   No protect range register available
 115   @retval EFI_UNSUPPORTED        Call This->SetBaseAddress because the BIOS
 116                                  base address is not set Not a legacy SPI host
 117                                  controller
 118
 119 **/
 120 typedef
 121 EFI_STATUS
 122 (EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE) (
 123   IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This,
 124   IN UINT32                               BiosAddress,
 125   IN UINT32                               BlocksToProtect
 126   );
 127
 128 /**
 129   Lock the SPI controller configuration.
 130
 131   This routine must be called at or below TPL_NOTIFY.
 132   This routine locks the SPI controller's configuration so that the software is
 133   no longer able to update:
 134   * Prefix table
 135   * Opcode menu
 136   * Opcode type table
 137   * BIOS base address
 138   * Protect range registers
 139
 140   @param[in] This  Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.
 141
 142   @retval EFI_SUCCESS          The SPI controller was successfully locked
 143   @retval EFI_ALREADY_STARTED  The SPI controller was already locked
 144   @retval EFI_UNSUPPORTED      Not a legacy SPI host controller
 145 **/
 146 typedef
 147 EFI_STATUS
 148 (EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER) (
 149   IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This
 150   );
 151
 152 ///
 153 /// The EFI_LEGACY_SPI_FLASH_PROTOCOL extends the EFI_SPI_NOR_FLASH_PROTOCOL
 154 /// with APls to support the legacy SPI flash controller.
 155 ///
 156 struct _EFI_LEGACY_SPI_FLASH_PROTOCOL {
 157   ///
 158   /// This protocol manipulates the SPI NOR flash parts using a common set of
 159   /// commands.
 160   ///
 161   EFI_SPI_NOR_FLASH_PROTOCOL                       FlashProtocol;
 162
 163   //
 164   // Legacy flash (SPI host) controller support
 165   //
 166
 167   ///
 168   /// Set the BIOS base address.
 169   ///
 170   EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS  BiosBaseAddress;
 171
 172   ///
 173   /// Clear the SPI protect range registers.
 174   ///
 175   EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT  ClearSpiProtect;
 176
 177   ///
 178   /// Determine if the SPI range is protected.
 179   ///
 180   EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected;
 181
 182   ///
 183   /// Set the next protect range register.
 184   ///
 185   EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange;
 186
 187   ///
 188   /// Lock the SPI controller configuration.
 189   ///
 190   EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER    LockController;
 191 };
 192
 193 extern EFI_GUID gEfiLegacySpiFlashProtocolGuid;
 194
 195 #endif // __LEGACY_SPI_FLASH_PROTOCOL_H__