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 | |