FrameworkFirmwareVolumeBlock.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347
  1. /** @file
  2. This file provides control over block-oriented firmware devices.
  3. Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. @par Revision Reference:
  6. This protocol is defined in framework spec: Firmware Volume Block Specification.
  7. **/
  8. #ifndef __FRAMEWORK_FIRMWARE_VOLUME_BLOCK_H__
  9. #define __FRAMEWORK_FIRMWARE_VOLUME_BLOCK_H__
  10. #define FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \
  11. { 0xDE28BC59, 0x6228, 0x41BD, {0xBD, 0xF6, 0xA3, 0xB9, 0xAD,0xB5, 0x8D, 0xA1 } }
  12. typedef struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL;
  13. ///
  14. /// The type of EFI FVB attribute per the Framework specification.
  15. ///
  16. typedef UINT32 EFI_FVB_ATTRIBUTES;
  17. /**
  18. The GetAttributes() function retrieves the attributes and
  19. current settings of the block.
  20. @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  21. @param Attributes Pointer to EFI_FVB_ATTRIBUTES in which the
  22. attributes and current settings are
  23. returned.
  24. @retval EFI_SUCCESS The firmware volume attributes were
  25. returned.
  26. **/
  27. typedef
  28. EFI_STATUS
  29. (EFIAPI * FRAMEWORK_EFI_FVB_GET_ATTRIBUTES)(
  30. IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
  31. OUT EFI_FVB_ATTRIBUTES *Attributes
  32. );
  33. /**
  34. The SetAttributes() function sets configurable firmware volume
  35. attributes and returns the new settings of the firmware volume.
  36. @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  37. @param Attributes On input, Attributes is a pointer to
  38. EFI_FVB_ATTRIBUTES that contains the
  39. desired firmware volume settings. On
  40. successful return, it contains the new
  41. settings of the firmware volume.
  42. @retval EFI_SUCCESS The firmware volume attributes were returned.
  43. @retval EFI_INVALID_PARAMETER The attributes requested are in
  44. conflict with the capabilities
  45. as declared in the firmware
  46. volume header.
  47. **/
  48. typedef
  49. EFI_STATUS
  50. (EFIAPI * FRAMEWORK_EFI_FVB_SET_ATTRIBUTES)(
  51. IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
  52. IN OUT EFI_FVB_ATTRIBUTES *Attributes
  53. );
  54. /**
  55. The GetPhysicalAddress() function retrieves the base address of
  56. a memory-mapped firmware volume. This function should be called
  57. only for memory-mapped firmware volumes.
  58. @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  59. @param Address Pointer to a caller-allocated
  60. EFI_PHYSICAL_ADDRESS that, on successful
  61. return from GetPhysicalAddress(), contains the
  62. base address of the firmware volume.
  63. @retval EFI_SUCCESS The firmware volume base address is returned.
  64. @retval EFI_NOT_SUPPORTED The firmware volume is not memory mapped.
  65. **/
  66. typedef
  67. EFI_STATUS
  68. (EFIAPI * FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS)(
  69. IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
  70. OUT EFI_PHYSICAL_ADDRESS *Address
  71. );
  72. /**
  73. The GetBlockSize() function retrieves the size of the requested
  74. block. It also returns the number of additional blocks with
  75. the identical size. The GetBlockSize() function is used to
  76. retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER).
  77. @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  78. @param Lba Indicates the block for which to return the size.
  79. @param BlockSize The pointer to a caller-allocated UINTN in which
  80. the size of the block is returned.
  81. @param NumberOfBlocks The pointer to a caller-allocated UINTN in
  82. which the number of consecutive blocks,
  83. starting with Lba, is returned. All
  84. blocks in this range have a size of
  85. BlockSize.
  86. @retval EFI_SUCCESS The firmware volume base address was returned.
  87. @retval EFI_INVALID_PARAMETER The requested LBA is out of range.
  88. **/
  89. typedef
  90. EFI_STATUS
  91. (EFIAPI * FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE)(
  92. IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
  93. IN EFI_LBA Lba,
  94. OUT UINTN *BlockSize,
  95. OUT UINTN *NumberOfBlocks
  96. );
  97. /**
  98. Reads the specified number of bytes into a buffer from the specified block.
  99. The Read() function reads the requested number of bytes from the
  100. requested block and stores them in the provided buffer.
  101. Implementations should be mindful that the firmware volume
  102. might be in the ReadDisabled state. If it is in this state,
  103. the Read() function must return the status code
  104. EFI_ACCESS_DENIED without modifying the contents of the
  105. buffer. The Read() function must also prevent spanning block
  106. boundaries. If a read is requested that would span a block
  107. boundary, the read must read up to the boundary but not
  108. beyond. The output parameter NumBytes must be set to correctly
  109. indicate the number of bytes actually read. The caller must be
  110. aware that a read may be partially completed.
  111. @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  112. @param Lba The starting logical block index
  113. from which to read.
  114. @param Offset Offset into the block at which to begin reading.
  115. @param NumBytes The pointer to a UINTN. At entry, *NumBytes
  116. contains the total size of the buffer. At
  117. exit, *NumBytes contains the total number of
  118. bytes read.
  119. @param Buffer The pointer to a caller-allocated buffer that will
  120. be used to hold the data that is read.
  121. @retval EFI_SUCCESS The firmware volume was read successfully
  122. and contents are in Buffer.
  123. @retval EFI_BAD_BUFFER_SIZE A read was attempted across an LBA
  124. boundary. On output, NumBytes
  125. contains the total number of bytes
  126. returned in Buffer.
  127. @retval EFI_ACCESS_DENIED The firmware volume is in the
  128. ReadDisabled state.
  129. @retval EFI_DEVICE_ERROR The block device is not
  130. functioning correctly and could
  131. not be read.
  132. **/
  133. typedef
  134. EFI_STATUS
  135. (EFIAPI *FRAMEWORK_EFI_FVB_READ)(
  136. IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
  137. IN EFI_LBA Lba,
  138. IN UINTN Offset,
  139. IN OUT UINTN *NumBytes,
  140. IN OUT UINT8 *Buffer
  141. );
  142. /**
  143. Writes the specified number of bytes from the input buffer to the block.
  144. The Write() function writes the specified number of bytes from
  145. the provided buffer to the specified block and offset. If the
  146. firmware volume is sticky write, the caller must ensure that
  147. all the bits of the specified range to write are in the
  148. EFI_FVB_ERASE_POLARITY state before calling the Write()
  149. function, or else the result will be unpredictable. This
  150. unpredictability arises because, for a sticky-write firmware
  151. volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY
  152. state but cannot flip it back again. In general, before
  153. calling the Write() function, the caller should call the
  154. EraseBlocks() function first to erase the specified block to
  155. write. A block erase cycle will transition bits from the
  156. (NOT)EFI_FVB_ERASE_POLARITY state back to the
  157. EFI_FVB_ERASE_POLARITY state. Implementors should note
  158. that the firmware volume might be in the WriteDisabled
  159. state. If it is in this state, the Write() function must
  160. return the status code EFI_ACCESS_DENIED without modifying the
  161. contents of the firmware volume. The Write() function must
  162. also prevent spanning block boundaries. If a write is
  163. requested that spans a block boundary, the write must store up
  164. to the boundary but not beyond. The output parameter NumBytes
  165. must be set to correctly indicate the number of bytes actually
  166. written. The caller must be aware that a write may be
  167. partially completed. All writes, partial or otherwise, must be
  168. fully flushed to the hardware before the Write() service
  169. returns.
  170. @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL instance.
  171. @param Lba The starting logical block index to write to.
  172. @param Offset Offset into the block at which to begin writing.
  173. @param NumBytes The pointer to a UINTN. Input: the total size of the buffer.
  174. Output: the total number of bytes actually written.
  175. @param Buffer The pointer to a caller-allocated buffer that
  176. contains the source for the write.
  177. @retval EFI_SUCCESS The firmware volume was written successfully.
  178. @retval EFI_BAD_BUFFER_SIZE The write was attempted across an
  179. LBA boundary. On output, NumBytes
  180. contains the total number of bytes
  181. actually written.
  182. @retval EFI_ACCESS_DENIED The firmware volume is in the
  183. WriteDisabled state.
  184. @retval EFI_DEVICE_ERROR The block device is malfunctioning
  185. and could not be written.
  186. **/
  187. typedef
  188. EFI_STATUS
  189. (EFIAPI * FRAMEWORK_EFI_FVB_WRITE)(
  190. IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
  191. IN EFI_LBA Lba,
  192. IN UINTN Offset,
  193. IN OUT UINTN *NumBytes,
  194. IN UINT8 *Buffer
  195. );
  196. ///
  197. /// EFI_LBA_LIST_TERMINATOR.
  198. ///
  199. #define FRAMEWORK_EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL
  200. /**
  201. Erases and initializes a firmware volume block.
  202. The EraseBlocks() function erases one or more blocks as denoted
  203. by the variable argument list. The entire parameter list of
  204. blocks must be verified before erasing any blocks. If a block is
  205. requested that does not exist within the associated firmware
  206. volume (it has a larger index than the last block of the
  207. firmware volume), the EraseBlocks() function must return the
  208. status code EFI_INVALID_PARAMETER without modifying the contents
  209. of the firmware volume. Implementors should note that
  210. the firmware volume might be in the WriteDisabled state. If it
  211. is in this state, the EraseBlocks() function must return the
  212. status code EFI_ACCESS_DENIED without modifying the contents of
  213. the firmware volume. All calls to EraseBlocks() must be fully
  214. flushed to the hardware before the EraseBlocks() service
  215. returns.
  216. @param This Indicates the FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
  217. instance.
  218. @param ... A list of tuples.
  219. Each tuple describes a range of LBAs to erase
  220. and consists of the following:
  221. - An EFI_LBA that indicates the starting LBA
  222. - A UINTN that indicates the number of blocks to
  223. erase
  224. The list is terminated with an
  225. EFI_LBA_LIST_TERMINATOR. For example, the
  226. following indicates that two ranges of blocks
  227. (5-7 and 10-11) are to be erased: EraseBlocks
  228. (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR);
  229. @retval EFI_SUCCESS The erase request successfully
  230. completed.
  231. @retval EFI_ACCESS_DENIED The firmware volume is in the
  232. WriteDisabled state.
  233. @retval EFI_DEVICE_ERROR The block device is not functioning
  234. correctly and could not be written.
  235. The firmware device may have been
  236. partially erased.
  237. @retval EFI_INVALID_PARAMETER One or more of the LBAs listed
  238. in the variable argument list do
  239. not exist in the firmware volume.
  240. **/
  241. typedef
  242. EFI_STATUS
  243. (EFIAPI * FRAMEWORK_EFI_FVB_ERASE_BLOCKS)(
  244. IN FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
  245. ...
  246. );
  247. ///
  248. /// The Firmware Volume Block Protocol is the low-level interface
  249. /// to a firmware volume. File-level access to a firmware volume
  250. /// should not be done using the Firmware Volume Block Protocol.
  251. /// Normal access to a firmware volume must use the Firmware
  252. /// Volume Protocol. Typically, only the file system driver that
  253. /// produces the Firmware Volume Protocol will bind to the
  254. /// Firmware Volume Block Protocol.
  255. ///
  256. struct _FRAMEWORK_EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL {
  257. FRAMEWORK_EFI_FVB_GET_ATTRIBUTES GetAttributes;
  258. FRAMEWORK_EFI_FVB_SET_ATTRIBUTES SetAttributes;
  259. FRAMEWORK_EFI_FVB_GET_PHYSICAL_ADDRESS GetPhysicalAddress;
  260. FRAMEWORK_EFI_FVB_GET_BLOCK_SIZE GetBlockSize;
  261. FRAMEWORK_EFI_FVB_READ Read;
  262. FRAMEWORK_EFI_FVB_WRITE Write;
  263. FRAMEWORK_EFI_FVB_ERASE_BLOCKS EraseBlocks;
  264. ///
  265. /// The handle of the parent firmware volume.
  266. ///
  267. EFI_HANDLE ParentHandle;
  268. };
  269. extern EFI_GUID gFramerworkEfiFirmwareVolumeBlockProtocolGuid;
  270. #endif