1 /*! 2 * @header 3 * Interfaces for manipulating Image4 firmware images. 4 */ 5 #ifndef __IMG4_IMAGE_H 6 #define __IMG4_IMAGE_H 7 8 #ifndef __IMG4_INDIRECT 9 #error "Please #include <img4/firmware.h> instead of this file directly" 10 #endif // __IMG4_INDIRECT 11 12 __BEGIN_DECLS 13 OS_ASSUME_NONNULL_BEGIN 14 OS_ASSUME_PTR_ABI_SINGLE_BEGIN 15 16 /*! 17 * @function img4_image_get_bytes 18 * Returns the authenticated payload from an Image4 image. 19 * 20 * @param image 21 * The image to query. May be NULL. 22 * 23 * @result 24 * A buffer which describes the authenticated payload. If the payload was not 25 * authenticated, NULL is returned. 26 */ 27 #if !XNU_KERNEL_PRIVATE 28 IMG4_API_AVAILABLE_20200508 29 OS_EXPORT OS_WARN_RESULT 30 const img4_buff_t *_Nullable 31 img4_image_get_bytes(img4_image_t _Nullable image); 32 #else 33 #define img4_image_get_bytes(...) (img4if->i4if_v7.image_get_bytes(__VA_ARGS__)) 34 #endif 35 36 /*! 37 * @function img4_image_get_property_bool 38 * Retrieves the Boolean value for the requested image property. 39 * 40 * @param image 41 * The image to query. 42 * 43 * @param _4cc 44 * The 4cc of the desired image property. 45 * 46 * @param storage 47 * A pointer to storage for a Boolean value. 48 * 49 * @result 50 * If the property is present for the image, a pointer to the storage provided 51 * in {@link storage}. If the property is not present in the image or its value 52 * is not a Boolean, NULL is returned. 53 */ 54 #if !XNU_KERNEL_PRIVATE 55 IMG4_API_AVAILABLE_20200508 56 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 57 const bool * 58 img4_image_get_property_bool(img4_image_t image, 59 img4_4cc_t _4cc, 60 bool *storage); 61 #else 62 #define img4_image_get_property_bool(...) \ 63 (img4if->i4if_v7.image_get_property_bool(__VA_ARGS__)) 64 #endif 65 66 /*! 67 * @function img4_image_get_property_uint32 68 * Retrieves the unsigned 32-bit integer value for the requested image property. 69 * 70 * @param image 71 * The image to query. 72 * 73 * @param _4cc 74 * The 4cc of the desired image property. 75 * 76 * @param storage 77 * A pointer to storage for a 32-bit unsigned integer value. 78 * 79 * @result 80 * If the property is present for the image, a pointer to the storage provided 81 * in {@link storage}. If the property is not present in the image or its value 82 * is not an unsigned 32-bit integer, NULL is returned. 83 */ 84 #if !XNU_KERNEL_PRIVATE 85 IMG4_API_AVAILABLE_20200508 86 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 87 const uint32_t * 88 img4_image_get_property_uint32(img4_image_t image, 89 img4_4cc_t _4cc, 90 uint32_t *storage); 91 #else 92 #define img4_image_get_property_uint32(...) \ 93 (img4if->i4if_v7.image_get_property_uint32(__VA_ARGS__)) 94 #endif 95 96 /*! 97 * @function img4_image_get_property_uint64 98 * Retrieves the unsigned 64-bit integer value for the requested image property. 99 * 100 * @param image 101 * The image to query. 102 * 103 * @param _4cc 104 * The 4cc of the desired image property. 105 * 106 * @param storage 107 * A pointer to storage for a 64-bit unsigned integer value. 108 * 109 * @result 110 * If the property is present for the image, a pointer to the storage provided 111 * in {@link storage}. If the property is not present in the image or its value 112 * is not an unsigned 64-bit integer, NULL is returned. 113 */ 114 #if !XNU_KERNEL_PRIVATE 115 IMG4_API_AVAILABLE_20200508 116 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 117 const uint64_t * 118 img4_image_get_property_uint64(img4_image_t image, 119 img4_4cc_t _4cc, 120 uint64_t *storage); 121 #else 122 #define img4_image_get_property_uint64(...) \ 123 (img4if->i4if_v7.image_get_property_uint64(__VA_ARGS__)) 124 #endif 125 126 /*! 127 * @function img4_image_get_property_data 128 * Retrieves the buffer value for the requested image property. 129 * 130 * @param image 131 * The image to query. 132 * 133 * @param _4cc 134 * The 4cc of the desired image property. 135 * 136 * @param storage 137 * A pointer to storage for a buffer value. 138 * 139 * @result 140 * If the property is present for the image, a pointer to the storage provided 141 * in {@link storage}. If the property is not present in the image or its value 142 * is not a data, NULL is returned. 143 */ 144 #if !XNU_KERNEL_PRIVATE 145 IMG4_API_AVAILABLE_20200508 146 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 147 const img4_buff_t * 148 img4_image_get_property_data(img4_image_t image, 149 img4_4cc_t _4cc, 150 img4_buff_t *storage); 151 #else 152 #define img4_image_get_property_data(...) \ 153 (img4if->i4if_v7.image_get_property_data(__VA_ARGS__)) 154 #endif 155 156 /*! 157 * @function img4_image_get_entitlement_bool 158 * Retrieves the Boolean value for the requested image entitlement. 159 * 160 * @param image 161 * The image to query. 162 * 163 * @param _4cc 164 * The 4cc of the desired image entitlement. 165 * 166 * @param storage 167 * A pointer to storage for a Boolean value. 168 * 169 * @result 170 * If the entitlement is present for the image, a pointer to the storage 171 * provided in {@link storage}. If the property is not present in the image or 172 * its value is not a Boolean, NULL is returned. 173 */ 174 #if !XNU_KERNEL_PRIVATE 175 IMG4_API_AVAILABLE_20220513 176 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 177 const bool * 178 img4_image_get_entitlement_bool(img4_image_t image, 179 img4_4cc_t _4cc, 180 bool *storage); 181 #else 182 #define img4_image_get_entitlement_bool(...) \ 183 (img4if->i4if_v18.image_get_entitlement_bool(__VA_ARGS__)) 184 #endif 185 186 /*! 187 * @function img4_image_get_entitlement_uint32 188 * Retrieves the unsigned 32-bit integer value for the requested image 189 * entitlement. 190 * 191 * @param image 192 * The image to query. 193 * 194 * @param _4cc 195 * The 4cc of the desired image entitlement. 196 * 197 * @param storage 198 * A pointer to storage for a 32-bit unsigned integer value. 199 * 200 * @result 201 * If the entitlement is present for the image, a pointer to the storage 202 * provided in {@link storage}. If the property is not present in the image or 203 * its value is not an unsigned 32-bit integer, NULL is returned. 204 */ 205 #if !XNU_KERNEL_PRIVATE 206 IMG4_API_AVAILABLE_20220513 207 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 208 const uint32_t * 209 img4_image_get_entitlement_uint32(img4_image_t image, 210 img4_4cc_t _4cc, 211 uint32_t *storage); 212 #else 213 #define img4_image_get_entitlement_uint32(...) \ 214 (img4if->i4if_v18.image_get_entitlement_uint32(__VA_ARGS__)) 215 #endif 216 217 /*! 218 * @function img4_image_get_entitlement_uint64 219 * Retrieves the unsigned 64-bit integer value for the requested image 220 * entitlement. 221 * 222 * @param image 223 * The image to query. 224 * 225 * @param _4cc 226 * The 4cc of the desired image entitlement. 227 * 228 * @param storage 229 * A pointer to storage for a 64-bit unsigned integer value. 230 * 231 * @result 232 * If the entitlement is present for the image, a pointer to the storage 233 * provided in {@link storage}. If the property is not present in the image or 234 * its value is not an unsigned 64-bit integer, NULL is returned. 235 */ 236 #if !XNU_KERNEL_PRIVATE 237 IMG4_API_AVAILABLE_20220513 238 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 239 const uint64_t * 240 img4_image_get_entitlement_uint64(img4_image_t image, 241 img4_4cc_t _4cc, 242 uint64_t *storage); 243 #else 244 #define img4_image_get_entitlement_uint64(...) \ 245 (img4if->i4if_v18.image_get_entitlement_uint64(__VA_ARGS__)) 246 #endif 247 248 /*! 249 * @function img4_image_get_entitlement_data 250 * Retrieves the buffer value for the requested image entitlement. 251 * 252 * @param image 253 * The image to query. 254 * 255 * @param _4cc 256 * The 4cc of the desired image entitlement. 257 * 258 * @param storage 259 * A pointer to storage for a buffer value. 260 * 261 * @result 262 * If the entitlement is present for the image, a pointer to the storage 263 * provided in {@link storage}. If the property is not present in the image or 264 * its value is not a data, NULL is returned. 265 */ 266 #if !XNU_KERNEL_PRIVATE 267 IMG4_API_AVAILABLE_20220513 268 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 269 const img4_buff_t * 270 img4_image_get_entitlement_data(img4_image_t image, 271 img4_4cc_t _4cc, 272 img4_buff_t *storage); 273 #else 274 #define img4_image_get_entitlement_data(...) \ 275 (img4if->i4if_v18.image_get_entitlement_data(__VA_ARGS__)) 276 #endif 277 278 OS_ASSUME_PTR_ABI_SINGLE_END 279 OS_ASSUME_NONNULL_END 280 __END_DECLS 281 282 #endif // __IMG4_IMAGE_H 283