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