Spi.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295
  1. /** @file
  2. This file defines the PCH SPI Protocol which implements the
  3. Intel(R) PCH SPI Host Controller Compatibility Interface.
  4. Copyright (c) 2019 Intel Corporation. All rights reserved. <BR>
  5. SPDX-License-Identifier: BSD-2-Clause-Patent
  6. **/
  7. #ifndef _PCH_SPI_PROTOCOL_H_
  8. #define _PCH_SPI_PROTOCOL_H_
  9. //
  10. // Extern the GUID for protocol users.
  11. //
  12. extern EFI_GUID gEfiSpiProtocolGuid;
  13. extern EFI_GUID gEfiSmmSpiProtocolGuid;
  14. //
  15. // Forward reference for ANSI C compatibility
  16. //
  17. typedef struct _PCH_SPI_PROTOCOL EFI_SPI_PROTOCOL;
  18. //
  19. // SPI protocol data structures and definitions
  20. //
  21. /**
  22. Flash Region Type
  23. **/
  24. typedef enum {
  25. FlashRegionDescriptor,
  26. FlashRegionBios,
  27. FlashRegionMe,
  28. FlashRegionGbE,
  29. FlashRegionPlatformData,
  30. FlashRegionDer,
  31. FlashRegionAll,
  32. FlashRegionMax
  33. } FLASH_REGION_TYPE;
  34. //
  35. // Protocol member functions
  36. //
  37. /**
  38. Read data from the flash part.
  39. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  40. @param[in] FlashRegionType The Flash Region type for flash cycle which is listed in the Descriptor.
  41. @param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
  42. @param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
  43. @param[out] Buffer The Pointer to caller-allocated buffer containing the dada received.
  44. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  45. @retval EFI_SUCCESS Command succeed.
  46. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  47. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  48. **/
  49. typedef
  50. EFI_STATUS
  51. (EFIAPI *PCH_SPI_FLASH_READ) (
  52. IN EFI_SPI_PROTOCOL *This,
  53. IN FLASH_REGION_TYPE FlashRegionType,
  54. IN UINT32 Address,
  55. IN UINT32 ByteCount,
  56. OUT UINT8 *Buffer
  57. );
  58. /**
  59. Write data to the flash part. Remark: Erase may be needed before write to the flash part.
  60. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  61. @param[in] FlashRegionType The Flash Region type for flash cycle which is listed in the Descriptor.
  62. @param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
  63. @param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
  64. @param[in] Buffer Pointer to caller-allocated buffer containing the data sent during the SPI cycle.
  65. @retval EFI_SUCCESS Command succeed.
  66. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  67. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  68. **/
  69. typedef
  70. EFI_STATUS
  71. (EFIAPI *PCH_SPI_FLASH_WRITE) (
  72. IN EFI_SPI_PROTOCOL *This,
  73. IN FLASH_REGION_TYPE FlashRegionType,
  74. IN UINT32 Address,
  75. IN UINT32 ByteCount,
  76. IN UINT8 *Buffer
  77. );
  78. /**
  79. Erase some area on the flash part.
  80. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  81. @param[in] FlashRegionType The Flash Region type for flash cycle which is listed in the Descriptor.
  82. @param[in] Address The Flash Linear Address must fall within a region for which BIOS has access permissions.
  83. @param[in] ByteCount Number of bytes in the data portion of the SPI cycle.
  84. @retval EFI_SUCCESS Command succeed.
  85. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  86. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  87. **/
  88. typedef
  89. EFI_STATUS
  90. (EFIAPI *PCH_SPI_FLASH_ERASE) (
  91. IN EFI_SPI_PROTOCOL *This,
  92. IN FLASH_REGION_TYPE FlashRegionType,
  93. IN UINT32 Address,
  94. IN UINT32 ByteCount
  95. );
  96. /**
  97. Read SFDP data from the flash part.
  98. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  99. @param[in] ComponentNumber The Componen Number for chip select
  100. @param[in] Address The starting byte address for SFDP data read.
  101. @param[in] ByteCount Number of bytes in SFDP data portion of the SPI cycle
  102. @param[out] SfdpData The Pointer to caller-allocated buffer containing the SFDP data received
  103. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read
  104. @retval EFI_SUCCESS Command succeed.
  105. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  106. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  107. **/
  108. typedef
  109. EFI_STATUS
  110. (EFIAPI *PCH_SPI_FLASH_READ_SFDP) (
  111. IN EFI_SPI_PROTOCOL *This,
  112. IN UINT8 ComponentNumber,
  113. IN UINT32 Address,
  114. IN UINT32 ByteCount,
  115. OUT UINT8 *SfdpData
  116. );
  117. /**
  118. Read Jedec Id from the flash part.
  119. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  120. @param[in] ComponentNumber The Componen Number for chip select
  121. @param[in] ByteCount Number of bytes in JedecId data portion of the SPI cycle, the data size is 3 typically
  122. @param[out] JedecId The Pointer to caller-allocated buffer containing JEDEC ID received
  123. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  124. @retval EFI_SUCCESS Command succeed.
  125. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  126. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  127. **/
  128. typedef
  129. EFI_STATUS
  130. (EFIAPI *PCH_SPI_FLASH_READ_JEDEC_ID) (
  131. IN EFI_SPI_PROTOCOL *This,
  132. IN UINT8 ComponentNumber,
  133. IN UINT32 ByteCount,
  134. OUT UINT8 *JedecId
  135. );
  136. /**
  137. Write the status register in the flash part.
  138. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  139. @param[in] ByteCount Number of bytes in Status data portion of the SPI cycle, the data size is 1 typically
  140. @param[in] StatusValue The Pointer to caller-allocated buffer containing the value of Status register writing
  141. @retval EFI_SUCCESS Command succeed.
  142. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  143. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  144. **/
  145. typedef
  146. EFI_STATUS
  147. (EFIAPI *PCH_SPI_FLASH_WRITE_STATUS) (
  148. IN EFI_SPI_PROTOCOL *This,
  149. IN UINT32 ByteCount,
  150. IN UINT8 *StatusValue
  151. );
  152. /**
  153. Read status register in the flash part.
  154. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  155. @param[in] ByteCount Number of bytes in Status data portion of the SPI cycle, the data size is 1 typically
  156. @param[out] StatusValue The Pointer to caller-allocated buffer containing the value of Status register received.
  157. @retval EFI_SUCCESS Command succeed.
  158. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  159. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  160. **/
  161. typedef
  162. EFI_STATUS
  163. (EFIAPI *PCH_SPI_FLASH_READ_STATUS) (
  164. IN EFI_SPI_PROTOCOL *This,
  165. IN UINT32 ByteCount,
  166. OUT UINT8 *StatusValue
  167. );
  168. /**
  169. Get the SPI region base and size, based on the enum type
  170. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  171. @param[in] FlashRegionType The Flash Region type for for the base address which is listed in the Descriptor.
  172. @param[out] BaseAddress The Flash Linear Address for the Region 'n' Base
  173. @param[out] RegionSize The size for the Region 'n'
  174. @retval EFI_SUCCESS Read success
  175. @retval EFI_INVALID_PARAMETER Invalid region type given
  176. @retval EFI_DEVICE_ERROR The region is not used
  177. **/
  178. typedef
  179. EFI_STATUS
  180. (EFIAPI *PCH_SPI_GET_REGION_ADDRESS) (
  181. IN EFI_SPI_PROTOCOL *This,
  182. IN FLASH_REGION_TYPE FlashRegionType,
  183. OUT UINT32 *BaseAddress,
  184. OUT UINT32 *RegionSize
  185. );
  186. /**
  187. Read PCH Soft Strap Values
  188. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  189. @param[in] SoftStrapAddr PCH Soft Strap address offset from FPSBA.
  190. @param[in] ByteCount Number of bytes in SoftStrap data portion of the SPI cycle
  191. @param[out] SoftStrapValue The Pointer to caller-allocated buffer containing PCH Soft Strap Value.
  192. If the value of ByteCount is 0, the data type of SoftStrapValue should be UINT16 and SoftStrapValue will be PCH Soft Strap Length
  193. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  194. @retval EFI_SUCCESS Command succeed.
  195. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  196. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  197. **/
  198. typedef
  199. EFI_STATUS
  200. (EFIAPI *PCH_SPI_READ_PCH_SOFTSTRAP) (
  201. IN EFI_SPI_PROTOCOL *This,
  202. IN UINT32 SoftStrapAddr,
  203. IN UINT32 ByteCount,
  204. OUT VOID *SoftStrapValue
  205. );
  206. /**
  207. Read CPU Soft Strap Values
  208. @param[in] This Pointer to the PCH_SPI_PROTOCOL instance.
  209. @param[in] SoftStrapAddr CPU Soft Strap address offset from FCPUSBA.
  210. @param[in] ByteCount Number of bytes in SoftStrap data portion of the SPI cycle.
  211. @param[out] SoftStrapValue The Pointer to caller-allocated buffer containing CPU Soft Strap Value.
  212. If the value of ByteCount is 0, the data type of SoftStrapValue should be UINT16 and SoftStrapValue will be PCH Soft Strap Length
  213. It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  214. @retval EFI_SUCCESS Command succeed.
  215. @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
  216. @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
  217. **/
  218. typedef
  219. EFI_STATUS
  220. (EFIAPI *PCH_SPI_READ_CPU_SOFTSTRAP) (
  221. IN EFI_SPI_PROTOCOL *This,
  222. IN UINT32 SoftStrapAddr,
  223. IN UINT32 ByteCount,
  224. OUT VOID *SoftStrapValue
  225. );
  226. /**
  227. These protocols/PPI allows a platform module to perform SPI operations through the
  228. Intel PCH SPI Host Controller Interface.
  229. **/
  230. struct _PCH_SPI_PROTOCOL {
  231. /**
  232. This member specifies the revision of this structure. This field is used to
  233. indicate backwards compatible changes to the protocol.
  234. **/
  235. UINT8 Revision;
  236. PCH_SPI_FLASH_READ FlashRead; ///< Read data from the flash part.
  237. PCH_SPI_FLASH_WRITE FlashWrite; ///< Write data to the flash part. Remark: Erase may be needed before write to the flash part.
  238. PCH_SPI_FLASH_ERASE FlashErase; ///< Erase some area on the flash part.
  239. PCH_SPI_FLASH_READ_SFDP FlashReadSfdp; ///< Read SFDP data from the flash part.
  240. PCH_SPI_FLASH_READ_JEDEC_ID FlashReadJedecId; ///< Read Jedec Id from the flash part.
  241. PCH_SPI_FLASH_WRITE_STATUS FlashWriteStatus; ///< Write the status register in the flash part.
  242. PCH_SPI_FLASH_READ_STATUS FlashReadStatus; ///< Read status register in the flash part.
  243. PCH_SPI_GET_REGION_ADDRESS GetRegionAddress; ///< Get the SPI region base and size
  244. PCH_SPI_READ_PCH_SOFTSTRAP ReadPchSoftStrap; ///< Read PCH Soft Strap Values
  245. PCH_SPI_READ_CPU_SOFTSTRAP ReadCpuSoftStrap; ///< Read CPU Soft Strap Values
  246. };
  247. /**
  248. PCH SPI PPI/PROTOCOL revision number
  249. Revision 1: Initial version
  250. **/
  251. #define PCH_SPI_SERVICES_REVISION 1
  252. #endif