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