diff options
Diffstat (limited to 'ReferenceCode/Chipset/LynxPoint/Spi/Common/SpiCommon.h')
| -rw-r--r-- | ReferenceCode/Chipset/LynxPoint/Spi/Common/SpiCommon.h | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/ReferenceCode/Chipset/LynxPoint/Spi/Common/SpiCommon.h b/ReferenceCode/Chipset/LynxPoint/Spi/Common/SpiCommon.h new file mode 100644 index 0000000..224ebee --- /dev/null +++ b/ReferenceCode/Chipset/LynxPoint/Spi/Common/SpiCommon.h @@ -0,0 +1,300 @@ +/** @file + Header file for the PCH SPI Common Driver. + +@copyright + Copyright (c) 2008 - 2012 Intel Corporation. All rights reserved + This software and associated documentation (if any) is furnished + under a license and may only be used or copied in accordance + with the terms of the license. Except as permitted by such + license, no part of this software or documentation may be + reproduced, stored in a retrieval system, or transmitted in any + form or by any means without the express written consent of + Intel Corporation. + + This file contains an 'Intel Peripheral Driver' and uniquely + identified as "Intel Reference Module" and is + licensed for Intel CPUs and chipsets under the terms of your + license agreement with Intel or your vendor. This file may + be modified by the user, subject to additional terms of the + license agreement + +**/ +#ifndef _SPI_COMMON_H_ +#define _SPI_COMMON_H_ + +// +// External include files do NOT need to be explicitly specified in real EDKII +// environment +// +#if !defined(EDK_RELEASE_VERSION) || (EDK_RELEASE_VERSION < 0x00020000) +#include "PchAccess.h" +#include "PchPlatformLib.h" +#endif +// +// Maximum time allowed while waiting the SPI cycle to complete +// Wait Time = 6 seconds = 6000000 microseconds +// Wait Period = 10 microseconds +// +#define WAIT_TIME 6000000 ///< Wait Time = 6 seconds = 6000000 microseconds +#define WAIT_PERIOD 10 ///< Wait Period = 10 microseconds +// +// PCH Required SPI Commands -------- COMMAND SET I ------------ +// SPI flash device must support in order to be compatible with PCH +// +#define PCH_SPI_COMMAND_WRITE_STATUS 0x01 +#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_DUAL_FAST_READ 0x3B ///< Dual Output Fast Read +#define PCH_SPI_COMMAND_ENABLE_WRITE_STATUS 0x50 ///< Enable Write Status Register +#define PCH_SPI_COMMAND_DISCOVERY_PARAMETERS 0x5A ///< Serial Flash Discovery Parameters +#define PCH_SPI_COMMAND_READ_ID 0x9F ///< JEDEC Read ID +#define PCH_SPI_COMMAND_FULL_CHIP_ERASE 0xC7 ///< Full Chip Erase +// +// Need to support at least one of the following three kinds of size of sector for erasing +// +#define PCH_SPI_COMMAND_4KB_ERASE 0x20 +#define PCH_SPI_COMMAND_64KB_ERASE 0xD8 +#define PCH_SPI_COMMAND_256B_ERASE 0xDB +// +// ICH8M Recommended SPI Commands -------- COMMAND SET II ------------ +// SPI flash device best to support +// +#define PCH_SPI_COMMAND_WRITE_STATUS 0x01 +#define PCH_SPI_COMMAND_WRITE_STATUS_EN 0x50 +#define PCH_SPI_COMMAND_FULL_CHIP_ERASE 0xC7 + +#define SIZE_OF_SPI_VTBA_ENTRY (S_PCH_SPI_VTBA_JID0 + S_PCH_SPI_VTBA_VSCC0) + +/// +/// Private data structure definitions for the driver +/// +#define PCH_SPI_PRIVATE_DATA_SIGNATURE EFI_SIGNATURE_32 ('P', 'S', 'P', 'I') + +/// +/// Initialization data table loaded to the SPI host controller +/// PrefixOpcode Prefix opcodes which are loaded into the SPI host controller +/// SpiCmdConfig Determines Opcode Type, Menu and Frequency of the SPI commands +/// BiosStartOffset The offset of the start of the BIOS image relative to the flash device. +/// Please note this is a Flash Linear Address, NOT a memory space address. +/// This value is platform specific and depends on the system flash map. +/// This value is only used on non Descriptor mode. +/// BiosSize The the BIOS Image size in flash. This value is platform specific +/// and depends on the system flash map. 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) +/// +typedef struct _SPI_INIT_TABLE { + UINT8 PrefixOpcode[SPI_NUM_PREFIX_OPCODE]; + SPI_COMMAND_CONFIG SpiCmdConfig[SPI_NUM_OPCODE]; + UINTN BiosStartOffset; + UINTN BiosSize; +} SPI_INIT_TABLE; + +typedef struct _SPI_ID_TABLE { + UINT8 VendorId; + UINT8 DeviceId0; + UINT8 DeviceId1; +} SPI_ID_TABLE; + +typedef struct _SPI_DESCRIPTOR_TABLE { + UINT8 NumberComponents :2; + UINT8 Comp1Density :4; + UINT8 Rsvd :2; +} SPI_DESCRIPTOR_TABLE; + +typedef struct { + UINTN Signature; + EFI_HANDLE Handle; + EFI_SPI_PROTOCOL SpiProtocol; + SPI_INIT_TABLE SpiInitTable; + SPI_ID_TABLE SpiIdTable[2]; + UINTN PchRootComplexBar; + SPI_DESCRIPTOR_TABLE SpiDescriptor; + BOOLEAN DescriptorMode; +} 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. +// + +/** + Initialize an SPI protocol instance. + The function will assert in debug if PCH RCBA has not been initialized + + @param[in] SpiInstance Pointer to SpiInstance to initialize + + @retval EFI_SUCCESS The protocol instance was properly initialized + @exception EFI_UNSUPPORTED The PCH is not supported by this module +**/ +EFI_STATUS +SpiProtocolConstructor ( + SPI_INSTANCE *SpiInstance + ); + +/** + JEDEC Read IDs from SPI flash part, this function will return 1-byte Vendor ID and 2-byte Device ID + + @param[in] This Pointer to the EFI_SPI_PROTOCOL instance. + @param[in] Address This value is for determines the command is sent to SPI Component 1 or 2 + @param[in, out] Buffer Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle. + + @retval EFI_SUCCESS Read Jedec Id completed. + @retval EFI_DEVICE_ERROR Device error, operation failed. + @exception EFI_UNSUPPORTED This function is unsupport after SpiProtocolInit is called +**/ +EFI_STATUS +EFIAPI +SpiProtocolReadId ( + IN EFI_SPI_PROTOCOL *This, + IN UINTN Address, + IN OUT UINT8 *Buffer + ); + +/** + Initialize the host controller to execute SPI command. + + @param[in] This Pointer to the EFI_SPI_PROTOCOL instance. + @param[in] InitData Initialization data to be programmed into the SPI host controller. + + @retval EFI_SUCCESS Initialization completed. + @retval EFI_ACCESS_DENIED The SPI static configuration interface has been locked-down. + @retval EFI_INVALID_PARAMETER Bad input parameters. + @exception EFI_UNSUPPORTED Can't get Descriptor mode VSCC values +**/ +EFI_STATUS +EFIAPI +SpiProtocolInit ( + IN EFI_SPI_PROTOCOL *This, + IN SPI_INIT_DATA *InitData + ); + +/** + Execute SPI commands from the host controller. + This function would be called by runtime driver, please do not use any MMIO marco here + + @param[in] This Pointer to the EFI_SPI_PROTOCOL instance. + @param[in] OpcodeIndex Index of the command in the OpCode Menu. + @param[in] PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence. + @param[in] DataCycle TRUE if the SPI cycle contains data + @param[in] Atomic TRUE if the SPI cycle is atomic and interleave cycles are not allowed. + @param[in] ShiftOut If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in. + @param[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) + @param[in] 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. + @param[in, out] Buffer Pointer to caller-allocated buffer containing the dada received or sent during the + SPI cycle. + @param[in] 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). + + @retval EFI_SUCCESS Command succeed. + @retval EFI_INVALID_PARAMETER The parameters specified are not valid. + @exception EFI_UNSUPPORTED Command not supported. + @retval EFI_DEVICE_ERROR Device error, command aborts abnormally. +**/ +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 + ); + +/** + This function sends the programmed SPI command to the slave device. + + @param[in] OpcodeIndex Index of the command in the OpCode Menu. + @param[in] PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence. + @param[in] DataCycle TRUE if the SPI cycle contains data + @param[in] Atomic TRUE if the SPI cycle is atomic and interleave cycles are not allowed. + @param[in] ShiftOut If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in. + @param[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) + @param[in] 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. + @param[in, out] Buffer Data received or sent during the SPI cycle. + @param[in] 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). + + @retval EFI_SUCCESS SPI command completes successfully. + @retval EFI_DEVICE_ERROR Device error, the command aborts abnormally. + @retval EFI_ACCESS_DENIED Some unrecognized command encountered in hardware sequencing mode + @retval EFI_INVALID_PARAMETER The parameters specified are not valid. +**/ +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 + ); + +/** + Wait execution cycle to complete on the SPI interface. Check both Hardware + and Software Sequencing status registers + + @param[in] This The SPI protocol instance + @param[in] UseSoftwareSequence TRUE if this is a Hardware Sequencing operation + @param[in] ErrorCheck TRUE if the SpiCycle needs to do the error check + + @retval TRUE SPI cycle completed on the interface. + @retval FALSE Time out while waiting the SPI cycle to complete. + It's not safe to program the next command on the SPI interface. +**/ +BOOLEAN +WaitForSpiCycleComplete ( + IN EFI_SPI_PROTOCOL *This, + IN BOOLEAN UseSoftwareSequence, + IN BOOLEAN ErrorCheck + ); + +#endif |