1 | /*! |
2 | * @header |
3 | * Image4 runtime interfaces. |
4 | */ |
5 | #ifndef __IMG4_RUNTIME_H |
6 | #define __IMG4_RUNTIME_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 | * @typedef img4_identifier_t |
18 | * An enumeration describing identifiers in the Image4 specification. |
19 | * |
20 | * @const IMG4_IDENTIFIER_CEPO |
21 | * The chip epoch as documented in 2.1.1. Authoritative manifests will specify a |
22 | * certificate epoch which is greater than or equal to that of the chip. |
23 | * |
24 | * Unsigned 32-bit integer. |
25 | * |
26 | * @const IMG4_IDENTIFIER_BORD |
27 | * The board identifier as documented in 2.1.3. Authoritative manifests will |
28 | * specify a board identifier which is equal to that of the chip. |
29 | * |
30 | * Unsigned 32-bit integer. |
31 | * |
32 | * @const IMG4_IDENTIFIER_CHIP |
33 | * The chip identifier as documented in 2.1.2. Authoritative manifests will |
34 | * specify a chip identifier which is equal to that of the chip. |
35 | * |
36 | * Unsigned 32-bit integer. |
37 | * |
38 | * @const IMG4_IDENTIFIER_SDOM |
39 | * The security domain as documented in 2.1.5. Authoritative manifests will |
40 | * specify a security domain which is equal to that that of the chip. |
41 | * |
42 | * Unsigned 32-bit integer. Valid values are |
43 | * |
44 | * 0 Manufacturing |
45 | * 1 Darwin |
46 | * 2 Data Center (unsure) |
47 | * 3 Unused |
48 | * |
49 | * @const IMG4_IDENTIFIER_ECID |
50 | * The unique chip identifier as documented in 2.1.4. Authoritative manifests |
51 | * will specify a unique chip identifier which is equal to that of the chip. |
52 | * |
53 | * Unsigned 64-bit integer. |
54 | * |
55 | * @const IMG4_IDENTIFIER_CPRO |
56 | * The certificate production status as documented in 2.1.6. Authoritative |
57 | * manifests will specify a certificate production status which is equal to that |
58 | * of the chip. |
59 | * |
60 | * Boolean. |
61 | * |
62 | * @const IMG4_IDENTIFIER_CSEC |
63 | * The certificate security mode as documented in 2.1.7. Authoritative manifests |
64 | * will specify a certificate security mode which is equal to that of the chip. |
65 | * |
66 | * Boolean. |
67 | * |
68 | * @const IMG4_IDENTIFIER_EPRO |
69 | * The effective production status as documented in 2.1.23. Unless the chip |
70 | * environment supports demotion, this will always be the same as |
71 | * {@link IMG4_IDENTIFIER_CPRO}. An executable firmware in an authoritative |
72 | * manifest will specify an EPRO object property which is equal to that of the |
73 | * chip post-demotion. |
74 | * |
75 | * Boolean. |
76 | * |
77 | * @const IMG4_IDENTIFIER_ESEC |
78 | * The effective security mode as documented in 2.1.25. Unless the chip |
79 | * environment supports demotion, this will always be the same as |
80 | * {@link IMG4_IDENTIFIER_CSEC}. An executable firmware in an authoritative |
81 | * manifest will specify an ESEC object property which is equal to that of the |
82 | * chip post-demotion. |
83 | * |
84 | * Boolean. |
85 | * |
86 | * @const IMG4_IDENTIFIER_IUOU |
87 | * The "internal use only unit" property. Indicates whether the chip is present |
88 | * on a server-side authlist which permits installing builds which are otherwise |
89 | * restricted to parts whose CPRO is 0. This property is only published by macOS |
90 | * devices whose root of trust is in an arm coprocessor (e.g. T2). |
91 | * |
92 | * Authoritative manifests will specify an internal-use-only-build property |
93 | * which, if true, is equal to the internal-use-only-unit property of the chip. |
94 | * If the internal-use-only-build property is false, then there is no constraint |
95 | * on the chip's internal-use-only-unit property. |
96 | * |
97 | * Boolean. |
98 | * |
99 | * @const IMG4_IDENTIFIER_RSCH |
100 | * The research fusing status. Indicates whether the chip is intended for |
101 | * security research to be performed by external parties. Authoritative |
102 | * manifests will specify a research fusing state which is equal to that of the |
103 | * chip. |
104 | * |
105 | * Boolean. |
106 | * |
107 | * This identifier was never recognized by SecureROM and has been obsoleted by |
108 | * {@link IMG4_IDENTIFIER_ESDM}. |
109 | * |
110 | * @const IMG4_IDENTIFIER_CHMH |
111 | * The chained manifest hash from the previous stage of secure boot as described |
112 | * in 2.2.11. An authoritative manifest will either |
113 | * |
114 | * - specify a manifest hash which is equal to that of the previous secure |
115 | * boot stage's manifest |
116 | * - itself have a manifest hash which is equal to that of the previous |
117 | * secure boot stage's manifest |
118 | * |
119 | * If the previous stage of secure boot enabled mix-n-match, there is no |
120 | * constraint on the previous stage's manifest hash. |
121 | * |
122 | * Manifests which specify this property cannot be used to create new trust |
123 | * chains -- they may only extend existing ones. |
124 | * |
125 | * Digest. |
126 | * |
127 | * @const IMG4_IDENTIFIER_AMNM |
128 | * The allow-mix-n-match status of the chip. If mix-n-match is enabled, secure |
129 | * boot will permit different manifests to be used at each stage of boot. If the |
130 | * chip environment allows mix-n-match, evaluation will not require an anti- |
131 | * replay token to be specified, and any chained manifest hash constraints are |
132 | * ignored. |
133 | * |
134 | * Boolean. |
135 | * |
136 | * @const IMG4_IDENTIFIER_EUOU |
137 | * The engineering-use-only-unit status of the chip. This is in effect an alias |
138 | * for the {@link IMG4_IDENTIFIER_IUOU} property. Either property being present |
139 | * in the environment will satisfy a manifest's iuob constraint. |
140 | * |
141 | * Boolean. |
142 | * |
143 | * @const IMG4_IDENTIFIER_LOVE |
144 | * The long version of the OS currently booted on the chip (Long Os VErsion). |
145 | * |
146 | * Authoritative manifests will specify a version number which is greater than |
147 | * that of the chip. |
148 | * |
149 | * C string. |
150 | * |
151 | * @const IMG4_IDENTIFIER_ESDM |
152 | * The extended security domain of the chip. Authoritative manifests will |
153 | * specify an extended security domain which is equal to that of the chip. |
154 | * |
155 | * Unsigned 32-bit integer. This integer represents 8 fusing bits, and therefore |
156 | * the maximum valid value is 0xff. |
157 | * |
158 | * @const IMG4_IDENTIFIER_FPGT |
159 | * The factory pre-release global trust status of the chip. This is in effect an |
160 | * alias for the {@link IMG4_IDENTIFIER_IUOU} property. Either property being |
161 | * present in the environment will satisfy a manifest's iuob constraint. |
162 | * |
163 | * Boolean. |
164 | * |
165 | * @const IMG4_IDENTIFIER_UDID |
166 | * The universal device identifier of the chip. This uniquely identifies the SoC |
167 | * globally across all SoCs. Authoritative manifests will specify a UDID which |
168 | * is equal to that of the chip. |
169 | * |
170 | * 128-bit octet string. |
171 | * |
172 | * @const IMG4_IDENTIFIER_FCHP |
173 | * The chip identifier of the Cryptex coprocessor associated with the chip. This |
174 | * distinguishes the software Crytpex coprocessor instances which operate on the |
175 | * AP. Authoritative manifests will specify a Cryptex chip identifier that is |
176 | * equal to that of the chip. |
177 | * |
178 | * Runtimes are not capable of reporting this value, and queries for it should |
179 | * return ENOENT. This invariant is defined for convenience to the |
180 | * implementation. |
181 | * |
182 | * Unsigned 32-bit integer. |
183 | * |
184 | * @const IMG4_IDENTIFIER_TYPE |
185 | * The type identifier of the Cryptex coprocessor associated with the chip. This |
186 | * distinguishes software Cryptex coprocessor instances of the same chip |
187 | * identifier which operate on the AP. Authoritative manifests will specify a |
188 | * Cryptex type that is equal to that of the chip. |
189 | * |
190 | * Runtimes are not capable of reporting this value, and queries for it should |
191 | * return ENOENT. This invariant is defined for convenience to the |
192 | * implementation. |
193 | * |
194 | * Unsigned 32-bit integer. |
195 | * |
196 | * @const IMG4_IDENTIFIER_STYP |
197 | * The subtype identifier of the Cryptex coprocessor associated with the chip. |
198 | * This permits an additional level of granularity to distinguish Cryptex |
199 | * coprocessor instances from one another. Authoritative manifests will specify |
200 | * a Cryptex subtype that is equal to that of the chip. |
201 | * |
202 | * Runtimes are not capable of reporting this value, and queries for it should |
203 | * return ENOENT. This invariant is defined for convenience to the |
204 | * implementation. |
205 | * |
206 | * Unsigned 32-bit integer. |
207 | * |
208 | * @const IMG4_IDENTIFIER_CLAS |
209 | * The product class of the Cryptex coprocessor associated with the chip. |
210 | * Authoritative manifests will specify a product class that is equal to that of |
211 | * the chip. |
212 | * |
213 | * Valid values for this property are: |
214 | * |
215 | * 0xf0 - Intel Mac (with or without T2 security chip) |
216 | * 0xf1 - Apple Silicon Mac |
217 | * 0xf2 - iPhone/iPad/iPod touch |
218 | * 0xf3 - watch |
219 | * 0xf4 - tv/HomePod |
220 | * |
221 | * Unsigned 32-bit integer. |
222 | * |
223 | * @const IMG4_IDENTIFIER_SPIH |
224 | * The booted supplemental manifest hash. |
225 | * |
226 | * Digest. |
227 | * |
228 | * @const IMG4_IDENTIFIER_NSPH |
229 | * The preboot supplemental manifest hash intended to become active at the next |
230 | * boot. |
231 | * |
232 | * Digest. |
233 | * |
234 | * @const IMG4_IDENTIFIER_STNG |
235 | * The generation number of the last-executed blessed local policy on the AP. |
236 | * |
237 | * Unsigned 64-bit integer. |
238 | * |
239 | * @const IMG4_IDENTIFIER_VUID |
240 | * The volume group UUID that the chip is booting from. |
241 | * |
242 | * 128-bit octet string. |
243 | * |
244 | * @const _IMG4_IDENTIFIER_CNT |
245 | * A convenience value representing the number of known identifiers. |
246 | */ |
247 | IMG4_API_AVAILABLE_20200508 |
248 | OS_CLOSED_ENUM(img4_identifier, uint64_t, |
249 | IMG4_IDENTIFIER_CEPO, |
250 | IMG4_IDENTIFIER_BORD, |
251 | IMG4_IDENTIFIER_CHIP, |
252 | IMG4_IDENTIFIER_SDOM, |
253 | IMG4_IDENTIFIER_ECID, |
254 | IMG4_IDENTIFIER_CPRO, |
255 | IMG4_IDENTIFIER_CSEC, |
256 | IMG4_IDENTIFIER_EPRO, |
257 | IMG4_IDENTIFIER_ESEC, |
258 | IMG4_IDENTIFIER_IUOU, |
259 | IMG4_IDENTIFIER_RSCH, |
260 | IMG4_IDENTIFIER_CHMH, |
261 | IMG4_IDENTIFIER_AMNM, |
262 | IMG4_IDENTIFIER_EUOU, |
263 | IMG4_IDENTIFIER_LOVE, |
264 | IMG4_IDENTIFIER_ESDM, |
265 | IMG4_IDENTIFIER_FPGT, |
266 | IMG4_IDENTIFIER_UDID, |
267 | IMG4_IDENTIFIER_FCHP, |
268 | IMG4_IDENTIFIER_TYPE, |
269 | IMG4_IDENTIFIER_STYP, |
270 | IMG4_IDENTIFIER_CLAS, |
271 | IMG4_IDENTIFIER_SPIH, |
272 | IMG4_IDENTIFIER_NSPH, |
273 | IMG4_IDENTIFIER_STNG, |
274 | IMG4_IDENTIFIER_VUID, |
275 | _IMG4_IDENTIFIER_CNT, |
276 | ); |
277 | |
278 | /*! |
279 | * @typedef img4_pmap_data_t |
280 | * An opaque type representing state protected by the host's page mapping layer |
281 | * as it deems appropriate. Do not use directly. |
282 | */ |
283 | IMG4_API_AVAILABLE_20210521 |
284 | typedef struct _img4_pmap_data img4_pmap_data_t; |
285 | |
286 | /*! |
287 | * @typedef img4_runtime_object_spec_index_t |
288 | * An enumeration describing the executable objects recognized by runtimes. |
289 | * |
290 | * @const IMG4_RUNTIME_OBJECT_SPEC_INDEX_MANIFEST |
291 | * The enumerated constant which refers to the internal manifest object. |
292 | * |
293 | * @const IMG4_RUNTIME_OBJECT_SPEC_INDEX_SUPPLEMENTAL_ROOT |
294 | * The enumerated constant which refers to the |
295 | * {@link IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT} object. |
296 | * |
297 | * @const IMG4_RUNTIME_OBJECT_SPEC_INDEX_SUPPLEMENTAL_OBJECT |
298 | * The enumerated constant which refers to the |
299 | * {@link IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_OBJECT} object. |
300 | * |
301 | * @const IMG4_RUNTIME_OBJECT_SPEC_INDEX_LOCAL_POLICY |
302 | * The enumerated constant which refers to the |
303 | * {@link IMG4_RUNTIME_OBJECT_SPEC_LOCAL_POLICY} object. |
304 | * |
305 | * @const _IMG4_RUNTIME_OBJECT_SPEC_INDEX_CNT |
306 | * A sentinel value representing the total number of executable object |
307 | * specifications. |
308 | */ |
309 | IMG4_API_AVAILABLE_20210521 |
310 | OS_CLOSED_ENUM(img4_runtime_object_spec_index, uint64_t, |
311 | IMG4_RUNTIME_OBJECT_SPEC_INDEX_MANIFEST, |
312 | IMG4_RUNTIME_OBJECT_SPEC_INDEX_SUPPLEMENTAL_ROOT, |
313 | IMG4_RUNTIME_OBJECT_SPEC_INDEX_SUPPLEMENTAL_OBJECT, |
314 | IMG4_RUNTIME_OBJECT_SPEC_INDEX_LOCAL_POLICY, |
315 | _IMG4_RUNTIME_OBJECT_SPEC_INDEX_CNT, |
316 | ); |
317 | |
318 | /*! |
319 | * @typedef img4_runtime_object_spec_t |
320 | * A specification for an object known to and executable by a runtime. |
321 | */ |
322 | IMG4_API_AVAILABLE_20210205 |
323 | typedef struct _img4_runtime_object_spec img4_runtime_object_spec_t; |
324 | |
325 | /*! |
326 | * @typedef img4_runtime_init_t |
327 | * A function which initializes the runtime. |
328 | * |
329 | * @param rt |
330 | * The runtime for which the function is being invoked. |
331 | * |
332 | * @discussion |
333 | * This function is called by the implementation prior to any other runtime |
334 | * function being called. The implementation will ensure that it is called only |
335 | * once. Any runtime with an initialization function must be registered with the |
336 | * {@link IMG4_RUNTIME_REGISTER} macro. |
337 | */ |
338 | IMG4_API_AVAILABLE_20200508 |
339 | typedef void (*img4_runtime_init_t)( |
340 | const img4_runtime_t *rt |
341 | ); |
342 | |
343 | /*! |
344 | * @typedef img4_runtime_alloc_t |
345 | * An allocation function. |
346 | * |
347 | * @param rt |
348 | * The runtime for which the function is being invoked. |
349 | * |
350 | * @param n |
351 | * The number of bytes to allocate. |
352 | * |
353 | * @result |
354 | * A pointer to the new allocation, or NULL if there was an allocation failure. |
355 | * |
356 | * The memory returned by this function is expected to be zero-filled. |
357 | */ |
358 | IMG4_API_AVAILABLE_20200508 |
359 | typedef void *_Nullable (*img4_runtime_alloc_t)( |
360 | const img4_runtime_t *rt, |
361 | size_t n |
362 | ); |
363 | |
364 | /*! |
365 | * @typedef img4_runtime_dealloc_t |
366 | * A deallocation function. |
367 | * |
368 | * @param rt |
369 | * The runtime for which the function is being invoked. |
370 | * |
371 | * @param p |
372 | * A pointer to the allocation to free. The callee is expected to return |
373 | * immediately if NULL is passed. |
374 | * |
375 | * @param n |
376 | * The size of the allocation. Not all implementation may require this |
377 | * information to be specified. |
378 | */ |
379 | IMG4_API_AVAILABLE_20200508 |
380 | typedef void (*img4_runtime_dealloc_t)( |
381 | const img4_runtime_t *rt, |
382 | void *_Nullable p, |
383 | size_t n |
384 | ); |
385 | |
386 | /*! |
387 | * @typedef img4_log_level_t |
388 | * An enumeration describing the importance/severity of a log message. |
389 | * |
390 | * @const IMG4_LOG_LEVEL_ERROR |
391 | * A fatal condition which will cause the implementation to abort its current |
392 | * operation. |
393 | * |
394 | * @const IMG4_LOG_LEVEL_INFO |
395 | * Information that may be of interest to the system operator. |
396 | * |
397 | * @const IMG4_LOG_LEVEL_DEBUG |
398 | * Information that may be of interest to the maintainer. |
399 | * |
400 | * @const _IMG4_LOG_LEVEL_CNT |
401 | * A convenience constant indicating the number of log levels. |
402 | */ |
403 | IMG4_API_AVAILABLE_20200508 |
404 | OS_CLOSED_ENUM(img4_log_level, uint64_t, |
405 | IMG4_LOG_LEVEL_ERROR, |
406 | IMG4_LOG_LEVEL_INFO, |
407 | IMG4_LOG_LEVEL_DEBUG, |
408 | _IMG4_LOG_LEVEL_CNT, |
409 | ); |
410 | |
411 | /*! |
412 | * @typedef img4_runtime_log_t |
413 | * A function which writes log messages. |
414 | * |
415 | * @param rt |
416 | * The runtime for which the function is being invoked. |
417 | * |
418 | * @param handle |
419 | * An implementation-specific handle for the log message. |
420 | * |
421 | * @param level |
422 | * The message of the log level. The implementation is free to determine whether |
423 | * a given message is worthy of record. |
424 | * |
425 | * @param fmt |
426 | * A printf(3)-style format string. |
427 | * |
428 | * @param ... |
429 | * Arguments to be interpreted by the format string according to the |
430 | * specifications in printf(3). |
431 | */ |
432 | OS_FORMAT_PRINTF(4, 5) |
433 | IMG4_API_AVAILABLE_20200508 |
434 | typedef void (*img4_runtime_log_t)( |
435 | const img4_runtime_t *rt, |
436 | void *_Nullable handle, |
437 | img4_log_level_t level, |
438 | const char *fmt, |
439 | ... |
440 | ); |
441 | |
442 | /*! |
443 | * @typedef img4_runtime_log_handle_t |
444 | * A function which returns a log handle. |
445 | * |
446 | * @param rt |
447 | * The runtime for which the function is being invoked. |
448 | * |
449 | * @result |
450 | * A runtime-specific log handle that will be passed to the logging function. |
451 | */ |
452 | IMG4_API_AVAILABLE_20200508 |
453 | typedef void *_Nullable (*img4_runtime_log_handle_t)( |
454 | const img4_runtime_t *rt |
455 | ); |
456 | |
457 | /*! |
458 | * @typedef img4_runtime_get_identifier_bool_t |
459 | * A function which retrieves a Boolean Image4 identifier. |
460 | * |
461 | * @param rt |
462 | * The runtime for which the function is being invoked. |
463 | * |
464 | * @param chip |
465 | * The chip for which to retrieve the identifier. |
466 | * |
467 | * @param identifier |
468 | * The identifier to retrieve. |
469 | * |
470 | * @param value |
471 | * Upon successful return, storage which is populated with the retrieved value. |
472 | * |
473 | * @result |
474 | * Upon success, the callee is expected to return zero. Otherwise, the callee |
475 | * may return one of the following error codes: |
476 | * |
477 | * [ENOTSUP] The identifier cannot be queried in the runtime |
478 | * [ENOENT] The identifier was not found in the runtime's identity |
479 | * oracle |
480 | * [ENODEV] There was an error querying the runtime's identity oracle |
481 | */ |
482 | IMG4_API_AVAILABLE_20200508 |
483 | typedef errno_t (*img4_runtime_get_identifier_bool_t)( |
484 | const img4_runtime_t *rt, |
485 | const img4_chip_t *chip, |
486 | img4_identifier_t identifier, |
487 | bool *value |
488 | ); |
489 | |
490 | /*! |
491 | * @typedef img4_runtime_get_identifier_uint32_t |
492 | * A function which retrieves an unsigned 32-bit integer Image4 identifier. |
493 | * |
494 | * @param rt |
495 | * The runtime for which the function is being invoked. |
496 | * |
497 | * @param chip |
498 | * The chip for which to retrieve the identifier. |
499 | * |
500 | * @param identifier |
501 | * The identifier to retrieve. |
502 | * |
503 | * @param value |
504 | * Upon successful return, storage which is populated with the retrieved value. |
505 | * |
506 | * @result |
507 | * Upon success, the callee is expected to return zero. Otherwise, the callee |
508 | * may return one of the following error codes: |
509 | * |
510 | * [ENOTSUP] The identifier cannot be queried in the runtime |
511 | * [ENOENT] The identifier was not found in the runtime's identity |
512 | * oracle |
513 | * [ENODEV] There was an error querying the runtime's identity oracle |
514 | */ |
515 | IMG4_API_AVAILABLE_20200508 |
516 | typedef errno_t (*img4_runtime_get_identifier_uint32_t)( |
517 | const img4_runtime_t *rt, |
518 | const img4_chip_t *chip, |
519 | img4_identifier_t identifier, |
520 | uint32_t *value |
521 | ); |
522 | |
523 | /*! |
524 | * @typedef img4_runtime_get_identifier_uint64_t |
525 | * A function which retrieves an unsigned 64-bit integer Image4 identifier. |
526 | * |
527 | * @param rt |
528 | * The runtime for which the function is being invoked. |
529 | * |
530 | * @param chip |
531 | * The chip for which to retrieve the identifier. |
532 | * |
533 | * @param identifier |
534 | * The identifier to retrieve. |
535 | * |
536 | * @param value |
537 | * Upon successful return, storage which is populated with the retrieved value. |
538 | * |
539 | * @result |
540 | * Upon success, the callee is expected to return zero. Otherwise, the callee |
541 | * may return one of the following error codes: |
542 | * |
543 | * [ENOTSUP] The identifier cannot be queried in the runtime |
544 | * [ENOENT] The identifier was not found in the runtime's identity |
545 | * oracle |
546 | * [ENODEV] There was an error querying the runtime's identity oracle |
547 | */ |
548 | IMG4_API_AVAILABLE_20200508 |
549 | typedef errno_t (*img4_runtime_get_identifier_uint64_t)( |
550 | const img4_runtime_t *rt, |
551 | const img4_chip_t *chip, |
552 | img4_identifier_t identifier, |
553 | uint64_t *value |
554 | ); |
555 | |
556 | /*! |
557 | * @typedef img4_runtime_get_identifier_digest_t |
558 | * A function which retrieves a digest Image4 identifier. |
559 | * |
560 | * @param rt |
561 | * The runtime for which the function is being invoked. |
562 | * |
563 | * @param chip |
564 | * The chip for which to retrieve the identifier. |
565 | * |
566 | * @param identifier |
567 | * The identifier to retrieve. |
568 | * |
569 | * @param value |
570 | * Upon successful return, storage which is populated with the retrieved value. |
571 | * |
572 | * @result |
573 | * Upon success, the callee is expected to return zero. Otherwise, the callee |
574 | * may return one of the following error codes: |
575 | * |
576 | * [ENOTSUP] The identifier cannot be queried in the runtime |
577 | * [ENOENT] The identifier was not found in the runtime's identity |
578 | * oracle |
579 | * [ENODEV] There was an error querying the runtime's identity oracle |
580 | */ |
581 | IMG4_API_AVAILABLE_20200508 |
582 | typedef errno_t (*img4_runtime_get_identifier_digest_t)( |
583 | const img4_runtime_t *rt, |
584 | const img4_chip_t *chip, |
585 | img4_identifier_t identifier, |
586 | img4_dgst_t *value |
587 | ); |
588 | |
589 | /*! |
590 | * @typedef img4_runtime_get_identifier_cstr_t |
591 | * A function which retrieves a C-string Image4 identifier. |
592 | * |
593 | * @param rt |
594 | * The runtime for which the function is being invoked. |
595 | * |
596 | * @param chip |
597 | * The chip for which to retrieve the identifier. |
598 | * |
599 | * @param identifier |
600 | * The identifier to retrieve. |
601 | * |
602 | * @param value |
603 | * Upon successful return, storage which is populated with the retrieved value. |
604 | * |
605 | * @result |
606 | * Upon success, the callee is expected to return zero. Otherwise, the callee |
607 | * may return one of the following error codes: |
608 | * |
609 | * [ENOTSUP] The identifier cannot be queried in the runtime |
610 | * [ENOENT] The identifier was not found in the runtime's identity |
611 | * oracle |
612 | * [ENODEV] There was an error querying the runtime's identity oracle |
613 | */ |
614 | IMG4_API_AVAILABLE_20210113 |
615 | typedef errno_t (*img4_runtime_get_identifier_cstr_t)( |
616 | const img4_runtime_t *rt, |
617 | const img4_chip_t *chip, |
618 | img4_identifier_t identifier, |
619 | img4_cstr_t *value |
620 | ); |
621 | |
622 | /*! |
623 | * @typedef img4_runtime_execute_object_t |
624 | * A function which executes an object type known to the runtime. |
625 | * |
626 | * @param rt |
627 | * The runtime for which the function is being invoked. |
628 | * |
629 | * @param obj_spec |
630 | * The object specification for the payload being executed. |
631 | * |
632 | * @param payload |
633 | * The payload bytes to execute. These bytes are delivered in their raw form, |
634 | * i.e. without any Image4 payload wrapping. |
635 | * |
636 | * @param manifest |
637 | * The manifest which authenticats the payload. If the payload is intended to be |
638 | * used without authentication (or with alternate means of authentication), this |
639 | * may be NULL. |
640 | * |
641 | * @result |
642 | * Upon success, the callee is expected to return zero. Otherwise, the callee |
643 | * may return any appropriate POSIX error code. |
644 | * |
645 | * @discussion |
646 | * This function is only called if the payload has been successfully |
647 | * authenticated; the callee can consider the bytes as trusted. |
648 | */ |
649 | IMG4_API_AVAILABLE_20210205 |
650 | typedef errno_t (*img4_runtime_execute_object_t)( |
651 | const img4_runtime_t *rt, |
652 | const img4_runtime_object_spec_t *obj_spec, |
653 | const img4_buff_t *payload, |
654 | const img4_buff_t *_Nullable manifest |
655 | ); |
656 | |
657 | /*! |
658 | * @typedef img4_runtime_copy_object_t |
659 | * A function which obtains the payload of a previously-executed object. |
660 | * |
661 | * @param rt |
662 | * The runtime for which the function is being invoked. |
663 | * |
664 | * @param obj_spec |
665 | * The object specification for the payload being obtained. |
666 | * |
667 | * @param payload |
668 | * A pointer to a buffer object in which to copy the object. |
669 | * |
670 | * @param payload_len |
671 | * Upon successful return, a pointer to the total number of bytes coped into the |
672 | * buffer referred to by {@link payload}. This parameter may be NULL. |
673 | * |
674 | * In the event that buffer referred to be {@link payload} is insufficient to, |
675 | * accommodate the object, the callee is expected to set this parameter to the |
676 | * total number of bytes required. |
677 | * |
678 | * @result |
679 | * Upon success, the callee is expected to return zero. Otherwise, the callee |
680 | * may return one of the following error codes: |
681 | * |
682 | * [EOVERFLOW] The provided buffer is not large enough for the payload; |
683 | * in this case the callee is expected to set the |
684 | * {@link i4b_len} of the given buffer to the required |
685 | * length |
686 | * [ENOENT] The object has not yet been executed |
687 | */ |
688 | IMG4_API_AVAILABLE_20210205 |
689 | typedef errno_t (*img4_runtime_copy_object_t)( |
690 | const img4_runtime_t *rt, |
691 | const img4_runtime_object_spec_t *obj_spec, |
692 | img4_buff_t *payload, |
693 | size_t *_Nullable payload_len |
694 | ); |
695 | |
696 | /*! |
697 | * @typedef img4_runtime_alloc_type_t |
698 | * A function which allocates a single object of a given type. |
699 | * |
700 | * @param rt |
701 | * The runtime for which the function is being invoked. |
702 | * |
703 | * @param handle |
704 | * The domain-specific handle describing the object and the allocation site. |
705 | * |
706 | * @result |
707 | * A pointer to the new allocation, or NULL if there was an allocation failure. |
708 | * The memory returned by this function is expected to be zero-filled. |
709 | */ |
710 | IMG4_API_AVAILABLE_20210226 |
711 | typedef void *_Nullable (*img4_runtime_alloc_type_t)( |
712 | const img4_runtime_t *rt, |
713 | void *_Nullable handle |
714 | ); |
715 | |
716 | /*! |
717 | * @typedef img4_runtime_dealloc_type_t |
718 | * A function which deallocates a single object of a given type. |
719 | * |
720 | * @param rt |
721 | * The runtime for which the function is being invoked. |
722 | * |
723 | * @param handle |
724 | * The domain-specific handle describing the object and the deallocation site. |
725 | * |
726 | * @param p |
727 | * The address of the object to deallocate. |
728 | */ |
729 | IMG4_API_AVAILABLE_20210226 |
730 | typedef void (*img4_runtime_dealloc_type_t)( |
731 | const img4_runtime_t *rt, |
732 | void *_Nullable handle, |
733 | void *p |
734 | ); |
735 | |
736 | /*! |
737 | * @typedef img4_runtime_set_nonce_t |
738 | * A function which sets the value of a nonce managed by the runtime. |
739 | * |
740 | * @param rt |
741 | * The runtime for which the function is being invoked. |
742 | * |
743 | * @param ndi |
744 | * The index of the nonce domain whose nonce should be set. |
745 | * |
746 | * @param n |
747 | * The value of the nonce indicated by {@link nd}. |
748 | */ |
749 | IMG4_API_AVAILABLE_20210521 |
750 | typedef void (*img4_runtime_set_nonce_t)( |
751 | const img4_runtime_t *rt, |
752 | img4_nonce_domain_index_t ndi, |
753 | const img4_nonce_t *n |
754 | ); |
755 | |
756 | /*! |
757 | * @typedef img4_runtime_roll_nonce_t |
758 | * A function which rolls a nonce managed by the runtime. |
759 | * |
760 | * @param rt |
761 | * The runtime for which the function is being invoked. |
762 | * |
763 | * @param ndi |
764 | * The index of the nonce domain whose nonce should be rolled. |
765 | */ |
766 | IMG4_API_AVAILABLE_20210521 |
767 | typedef void (*img4_runtime_roll_nonce_t)( |
768 | const img4_runtime_t *rt, |
769 | img4_nonce_domain_index_t ndi |
770 | ); |
771 | |
772 | /*! |
773 | * @typedef img4_runtime_copy_nonce_t |
774 | * A function which retrieve the value of a nonce managed by the runtime. |
775 | * |
776 | * @param rt |
777 | * The runtime for which the function is being invoked. |
778 | * |
779 | * @param ndi |
780 | * The index of the nonce domain whose nonce should be queried. |
781 | * |
782 | * @param n |
783 | * Upon successful return, the value of the nonce indicated by {@link nd}. If |
784 | * the caller simply wishes to check if the nonce has been invalidated, this |
785 | * parameter may be NULL, and the caller can check for ESTALE. |
786 | * |
787 | * @result |
788 | * Upon success, zero is returned. The implementation may also return one of the |
789 | * following error codes directly: |
790 | * |
791 | * [ESTALE] The nonce for the given domain has been invalidated, and the |
792 | * host must reboot in order to generate a new one |
793 | */ |
794 | IMG4_API_AVAILABLE_20210521 |
795 | typedef errno_t (*img4_runtime_copy_nonce_t)( |
796 | const img4_runtime_t *rt, |
797 | img4_nonce_domain_index_t ndi, |
798 | img4_nonce_t *_Nullable n |
799 | ); |
800 | |
801 | /*! |
802 | * @define IMG4_BUFF_STRUCT_VERSION |
803 | * The version of the {@link img4_buff_t} structure supported by the |
804 | * implementation. |
805 | */ |
806 | #define IMG4_BUFF_STRUCT_VERSION (0u) |
807 | |
808 | /*! |
809 | * @struct _img4_buff |
810 | * A structure describing a buffer. |
811 | * |
812 | * @field i4b_version |
813 | * The version of the structure. Initialize to {@link IMG4_BUFF_STRUCT_VERSION}. |
814 | * |
815 | * @field i4b_bytes |
816 | * A pointer to the buffer. |
817 | * |
818 | * @field i4b_len |
819 | * The length of the buffer. |
820 | * |
821 | * @field i4b_dealloc |
822 | * The deallocation function for the buffer. May be NULL if the underlying |
823 | * memory does not require cleanup. When the implementation invokes this |
824 | * function, it will always pass {@link IMG4_RUNTIME_DEFAULT}, and the callee |
825 | * should not consult this parameter for any reason. |
826 | */ |
827 | struct _img4_buff { |
828 | img4_struct_version_t i4b_version; |
829 | uint8_t *__counted_by(i4b_len) i4b_bytes; |
830 | size_t i4b_len; |
831 | img4_runtime_dealloc_t _Nullable i4b_dealloc; |
832 | } IMG4_API_AVAILABLE_20200508; |
833 | |
834 | /*! |
835 | * @const IMG4_BUFF_INIT |
836 | * A convenience initializer for the {@link img4_buff_t} structure. |
837 | */ |
838 | #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L |
839 | #define IMG4_BUFF_INIT (img4_buff_t){ \ |
840 | .i4b_version = IMG4_BUFF_STRUCT_VERSION, \ |
841 | .i4b_len = 0, \ |
842 | .i4b_bytes = NULL, \ |
843 | .i4b_dealloc = NULL, \ |
844 | } |
845 | #elif defined(__cplusplus) && __cplusplus >= 201103L |
846 | #define IMG4_BUFF_INIT (img4_buff_t{ \ |
847 | IMG4_BUFF_STRUCT_VERSION, \ |
848 | NULL, \ |
849 | 0, \ |
850 | NULL, \ |
851 | }) |
852 | #elif defined(__cplusplus) |
853 | #define IMG4_BUFF_INIT (img4_buff_t((img4_buff_t){ \ |
854 | IMG4_BUFF_STRUCT_VERSION, \ |
855 | NULL, \ |
856 | 0, \ |
857 | NULL, \ |
858 | })) |
859 | #else |
860 | #define IMG4_BUFF_INIT {IMG4_BUFF_STRUCT_VERSION} |
861 | #endif |
862 | |
863 | /*! |
864 | * @define IMG4_RUNTIME_STRUCT_VERSION |
865 | * The version of the {@link img4_runtime_t} structure supported by the |
866 | * implementation. |
867 | */ |
868 | #define IMG4_RUNTIME_STRUCT_VERSION (5u) |
869 | |
870 | /*! |
871 | * @struct _img4_runtime |
872 | * A structure describing required primitives in the operating environment's |
873 | * runtime. |
874 | * |
875 | * @field i4rt_version |
876 | * The version of the structure supported by the implementation. In a custom |
877 | * execution context, initialize to {@link IMG4_RUNTIME_STRUCT_VERSION}. |
878 | * |
879 | * @field i4rt_name |
880 | * A string describing the environment. |
881 | * |
882 | * @field i4rt_init |
883 | * The runtime initialization function. See discussion in |
884 | * {@link img4_runtime_init_t}. |
885 | * |
886 | * @field i4rt_alloc |
887 | * The allocation function for the environment (e.g. in Darwin userspace, this |
888 | * would be a pointer to malloc(3)). The memory returned is expected to be zero- |
889 | * filled. |
890 | * |
891 | * @field i4rt_dealloc |
892 | * The deallocation function for the environment (e.g. in Darwin userspace, this |
893 | * would be a pointer to free(3)). |
894 | * |
895 | * @field i4rt_log |
896 | * The function which logs messages from the implementation. |
897 | * |
898 | * @field i4rt_log_handle |
899 | * The function which returns the handle to be passed to the logging function. |
900 | * |
901 | * @field i4rt_get_identifier_bool |
902 | * The function which returns Boolean identifiers. |
903 | * |
904 | * @field i4rt_get_identifier_uint32 |
905 | * The function which returns unsigned 32-bit integer identifiers. |
906 | * |
907 | * @field i4rt_get_identifier_uint64 |
908 | * The function which returns unsigned 64-bit integer identifiers. |
909 | * |
910 | * @field i4rt_get_identifier_digest |
911 | * The function which returns digest identifiers. |
912 | * |
913 | * @field i4rt_context |
914 | * A user-defined context pointer. Introduced in version 1 of the structure. |
915 | * |
916 | * @field i4rt_get_identifier_cstr |
917 | * The function which returns C-string identifiers. Introduced in version 2 of |
918 | * the structure. |
919 | * |
920 | * @field i4rt_execute_object |
921 | * The function which executes objects. Introduced in version 3 of the |
922 | * structure. |
923 | * |
924 | * @field i4rt_copy_object |
925 | * The function which copies objects. Introduced in version 3 of the structure. |
926 | * |
927 | * @field i4rt_alloc_type |
928 | * The typed allocation function for the environment. This allocator should be |
929 | * used for any fixed-size, structured allocation that may contain pointers. |
930 | * |
931 | * The memory returned is expected to be zero-filled. Introduced in version 4 of |
932 | * the structure. |
933 | * |
934 | * @field i4rt_dealloc_type |
935 | * The typed deallocation function for the environment. Introduced in version 4 |
936 | * of the structure. |
937 | * |
938 | * @field i4rt_set_nonce |
939 | * The nonce-set function for the environment. Introduced in version 5 of the |
940 | * structure. |
941 | * |
942 | * @field i4rt_roll_nonce |
943 | * The nonce-roll function for the environment. Introduced in version 5 of the |
944 | * structure. |
945 | * |
946 | * @field i4rt_roll_nonce |
947 | * The nonce-copy function for the environment. Introduced in version 5 of the |
948 | * structure. |
949 | */ |
950 | struct _img4_runtime { |
951 | img4_struct_version_t i4rt_version; |
952 | const char *i4rt_name; |
953 | img4_runtime_init_t _Nullable i4rt_init; |
954 | img4_runtime_alloc_t i4rt_alloc; |
955 | img4_runtime_dealloc_t i4rt_dealloc; |
956 | img4_runtime_log_t i4rt_log; |
957 | img4_runtime_log_handle_t i4rt_log_handle; |
958 | img4_runtime_get_identifier_bool_t i4rt_get_identifier_bool; |
959 | img4_runtime_get_identifier_uint32_t i4rt_get_identifier_uint32; |
960 | img4_runtime_get_identifier_uint64_t i4rt_get_identifier_uint64; |
961 | img4_runtime_get_identifier_digest_t i4rt_get_identifier_digest; |
962 | void *_Nullable i4rt_context; |
963 | img4_runtime_get_identifier_cstr_t i4rt_get_identifier_cstr; |
964 | img4_runtime_execute_object_t i4rt_execute_object; |
965 | img4_runtime_copy_object_t i4rt_copy_object; |
966 | img4_runtime_alloc_type_t i4rt_alloc_type; |
967 | img4_runtime_dealloc_type_t i4rt_dealloc_type; |
968 | img4_runtime_set_nonce_t i4rt_set_nonce; |
969 | img4_runtime_roll_nonce_t i4rt_roll_nonce; |
970 | img4_runtime_copy_nonce_t i4rt_copy_nonce; |
971 | } IMG4_API_AVAILABLE_20200508; |
972 | |
973 | /*! |
974 | * @function IMG4_RUNTIME_REGISTER |
975 | * Registers a runtime with the module implementation such that its |
976 | * initialization function can be called. In environments which support dynamic |
977 | * library linkage, only runtimes registered from the main executable image can |
978 | * be discovered by the implementation. |
979 | * |
980 | * @param _rt |
981 | * The img4_runtime_t structure to register. |
982 | */ |
983 | #define IMG4_RUNTIME_REGISTER(_rt) LINKER_SET_ENTRY(__img4_rt, _rt); |
984 | |
985 | /*! |
986 | * @const IMG4_RUNTIME_DEFAULT |
987 | * The default runtime for the current operating environment. |
988 | */ |
989 | #if !XNU_KERNEL_PRIVATE |
990 | IMG4_API_AVAILABLE_20200508 |
991 | OS_EXPORT |
992 | const img4_runtime_t _img4_runtime_default; |
993 | #define IMG4_RUNTIME_DEFAULT (&_img4_runtime_default) |
994 | #else |
995 | #define IMG4_RUNTIME_DEFAULT (img4if->i4if_v7.runtime_default) |
996 | #endif |
997 | |
998 | /*! |
999 | * @const IMG4_RUNTIME_PMAP_CS |
1000 | * The runtime for the xnu pmap layer which is safe to be executed in a |
1001 | * supervisor execution level if supported by hardware. This runtime is not |
1002 | * available outside the kernel-proper. |
1003 | */ |
1004 | #if XNU_KERNEL_PRIVATE |
1005 | #define IMG4_RUNTIME_PMAP_CS (img4if->i4if_v7.runtime_pmap_cs) |
1006 | #elif _DARWIN_BUILDING_TARGET_APPLEIMAGE4 |
1007 | #define IMG4_RUNTIME_PMAP_CS (&_img4_runtime_pmap_cs) |
1008 | #endif |
1009 | |
1010 | /*! |
1011 | * @const IMG4_RUNTIME_RESTORE |
1012 | * The runtime for the restore ramdisk. This runtime is not available outside |
1013 | * of the Darwin userspace library. |
1014 | */ |
1015 | #if !KERNEL |
1016 | IMG4_API_AVAILABLE_20200508 |
1017 | OS_EXPORT |
1018 | const img4_runtime_t _img4_runtime_restore; |
1019 | #define IMG4_RUNTIME_RESTORE (&_img4_runtime_restore) |
1020 | #endif |
1021 | |
1022 | /*! |
1023 | * @function img4_buff_dealloc |
1024 | * Deallocates a buffer according to its deallocation function. |
1025 | * |
1026 | * @param buff |
1027 | * A pointer to the a pointer to the buffer. This parameter may be NULL, in |
1028 | * which case the implementation will return immediately. |
1029 | * |
1030 | * @discussion |
1031 | * This interface will always invoke the deallocation callback with |
1032 | * {@link IMG4_RUNTIME_DEFAULT}. The callee should not consult this parameter |
1033 | * for any reason. |
1034 | */ |
1035 | #if !XNU_KERNEL_PRIVATE |
1036 | IMG4_API_AVAILABLE_20200508 |
1037 | OS_EXPORT |
1038 | void |
1039 | img4_buff_dealloc(img4_buff_t *_Nullable buff); |
1040 | #else |
1041 | #define img4_buff_dealloc(...) (img4if->i4if_v7.buff_dealloc(__VA_ARGS__)) |
1042 | #endif |
1043 | |
1044 | #pragma mark Object Specifications |
1045 | /*! |
1046 | * @const IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT |
1047 | * The DER representation of the certificate to use as the root of trust for |
1048 | * evaluating the supplemental software package. This object can only be |
1049 | * executed once for any given boot session. |
1050 | */ |
1051 | #if !XNU_KERNEL_PRIVATE |
1052 | IMG4_API_AVAILABLE_20210205 |
1053 | OS_EXPORT |
1054 | const img4_runtime_object_spec_t _img4_runtime_object_spec_supplemental_root; |
1055 | #define IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT \ |
1056 | (&_img4_runtime_object_spec_supplemental_root) |
1057 | #else |
1058 | #define IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT \ |
1059 | (img4if->i4if_v11.runtime_object_spec_supplemental_root) |
1060 | #endif |
1061 | |
1062 | /*! |
1063 | * @const IMG4_RUNTIME_OBJECT_SPEC_LOCAL_POLICY |
1064 | * The local policy object which has been authorized by the user for a |
1065 | * subsequent boot of the system. This object may be executed multiple times in |
1066 | * a given boot session. A subsequent local policy must have been authorized by |
1067 | * the user after the currently-active one in order to successfully execute. |
1068 | */ |
1069 | #if !XNU_KERNEL_PRIVATE |
1070 | IMG4_API_AVAILABLE_20210205 |
1071 | OS_EXPORT |
1072 | const img4_runtime_object_spec_t _img4_runtime_object_spec_local_policy; |
1073 | #define IMG4_RUNTIME_OBJECT_SPEC_LOCAL_POLICY \ |
1074 | (&_img4_runtime_object_spec_local_policy) |
1075 | #else |
1076 | #define IMG4_RUNTIME_OBJECT_SPEC_LOCAL_POLICY \ |
1077 | (img4if->i4if_v18.runtime_object_spec_local_policy) |
1078 | #endif |
1079 | |
1080 | #pragma mark API |
1081 | /*! |
1082 | * @function img4_runtime_find_object_spec |
1083 | * Returns the object specification for the given four-character code. |
1084 | * |
1085 | * @param _4cc |
1086 | * The four-character code for which to find the object specification. |
1087 | * |
1088 | * @result |
1089 | * The object specification, or NULL if the four-character code is not an |
1090 | * executable object known to the implementation. |
1091 | */ |
1092 | #if !XNU_KERNEL_PRIVATE |
1093 | IMG4_API_AVAILABLE_20210205 |
1094 | OS_EXPORT OS_WARN_RESULT |
1095 | const img4_runtime_object_spec_t *_Nullable |
1096 | img4_runtime_find_object_spec(img4_4cc_t _4cc); |
1097 | #else |
1098 | #define img4_runtime_find_object_spec(...) \ |
1099 | (img4if->i4if_v11.runtime_find_object_spec(__VA_ARGS__)) |
1100 | #endif |
1101 | |
1102 | /*! |
1103 | * @function img4_runtime_execute_object |
1104 | * Executes an object within the runtime. |
1105 | * |
1106 | * @param rt |
1107 | * The runtime in which to execute the object. |
1108 | * |
1109 | * @param obj_spec |
1110 | * The specification for the object. |
1111 | * |
1112 | * @param obj |
1113 | * The buffer representing the object. The structure and form of the bytes |
1114 | * is dictated by the object specification. Usually, these bytes are a wrapped |
1115 | * Image4 payload. |
1116 | * |
1117 | * @param manifest |
1118 | * The Image4 manifest authenticating the object. If the object has a manifest |
1119 | * stitched to it, this parameter may be NULL. |
1120 | * |
1121 | * @result |
1122 | * Upon success, zero is returned. Otherwise, one of the following error codes: |
1123 | * |
1124 | * [EPERM] The caller does not have permission to set the object |
1125 | * [EALREADY] The object may only be set once, and it has already been set |
1126 | * |
1127 | * Any error code returned by {@link img4_firmware_evaluate} may also be |
1128 | * returned. |
1129 | * |
1130 | * Any error code returned by the runtime's {@link i4rt_execute_object} callback |
1131 | * will also be returned. |
1132 | */ |
1133 | #if !XNU_KERNEL_PRIVATE |
1134 | IMG4_API_AVAILABLE_20210205 |
1135 | OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2 OS_NONNULL3 |
1136 | errno_t |
1137 | img4_runtime_execute_object(const img4_runtime_t *rt, |
1138 | const img4_runtime_object_spec_t *obj_spec, |
1139 | const img4_buff_t *obj, |
1140 | const img4_buff_t *_Nullable manifest); |
1141 | #else |
1142 | #define img4_runtime_execute_object(...) \ |
1143 | (img4if->i4if_v11.runtime_execute_object(__VA_ARGS__)) |
1144 | #endif |
1145 | |
1146 | /*! |
1147 | * @function img4_runtime_copy_object |
1148 | * Copies the payload of an object executed within the runtime. |
1149 | * |
1150 | * @param rt |
1151 | * The runtime in which to query the object. |
1152 | * |
1153 | * @param obj_spec |
1154 | * The specification for the object. |
1155 | * |
1156 | * @param payload |
1157 | * Upon successful return, a pointer to a buffer object which refers to storage |
1158 | * that will hold the payload. |
1159 | * |
1160 | * @param payload_len |
1161 | * Upon successful return, a pointer to the total number of bytes coped into the |
1162 | * buffer referred to by {@link payload}. This parameter may be NULL. |
1163 | * |
1164 | * In the event that buffer referred to be {@link payload} is not large enough, |
1165 | * this parameter will be set to the total number of bytes required. |
1166 | * |
1167 | * @result |
1168 | * Upon success, zero is returned. Otherwise, one of the following error codes: |
1169 | * |
1170 | * [EPERM] The caller does not have permission to copy the object |
1171 | * [ENOENT] The requested object is not present |
1172 | */ |
1173 | #if !XNU_KERNEL_PRIVATE |
1174 | IMG4_API_AVAILABLE_20210205 |
1175 | OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2 OS_NONNULL3 |
1176 | errno_t |
1177 | img4_runtime_copy_object(const img4_runtime_t *rt, |
1178 | const img4_runtime_object_spec_t *obj_spec, |
1179 | img4_buff_t *payload, |
1180 | size_t *_Nullable payload_len); |
1181 | #else |
1182 | #define img4_runtime_copy_object(...) \ |
1183 | (img4if->i4if_v11.runtime_copy_object(__VA_ARGS__)) |
1184 | #endif |
1185 | |
1186 | OS_ASSUME_PTR_ABI_SINGLE_END |
1187 | OS_ASSUME_NONNULL_END |
1188 | __END_DECLS |
1189 | |
1190 | #endif // __IMG4_RUNTIME_H |
1191 | |