1 /*! 2 * @header 3 * Supported chip environments. 4 */ 5 #ifndef __IMG4_CHIP_H 6 #define __IMG4_CHIP_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 * @typedef img4_chip_t 16 * An opaque type describing a destination chip environment for the firmware 17 * image. 18 */ 19 IMG4_API_AVAILABLE_20200508 20 typedef struct _img4_chip img4_chip_t; 21 22 /*! 23 * @typedef img4_chip_select_array_t 24 * A type representing a list of chips from which the implementation may select. 25 */ 26 IMG4_API_AVAILABLE_20200724 27 typedef const img4_chip_t *_Nullable const *img4_chip_select_array_t; 28 29 /*! 30 * @const IMG4_CHIP_INSTANCE_STRUCT_VERSION 31 * The version of the {@link img4_chip_instance_t} supported by the 32 * implementation. 33 */ 34 #define IMG4_CHIP_INSTANCE_STRUCT_VERSION (2u) 35 36 /*! 37 * @typedef img4_chip_instance_omit_t 38 * A bitfield describing omitted identifiers from a chip instance. 39 * 40 * @const IMG4_CHIP_INSTANCE_OMIT_CEPO 41 * The chip instance has no epoch. 42 * 43 * @const IMG4_CHIP_INSTANCE_OMIT_BORD 44 * The chip instance has no board identifier. 45 * 46 * @const IMG4_CHIP_INSTANCE_OMIT_CHIP 47 * The chip instance has no chip identifier. 48 * 49 * @const IMG4_CHIP_INSTANCE_OMIT_SDOM 50 * The chip instance has no security domain. 51 * 52 * @const IMG4_CHIP_INSTANCE_OMIT_ECID 53 * The chip instance has no unique chip identifier. 54 * 55 * @const IMG4_CHIP_INSTANCE_OMIT_CPRO 56 * The chip instance has no certificate production status. 57 * 58 * @const IMG4_CHIP_INSTANCE_OMIT_CSEC 59 * The chip instance has no certificate security mode. 60 * 61 * @const IMG4_CHIP_INSTANCE_OMIT_EPRO 62 * The chip instance has no effective production status. 63 * 64 * @const IMG4_CHIP_INSTANCE_OMIT_ESEC 65 * The chip instance has no effective security mode. 66 * 67 * @const IMG4_CHIP_INSTANCE_OMIT_IUOU 68 * The chip instance has no internal-use-only-unit property. 69 * 70 * @const IMG4_CHIP_INSTANCE_OMIT_RSCH 71 * The chip instance has no research fusing state. 72 * 73 * @const IMG4_CHIP_INSTANCE_OMIT_EUOU 74 * The chip instance has no engineering-use-only-unit property. 75 */ 76 OS_CLOSED_OPTIONS(img4_chip_instance_omit, uint64_t, 77 IMG4_CHIP_INSTANCE_OMIT_CEPO = (1 << 0), 78 IMG4_CHIP_INSTANCE_OMIT_BORD = (1 << 1), 79 IMG4_CHIP_INSTANCE_OMIT_CHIP = (1 << 2), 80 IMG4_CHIP_INSTANCE_OMIT_SDOM = (1 << 3), 81 IMG4_CHIP_INSTANCE_OMIT_ECID = (1 << 4), 82 IMG4_CHIP_INSTANCE_OMIT_CPRO = (1 << 5), 83 IMG4_CHIP_INSTANCE_OMIT_CSEC = (1 << 6), 84 IMG4_CHIP_INSTANCE_OMIT_EPRO = (1 << 7), 85 IMG4_CHIP_INSTANCE_OMIT_ESEC = (1 << 8), 86 IMG4_CHIP_INSTANCE_OMIT_IUOU = (1 << 9), 87 IMG4_CHIP_INSTANCE_OMIT_RSCH = (1 << 10), 88 IMG4_CHIP_INSTANCE_OMIT_EUOU = (1 << 11), 89 ); 90 91 /*! 92 * @typedef img4_chip_instance_t 93 * An structure describing an instance of a chip. 94 * 95 * @field chid_version 96 * The version of the structure. Initialize to 97 * {@link IMG4_CHIP_INSTANCE_STRUCT_VERSION}. 98 * 99 * @field chid_chip_family 100 * The chip family of which this is an instance. 101 * 102 * @field chid_omit 103 * The identifiers which are absent from the chip instance. 104 * 105 * @field chid_cepo 106 * The certificate epoch of the chip instance. 107 * 108 * @field chid_bord 109 * The board identifier of the chip instance. 110 * 111 * @field chid_chip 112 * The chip identifier of the chip instance. 113 * 114 * @field chid_sdom 115 * The security domain of the chip instance. 116 * 117 * @field chid_ecid 118 * The unique chip identifier of the chip instance. 119 * 120 * @field chid_cpro 121 * The certificate production status of the chip instance. 122 * 123 * @field chid_csec 124 * The certificate security mode of the chip instance. 125 * 126 * @field chid_epro 127 * The effective production status of the chip instance. 128 * 129 * @field chid_esec 130 * The effective security mode of the chip instance. 131 * 132 * @field chid_iuou 133 * The internal use-only unit status of the chip instance. 134 * 135 * @field chid_rsch 136 * The research mode of the chip instance. 137 * 138 * @field chid_euou 139 * The engineering use-only unit status of the chip instance. 140 * 141 * Added in version 1 of the structure. 142 */ 143 IMG4_API_AVAILABLE_20200508 144 typedef struct _img4_chip_instance { 145 img4_struct_version_t chid_version; 146 const img4_chip_t *chid_chip_family; 147 img4_chip_instance_omit_t chid_omit; 148 uint32_t chid_cepo; 149 uint32_t chid_bord; 150 uint32_t chid_chip; 151 uint32_t chid_sdom; 152 uint64_t chid_ecid; 153 bool chid_cpro; 154 bool chid_csec; 155 bool chid_epro; 156 bool chid_esec; 157 bool chid_iuou; 158 bool chid_rsch; 159 bool chid_euou; 160 } img4_chip_instance_t; 161 162 /*! 163 * @function IMG4_CHIP_INSTANCE_INIT 164 * A convenience initializer which can be used to initialize a chip instance to 165 * a given family. 166 * 167 * @param _family 168 * The family of chip. 169 * 170 * @result 171 * A fully-initialized structure of the appropriate version supported by the 172 * implementation. The resulting chip instance omits no identifiers. 173 */ 174 #define IMG4_CHIP_INSTANCE_INIT(_family) (img4_chip_instance_t){ \ 175 .chid_version = IMG4_CHIP_INSTANCE_STRUCT_VERSION, \ 176 .chid_chip_family = (_family), \ 177 .chid_omit = 0, \ 178 .chid_cepo = 0, \ 179 .chid_bord = 0, \ 180 .chid_chip = 0, \ 181 .chid_sdom = 0, \ 182 .chid_ecid = 0, \ 183 .chid_cpro = false, \ 184 .chid_csec = false, \ 185 .chid_epro = false, \ 186 .chid_esec = false, \ 187 .chid_iuou = false, \ 188 .chid_rsch = false, \ 189 .chid_euou = false, \ 190 } 191 192 /*! 193 * @const IMG4_CHIP_AP_SHA1 194 * The Application Processor on an Apple ARM SoC with an embedded sha1 195 * certifcate chain. 196 * 197 * This chip environment represents one unique instance of such a chip. 198 */ 199 #if !XNU_KERNEL_PRIVATE 200 IMG4_API_AVAILABLE_20200508 201 OS_EXPORT 202 const img4_chip_t _img4_chip_ap_sha1; 203 #define IMG4_CHIP_AP_SHA1 (&_img4_chip_ap_sha1) 204 #else 205 #define IMG4_CHIP_AP_SHA1 (img4if->i4if_v7.chip_ap_sha1) 206 #endif 207 208 /*! 209 * @const IMG4_CHIP_AP_SHA2_384 210 * The Application Processor on an Apple ARM SoC with an embedded sha2-384 211 * certifcate chain. 212 * 213 * This chip environment represents one unique instance of such a chip. 214 */ 215 #if !XNU_KERNEL_PRIVATE 216 IMG4_API_AVAILABLE_20200508 217 OS_EXPORT 218 const img4_chip_t _img4_chip_ap_sha2_384; 219 #define IMG4_CHIP_AP_SHA2_384 (&_img4_chip_ap_sha2_384) 220 #else 221 #define IMG4_CHIP_AP_SHA2_384 (img4if->i4if_v7.chip_ap_sha2_384) 222 #endif 223 224 /*! 225 * @const IMG4_CHIP_AP_HYBRID 226 * An Intel x86 processor whose chain of trust is rooted in an instance of a 227 * {@link IMG4_CHIP_AP_SHA2_384} chip. Firmwares executed on this chip are 228 * authenticated against the characteristics of the corresponding AP chip 229 * environment and not the characteristics of the x86 processor. 230 * 231 * This chip environment represents one unique instance of such a chip pair. 232 */ 233 #if !XNU_KERNEL_PRIVATE 234 IMG4_API_AVAILABLE_20200508 235 OS_EXPORT 236 const img4_chip_t _img4_chip_ap_hybrid; 237 #define IMG4_CHIP_AP_HYBRID (&_img4_chip_ap_hybrid) 238 #else 239 #define IMG4_CHIP_AP_HYBRID (img4if->i4if_v7.chip_ap_hybrid) 240 #endif 241 242 /*! 243 * @const IMG4_CHIP_AP_REDUCED 244 * An Application Processor on an Apple ARM SoC operating in a reduced security 245 * configuration. 246 * 247 * This chip cannot be uniquely identified. 248 */ 249 #if !XNU_KERNEL_PRIVATE 250 IMG4_API_AVAILABLE_20200508 251 OS_EXPORT 252 const img4_chip_t _img4_chip_ap_reduced; 253 #define IMG4_CHIP_AP_REDUCED (&_img4_chip_ap_reduced) 254 #else 255 #define IMG4_CHIP_AP_REDUCED (img4if->i4if_v7.chip_ap_reduced) 256 #endif 257 258 /*! 259 * @const IMG4_CHIP_AP_PERMISSIVE 260 * An Application Processor on an Apple ARM SoC operating with no secure boot 261 * enforcement. 262 * 263 * This chip's identity is rooted in a device-specific authority rather than one 264 * maintained by Apple. 265 */ 266 #if !XNU_KERNEL_PRIVATE 267 IMG4_API_AVAILABLE_20200508 268 OS_EXPORT 269 const img4_chip_t _img4_chip_ap_permissive; 270 #define IMG4_CHIP_AP_PERMISSIVE (&_img4_chip_ap_permissive) 271 #else 272 #define IMG4_CHIP_AP_PERMISSIVE (img4if->i4if_v8.chip_ap_permissive) 273 #endif 274 275 /*! 276 * @const IMG4_CHIP_AP_HYBRID_MEDIUM 277 * An Intel x86 processor whose chain of trust is rooted in an instance of a 278 * {@link IMG4_CHIP_AP_SHA2_384} chip and is operating in a "medium security" 279 * mode due to a user-approved security degradation. 280 * 281 * This chip cannot be uniquely identified. 282 */ 283 #if !XNU_KERNEL_PRIVATE 284 IMG4_API_AVAILABLE_20200508 285 OS_EXPORT 286 const img4_chip_t _img4_chip_ap_hybrid_medium; 287 #define IMG4_CHIP_AP_HYBRID_MEDIUM (&_img4_chip_ap_hybrid_medium) 288 #else 289 #define IMG4_CHIP_AP_HYBRID_MEDIUM (img4if->i4if_v8.chip_ap_hybrid_medium) 290 #endif 291 292 /*! 293 * @const IMG4_CHIP_AP_HYBRID_RELAXED 294 * An Intel x86 processor whose chain of trust is rooted in an instance of a 295 * {@link IMG4_CHIP_AP_SHA2_384} chip and is operating with no secure boot 296 * due to a user-approved security degradation. 297 * 298 * This chip cannot be uniquely identified. 299 */ 300 #if !XNU_KERNEL_PRIVATE 301 IMG4_API_AVAILABLE_20200508 302 OS_EXPORT 303 const img4_chip_t _img4_chip_ap_hybrid_relaxed; 304 #define IMG4_CHIP_AP_HYBRID_RELAXED (&_img4_chip_ap_hybrid_relaxed) 305 #else 306 #define IMG4_CHIP_AP_HYBRID_RELAXED (img4if->i4if_v8.chip_ap_hybrid_relaxed) 307 #endif 308 309 /*! 310 * @const IMG4_CHIP_AP_SOFTWARE_FF00 311 * A software-defined chip environment whose firmwares are executed on any 312 * Application Processor on an Apple ARM SoC. The firmwares are loadable trust 313 * caches shipped with OTA update brains. 314 * 315 * This chip cannot be uniquely identified. 316 */ 317 #if !XNU_KERNEL_PRIVATE 318 IMG4_API_AVAILABLE_20200508 319 OS_EXPORT 320 const img4_chip_t _img4_chip_ap_software_ff00; 321 #define IMG4_CHIP_AP_SOFTWARE_FF00 (&_img4_chip_ap_software_ff00) 322 #else 323 #define IMG4_CHIP_AP_SOFTWARE_FF00 (img4if->i4if_v7.chip_ap_software_ff00) 324 #endif 325 326 /*! 327 * @const IMG4_CHIP_AP_SOFTWARE_FF01 328 * A software-defined chip environment whose firmwares are executed on any 329 * Application Processor on an Apple ARM SoC. The firmwares are loadable trust 330 * caches which are shipped in the Install Assistant and loaded by an 331 * unprivileged trampoline. 332 * 333 * This chip cannot be uniquely identified. 334 */ 335 #if !XNU_KERNEL_PRIVATE 336 IMG4_API_AVAILABLE_20200508 337 OS_EXPORT 338 const img4_chip_t _img4_chip_ap_software_ff01; 339 #define IMG4_CHIP_AP_SOFTWARE_FF01 (&_img4_chip_ap_software_ff01) 340 #else 341 #define IMG4_CHIP_AP_SOFTWARE_FF01 (img4if->i4if_v7.chip_ap_software_ff01) 342 #endif 343 344 /*! 345 * @const IMG4_CHIP_AP_CATEGORY_FF02 346 * The Application Processor on an Intel Mac product. 347 * 348 * This chip environment represents one unique instance of such a chip, though 349 * the uniqueness is not enforced by a secure boot chain with anti-replay 350 * properties, and therefore this chip environment should be considered as 351 * equivalent to a global signing environment. 352 */ 353 #if !XNU_KERNEL_PRIVATE 354 IMG4_API_AVAILABLE_20210305 355 OS_EXPORT 356 const img4_chip_t _img4_chip_ap_category_ff02; 357 #define IMG4_CHIP_AP_CATEGORY_FF02 (&_img4_chip_ap_category_ff02) 358 #else 359 #define IMG4_CHIP_AP_CATEGORY_FF02 (img4if->i4if_v12.chip_ap_category_ff02) 360 #endif 361 362 /*! 363 * @const IMG4_CHIP_AP_CATEGORY_FF03 364 * An Intel x86 processor whose chain of trust is rooted in an instance of a 365 * {@link IMG4_CHIP_AP_SHA2_384} chip. 366 * 367 * This chip environment represents one unique instance of such a chip pair. 368 */ 369 #if !XNU_KERNEL_PRIVATE 370 IMG4_API_AVAILABLE_20210305 371 OS_EXPORT 372 const img4_chip_t _img4_chip_ap_category_ff03; 373 #define IMG4_CHIP_AP_CATEGORY_FF03 (&_img4_chip_ap_category_ff03) 374 #else 375 #define IMG4_CHIP_AP_CATEGORY_FF03 (img4if->i4if_v12.chip_ap_category_ff03) 376 #endif 377 378 /*! 379 * @const IMG4_CHIP_AP_CATEGORY_FF04_F0 380 * The Application Processor of an Apple ARM SoC in an Apple Silicon Mac 381 * product. 382 * 383 * This chip environment represents one unique instance of such a chip. 384 */ 385 #if !XNU_KERNEL_PRIVATE 386 IMG4_API_AVAILABLE_20210305 387 OS_EXPORT 388 const img4_chip_t _img4_chip_ap_category_ff04_f0; 389 #define IMG4_CHIP_AP_CATEGORY_FF04_F0 (&_img4_chip_ap_category_ff04_f0) 390 #else 391 #define IMG4_CHIP_AP_CATEGORY_FF04_F0 \ 392 (img4if->i4if_v12.chip_ap_category_ff04_f0) 393 #endif 394 395 /*! 396 * @const IMG4_CHIP_AP_CATEGORY_FF04_F1 397 * The Application Processor of an Apple ARM SoC in an iPhone, iPad, or iPod 398 * touch product. 399 * 400 * This chip environment represents one unique instance of such a chip. 401 */ 402 #if !XNU_KERNEL_PRIVATE 403 IMG4_API_AVAILABLE_20210305 404 OS_EXPORT 405 const img4_chip_t _img4_chip_ap_category_ff04_f1; 406 #define IMG4_CHIP_AP_CATEGORY_FF04_F1 (&_img4_chip_ap_category_ff04_f1) 407 #else 408 #define IMG4_CHIP_AP_CATEGORY_FF04_F1 \ 409 (img4if->i4if_v12.chip_ap_category_ff04_f1) 410 #endif 411 412 /*! 413 * @const IMG4_CHIP_AP_CATEGORY_FF04_F2 414 * The Application Processor of an Apple ARM SoC in an watch product. 415 * 416 * This chip environment represents one unique instance of such a chip. 417 */ 418 #if !XNU_KERNEL_PRIVATE 419 IMG4_API_AVAILABLE_20210305 420 OS_EXPORT 421 const img4_chip_t _img4_chip_ap_category_ff04_f2; 422 #define IMG4_CHIP_AP_CATEGORY_FF04_F2 (&_img4_chip_ap_category_ff04_f2) 423 #else 424 #define IMG4_CHIP_AP_CATEGORY_FF04_F2 \ 425 (img4if->i4if_v12.chip_ap_category_ff04_f2) 426 #endif 427 428 /*! 429 * @const IMG4_CHIP_AP_CATEGORY_FF04_F3 430 * The Application Processor of an Apple ARM SoC in an tv or HomePod product. 431 * 432 * This chip environment represents one unique instance of such a chip. 433 */ 434 #if !XNU_KERNEL_PRIVATE 435 IMG4_API_AVAILABLE_20210305 436 OS_EXPORT 437 const img4_chip_t _img4_chip_ap_category_ff04_f3; 438 #define IMG4_CHIP_AP_CATEGORY_FF04_F3 (&_img4_chip_ap_category_ff04_f3) 439 #else 440 #define IMG4_CHIP_AP_CATEGORY_FF04_F3 \ 441 (img4if->i4if_v12.chip_ap_category_ff04_f3) 442 #endif 443 444 /*! 445 * @const IMG4_CHIP_AP_SOFTWARE_FF06 446 * A software-defined chip environment whose firmwares are executed on any 447 * Application Processor on an Apple ARM SoC. The firmwares are loadable trust 448 * caches which are shipped in the preboot volume. 449 * 450 * This chip cannot be uniquely identified. 451 */ 452 #if !XNU_KERNEL_PRIVATE 453 IMG4_API_AVAILABLE_20210113 454 OS_EXPORT 455 const img4_chip_t _img4_chip_ap_software_ff06; 456 #define IMG4_CHIP_AP_SOFTWARE_FF06 (&_img4_chip_ap_software_ff06) 457 #else 458 #define IMG4_CHIP_AP_SOFTWARE_FF06 (img4if->i4if_v11.chip_ap_software_ff06) 459 #endif 460 461 /*! 462 * @const IMG4_CHIP_X86 463 * An Intel x86 processor which cannot be uniquely identified. 464 */ 465 #if !XNU_KERNEL_PRIVATE 466 IMG4_API_AVAILABLE_20200508 467 OS_EXPORT 468 const img4_chip_t _img4_chip_x86; 469 #define IMG4_CHIP_X86 (&_img4_chip_x86) 470 #else 471 #define IMG4_CHIP_X86 (img4if->i4if_v7.chip_x86) 472 #endif 473 474 /*! 475 * @const IMG4_CHIP_X86_SOFTWARE_8012 476 * A software-defined chip environment describing a virtualized x86 processor. 477 * Since the virtual machine is at the mercy of the VM, support for any sort of 478 * chip identity may not be available. Therefore this environment is returned 479 * from {@link img4_chip_select_personalized_ap} and 480 * {@link img4_chip_select_effective_ap} when it is called on a virtual machine 481 * so that the appropriate chip environment is present entirely in software. 482 * 483 * This environment provides an equivalent software identity to that of 484 * the {@link IMG4_CHIP_X86} chip environment on non-Gibraltar Macs. 485 * 486 * @discussion 487 * Do not use this environment directly. 488 */ 489 #if !XNU_KERNEL_PRIVATE 490 IMG4_API_AVAILABLE_20200508 491 OS_EXPORT 492 const img4_chip_t _img4_chip_x86_software_8012; 493 #define IMG4_CHIP_X86_SOFTWARE_8012 (&_img4_chip_x86_software_8012) 494 #else 495 #define IMG4_CHIP_X86_SOFTWARE_8012 (img4if->i4if_v7.chip_x86_software_8012) 496 #endif 497 498 /*! 499 * @const IMG4_CHIP_AP_INTRANSIGENT 500 * An Application Processor which is incapable of executing code. This chip 501 * environment's root of trust is a certificate authority which has never and 502 * will never issue any certificates. 503 */ 504 #if !XNU_KERNEL_PRIVATE 505 IMG4_API_AVAILABLE_20210113 506 OS_EXPORT 507 const img4_chip_t _img4_chip_ap_intransigent; 508 #define IMG4_CHIP_AP_INTRANSIGENT (&_img4_chip_ap_intransigent) 509 #else 510 #define IMG4_CHIP_AP_INTRANSIGENT (img4if->i4if_v11.chip_ap_intransigent) 511 #endif 512 513 /*! 514 * @const IMG4_CHIP_AP_SUPPLEMENTAL 515 * An Application Processor whose root of trust resides in the 516 * {@link IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT} object. Once the 517 * supplemental root object is executed on the host's AP, this chip environment 518 * is available to execute payloads. 519 */ 520 #if !XNU_KERNEL_PRIVATE 521 IMG4_API_AVAILABLE_20210113 522 OS_EXPORT 523 const img4_chip_t _img4_chip_ap_supplemental; 524 #define IMG4_CHIP_AP_SUPPLEMENTAL (&_img4_chip_ap_supplemental) 525 #else 526 #define IMG4_CHIP_AP_SUPPLEMENTAL (img4if->i4if_v11.chip_ap_supplemental) 527 #endif 528 529 /*! 530 * @const IMG4_CHIP_AP_VMA2 531 * The Application Processor of a virtualized Apple ARM device. 532 * 533 * This chip environment represents one unique instance of such a chip on the 534 * host device. 535 */ 536 #if !XNU_KERNEL_PRIVATE 537 IMG4_API_AVAILABLE_20210113 538 OS_EXPORT 539 const img4_chip_t _img4_chip_ap_vma2; 540 #define IMG4_CHIP_AP_VMA2 (&_img4_chip_ap_vma2) 541 #else 542 #define IMG4_CHIP_AP_VMA2 (img4if->i4if_v13.chip_ap_vma2) 543 #endif 544 545 /*! 546 * @const IMG4_CHIP_AP_VMA2_CLONE 547 * The Application Processor of a virtualized Apple ARM device which has been 548 * cloned from another on the same host. 549 * 550 * This chip environment cannot be uniquely identified. 551 */ 552 #if !XNU_KERNEL_PRIVATE 553 IMG4_API_AVAILABLE_20210113 554 OS_EXPORT 555 const img4_chip_t _img4_chip_ap_vma2_clone; 556 #define IMG4_CHIP_AP_VMA2_CLONE (&_img4_chip_ap_vma2_clone) 557 #else 558 #define IMG4_CHIP_AP_VMA2_CLONE (img4if->i4if_v13.chip_ap_vma2_clone) 559 #endif 560 561 /*! 562 * @function img4_chip_init_from_buff 563 * Initializes a buffer as a chip object. 564 * 565 * @param buff 566 * A pointer to the storage to use for the chip object. 567 * 568 * @param len 569 * The size of the buffer. 570 * 571 * @discussion 572 * The caller is expected to pass a buffer that is "big enough". If the provided 573 * buffer is too small, the implementation will abort the caller. 574 * 575 * @example 576 * 577 * uint8_t _buff[IMG4_CHIP_SIZE_RECOMMENDED]; 578 * img4_chip_t *chip = NULL; 579 * 580 * chip = img4_chip_init_from_buff(_buff, sizeof(_buff)); 581 */ 582 #if !XNU_KERNEL_PRIVATE 583 IMG4_API_AVAILABLE_20200508 584 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 585 img4_chip_t * 586 img4_chip_init_from_buff(void *buff, size_t len); 587 #else 588 #define img4_chip_init_from_buff (img4if->i4if_v7.chip_init_from_buff) 589 #endif 590 591 /*! 592 * @function img4_chip_select_personalized_ap 593 * Returns the chip appropriate for personalized verification against the host 594 * AP. 595 * 596 * @result 597 * The personalized chip environment for the host which corresponds to its 598 * silicon identity. 599 */ 600 #if !XNU_KERNEL_PRIVATE 601 IMG4_API_AVAILABLE_20200508 602 OS_EXPORT OS_WARN_RESULT 603 const img4_chip_t * 604 img4_chip_select_personalized_ap(void); 605 #else 606 #define img4_chip_select_personalized_ap(...) \ 607 (img4if->i4if_v7.chip_select_personalized_ap(__VA_ARGS__)) 608 #endif 609 610 /*! 611 * @function img4_chip_select_categorized_ap 612 * Returns the chip appropriate for categorized verification against the host 613 * AP. 614 * 615 * @result 616 * The categorized chip environment for the host which corresponds to its 617 * silicon identity. If the host has no AP category defined for it, NULL will be 618 * returned. 619 */ 620 #if !XNU_KERNEL_PRIVATE 621 IMG4_API_AVAILABLE_20210305 622 OS_EXPORT OS_WARN_RESULT 623 const img4_chip_t *_Nullable 624 img4_chip_select_categorized_ap(void); 625 #else 626 #define img4_chip_select_categorized_ap(...) \ 627 (img4if->i4if_v12.chip_select_categorized_ap(__VA_ARGS__)) 628 #endif 629 630 /*! 631 * @function img4_chip_select_effective_ap 632 * Returns the chip appropriate for verification against the host AP. 633 * 634 * @result 635 * The currently enforced chip environment for the host. This interface is 636 * generally only useful on the AP. 637 */ 638 #if !XNU_KERNEL_PRIVATE 639 IMG4_API_AVAILABLE_20200508 640 OS_EXPORT OS_WARN_RESULT 641 const img4_chip_t * 642 img4_chip_select_effective_ap(void); 643 #else 644 #define img4_chip_select_effective_ap(...) \ 645 (img4if->i4if_v7.chip_select_effective_ap(__VA_ARGS__)) 646 #endif 647 648 /*! 649 * @function img4_chip_instantiate 650 * Returns an instantiation of the given chip using the default runtime where 651 * necessary. 652 * 653 * @param chip 654 * The chip to instantiate. 655 * 656 * @param chip_instance 657 * Upon successful return, storage to be populated with the instantiated chip. 658 * Upon failure, the contents of this storage are undefined. 659 * 660 * @result 661 * Upon success, zero is returned. Otherwise, one of the following error codes 662 * will be returned: 663 * 664 * [EXDEV] There was an error querying the runtime's identity oracle 665 * [ENODATA] The expected property in the runtime's identity oracle was 666 * of an unexpected type 667 * [EOVERFLOW] The expected property in the runtime's identity oracle had 668 * a value that was too large to be represented in the 669 * expected type 670 */ 671 #if !XNU_KERNEL_PRIVATE 672 IMG4_API_AVAILABLE_20200508 673 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2 674 errno_t 675 img4_chip_instantiate(const img4_chip_t *chip, 676 img4_chip_instance_t *chip_instance); 677 #else 678 #define img4_chip_instantiate(...) \ 679 (img4if->i4if_v7.chip_instantiate(__VA_ARGS__)) 680 #endif 681 682 /*! 683 * @function img4_chip_custom 684 * Returns a custom chip derived from the given chip instance. The 685 * {@link chid_chip_family} field of the given instance will be used as a 686 * template from which to derive the new chip. 687 * 688 * @param chip_instance 689 * The instance of the custom chip. 690 * 691 * The memory referenced by this pointer must be static or otherwise guaranteed 692 * to be valid for the duration of the caller's use of the custom chip. 693 * 694 * @param chip 695 * A pointer to storage for the new custom chip. 696 * 697 * The memory referenced by this pointer must be static or otherwise guaranteed 698 * to be valid for the duration of the caller's use of the custom chip. 699 * 700 * This pointer should be obtained as the result of a call to 701 * {@link img4_chip_init_from_buff}. 702 * 703 * @result 704 * A new custom chip. 705 */ 706 #if !XNU_KERNEL_PRIVATE 707 IMG4_API_AVAILABLE_20200508 708 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 709 const img4_chip_t * 710 img4_chip_custom(const img4_chip_instance_t *chip_instance, img4_chip_t *chip); 711 #else 712 #define img4_chip_custom(...) (img4if->i4if_v7.chip_custom(__VA_ARGS__)) 713 #endif 714 715 OS_ASSUME_NONNULL_END 716 717 #endif // __IMG4_CHIP_H 718