FmpDeviceLib.c 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410
  1. /** @file
  2. Provides firmware device specific services to support updates of a firmware
  3. image stored in a firmware device.
  4. Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>
  5. Copyright (c) 2018, Intel Corporation. All rights reserved.<BR>
  6. SPDX-License-Identifier: BSD-2-Clause-Patent
  7. **/
  8. #include <PiDxe.h>
  9. #include <Library/FmpDeviceLib.h>
  10. /**
  11. Provide a function to install the Firmware Management Protocol instance onto a
  12. device handle when the device is managed by a driver that follows the UEFI
  13. Driver Model. If the device is not managed by a driver that follows the UEFI
  14. Driver Model, then EFI_UNSUPPORTED is returned.
  15. @param[in] FmpInstaller Function that installs the Firmware Management
  16. Protocol.
  17. @retval EFI_SUCCESS The device is managed by a driver that follows the
  18. UEFI Driver Model. FmpInstaller must be called on
  19. each Driver Binding Start().
  20. @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
  21. the UEFI Driver Model.
  22. @retval other The Firmware Management Protocol for this firmware
  23. device is not installed. The firmware device is
  24. still locked using FmpDeviceLock().
  25. **/
  26. EFI_STATUS
  27. EFIAPI
  28. RegisterFmpInstaller (
  29. IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER Function
  30. )
  31. {
  32. return EFI_UNSUPPORTED;
  33. }
  34. /**
  35. Returns the size, in bytes, of the firmware image currently stored in the
  36. firmware device. This function is used to by the GetImage() and
  37. GetImageInfo() services of the Firmware Management Protocol. If the image
  38. size can not be determined from the firmware device, then 0 must be returned.
  39. @param[out] Size Pointer to the size, in bytes, of the firmware image
  40. currently stored in the firmware device.
  41. @retval EFI_SUCCESS The size of the firmware image currently
  42. stored in the firmware device was returned.
  43. @retval EFI_INVALID_PARAMETER Size is NULL.
  44. @retval EFI_UNSUPPORTED The firmware device does not support reporting
  45. the size of the currently stored firmware image.
  46. @retval EFI_DEVICE_ERROR An error occurred attempting to determine the
  47. size of the firmware image currently stored in
  48. in the firmware device.
  49. **/
  50. EFI_STATUS
  51. EFIAPI
  52. FmpDeviceGetSize (
  53. OUT UINTN *Size
  54. )
  55. {
  56. if (Size == NULL) {
  57. return EFI_INVALID_PARAMETER;
  58. }
  59. *Size = 0;
  60. return EFI_SUCCESS;
  61. }
  62. /**
  63. Returns the GUID value used to fill in the ImageTypeId field of the
  64. EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
  65. service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned,
  66. then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is
  67. returned, then ImageTypeId is set to the Guid returned from this function.
  68. @param[out] Guid Double pointer to a GUID value that is updated to point to
  69. to a GUID value. The GUID value is not allocated and must
  70. not be modified or freed by the caller.
  71. @retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
  72. to the returned Guid value.
  73. @retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
  74. to gEfiCallerIdGuid.
  75. **/
  76. EFI_STATUS
  77. EFIAPI
  78. FmpDeviceGetImageTypeIdGuidPtr (
  79. OUT EFI_GUID **Guid
  80. )
  81. {
  82. return EFI_UNSUPPORTED;
  83. }
  84. /**
  85. Returns values used to fill in the AttributesSupported and AttributesSettings
  86. fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
  87. GetImageInfo() service of the Firmware Management Protocol. The following
  88. bit values from the Firmware Management Protocol may be combined:
  89. IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
  90. IMAGE_ATTRIBUTE_RESET_REQUIRED
  91. IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
  92. IMAGE_ATTRIBUTE_IN_USE
  93. IMAGE_ATTRIBUTE_UEFI_IMAGE
  94. @param[out] Supported Attributes supported by this firmware device.
  95. @param[out] Setting Attributes settings for this firmware device.
  96. @retval EFI_SUCCESS The attributes supported by the firmware
  97. device were returned.
  98. @retval EFI_INVALID_PARAMETER Supported is NULL.
  99. @retval EFI_INVALID_PARAMETER Setting is NULL.
  100. **/
  101. EFI_STATUS
  102. EFIAPI
  103. FmpDeviceGetAttributes (
  104. OUT UINT64 *Supported,
  105. OUT UINT64 *Setting
  106. )
  107. {
  108. if (Supported == NULL || Setting == NULL) {
  109. return EFI_INVALID_PARAMETER;
  110. }
  111. *Supported = 0;
  112. *Setting = 0;
  113. return EFI_SUCCESS;
  114. }
  115. /**
  116. Returns the value used to fill in the LowestSupportedVersion field of the
  117. EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
  118. service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
  119. the firmware device supports a method to report the LowestSupportedVersion
  120. value from the currently stored firmware image. If the value can not be
  121. reported for the firmware image currently stored in the firmware device, then
  122. EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error
  123. occurs attempting to retrieve the LowestSupportedVersion value for the
  124. currently stored firmware image.
  125. @note It is recommended that all firmware devices support a method to report
  126. the LowestSupportedVersion value from the currently stored firmware
  127. image.
  128. @param[out] LowestSupportedVersion LowestSupportedVersion value retrieved
  129. from the currently stored firmware image.
  130. @retval EFI_SUCCESS The lowest supported version of currently stored
  131. firmware image was returned in LowestSupportedVersion.
  132. @retval EFI_UNSUPPORTED The firmware device does not support a method to
  133. report the lowest supported version of the currently
  134. stored firmware image.
  135. @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest
  136. supported version of the currently stored firmware
  137. image.
  138. **/
  139. EFI_STATUS
  140. EFIAPI
  141. FmpDeviceGetLowestSupportedVersion (
  142. OUT UINT32 *LowestSupportedVersion
  143. )
  144. {
  145. return EFI_UNSUPPORTED;
  146. }
  147. /**
  148. Returns the Null-terminated Unicode string that is used to fill in the
  149. VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
  150. returned by the GetImageInfo() service of the Firmware Management Protocol.
  151. The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
  152. @note It is recommended that all firmware devices support a method to report
  153. the VersionName string from the currently stored firmware image.
  154. @param[out] VersionString The version string retrieved from the currently
  155. stored firmware image.
  156. @retval EFI_SUCCESS The version string of currently stored
  157. firmware image was returned in Version.
  158. @retval EFI_INVALID_PARAMETER VersionString is NULL.
  159. @retval EFI_UNSUPPORTED The firmware device does not support a method
  160. to report the version string of the currently
  161. stored firmware image.
  162. @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
  163. version string of the currently stored
  164. firmware image.
  165. @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the
  166. buffer for the version string of the currently
  167. stored firmware image.
  168. **/
  169. EFI_STATUS
  170. EFIAPI
  171. FmpDeviceGetVersionString (
  172. OUT CHAR16 **VersionString
  173. )
  174. {
  175. if (VersionString == NULL) {
  176. return EFI_INVALID_PARAMETER;
  177. }
  178. *VersionString = NULL;
  179. return EFI_UNSUPPORTED;
  180. }
  181. /**
  182. Returns the value used to fill in the Version field of the
  183. EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
  184. service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
  185. the firmware device supports a method to report the Version value from the
  186. currently stored firmware image. If the value can not be reported for the
  187. firmware image currently stored in the firmware device, then EFI_UNSUPPORTED
  188. must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
  189. to retrieve the LowestSupportedVersion value for the currently stored firmware
  190. image.
  191. @note It is recommended that all firmware devices support a method to report
  192. the Version value from the currently stored firmware image.
  193. @param[out] Version The version value retrieved from the currently stored
  194. firmware image.
  195. @retval EFI_SUCCESS The version of currently stored firmware image was
  196. returned in Version.
  197. @retval EFI_UNSUPPORTED The firmware device does not support a method to
  198. report the version of the currently stored firmware
  199. image.
  200. @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version
  201. of the currently stored firmware image.
  202. **/
  203. EFI_STATUS
  204. EFIAPI
  205. FmpDeviceGetVersion (
  206. OUT UINT32 *Version
  207. )
  208. {
  209. return EFI_UNSUPPORTED;
  210. }
  211. /**
  212. Returns a copy of the firmware image currently stored in the firmware device.
  213. @note It is recommended that all firmware devices support a method to retrieve
  214. a copy currently stored firmware image. This can be used to support
  215. features such as recovery and rollback.
  216. @param[out] Image Pointer to a caller allocated buffer where the
  217. currently stored firmware image is copied to.
  218. @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.
  219. On return, points to the size, in bytes, of firmware
  220. image currently stored in the firmware device.
  221. @retval EFI_SUCCESS Image contains a copy of the firmware image
  222. currently stored in the firmware device, and
  223. ImageSize contains the size, in bytes, of the
  224. firmware image currently stored in the
  225. firmware device.
  226. @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small
  227. to hold the firmware image currently stored in
  228. the firmware device. The buffer size required
  229. is returned in ImageSize.
  230. @retval EFI_INVALID_PARAMETER The Image is NULL.
  231. @retval EFI_INVALID_PARAMETER The ImageSize is NULL.
  232. @retval EFI_UNSUPPORTED The operation is not supported.
  233. @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
  234. firmware image currently stored in the firmware
  235. device.
  236. **/
  237. EFI_STATUS
  238. EFIAPI
  239. FmpDeviceGetImage (
  240. OUT VOID *Image,
  241. IN OUT UINTN *ImageSize
  242. )
  243. {
  244. return EFI_UNSUPPORTED;
  245. }
  246. /**
  247. Checks if a new firmware image is valid for the firmware device. This
  248. function allows firmware update operation to validate the firmware image
  249. before FmpDeviceSetImage() is called.
  250. @param[in] Image Points to a new firmware image.
  251. @param[in] ImageSize Size, in bytes, of a new firmware image.
  252. @param[out] ImageUpdatable Indicates if a new firmware image is valid for
  253. a firmware update to the firmware device. The
  254. following values from the Firmware Management
  255. Protocol are supported:
  256. IMAGE_UPDATABLE_VALID
  257. IMAGE_UPDATABLE_INVALID
  258. IMAGE_UPDATABLE_INVALID_TYPE
  259. IMAGE_UPDATABLE_INVALID_OLD
  260. IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
  261. @retval EFI_SUCCESS The image was successfully checked. Additional
  262. status information is returned in
  263. ImageUpdatable.
  264. @retval EFI_INVALID_PARAMETER Image is NULL.
  265. @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
  266. **/
  267. EFI_STATUS
  268. EFIAPI
  269. FmpDeviceCheckImage (
  270. IN CONST VOID *Image,
  271. IN UINTN ImageSize,
  272. OUT UINT32 *ImageUpdatable
  273. )
  274. {
  275. return EFI_SUCCESS;
  276. }
  277. /**
  278. Updates a firmware device with a new firmware image. This function returns
  279. EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
  280. is updatable, the function should perform the following minimal validations
  281. before proceeding to do the firmware image update.
  282. - Validate that the image is a supported image for this firmware device.
  283. Return EFI_ABORTED if the image is not supported. Additional details
  284. on why the image is not a supported image may be returned in AbortReason.
  285. - Validate the data from VendorCode if is not NULL. Firmware image
  286. validation must be performed before VendorCode data validation.
  287. VendorCode data is ignored or considered invalid if image validation
  288. fails. Return EFI_ABORTED if the VendorCode data is invalid.
  289. VendorCode enables vendor to implement vendor-specific firmware image update
  290. policy. Null if the caller did not specify the policy or use the default
  291. policy. As an example, vendor can implement a policy to allow an option to
  292. force a firmware image update when the abort reason is due to the new firmware
  293. image version is older than the current firmware image version or bad image
  294. checksum. Sensitive operations such as those wiping the entire firmware image
  295. and render the device to be non-functional should be encoded in the image
  296. itself rather than passed with the VendorCode. AbortReason enables vendor to
  297. have the option to provide a more detailed description of the abort reason to
  298. the caller.
  299. @param[in] Image Points to the new firmware image.
  300. @param[in] ImageSize Size, in bytes, of the new firmware image.
  301. @param[in] VendorCode This enables vendor to implement vendor-specific
  302. firmware image update policy. NULL indicates
  303. the caller did not specify the policy or use the
  304. default policy.
  305. @param[in] Progress A function used to report the progress of
  306. updating the firmware device with the new
  307. firmware image.
  308. @param[in] CapsuleFwVersion The version of the new firmware image from the
  309. update capsule that provided the new firmware
  310. image.
  311. @param[out] AbortReason A pointer to a pointer to a Null-terminated
  312. Unicode string providing more details on an
  313. aborted operation. The buffer is allocated by
  314. this function with
  315. EFI_BOOT_SERVICES.AllocatePool(). It is the
  316. caller's responsibility to free this buffer with
  317. EFI_BOOT_SERVICES.FreePool().
  318. @retval EFI_SUCCESS The firmware device was successfully updated
  319. with the new firmware image.
  320. @retval EFI_ABORTED The operation is aborted. Additional details
  321. are provided in AbortReason.
  322. @retval EFI_INVALID_PARAMETER The Image was NULL.
  323. @retval EFI_UNSUPPORTED The operation is not supported.
  324. **/
  325. EFI_STATUS
  326. EFIAPI
  327. FmpDeviceSetImage (
  328. IN CONST VOID *Image,
  329. IN UINTN ImageSize,
  330. IN CONST VOID *VendorCode, OPTIONAL
  331. IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, OPTIONAL
  332. IN UINT32 CapsuleFwVersion,
  333. OUT CHAR16 **AbortReason
  334. )
  335. {
  336. return EFI_UNSUPPORTED;
  337. }
  338. /**
  339. Lock the firmware device that contains a firmware image. Once a firmware
  340. device is locked, any attempts to modify the firmware image contents in the
  341. firmware device must fail.
  342. @note It is recommended that all firmware devices support a lock method to
  343. prevent modifications to a stored firmware image.
  344. @note A firmware device lock mechanism is typically only cleared by a full
  345. system reset (not just sleep state/low power mode).
  346. @retval EFI_SUCCESS The firmware device was locked.
  347. @retval EFI_UNSUPPORTED The firmware device does not support locking
  348. **/
  349. EFI_STATUS
  350. EFIAPI
  351. FmpDeviceLock (
  352. VOID
  353. )
  354. {
  355. return EFI_UNSUPPORTED;
  356. }