/** @file
|
Header file for the PCH SPI Common Driver.
|
|
Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
**/
|
#ifndef _PCH_SPI_COMMON_LIB_H_
|
#define _PCH_SPI_COMMON_LIB_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 ///< Wait Time = 6 seconds = 6000000 microseconds
|
#define WAIT_PERIOD 10 ///< Wait Period = 10 microseconds
|
|
///
|
/// Flash cycle Type
|
///
|
typedef enum {
|
FlashCycleRead,
|
FlashCycleWrite,
|
FlashCycleErase,
|
FlashCycleReadSfdp,
|
FlashCycleReadJedecId,
|
FlashCycleWriteStatus,
|
FlashCycleReadStatus,
|
FlashCycleMax
|
} FLASH_CYCLE_TYPE;
|
|
///
|
/// Flash Component Number
|
///
|
typedef enum {
|
FlashComponent0,
|
FlashComponent1,
|
FlashComponentMax
|
} FLASH_COMPONENT_NUM;
|
|
///
|
/// Private data structure definitions for the driver
|
///
|
#define PCH_SPI_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('P', 'S', 'P', 'I')
|
|
typedef struct {
|
UINT32 Signature;
|
EFI_HANDLE Handle;
|
PCH_SPI_PROTOCOL SpiProtocol;
|
UINT16 PchAcpiBase;
|
UINTN PchSpiBase;
|
UINT8 ReadPermission;
|
UINT8 WritePermission;
|
UINT32 SfdpVscc0Value;
|
UINT32 SfdpVscc1Value;
|
UINT16 PchStrapBaseAddr;
|
UINT16 PchStrapSize;
|
UINT16 CpuStrapBaseAddr;
|
UINT16 CpuStrapSize;
|
UINT8 NumberOfComponents;
|
UINT32 Component1StartAddr;
|
UINT32 TotalFlashSize;
|
} 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.
|
|
@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 (
|
IN SPI_INSTANCE *SpiInstance
|
);
|
|
/**
|
This function is a hook for Spi to disable BIOS Write Protect
|
|
@retval EFI_SUCCESS The protocol instance was properly initialized
|
@retval EFI_ACCESS_DENIED The BIOS Region can only be updated in SMM phase
|
|
**/
|
EFI_STATUS
|
EFIAPI
|
DisableBiosWriteProtect (
|
VOID
|
);
|
|
/**
|
This function is a hook for Spi to enable BIOS Write Protect
|
|
|
**/
|
VOID
|
EFIAPI
|
EnableBiosWriteProtect (
|
VOID
|
);
|
|
/**
|
Acquire pch spi mmio address.
|
|
@param[in] SpiInstance Pointer to SpiInstance to initialize
|
|
@retval PchSpiBar0 return SPI MMIO address
|
**/
|
UINTN
|
AcquireSpiBar0 (
|
IN SPI_INSTANCE *SpiInstance
|
);
|
|
/**
|
Release pch spi mmio address.
|
|
@param[in] SpiInstance Pointer to SpiInstance to initialize
|
|
@retval None
|
**/
|
VOID
|
ReleaseSpiBar0 (
|
IN SPI_INSTANCE *SpiInstance
|
);
|
|
/**
|
Read data from the flash part.
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] FlashRegionType The Flash Region type for flash cycle which is listed in the Descriptor.
|
@param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
|
@param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
|
@param[out] Buffer The Pointer to caller-allocated buffer containing the dada received.
|
It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
|
|
@retval EFI_SUCCESS Command succeed.
|
@retval EFI_INVALID_PARAMETER The parameters specified are not valid.
|
@retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolFlashRead (
|
IN PCH_SPI_PROTOCOL *This,
|
IN FLASH_REGION_TYPE FlashRegionType,
|
IN UINT32 Address,
|
IN UINT32 ByteCount,
|
OUT UINT8 *Buffer
|
);
|
|
/**
|
Write data to the flash part.
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] FlashRegionType The Flash Region type for flash cycle which is listed in the Descriptor.
|
@param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
|
@param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
|
@param[in] Buffer Pointer to caller-allocated buffer containing the data sent during the SPI cycle.
|
|
@retval EFI_SUCCESS Command succeed.
|
@retval EFI_INVALID_PARAMETER The parameters specified are not valid.
|
@retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolFlashWrite (
|
IN PCH_SPI_PROTOCOL *This,
|
IN FLASH_REGION_TYPE FlashRegionType,
|
IN UINT32 Address,
|
IN UINT32 ByteCount,
|
IN UINT8 *Buffer
|
);
|
|
/**
|
Erase some area on the flash part.
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] FlashRegionType The Flash Region type for flash cycle which is listed in the Descriptor.
|
@param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
|
@param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
|
|
@retval EFI_SUCCESS Command succeed.
|
@retval EFI_INVALID_PARAMETER The parameters specified are not valid.
|
@retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolFlashErase (
|
IN PCH_SPI_PROTOCOL *This,
|
IN FLASH_REGION_TYPE FlashRegionType,
|
IN UINT32 Address,
|
IN UINT32 ByteCount
|
);
|
|
/**
|
Read SFDP data from the flash part.
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] ComponentNumber The Componen Number for chip select
|
@param[in] Address The starting byte address for SFDP data read.
|
@param[in] ByteCount Number of bytes in SFDP data portion of the SPI cycle
|
@param[out] SfdpData The Pointer to caller-allocated buffer containing the SFDP data received
|
It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read
|
|
@retval EFI_SUCCESS Command succeed.
|
@retval EFI_INVALID_PARAMETER The parameters specified are not valid.
|
@retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolFlashReadSfdp (
|
IN PCH_SPI_PROTOCOL *This,
|
IN UINT8 ComponentNumber,
|
IN UINT32 Address,
|
IN UINT32 ByteCount,
|
OUT UINT8 *SfdpData
|
);
|
|
/**
|
Read Jedec Id from the flash part.
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] ComponentNumber The Componen Number for chip select
|
@param[in] ByteCount Number of bytes in JedecId data portion of the SPI cycle, the data size is 3 typically
|
@param[out] JedecId The Pointer to caller-allocated buffer containing JEDEC ID received
|
It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
|
|
@retval EFI_SUCCESS Command succeed.
|
@retval EFI_INVALID_PARAMETER The parameters specified are not valid.
|
@retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolFlashReadJedecId (
|
IN PCH_SPI_PROTOCOL *This,
|
IN UINT8 ComponentNumber,
|
IN UINT32 ByteCount,
|
OUT UINT8 *JedecId
|
);
|
|
/**
|
Write the status register in the flash part.
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] ByteCount Number of bytes in Status data portion of the SPI cycle, the data size is 1 typically
|
@param[in] StatusValue The Pointer to caller-allocated buffer containing the value of Status register writing
|
|
@retval EFI_SUCCESS Command succeed.
|
@retval EFI_INVALID_PARAMETER The parameters specified are not valid.
|
@retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolFlashWriteStatus (
|
IN PCH_SPI_PROTOCOL *This,
|
IN UINT32 ByteCount,
|
IN UINT8 *StatusValue
|
);
|
|
/**
|
Read status register in the flash part.
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] ByteCount Number of bytes in Status data portion of the SPI cycle, the data size is 1 typically
|
@param[out] StatusValue The Pointer to caller-allocated buffer containing the value of Status register received.
|
|
@retval EFI_SUCCESS Command succeed.
|
@retval EFI_INVALID_PARAMETER The parameters specified are not valid.
|
@retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolFlashReadStatus (
|
IN PCH_SPI_PROTOCOL *This,
|
IN UINT32 ByteCount,
|
OUT UINT8 *StatusValue
|
);
|
|
/**
|
Get the SPI region base and size, based on the enum type
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] FlashRegionType The Flash Region type for for the base address which is listed in the Descriptor.
|
@param[out] BaseAddress The Flash Linear Address for the Region 'n' Base
|
@param[out] RegionSize The size for the Region 'n'
|
|
@retval EFI_SUCCESS Read success
|
@retval EFI_INVALID_PARAMETER Invalid region type given
|
@retval EFI_DEVICE_ERROR The region is not used
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolGetRegionAddress (
|
IN PCH_SPI_PROTOCOL *This,
|
IN FLASH_REGION_TYPE FlashRegionType,
|
OUT UINT32 *BaseAddress,
|
OUT UINT32 *RegionSize
|
);
|
|
/**
|
Read PCH Soft Strap Values
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] SoftStrapAddr PCH Soft Strap address offset from FPSBA.
|
@param[in] ByteCount Number of bytes in SoftStrap data portion of the SPI cycle
|
@param[out] SoftStrapValue The Pointer to caller-allocated buffer containing PCH Soft Strap Value.
|
If the value of ByteCount is 0, the data type of SoftStrapValue should be UINT16 and SoftStrapValue will be PCH Soft Strap Length
|
It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
|
|
@retval EFI_SUCCESS Command succeed.
|
@retval EFI_INVALID_PARAMETER The parameters specified are not valid.
|
@retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolReadPchSoftStrap (
|
IN PCH_SPI_PROTOCOL *This,
|
IN UINT32 SoftStrapAddr,
|
IN UINT32 ByteCount,
|
OUT VOID *SoftStrapValue
|
);
|
|
/**
|
Read CPU Soft Strap Values
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] SoftStrapAddr CPU Soft Strap address offset from FCPUSBA.
|
@param[in] ByteCount Number of bytes in SoftStrap data portion of the SPI cycle.
|
@param[out] SoftStrapValue The Pointer to caller-allocated buffer containing CPU Soft Strap Value.
|
If the value of ByteCount is 0, the data type of SoftStrapValue should be UINT16 and SoftStrapValue will be PCH Soft Strap Length
|
It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
|
|
@retval EFI_SUCCESS Command succeed.
|
@retval EFI_INVALID_PARAMETER The parameters specified are not valid.
|
@retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
|
**/
|
EFI_STATUS
|
EFIAPI
|
SpiProtocolReadCpuSoftStrap (
|
IN PCH_SPI_PROTOCOL *This,
|
IN UINT32 SoftStrapAddr,
|
IN UINT32 ByteCount,
|
OUT VOID *SoftStrapValue
|
);
|
|
/**
|
This function sends the programmed SPI command to the slave device.
|
|
@param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
|
@param[in] SpiRegionType The SPI Region type for flash cycle which is listed in the Descriptor
|
@param[in] FlashCycleType The Flash SPI cycle type list in HSFC (Hardware Sequencing Flash Control Register) register
|
@param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
|
@param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
|
@param[in,out] Buffer Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle.
|
|
@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 PCH_SPI_PROTOCOL *This,
|
IN FLASH_REGION_TYPE FlashRegionType,
|
IN FLASH_CYCLE_TYPE FlashCycleType,
|
IN UINT32 Address,
|
IN UINT32 ByteCount,
|
IN OUT UINT8 *Buffer
|
);
|
|
/**
|
Wait execution cycle to complete on the SPI interface.
|
|
@param[in] This The SPI protocol instance
|
@param[in] PchSpiBar0 Spi MMIO base address
|
@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 PCH_SPI_PROTOCOL *This,
|
IN UINTN PchSpiBar0,
|
IN BOOLEAN ErrorCheck
|
);
|
|
#endif
|
