PchSpiCommonLib.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396
  1. /** @file
  2. Header file for the PCH SPI Common Driver.
  3. Copyright (c) 2019 Intel Corporation. All rights reserved. <BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. **/
  6. #ifndef _PCH_SPI_COMMON_LIB_H_
  7. #define _PCH_SPI_COMMON_LIB_H_
  8. //
  9. // Maximum time allowed while waiting the SPI cycle to complete
  10. // Wait Time = 6 seconds = 6000000 microseconds
  11. // Wait Period = 10 microseconds
  12. //
  13. #define SPI_WAIT_TIME 6000000 ///< Wait Time = 6 seconds = 6000000 microseconds
  14. #define SPI_WAIT_PERIOD 10 ///< Wait Period = 10 microseconds
  15. ///
  16. /// Flash cycle Type
  17. ///
  18. typedef enum {
  19. FlashCycleRead,
  20. FlashCycleWrite,
  21. FlashCycleErase,
  22. FlashCycleReadSfdp,
  23. FlashCycleReadJedecId,
  24. FlashCycleWriteStatus,
  25. FlashCycleReadStatus,
  26. FlashCycleMax
  27. } FLASH_CYCLE_TYPE;
  28. ///
  29. /// Flash Component Number
  30. ///
  31. typedef enum {
  32. FlashComponent0,
  33. FlashComponent1,
  34. FlashComponentMax
  35. } FLASH_COMPONENT_NUM;
  36. ///
  37. /// Private data structure definitions for the driver
  38. ///
  39. #define PCH_SPI_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('P', 'S', 'P', 'I')
  40. typedef struct {
  41. UINT32 Signature;
  42. EFI_HANDLE Handle;
  43. EFI_SPI_PROTOCOL SpiProtocol;
  44. UINT16 PchAcpiBase;
  45. UINTN PchSpiBase;
  46. UINT16 ReadPermission;
  47. UINT16 WritePermission;
  48. UINT32 SfdpVscc0Value;
  49. UINT32 SfdpVscc1Value;
  50. UINT16 PchStrapBaseAddr;
  51. UINT16 PchStrapSize;
  52. UINT16 CpuStrapBaseAddr;
  53. UINT16 CpuStrapSize;
  54. UINT8 NumberOfComponents;
  55. UINT32 Component1StartAddr;
  56. UINT32 TotalFlashSize;
  57. } SPI_INSTANCE;
  58. #define SPI_INSTANCE_FROM_SPIPROTOCOL(a) CR (a, SPI_INSTANCE, SpiProtocol, PCH_SPI_PRIVATE_DATA_SIGNATURE)
  59. //
  60. // Function prototypes used by the SPI protocol.
  61. //
  62. /**
  63. Initialize an SPI protocol instance.
  64. @param[in] SpiInstance Pointer to SpiInstance to initialize
  65. @retval EFI_SUCCESS The protocol instance was properly initialized
  66. @exception EFI_UNSUPPORTED The PCH is not supported by this module
  67. **/
  68. EFI_STATUS
  69. SpiProtocolConstructor (
  70. IN SPI_INSTANCE *SpiInstance
  71. );
  72. /**
  73. This function is a hook for Spi to disable BIOS Write Protect
  74. @retval EFI_SUCCESS The protocol instance was properly initialized
  75. @retval EFI_ACCESS_DENIED The BIOS Region can only be updated in SMM phase
  76. **/
  77. EFI_STATUS
  78. EFIAPI
  79. DisableBiosWriteProtect (
  80. VOID
  81. );
  82. /**
  83. This function is a hook for Spi to enable BIOS Write Protect
  84. **/
  85. VOID
  86. EFIAPI
  87. EnableBiosWriteProtect (
  88. VOID
  89. );
  90. /**
  91. Acquire pch spi mmio address.
  92. @param[in] SpiInstance Pointer to SpiInstance to initialize
  93. @retval PchSpiBar0 return SPI MMIO address
  94. **/
  95. UINTN
  96. AcquireSpiBar0 (
  97. IN SPI_INSTANCE *SpiInstance
  98. );
  99. /**
  100. Release pch spi mmio address.
  101. @param[in] SpiInstance Pointer to SpiInstance to initialize
  102. @retval None
  103. **/
  104. VOID
  105. ReleaseSpiBar0 (
  106. IN SPI_INSTANCE *SpiInstance
  107. );
  108. /**
  109. Read data from the flash part.
  110. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  111. @param[in] FlashRegionType The Flash Region type for flash cycle which is listed in the Descriptor.
  112. @param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
  113. @param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
  114. @param[out] Buffer The Pointer to caller-allocated buffer containing the dada received.
  115. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  116. @retval EFI_SUCCESS Command succeed.
  117. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  118. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  119. **/
  120. EFI_STATUS
  121. EFIAPI
  122. SpiProtocolFlashRead (
  123. IN EFI_SPI_PROTOCOL *This,
  124. IN FLASH_REGION_TYPE FlashRegionType,
  125. IN UINT32 Address,
  126. IN UINT32 ByteCount,
  127. OUT UINT8 *Buffer
  128. );
  129. /**
  130. Write data to the flash part.
  131. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  132. @param[in] FlashRegionType The Flash Region type for flash cycle which is listed in the Descriptor.
  133. @param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
  134. @param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
  135. @param[in] Buffer Pointer to caller-allocated buffer containing the data sent during the SPI cycle.
  136. @retval EFI_SUCCESS Command succeed.
  137. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  138. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  139. **/
  140. EFI_STATUS
  141. EFIAPI
  142. SpiProtocolFlashWrite (
  143. IN EFI_SPI_PROTOCOL *This,
  144. IN FLASH_REGION_TYPE FlashRegionType,
  145. IN UINT32 Address,
  146. IN UINT32 ByteCount,
  147. IN UINT8 *Buffer
  148. );
  149. /**
  150. Erase some area on the flash part.
  151. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  152. @param[in] FlashRegionType The Flash Region type for flash cycle which is listed in the Descriptor.
  153. @param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
  154. @param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
  155. @retval EFI_SUCCESS Command succeed.
  156. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  157. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  158. **/
  159. EFI_STATUS
  160. EFIAPI
  161. SpiProtocolFlashErase (
  162. IN EFI_SPI_PROTOCOL *This,
  163. IN FLASH_REGION_TYPE FlashRegionType,
  164. IN UINT32 Address,
  165. IN UINT32 ByteCount
  166. );
  167. /**
  168. Read SFDP data from the flash part.
  169. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  170. @param[in] ComponentNumber The Componen Number for chip select
  171. @param[in] Address The starting byte address for SFDP data read.
  172. @param[in] ByteCount Number of bytes in SFDP data portion of the SPI cycle
  173. @param[out] SfdpData The Pointer to caller-allocated buffer containing the SFDP data received
  174. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read
  175. @retval EFI_SUCCESS Command succeed.
  176. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  177. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  178. **/
  179. EFI_STATUS
  180. EFIAPI
  181. SpiProtocolFlashReadSfdp (
  182. IN EFI_SPI_PROTOCOL *This,
  183. IN UINT8 ComponentNumber,
  184. IN UINT32 Address,
  185. IN UINT32 ByteCount,
  186. OUT UINT8 *SfdpData
  187. );
  188. /**
  189. Read Jedec Id from the flash part.
  190. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  191. @param[in] ComponentNumber The Componen Number for chip select
  192. @param[in] ByteCount Number of bytes in JedecId data portion of the SPI cycle, the data size is 3 typically
  193. @param[out] JedecId The Pointer to caller-allocated buffer containing JEDEC ID received
  194. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  195. @retval EFI_SUCCESS Command succeed.
  196. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  197. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  198. **/
  199. EFI_STATUS
  200. EFIAPI
  201. SpiProtocolFlashReadJedecId (
  202. IN EFI_SPI_PROTOCOL *This,
  203. IN UINT8 ComponentNumber,
  204. IN UINT32 ByteCount,
  205. OUT UINT8 *JedecId
  206. );
  207. /**
  208. Write the status register in the flash part.
  209. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  210. @param[in] ByteCount Number of bytes in Status data portion of the SPI cycle, the data size is 1 typically
  211. @param[in] StatusValue The Pointer to caller-allocated buffer containing the value of Status register writing
  212. @retval EFI_SUCCESS Command succeed.
  213. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  214. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  215. **/
  216. EFI_STATUS
  217. EFIAPI
  218. SpiProtocolFlashWriteStatus (
  219. IN EFI_SPI_PROTOCOL *This,
  220. IN UINT32 ByteCount,
  221. IN UINT8 *StatusValue
  222. );
  223. /**
  224. Read status register in the flash part.
  225. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  226. @param[in] ByteCount Number of bytes in Status data portion of the SPI cycle, the data size is 1 typically
  227. @param[out] StatusValue The Pointer to caller-allocated buffer containing the value of Status register received.
  228. @retval EFI_SUCCESS Command succeed.
  229. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  230. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  231. **/
  232. EFI_STATUS
  233. EFIAPI
  234. SpiProtocolFlashReadStatus (
  235. IN EFI_SPI_PROTOCOL *This,
  236. IN UINT32 ByteCount,
  237. OUT UINT8 *StatusValue
  238. );
  239. /**
  240. Get the SPI region base and size, based on the enum type
  241. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  242. @param[in] FlashRegionType The Flash Region type for for the base address which is listed in the Descriptor.
  243. @param[out] BaseAddress The Flash Linear Address for the Region 'n' Base
  244. @param[out] RegionSize The size for the Region 'n'
  245. @retval EFI_SUCCESS Read success
  246. @retval EFI_INVALID_PARAMETER Invalid region type given
  247. @retval EFI_DEVICE_ERROR The region is not used
  248. **/
  249. EFI_STATUS
  250. EFIAPI
  251. SpiProtocolGetRegionAddress (
  252. IN EFI_SPI_PROTOCOL *This,
  253. IN FLASH_REGION_TYPE FlashRegionType,
  254. OUT UINT32 *BaseAddress,
  255. OUT UINT32 *RegionSize
  256. );
  257. /**
  258. Read PCH Soft Strap Values
  259. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  260. @param[in] SoftStrapAddr PCH Soft Strap address offset from FPSBA.
  261. @param[in] ByteCount Number of bytes in SoftStrap data portion of the SPI cycle
  262. @param[out] SoftStrapValue The Pointer to caller-allocated buffer containing PCH Soft Strap Value.
  263. If the value of ByteCount is 0, the data type of SoftStrapValue should be UINT16 and SoftStrapValue will be PCH Soft Strap Length
  264. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  265. @retval EFI_SUCCESS Command succeed.
  266. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  267. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  268. **/
  269. EFI_STATUS
  270. EFIAPI
  271. SpiProtocolReadPchSoftStrap (
  272. IN EFI_SPI_PROTOCOL *This,
  273. IN UINT32 SoftStrapAddr,
  274. IN UINT32 ByteCount,
  275. OUT VOID *SoftStrapValue
  276. );
  277. /**
  278. Read CPU Soft Strap Values
  279. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  280. @param[in] SoftStrapAddr CPU Soft Strap address offset from FCPUSBA.
  281. @param[in] ByteCount Number of bytes in SoftStrap data portion of the SPI cycle.
  282. @param[out] SoftStrapValue The Pointer to caller-allocated buffer containing CPU Soft Strap Value.
  283. If the value of ByteCount is 0, the data type of SoftStrapValue should be UINT16 and SoftStrapValue will be PCH Soft Strap Length
  284. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  285. @retval EFI_SUCCESS Command succeed.
  286. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  287. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  288. **/
  289. EFI_STATUS
  290. EFIAPI
  291. SpiProtocolReadCpuSoftStrap (
  292. IN EFI_SPI_PROTOCOL *This,
  293. IN UINT32 SoftStrapAddr,
  294. IN UINT32 ByteCount,
  295. OUT VOID *SoftStrapValue
  296. );
  297. /**
  298. This function sends the programmed SPI command to the slave device.
  299. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  300. @param[in] SpiRegionType The SPI Region type for flash cycle which is listed in the Descriptor
  301. @param[in] FlashCycleType The Flash SPI cycle type list in HSFC (Hardware Sequencing Flash Control Register) register
  302. @param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
  303. @param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
  304. @param[in,out] Buffer Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle.
  305. @retval EFI_SUCCESS SPI command completes successfully.
  306. @retval EFI_DEVICE_ERROR Device error, the command aborts abnormally.
  307. @retval EFI_ACCESS_DENIED Some unrecognized command encountered in hardware sequencing mode
  308. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  309. **/
  310. EFI_STATUS
  311. SendSpiCmd (
  312. IN EFI_SPI_PROTOCOL *This,
  313. IN FLASH_REGION_TYPE FlashRegionType,
  314. IN FLASH_CYCLE_TYPE FlashCycleType,
  315. IN UINT32 Address,
  316. IN UINT32 ByteCount,
  317. IN OUT UINT8 *Buffer
  318. );
  319. /**
  320. Wait execution cycle to complete on the SPI interface.
  321. @param[in] This The SPI protocol instance
  322. @param[in] PchSpiBar0 Spi MMIO base address
  323. @param[in] ErrorCheck TRUE if the SpiCycle needs to do the error check
  324. @retval TRUE SPI cycle completed on the interface.
  325. @retval FALSE Time out while waiting the SPI cycle to complete.
  326. It's not safe to program the next command on the SPI interface.
  327. **/
  328. BOOLEAN
  329. WaitForSpiCycleComplete (
  330. IN EFI_SPI_PROTOCOL *This,
  331. IN UINTN PchSpiBar0,
  332. IN BOOLEAN ErrorCheck
  333. );
  334. #endif