FmpDeviceLib.h 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608
  1. /** @file
  2. Provides firmware device specific services to support updates of a firmware
  3. image stored in a firmware device.
  4. Copyright (c) Microsoft Corporation.<BR>
  5. Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>
  6. SPDX-License-Identifier: BSD-2-Clause-Patent
  7. **/
  8. #ifndef __FMP_DEVICE_LIB__
  9. #define __FMP_DEVICE_LIB__
  10. #include <Protocol/FirmwareManagement.h>
  11. /**
  12. Callback function that installs a Firmware Management Protocol instance onto
  13. a handle.
  14. @param[in] Handle The device handle to install a Firmware Management
  15. Protocol instance.
  16. @retval EFI_SUCCESS A Firmware Management Protocol instance was
  17. installed onto Handle.
  18. @retval EFI_INVALID_PARAMETER Handle is invalid
  19. @retval other A Firmware Management Protocol instance could
  20. not be installed onto Handle.
  21. **/
  22. typedef
  23. EFI_STATUS
  24. (EFIAPI *FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER)(
  25. IN EFI_HANDLE Handle
  26. );
  27. /**
  28. Callback function that uninstalls a Firmware Management Protocol instance from
  29. a handle.
  30. @param[in] Handle The device handle to uninstall a Firmware Management
  31. Protocol instance.
  32. @retval EFI_SUCCESS A Firmware Management Protocol instance was
  33. uninstalled from Handle.
  34. @retval EFI_INVALID_PARAMETER Handle is invalid
  35. @retval other A Firmware Management Protocol instance could
  36. not be uninstalled from Handle.
  37. **/
  38. typedef
  39. EFI_STATUS
  40. (EFIAPI *FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER)(
  41. IN EFI_HANDLE Handle
  42. );
  43. /**
  44. Provide a function to install the Firmware Management Protocol instance onto a
  45. device handle when the device is managed by a driver that follows the UEFI
  46. Driver Model. If the device is not managed by a driver that follows the UEFI
  47. Driver Model, then EFI_UNSUPPORTED is returned.
  48. @param[in] FmpInstaller Function that installs the Firmware Management
  49. Protocol.
  50. @retval EFI_SUCCESS The device is managed by a driver that follows the
  51. UEFI Driver Model. FmpInstaller must be called on
  52. each Driver Binding Start().
  53. @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
  54. the UEFI Driver Model.
  55. @retval other The Firmware Management Protocol for this firmware
  56. device is not installed. The firmware device is
  57. still locked using FmpDeviceLock().
  58. **/
  59. EFI_STATUS
  60. EFIAPI
  61. RegisterFmpInstaller (
  62. IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER FmpInstaller
  63. );
  64. /**
  65. Provide a function to uninstall the Firmware Management Protocol instance from a
  66. device handle when the device is managed by a driver that follows the UEFI
  67. Driver Model. If the device is not managed by a driver that follows the UEFI
  68. Driver Model, then EFI_UNSUPPORTED is returned.
  69. @param[in] FmpUninstaller Function that installs the Firmware Management
  70. Protocol.
  71. @retval EFI_SUCCESS The device is managed by a driver that follows the
  72. UEFI Driver Model. FmpUninstaller must be called on
  73. each Driver Binding Stop().
  74. @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
  75. the UEFI Driver Model.
  76. @retval other The Firmware Management Protocol for this firmware
  77. device is not installed. The firmware device is
  78. still locked using FmpDeviceLock().
  79. **/
  80. EFI_STATUS
  81. EFIAPI
  82. RegisterFmpUninstaller (
  83. IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER FmpUninstaller
  84. );
  85. /**
  86. Set the device context for the FmpDeviceLib services when the device is
  87. managed by a driver that follows the UEFI Driver Model. If the device is not
  88. managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED
  89. is returned. Once a device context is set, the FmpDeviceLib services
  90. operate on the currently set device context.
  91. @param[in] Handle Device handle for the FmpDeviceLib services.
  92. If Handle is NULL, then Context is freed.
  93. @param[in, out] Context Device context for the FmpDeviceLib services.
  94. If Context is NULL, then a new context is allocated
  95. for Handle and the current device context is set and
  96. returned in Context. If Context is not NULL, then
  97. the current device context is set.
  98. @retval EFI_SUCCESS The device is managed by a driver that follows the
  99. UEFI Driver Model.
  100. @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
  101. the UEFI Driver Model.
  102. @retval other The Firmware Management Protocol for this firmware
  103. device is not installed. The firmware device is
  104. still locked using FmpDeviceLock().
  105. **/
  106. EFI_STATUS
  107. EFIAPI
  108. FmpDeviceSetContext (
  109. IN EFI_HANDLE Handle,
  110. IN OUT VOID **Context
  111. );
  112. /**
  113. Returns the size, in bytes, of the firmware image currently stored in the
  114. firmware device. This function is used to by the GetImage() and
  115. GetImageInfo() services of the Firmware Management Protocol. If the image
  116. size can not be determined from the firmware device, then 0 must be returned.
  117. @param[out] Size Pointer to the size, in bytes, of the firmware image
  118. currently stored in the firmware device.
  119. @retval EFI_SUCCESS The size of the firmware image currently
  120. stored in the firmware device was returned.
  121. @retval EFI_INVALID_PARAMETER Size is NULL.
  122. @retval EFI_UNSUPPORTED The firmware device does not support reporting
  123. the size of the currently stored firmware image.
  124. @retval EFI_DEVICE_ERROR An error occurred attempting to determine the
  125. size of the firmware image currently stored in
  126. in the firmware device.
  127. **/
  128. EFI_STATUS
  129. EFIAPI
  130. FmpDeviceGetSize (
  131. OUT UINTN *Size
  132. );
  133. /**
  134. Returns the GUID value used to fill in the ImageTypeId field of the
  135. EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
  136. service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned,
  137. then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is
  138. returned, then ImageTypeId is set to the Guid returned from this function.
  139. @param[out] Guid Double pointer to a GUID value that is updated to point to
  140. to a GUID value. The GUID value is not allocated and must
  141. not be modified or freed by the caller.
  142. @retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
  143. to the returned Guid value.
  144. @retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
  145. to gEfiCallerIdGuid.
  146. **/
  147. EFI_STATUS
  148. EFIAPI
  149. FmpDeviceGetImageTypeIdGuidPtr (
  150. OUT EFI_GUID **Guid
  151. );
  152. /**
  153. Returns values used to fill in the AttributesSupported and AttributesSettings
  154. fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
  155. GetImageInfo() service of the Firmware Management Protocol. The following
  156. bit values from the Firmware Management Protocol may be combined:
  157. IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
  158. IMAGE_ATTRIBUTE_RESET_REQUIRED
  159. IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
  160. IMAGE_ATTRIBUTE_IN_USE
  161. IMAGE_ATTRIBUTE_UEFI_IMAGE
  162. @param[out] Supported Attributes supported by this firmware device.
  163. @param[out] Setting Attributes settings for this firmware device.
  164. @retval EFI_SUCCESS The attributes supported by the firmware
  165. device were returned.
  166. @retval EFI_INVALID_PARAMETER Supported is NULL.
  167. @retval EFI_INVALID_PARAMETER Setting is NULL.
  168. **/
  169. EFI_STATUS
  170. EFIAPI
  171. FmpDeviceGetAttributes (
  172. OUT UINT64 *Supported,
  173. OUT UINT64 *Setting
  174. );
  175. /**
  176. Returns the value used to fill in the LowestSupportedVersion field of the
  177. EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
  178. service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
  179. the firmware device supports a method to report the LowestSupportedVersion
  180. value from the currently stored firmware image. If the value can not be
  181. reported for the firmware image currently stored in the firmware device, then
  182. EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error
  183. occurs attempting to retrieve the LowestSupportedVersion value for the
  184. currently stored firmware image.
  185. @note It is recommended that all firmware devices support a method to report
  186. the LowestSupportedVersion value from the currently stored firmware
  187. image.
  188. @param[out] LowestSupportedVersion LowestSupportedVersion value retrieved
  189. from the currently stored firmware image.
  190. @retval EFI_SUCCESS The lowest supported version of currently stored
  191. firmware image was returned in LowestSupportedVersion.
  192. @retval EFI_UNSUPPORTED The firmware device does not support a method to
  193. report the lowest supported version of the currently
  194. stored firmware image.
  195. @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest
  196. supported version of the currently stored firmware
  197. image.
  198. **/
  199. EFI_STATUS
  200. EFIAPI
  201. FmpDeviceGetLowestSupportedVersion (
  202. OUT UINT32 *LowestSupportedVersion
  203. );
  204. /**
  205. Returns the Null-terminated Unicode string that is used to fill in the
  206. VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
  207. returned by the GetImageInfo() service of the Firmware Management Protocol.
  208. The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
  209. @note It is recommended that all firmware devices support a method to report
  210. the VersionName string from the currently stored firmware image.
  211. @param[out] VersionString The version string retrieved from the currently
  212. stored firmware image.
  213. @retval EFI_SUCCESS The version string of currently stored
  214. firmware image was returned in Version.
  215. @retval EFI_INVALID_PARAMETER VersionString is NULL.
  216. @retval EFI_UNSUPPORTED The firmware device does not support a method
  217. to report the version string of the currently
  218. stored firmware image.
  219. @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
  220. version string of the currently stored
  221. firmware image.
  222. @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the
  223. buffer for the version string of the currently
  224. stored firmware image.
  225. **/
  226. EFI_STATUS
  227. EFIAPI
  228. FmpDeviceGetVersionString (
  229. OUT CHAR16 **VersionString
  230. );
  231. /**
  232. Returns the value used to fill in the Version field of the
  233. EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
  234. service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
  235. the firmware device supports a method to report the Version value from the
  236. currently stored firmware image. If the value can not be reported for the
  237. firmware image currently stored in the firmware device, then EFI_UNSUPPORTED
  238. must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
  239. to retrieve the LowestSupportedVersion value for the currently stored firmware
  240. image.
  241. @note It is recommended that all firmware devices support a method to report
  242. the Version value from the currently stored firmware image.
  243. @param[out] Version The version value retrieved from the currently stored
  244. firmware image.
  245. @retval EFI_SUCCESS The version of currently stored firmware image was
  246. returned in Version.
  247. @retval EFI_UNSUPPORTED The firmware device does not support a method to
  248. report the version of the currently stored firmware
  249. image.
  250. @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version
  251. of the currently stored firmware image.
  252. **/
  253. EFI_STATUS
  254. EFIAPI
  255. FmpDeviceGetVersion (
  256. OUT UINT32 *Version
  257. );
  258. /**
  259. Returns the value used to fill in the HardwareInstance field of the
  260. EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
  261. service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
  262. the firmware device supports a method to report the HardwareInstance value.
  263. If the value can not be reported for the firmware device, then EFI_UNSUPPORTED
  264. must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
  265. to retrieve the HardwareInstance value for the firmware device.
  266. @param[out] HardwareInstance The hardware instance value for the firmware
  267. device.
  268. @retval EFI_SUCCESS The hardware instance for the current firmware
  269. device is returned in HardwareInstance.
  270. @retval EFI_UNSUPPORTED The firmware device does not support a method to
  271. report the hardware instance value.
  272. @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the hardware
  273. instance value.
  274. **/
  275. EFI_STATUS
  276. EFIAPI
  277. FmpDeviceGetHardwareInstance (
  278. OUT UINT64 *HardwareInstance
  279. );
  280. /**
  281. Returns a copy of the firmware image currently stored in the firmware device.
  282. @note It is recommended that all firmware devices support a method to retrieve
  283. a copy currently stored firmware image. This can be used to support
  284. features such as recovery and rollback.
  285. @param[out] Image Pointer to a caller allocated buffer where the
  286. currently stored firmware image is copied to.
  287. @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.
  288. On return, points to the size, in bytes, of firmware
  289. image currently stored in the firmware device.
  290. @retval EFI_SUCCESS Image contains a copy of the firmware image
  291. currently stored in the firmware device, and
  292. ImageSize contains the size, in bytes, of the
  293. firmware image currently stored in the
  294. firmware device.
  295. @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small
  296. to hold the firmware image currently stored in
  297. the firmware device. The buffer size required
  298. is returned in ImageSize.
  299. @retval EFI_INVALID_PARAMETER The Image is NULL.
  300. @retval EFI_INVALID_PARAMETER The ImageSize is NULL.
  301. @retval EFI_UNSUPPORTED The operation is not supported.
  302. @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
  303. firmware image currently stored in the firmware
  304. device.
  305. **/
  306. EFI_STATUS
  307. EFIAPI
  308. FmpDeviceGetImage (
  309. OUT VOID *Image,
  310. IN OUT UINTN *ImageSize
  311. );
  312. /**
  313. Checks if a new firmware image is valid for the firmware device. This
  314. function allows firmware update operation to validate the firmware image
  315. before FmpDeviceSetImage() is called.
  316. @param[in] Image Points to a new firmware image.
  317. @param[in] ImageSize Size, in bytes, of a new firmware image.
  318. @param[out] ImageUpdatable Indicates if a new firmware image is valid for
  319. a firmware update to the firmware device. The
  320. following values from the Firmware Management
  321. Protocol are supported:
  322. IMAGE_UPDATABLE_VALID
  323. IMAGE_UPDATABLE_INVALID
  324. IMAGE_UPDATABLE_INVALID_TYPE
  325. IMAGE_UPDATABLE_INVALID_OLD
  326. IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
  327. @retval EFI_SUCCESS The image was successfully checked. Additional
  328. status information is returned in
  329. ImageUpdatable.
  330. @retval EFI_INVALID_PARAMETER Image is NULL.
  331. @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
  332. **/
  333. EFI_STATUS
  334. EFIAPI
  335. FmpDeviceCheckImage (
  336. IN CONST VOID *Image,
  337. IN UINTN ImageSize,
  338. OUT UINT32 *ImageUpdatable
  339. );
  340. /**
  341. Checks if a new firmware image is valid for the firmware device. This
  342. function allows firmware update operation to validate the firmware image
  343. before FmpDeviceSetImage() is called.
  344. @param[in] Image Points to a new firmware image.
  345. @param[in] ImageSize Size, in bytes, of a new firmware image.
  346. @param[out] ImageUpdatable Indicates if a new firmware image is valid for
  347. a firmware update to the firmware device. The
  348. following values from the Firmware Management
  349. Protocol are supported:
  350. IMAGE_UPDATABLE_VALID
  351. IMAGE_UPDATABLE_INVALID
  352. IMAGE_UPDATABLE_INVALID_TYPE
  353. IMAGE_UPDATABLE_INVALID_OLD
  354. IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
  355. @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt
  356. status to report back to the ESRT table in case
  357. of error.
  358. The return status code must fall in the range of
  359. LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
  360. LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
  361. If the value falls outside this range, it will be converted
  362. to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
  363. @retval EFI_SUCCESS The image was successfully checked. Additional
  364. status information is returned in
  365. ImageUpdatable.
  366. @retval EFI_INVALID_PARAMETER Image is NULL.
  367. @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
  368. **/
  369. EFI_STATUS
  370. EFIAPI
  371. FmpDeviceCheckImageWithStatus (
  372. IN CONST VOID *Image,
  373. IN UINTN ImageSize,
  374. OUT UINT32 *ImageUpdatable,
  375. OUT UINT32 *LastAttemptStatus
  376. );
  377. /**
  378. Updates a firmware device with a new firmware image. This function returns
  379. EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
  380. is updatable, the function should perform the following minimal validations
  381. before proceeding to do the firmware image update.
  382. - Validate that the image is a supported image for this firmware device.
  383. Return EFI_ABORTED if the image is not supported. Additional details
  384. on why the image is not a supported image may be returned in AbortReason.
  385. - Validate the data from VendorCode if is not NULL. Firmware image
  386. validation must be performed before VendorCode data validation.
  387. VendorCode data is ignored or considered invalid if image validation
  388. fails. Return EFI_ABORTED if the VendorCode data is invalid.
  389. VendorCode enables vendor to implement vendor-specific firmware image update
  390. policy. Null if the caller did not specify the policy or use the default
  391. policy. As an example, vendor can implement a policy to allow an option to
  392. force a firmware image update when the abort reason is due to the new firmware
  393. image version is older than the current firmware image version or bad image
  394. checksum. Sensitive operations such as those wiping the entire firmware image
  395. and render the device to be non-functional should be encoded in the image
  396. itself rather than passed with the VendorCode. AbortReason enables vendor to
  397. have the option to provide a more detailed description of the abort reason to
  398. the caller.
  399. @param[in] Image Points to the new firmware image.
  400. @param[in] ImageSize Size, in bytes, of the new firmware image.
  401. @param[in] VendorCode This enables vendor to implement vendor-specific
  402. firmware image update policy. NULL indicates
  403. the caller did not specify the policy or use the
  404. default policy.
  405. @param[in] Progress A function used to report the progress of
  406. updating the firmware device with the new
  407. firmware image.
  408. @param[in] CapsuleFwVersion The version of the new firmware image from the
  409. update capsule that provided the new firmware
  410. image.
  411. @param[out] AbortReason A pointer to a pointer to a Null-terminated
  412. Unicode string providing more details on an
  413. aborted operation. The buffer is allocated by
  414. this function with
  415. EFI_BOOT_SERVICES.AllocatePool(). It is the
  416. caller's responsibility to free this buffer with
  417. EFI_BOOT_SERVICES.FreePool().
  418. @retval EFI_SUCCESS The firmware device was successfully updated
  419. with the new firmware image.
  420. @retval EFI_ABORTED The operation is aborted. Additional details
  421. are provided in AbortReason.
  422. @retval EFI_INVALID_PARAMETER The Image was NULL.
  423. @retval EFI_UNSUPPORTED The operation is not supported.
  424. **/
  425. EFI_STATUS
  426. EFIAPI
  427. FmpDeviceSetImage (
  428. IN CONST VOID *Image,
  429. IN UINTN ImageSize,
  430. IN CONST VOID *VendorCode OPTIONAL,
  431. IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL,
  432. IN UINT32 CapsuleFwVersion,
  433. OUT CHAR16 **AbortReason
  434. );
  435. /**
  436. Updates a firmware device with a new firmware image. This function returns
  437. EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
  438. is updatable, the function should perform the following minimal validations
  439. before proceeding to do the firmware image update.
  440. - Validate that the image is a supported image for this firmware device.
  441. Return EFI_ABORTED if the image is not supported. Additional details
  442. on why the image is not a supported image may be returned in AbortReason.
  443. - Validate the data from VendorCode if is not NULL. Firmware image
  444. validation must be performed before VendorCode data validation.
  445. VendorCode data is ignored or considered invalid if image validation
  446. fails. Return EFI_ABORTED if the VendorCode data is invalid.
  447. VendorCode enables vendor to implement vendor-specific firmware image update
  448. policy. Null if the caller did not specify the policy or use the default
  449. policy. As an example, vendor can implement a policy to allow an option to
  450. force a firmware image update when the abort reason is due to the new firmware
  451. image version is older than the current firmware image version or bad image
  452. checksum. Sensitive operations such as those wiping the entire firmware image
  453. and render the device to be non-functional should be encoded in the image
  454. itself rather than passed with the VendorCode. AbortReason enables vendor to
  455. have the option to provide a more detailed description of the abort reason to
  456. the caller.
  457. @param[in] Image Points to the new firmware image.
  458. @param[in] ImageSize Size, in bytes, of the new firmware image.
  459. @param[in] VendorCode This enables vendor to implement vendor-specific
  460. firmware image update policy. NULL indicates
  461. the caller did not specify the policy or use the
  462. default policy.
  463. @param[in] Progress A function used to report the progress of
  464. updating the firmware device with the new
  465. firmware image.
  466. @param[in] CapsuleFwVersion The version of the new firmware image from the
  467. update capsule that provided the new firmware
  468. image.
  469. @param[out] AbortReason A pointer to a pointer to a Null-terminated
  470. Unicode string providing more details on an
  471. aborted operation. The buffer is allocated by
  472. this function with
  473. EFI_BOOT_SERVICES.AllocatePool(). It is the
  474. caller's responsibility to free this buffer with
  475. EFI_BOOT_SERVICES.FreePool().
  476. @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt
  477. status to report back to the ESRT table in case
  478. of error. This value will only be checked when this
  479. function returns an error.
  480. The return status code must fall in the range of
  481. LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
  482. LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
  483. If the value falls outside this range, it will be converted
  484. to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
  485. @retval EFI_SUCCESS The firmware device was successfully updated
  486. with the new firmware image.
  487. @retval EFI_ABORTED The operation is aborted. Additional details
  488. are provided in AbortReason.
  489. @retval EFI_INVALID_PARAMETER The Image was NULL.
  490. @retval EFI_UNSUPPORTED The operation is not supported.
  491. **/
  492. EFI_STATUS
  493. EFIAPI
  494. FmpDeviceSetImageWithStatus (
  495. IN CONST VOID *Image,
  496. IN UINTN ImageSize,
  497. IN CONST VOID *VendorCode OPTIONAL,
  498. IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL,
  499. IN UINT32 CapsuleFwVersion,
  500. OUT CHAR16 **AbortReason,
  501. OUT UINT32 *LastAttemptStatus
  502. );
  503. /**
  504. Lock the firmware device that contains a firmware image. Once a firmware
  505. device is locked, any attempts to modify the firmware image contents in the
  506. firmware device must fail.
  507. @note It is recommended that all firmware devices support a lock method to
  508. prevent modifications to a stored firmware image.
  509. @note A firmware device lock mechanism is typically only cleared by a full
  510. system reset (not just sleep state/low power mode).
  511. @retval EFI_SUCCESS The firmware device was locked.
  512. @retval EFI_UNSUPPORTED The firmware device does not support locking
  513. **/
  514. EFI_STATUS
  515. EFIAPI
  516. FmpDeviceLock (
  517. VOID
  518. );
  519. #endif