| /** @file | |
| Header file for the PCH SPI Common Driver. | |
| Copyright (c) 2013-2015 Intel Corporation. | |
| This program and the accompanying materials | |
| are licensed and made available under the terms and conditions of the BSD License | |
| which accompanies this distribution. The full text of the license may be found at | |
| http://opensource.org/licenses/bsd-license.php | |
| THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, | |
| WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. | |
| **/ | |
| #ifndef _SPI_COMMON_H_ | |
| #define _SPI_COMMON_H_ | |
| #include "Protocol/Spi.h" | |
| #include <Library/PciLib.h> | |
| #include <Library/IoLib.h> | |
| #include <Library/DebugLib.h> | |
| #include <Library/PcdLib.h> | |
| #include <Library/BaseMemoryLib.h> | |
| #include <Library/IntelQNCLib.h> | |
| #include <Library/QNCAccessLib.h> | |
| #include <Uefi/UefiBaseType.h> | |
| // | |
| // Maximum time allowed while waiting the SPI cycle to complete | |
| // Wait Time = 6 seconds = 6000000 microseconds | |
| // Wait Period = 10 microseconds | |
| // | |
| #define WAIT_TIME 6000000 | |
| #define WAIT_PERIOD 10 | |
| // | |
| // PCH Required SPI Commands -------- COMMAND SET I ------------ | |
| // SPI flash device must support in order to be compatible with PCH | |
| // | |
| #define PCH_SPI_COMMAND_PROGRAM_BYTE 0x02 | |
| #define PCH_SPI_COMMAND_READ_DATA 0x03 | |
| #define PCH_SPI_COMMAND_WRITE_DISABLE 0x04 | |
| #define PCH_SPI_COMMAND_READ_STATUS 0x05 | |
| #define PCH_SPI_COMMAND_WRITE_ENABLE 0x06 | |
| #define PCH_SPI_COMMAND_FAST_READ 0x0B | |
| #define PCH_SPI_COMMAND_READ_ID 0x9F | |
| #define PCH_SPI_COMMAND_DUAL_FAST_READ 0x3B // Dual Output Fast Read | |
| // | |
| // Need to support at least one of the following two kinds of size of sector for erasing | |
| // | |
| #define PCH_SPI_COMMAND_4KB_ERASE 0x20 | |
| #define PCH_SPI_COMMAND_64KB_ERASE 0xD8 | |
| // | |
| // Recommended SPI Commands -------- COMMAND SET II ------------ | |
| // SPI flash device best to support | |
| // | |
| #define PCH_SPI_COMMAND_WRITE_STATUS 0x01 | |
| #define PCH_SPI_COMMAND_FULL_CHIP_ERASE 0xC7 | |
| // | |
| // Private data structure definitions for the driver | |
| // | |
| #define PCH_SPI_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('P', 'S', 'P', 'I') | |
| typedef struct { | |
| UINTN Signature; | |
| EFI_HANDLE Handle; | |
| EFI_SPI_PROTOCOL SpiProtocol; | |
| SPI_INIT_TABLE SpiInitTable; | |
| UINTN PchRootComplexBar; | |
| BOOLEAN InitDone; // Set to TRUE on SpiProtocolInit SUCCESS. | |
| SPI_INIT_INFO InitInfo; | |
| } SPI_INSTANCE; | |
| #define SPI_INSTANCE_FROM_SPIPROTOCOL(a) CR (a, SPI_INSTANCE, SpiProtocol, PCH_SPI_PRIVATE_DATA_SIGNATURE) | |
| // | |
| // Function prototypes used by the SPI protocol. | |
| // | |
| EFI_STATUS | |
| SpiProtocolConstructor ( | |
| SPI_INSTANCE *SpiInstance | |
| ) | |
| /*++ | |
| Routine Description: | |
| Initialize an SPI protocol instance. | |
| The function will assert in debug if PCH RCBA has not been initialized | |
| Arguments: | |
| SpiInstance - Pointer to SpiInstance to initialize | |
| Returns: | |
| EFI_SUCCESS The protocol instance was properly initialized | |
| EFI_UNSUPPORTED The PCH is not supported by this module | |
| --*/ | |
| ; | |
| EFI_STATUS | |
| EFIAPI | |
| SpiProtocolInit ( | |
| IN EFI_SPI_PROTOCOL *This, | |
| IN SPI_INIT_TABLE *InitTable | |
| ) | |
| /*++ | |
| Routine Description: | |
| Initialize the host controller to execute SPI command. | |
| Arguments: | |
| This Pointer to the EFI_SPI_PROTOCOL instance. | |
| InitTable Initialization data to be programmed into the SPI host controller. | |
| Returns: | |
| EFI_SUCCESS Initialization completed. | |
| EFI_ACCESS_DENIED The SPI static configuration interface has been locked-down. | |
| EFI_INVALID_PARAMETER Bad input parameters. | |
| --*/ | |
| ; | |
| EFI_STATUS | |
| EFIAPI | |
| SpiProtocolLock ( | |
| IN EFI_SPI_PROTOCOL *This | |
| ) | |
| /*++ | |
| Routine Description: | |
| Lock the SPI Static Configuration Interface. | |
| Once locked, the interface can not be changed and can only be clear by system reset. | |
| Arguments: | |
| This Pointer to the EFI_SPI_PROTOCOL instance. | |
| Returns: | |
| EFI_SUCCESS Lock operation succeed. | |
| EFI_DEVICE_ERROR Device error, operation failed. | |
| EFI_ACCESS_DENIED The interface has already been locked. | |
| --*/ | |
| ; | |
| EFI_STATUS | |
| EFIAPI | |
| SpiProtocolExecute ( | |
| IN EFI_SPI_PROTOCOL *This, | |
| IN UINT8 OpcodeIndex, | |
| IN UINT8 PrefixOpcodeIndex, | |
| IN BOOLEAN DataCycle, | |
| IN BOOLEAN Atomic, | |
| IN BOOLEAN ShiftOut, | |
| IN UINTN Address, | |
| IN UINT32 DataByteCount, | |
| IN OUT UINT8 *Buffer, | |
| IN SPI_REGION_TYPE SpiRegionType | |
| ) | |
| /*++ | |
| Routine Description: | |
| Execute SPI commands from the host controller. | |
| Arguments: | |
| This Pointer to the EFI_SPI_PROTOCOL instance. | |
| OpcodeIndex Index of the command in the OpCode Menu. | |
| PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence. | |
| DataCycle TRUE if the SPI cycle contains data | |
| Atomic TRUE if the SPI cycle is atomic and interleave cycles are not allowed. | |
| ShiftOut If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in. | |
| Address In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform | |
| Region, this value specifies the offset from the Region Base; for BIOS Region, | |
| this value specifies the offset from the start of the BIOS Image. In Non | |
| Descriptor Mode, this value specifies the offset from the start of the BIOS Image. | |
| Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor | |
| Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is | |
| supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or | |
| the flash (in Non Descriptor Mode) | |
| DataByteCount Number of bytes in the data portion of the SPI cycle. | |
| Buffer Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle. | |
| SpiRegionType SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe, | |
| EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in | |
| Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode | |
| and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative | |
| to base of the 1st flash device (i.e., it is a Flash Linear Address). | |
| Returns: | |
| EFI_SUCCESS Command succeed. | |
| EFI_INVALID_PARAMETER The parameters specified are not valid. | |
| EFI_UNSUPPORTED Command not supported. | |
| EFI_DEVICE_ERROR Device error, command aborts abnormally. | |
| --*/ | |
| ; | |
| EFI_STATUS | |
| SendSpiCmd ( | |
| IN EFI_SPI_PROTOCOL *This, | |
| IN UINT8 OpcodeIndex, | |
| IN UINT8 PrefixOpcodeIndex, | |
| IN BOOLEAN DataCycle, | |
| IN BOOLEAN Atomic, | |
| IN BOOLEAN ShiftOut, | |
| IN UINTN Address, | |
| IN UINT32 DataByteCount, | |
| IN OUT UINT8 *Buffer, | |
| IN SPI_REGION_TYPE SpiRegionType | |
| ) | |
| /*++ | |
| Routine Description: | |
| This function sends the programmed SPI command to the slave device. | |
| Arguments: | |
| OpcodeIndex Index of the command in the OpCode Menu. | |
| PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence. | |
| DataCycle TRUE if the SPI cycle contains data | |
| Atomic TRUE if the SPI cycle is atomic and interleave cycles are not allowed. | |
| ShiftOut If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in. | |
| Address In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform | |
| Region, this value specifies the offset from the Region Base; for BIOS Region, | |
| this value specifies the offset from the start of the BIOS Image. In Non | |
| Descriptor Mode, this value specifies the offset from the start of the BIOS Image. | |
| Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor | |
| Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is | |
| supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or | |
| the flash (in Non Descriptor Mode) | |
| DataByteCount Number of bytes in the data portion of the SPI cycle. This function may break the | |
| data transfer into multiple operations. This function ensures each operation does | |
| not cross 256 byte flash address boundary. | |
| *NOTE: if there is some SPI chip that has a stricter address boundary requirement | |
| (e.g., its write page size is < 256 byte), then the caller cannot rely on this | |
| function to cut the data transfer at proper address boundaries, and it's the | |
| caller's reponsibility to pass in a properly cut DataByteCount parameter. | |
| Buffer Data received or sent during the SPI cycle. | |
| SpiRegionType SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe, | |
| EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in | |
| Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode | |
| and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative | |
| to base of the 1st flash device (i.e., it is a Flash Linear Address). | |
| Returns: | |
| EFI_SUCCESS SPI command completes successfully. | |
| EFI_DEVICE_ERROR Device error, the command aborts abnormally. | |
| EFI_ACCESS_DENIED Some unrecognized command encountered in hardware sequencing mode | |
| EFI_INVALID_PARAMETER The parameters specified are not valid. | |
| --*/ | |
| ; | |
| BOOLEAN | |
| WaitForSpiCycleComplete ( | |
| IN EFI_SPI_PROTOCOL *This, | |
| IN BOOLEAN ErrorCheck | |
| ) | |
| /*++ | |
| Routine Description: | |
| Wait execution cycle to complete on the SPI interface. Check both Hardware | |
| and Software Sequencing status registers | |
| Arguments: | |
| This - The SPI protocol instance | |
| UseSoftwareSequence - TRUE if this is a Hardware Sequencing operation | |
| ErrorCheck - TRUE if the SpiCycle needs to do the error check | |
| Returns: | |
| TRUE SPI cycle completed on the interface. | |
| FALSE Time out while waiting the SPI cycle to complete. | |
| It's not safe to program the next command on the SPI interface. | |
| --*/ | |
| ; | |
| EFI_STATUS | |
| EFIAPI | |
| SpiProtocolInfo ( | |
| IN EFI_SPI_PROTOCOL *This, | |
| OUT SPI_INIT_INFO **InitInfoPtr | |
| ) | |
| /*++ | |
| Routine Description: | |
| Return info about SPI host controller, to help callers usage of Execute | |
| service. | |
| If 0xff is returned as an opcode index in init info struct | |
| then device does not support the operation. | |
| Arguments: | |
| This Pointer to the EFI_SPI_PROTOCOL instance. | |
| InitInfoPtr Pointer to init info written to this memory location. | |
| Returns: | |
| EFI_SUCCESS Information returned. | |
| EFI_INVALID_PARAMETER Invalid parameter. | |
| EFI_NOT_READY Required resources not setup. | |
| Others Unexpected error happened. | |
| --*/ | |
| ; | |
| #endif |