fwu.h 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286
  1. /* SPDX-License-Identifier: GPL-2.0-or-later */
  2. /*
  3. * Copyright (c) 2022, Linaro Limited
  4. */
  5. #if !defined _FWU_H_
  6. #define _FWU_H_
  7. #include <blk.h>
  8. #include <efi.h>
  9. #include <mtd.h>
  10. #include <uuid.h>
  11. #include <linux/types.h>
  12. struct fwu_mdata;
  13. struct udevice;
  14. struct fwu_mdata_gpt_blk_priv {
  15. struct udevice *blk_dev;
  16. };
  17. struct fwu_mtd_image_info {
  18. u32 start, size;
  19. int bank_num, image_num;
  20. char uuidbuf[UUID_STR_LEN + 1];
  21. };
  22. struct fwu_mdata_ops {
  23. /**
  24. * read_mdata() - Populate the asked FWU metadata copy
  25. * @dev: FWU metadata device
  26. * @mdata: Output FWU mdata read
  27. * @primary: If primary or secondary copy of metadata is to be read
  28. *
  29. * Return: 0 if OK, -ve on error
  30. */
  31. int (*read_mdata)(struct udevice *dev, struct fwu_mdata *mdata, bool primary);
  32. /**
  33. * write_mdata() - Write the given FWU metadata copy
  34. * @dev: FWU metadata device
  35. * @mdata: Copy of the FWU metadata to write
  36. * @primary: If primary or secondary copy of metadata is to be written
  37. *
  38. * Return: 0 if OK, -ve on error
  39. */
  40. int (*write_mdata)(struct udevice *dev, struct fwu_mdata *mdata, bool primary);
  41. };
  42. #define FWU_MDATA_VERSION 0x1
  43. #define FWU_IMAGE_ACCEPTED 0x1
  44. /*
  45. * GUID value defined in the FWU specification for identification
  46. * of the FWU metadata partition.
  47. */
  48. #define FWU_MDATA_GUID \
  49. EFI_GUID(0x8a7a84a0, 0x8387, 0x40f6, 0xab, 0x41, \
  50. 0xa8, 0xb9, 0xa5, 0xa6, 0x0d, 0x23)
  51. /*
  52. * GUID value defined in the Dependable Boot specification for
  53. * identification of the revert capsule, used for reverting
  54. * any image in the updated bank.
  55. */
  56. #define FWU_OS_REQUEST_FW_REVERT_GUID \
  57. EFI_GUID(0xacd58b4b, 0xc0e8, 0x475f, 0x99, 0xb5, \
  58. 0x6b, 0x3f, 0x7e, 0x07, 0xaa, 0xf0)
  59. /*
  60. * GUID value defined in the Dependable Boot specification for
  61. * identification of the accept capsule, used for accepting
  62. * an image in the updated bank.
  63. */
  64. #define FWU_OS_REQUEST_FW_ACCEPT_GUID \
  65. EFI_GUID(0x0c996046, 0xbcc0, 0x4d04, 0x85, 0xec, \
  66. 0xe1, 0xfc, 0xed, 0xf1, 0xc6, 0xf8)
  67. /**
  68. * fwu_read_mdata() - Wrapper around fwu_mdata_ops.read_mdata()
  69. */
  70. int fwu_read_mdata(struct udevice *dev, struct fwu_mdata *mdata, bool primary);
  71. /**
  72. * fwu_write_mdata() - Wrapper around fwu_mdata_ops.write_mdata()
  73. */
  74. int fwu_write_mdata(struct udevice *dev, struct fwu_mdata *mdata, bool primary);
  75. /**
  76. * fwu_get_mdata() - Read, verify and return the FWU metadata
  77. *
  78. * Read both the metadata copies from the storage media, verify their checksum,
  79. * and ascertain that both copies match. If one of the copies has gone bad,
  80. * restore it from the good copy.
  81. *
  82. * Return: 0 if OK, -ve on error
  83. */
  84. int fwu_get_mdata(struct fwu_mdata *mdata);
  85. /**
  86. * fwu_get_active_index() - Get active_index from the FWU metadata
  87. * @active_idxp: active_index value to be read
  88. *
  89. * Read the active_index field from the FWU metadata and place it in
  90. * the variable pointed to be the function argument.
  91. *
  92. * Return: 0 if OK, -ve on error
  93. *
  94. */
  95. int fwu_get_active_index(uint *active_idxp);
  96. /**
  97. * fwu_set_active_index() - Set active_index in the FWU metadata
  98. * @active_idx: active_index value to be set
  99. *
  100. * Update the active_index field in the FWU metadata
  101. *
  102. * Return: 0 if OK, -ve on error
  103. *
  104. */
  105. int fwu_set_active_index(uint active_idx);
  106. /**
  107. * fwu_get_image_index() - Get the Image Index to be used for capsule update
  108. * @image_index: The Image Index for the image
  109. *
  110. * The FWU multi bank update feature computes the value of image_index at
  111. * runtime, based on the bank to which the image needs to be written to.
  112. * Derive the image_index value for the image.
  113. *
  114. * Currently, the capsule update driver uses the DFU framework for
  115. * the updates. This function gets the DFU alt number which is to
  116. * be used as the Image Index
  117. *
  118. * Return: 0 if OK, -ve on error
  119. *
  120. */
  121. int fwu_get_image_index(u8 *image_index);
  122. /**
  123. * fwu_revert_boot_index() - Revert the active index in the FWU metadata
  124. *
  125. * Revert the active_index value in the FWU metadata, by swapping the values
  126. * of active_index and previous_active_index in both copies of the
  127. * FWU metadata.
  128. *
  129. * Return: 0 if OK, -ve on error
  130. *
  131. */
  132. int fwu_revert_boot_index(void);
  133. /**
  134. * fwu_accept_image() - Set the Acceptance bit for the image
  135. * @img_type_id: GUID of the image type for which the accepted bit is to be
  136. * cleared
  137. * @bank: Bank of which the image's Accept bit is to be set
  138. *
  139. * Set the accepted bit for the image specified by the img_guid parameter. This
  140. * indicates acceptance of image for subsequent boots by some governing component
  141. * like OS(or firmware).
  142. *
  143. * Return: 0 if OK, -ve on error
  144. *
  145. */
  146. int fwu_accept_image(efi_guid_t *img_type_id, u32 bank);
  147. /**
  148. * fwu_clear_accept_image() - Clear the Acceptance bit for the image
  149. * @img_type_id: GUID of the image type for which the accepted bit is to be
  150. * cleared
  151. * @bank: Bank of which the image's Accept bit is to be cleared
  152. *
  153. * Clear the accepted bit for the image type specified by the img_type_id parameter.
  154. * This function is called after the image has been updated. The accepted bit is
  155. * cleared to be set subsequently after passing the image acceptance criteria, by
  156. * either the OS(or firmware)
  157. *
  158. * Return: 0 if OK, -ve on error
  159. *
  160. */
  161. int fwu_clear_accept_image(efi_guid_t *img_type_id, u32 bank);
  162. /**
  163. * fwu_plat_get_alt_num() - Get the DFU Alt Num for the image from the platform
  164. * @dev: FWU device
  165. * @image_guid: Image GUID for which DFU alt number needs to be retrieved
  166. * @alt_num: Pointer to the alt_num
  167. *
  168. * Get the DFU alt number from the platform for the image specified by the
  169. * image GUID.
  170. *
  171. * Return: 0 if OK, -ve on error
  172. *
  173. */
  174. int fwu_plat_get_alt_num(struct udevice *dev, efi_guid_t *image_guid,
  175. u8 *alt_num);
  176. /**
  177. * fwu_plat_get_update_index() - Get the value of the update bank
  178. * @update_idx: Bank number to which images are to be updated
  179. *
  180. * Get the value of the bank(partition) to which the update needs to be
  181. * made.
  182. *
  183. * Note: This is a weak function and platforms can override this with
  184. * their own implementation for selection of the update bank.
  185. *
  186. * Return: 0 if OK, -ve on error
  187. *
  188. */
  189. int fwu_plat_get_update_index(uint *update_idx);
  190. /**
  191. * fwu_plat_get_bootidx() - Get the value of the boot index
  192. * @boot_idx: Boot index value
  193. *
  194. * Get the value of the bank(partition) from which the platform
  195. * has booted. This value is passed to U-Boot from the earlier
  196. * stage bootloader which loads and boots all the relevant
  197. * firmware images
  198. *
  199. */
  200. void fwu_plat_get_bootidx(uint *boot_idx);
  201. /**
  202. * fwu_update_checks_pass() - Check if FWU update can be done
  203. *
  204. * Check if the FWU update can be executed. The updates are
  205. * allowed only when the platform is not in Trial State and
  206. * the boot time checks have passed
  207. *
  208. * Return: 1 if OK, 0 if checks do not pass
  209. *
  210. */
  211. u8 fwu_update_checks_pass(void);
  212. /**
  213. * fwu_empty_capsule_checks_pass() - Check if empty capsule can be processed
  214. *
  215. * Check if the empty capsule can be processed to either accept or revert
  216. * an earlier executed update. The empty capsules need to be processed
  217. * only when the platform is in Trial State and the boot time checks have
  218. * passed
  219. *
  220. * Return: 1 if OK, 0 if not to be allowed
  221. *
  222. */
  223. u8 fwu_empty_capsule_checks_pass(void);
  224. /**
  225. * fwu_trial_state_ctr_start() - Start the Trial State counter
  226. *
  227. * Start the counter to identify the platform booting in the
  228. * Trial State. The counter is implemented as an EFI variable.
  229. *
  230. * Return: 0 if OK, -ve on error
  231. *
  232. */
  233. int fwu_trial_state_ctr_start(void);
  234. /**
  235. * fwu_gen_alt_info_from_mtd() - Parse dfu_alt_info from metadata in mtd
  236. * @buf: Buffer into which the dfu_alt_info is filled
  237. * @len: Maximum characters that can be written in buf
  238. * @mtd: Pointer to underlying MTD device
  239. *
  240. * Parse dfu_alt_info from metadata in mtd. Used for setting the env.
  241. *
  242. * Return: 0 if OK, -ve on error
  243. */
  244. int fwu_gen_alt_info_from_mtd(char *buf, size_t len, struct mtd_info *mtd);
  245. /**
  246. * fwu_mtd_get_alt_num() - Mapping of fwu_plat_get_alt_num for MTD device
  247. * @image_guid: Image GUID for which DFU alt number needs to be retrieved
  248. * @alt_num: Pointer to the alt_num
  249. * @mtd_dev: Name of mtd device instance
  250. *
  251. * To map fwu_plat_get_alt_num onto mtd based metadata implementation.
  252. *
  253. * Return: 0 if OK, -ve on error
  254. */
  255. int fwu_mtd_get_alt_num(efi_guid_t *image_guid, u8 *alt_num, const char *mtd_dev);
  256. #endif /* _FWU_H_ */