FmpDeviceLib.c 21 KB

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