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
13OS_ASSUME_NONNULL_BEGIN
14OS_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
28IMG4_API_AVAILABLE_20200508
29OS_EXPORT OS_WARN_RESULT
30const img4_buff_t *_Nullable
31img4_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
55IMG4_API_AVAILABLE_20200508
56OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
57const bool *
58img4_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
85IMG4_API_AVAILABLE_20200508
86OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
87const uint32_t *
88img4_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
115IMG4_API_AVAILABLE_20200508
116OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
117const uint64_t *
118img4_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
145IMG4_API_AVAILABLE_20200508
146OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
147const img4_buff_t *
148img4_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
175IMG4_API_AVAILABLE_20220513
176OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
177const bool *
178img4_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
206IMG4_API_AVAILABLE_20220513
207OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
208const uint32_t *
209img4_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
237IMG4_API_AVAILABLE_20220513
238OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
239const uint64_t *
240img4_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
267IMG4_API_AVAILABLE_20220513
268OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
269const img4_buff_t *
270img4_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
278OS_ASSUME_PTR_ABI_SINGLE_END
279OS_ASSUME_NONNULL_END
280__END_DECLS
281
282#endif // __IMG4_IMAGE_H
283