FmpDeviceLib.c 28 KB

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