[apple/xnu.git] / EXTERNAL_HEADERS / img4 / chip.h

/*!
 * @header
 * Supported chip environments.
 */
#ifndef __IMG4_CHIP_H
#define __IMG4_CHIP_H

#ifndef __IMG4_INDIRECT
#error "Please #include <img4/firmware.h> instead of this file directly"
#endif // __IMG4_INDIRECT

#if IMG4_TAPI
#include "tapi.h"
#endif

OS_ASSUME_NONNULL_BEGIN

/*!
 * @typedef img4_chip_t
 * An opaque type describing a destination chip environment for the firmware
 * image.
 */
IMG4_API_AVAILABLE_20200508
typedef struct _img4_chip img4_chip_t;

/*!
 * @typedef img4_chip_select_array_t
 * A type representing a list of chips from which the implementation may select.
 */
IMG4_API_AVAILABLE_20200724
typedef const img4_chip_t *_Nullable const *img4_chip_select_array_t;

/*!
 * @const IMG4_CHIP_INSTANCE_STRUCT_VERSION
 * The version of the {@link img4_chip_instance_t} supported by the
 * implementation.
 */
#define IMG4_CHIP_INSTANCE_STRUCT_VERSION (1u)

/*!
 * @typedef img4_chip_instance_omit_t
 * A bitfield describing omitted identifiers from a chip instance.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_CEPO
 * The chip instance has no epoch.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_BORD
 * The chip instance has no board identifier.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_CHIP
 * The chip instance has no chip identifier.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_SDOM
 * The chip instance has no security domain.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_ECID
 * The chip instance has no unique chip identifier.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_CPRO
 * The chip instance has no certificate production status.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_CSEC
 * The chip instance has no certificate security mode.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_EPRO
 * The chip instance has no effective production status.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_ESEC
 * The chip instance has no effective security mode.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_IUOU
 * The chip instance has no internal-use-only-unit property.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_RSCH
 * The chip instance has no research fusing state.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_EUOU
 * The chip instance has no engineering-use-only-unit property.
 */
OS_CLOSED_OPTIONS(img4_chip_instance_omit, uint64_t,
	IMG4_CHIP_INSTANCE_OMIT_CEPO = (1 << 0),
	IMG4_CHIP_INSTANCE_OMIT_BORD = (1 << 1),
	IMG4_CHIP_INSTANCE_OMIT_CHIP = (1 << 2),
	IMG4_CHIP_INSTANCE_OMIT_SDOM = (1 << 3),
	IMG4_CHIP_INSTANCE_OMIT_ECID = (1 << 4),
	IMG4_CHIP_INSTANCE_OMIT_CPRO = (1 << 5),
	IMG4_CHIP_INSTANCE_OMIT_CSEC = (1 << 6),
	IMG4_CHIP_INSTANCE_OMIT_EPRO = (1 << 7),
	IMG4_CHIP_INSTANCE_OMIT_ESEC = (1 << 8),
	IMG4_CHIP_INSTANCE_OMIT_IUOU = (1 << 9),
	IMG4_CHIP_INSTANCE_OMIT_RSCH = (1 << 10),
	IMG4_CHIP_INSTANCE_OMIT_EUOU = (1 << 11),
);

/*!
 * @typedef img4_chip_instance_t
 * An structure describing an instance of a chip.
 *
 * @field chid_version
 * The version of the structure. Initialize to
 * {@link IMG4_CHIP_INSTANCE_STRUCT_VERSION}.
 *
 * @field chid_chip_family
 * The chip family of which this is an instance.
 *
 * @field chid_omit
 * The identifiers which are absent from the chip instance.
 *
 * @field chid_cepo
 * The certificate epoch of the chip instance.
 *
 * @field chid_bord
 * The board identifier of the chip instance.
 *
 * @field chid_chip
 * The chip identifier of the chip instance.
 *
 * @field chid_sdom
 * The security domain of the chip instance.
 *
 * @field chid_ecid
 * The unique chip identifier of the chip instance.
 *
 * @field chid_cpro
 * The certificate production status of the chip instance.
 *
 * @field chid_csec
 * The certificate security mode of the chip instance.
 *
 * @field chid_epro
 * The effective production status of the chip instance.
 *
 * @field chid_esec
 * The effective security mode of the chip instance.
 *
 * @field chid_iuou
 * The internal use-only unit status of the chip instance.
 *
 * @field chid_rsch
 * The research mode of the chip instance.
 *
 * @field chid_euou
 * The engineering use-only unit status of the chip instance.
 *
 * Added in version 1 of the structure.
 */
IMG4_API_AVAILABLE_20200508
typedef struct _img4_chip_instance {
	img4_struct_version_t chid_version;
	const img4_chip_t *chid_chip_family;
	img4_chip_instance_omit_t chid_omit;
	uint32_t chid_cepo;
	uint32_t chid_bord;
	uint32_t chid_chip;
	uint32_t chid_sdom;
	uint64_t chid_ecid;
	bool chid_cpro;
	bool chid_csec;
	bool chid_epro;
	bool chid_esec;
	bool chid_iuou;
	bool chid_rsch;
	bool chid_euou;
} img4_chip_instance_t;

/*!
 * @const IMG4_CHIP_AP_SHA1
 * The Application Processor on an Apple ARM SoC with an embedded sha1
 * certifcate chain.
 *
 * This chip environment represents one unique instance of such a chip.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_ap_sha1;
#define IMG4_CHIP_AP_SHA1 (&_img4_chip_ap_sha1)
#else
#define IMG4_CHIP_AP_SHA1 (img4if->i4if_v7.chip_ap_sha1)
#endif

/*!
 * @const IMG4_CHIP_AP_SHA2_384
 * The Application Processor on an Apple ARM SoC with an embedded sha2-384
 * certifcate chain.
 *
 * This chip environment represents one unique instance of such a chip.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_ap_sha2_384;
#define IMG4_CHIP_AP_SHA2_384 (&_img4_chip_ap_sha2_384)
#else
#define IMG4_CHIP_AP_SHA2_384 (img4if->i4if_v7.chip_ap_sha2_384)
#endif

/*!
 * @const IMG4_CHIP_AP_HYBRID
 * An Intel x86 processor whose chain of trust is rooted in an
 * {@link IMG4_CHIP_AP_SHA2_384} environment. Firmwares executed on this chip
 * are authenticated against the characteristics of the corresponding AP chip
 * environment.
 *
 * This chip environment represents one unique instance of such a chip pair.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_ap_hybrid;
#define IMG4_CHIP_AP_HYBRID (&_img4_chip_ap_hybrid)
#else
#define IMG4_CHIP_AP_HYBRID (img4if->i4if_v7.chip_ap_hybrid)
#endif

/*!
 * @const IMG4_CHIP_AP_REDUCED
 * An Application Processor on an Apple ARM SoC operating in a reduced security
 * configuration.
 *
 * This chip cannot be uniquely identified.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_ap_reduced;
#define IMG4_CHIP_AP_REDUCED (&_img4_chip_ap_reduced)
#else
#define IMG4_CHIP_AP_REDUCED (img4if->i4if_v7.chip_ap_reduced)
#endif

/*!
 * @const IMG4_CHIP_AP_PERMISSIVE
 * An Application Processor on an Apple ARM SoC operating with no secure boot
 * enforcement.
 *
 * This chip cannot be uniquely identified.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_ap_permissive;
#define IMG4_CHIP_AP_PERMISSIVE (&_img4_chip_ap_permissive)
#else
#define IMG4_CHIP_AP_PERMISSIVE (img4if->i4if_v8.chip_ap_permissive)
#endif

/*!
 * @const IMG4_CHIP_AP_HYBRID_MEDIUM
 * An Intel x86 processor whose chain of trust is rooted in an
 * {@link IMG4_CHIP_AP_SHA2_384} environment and is operating in a "medium
 * security" mode due to a user-approved security degradation.
 *
 * This chip cannot be uniquely identified.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_ap_hybrid_medium;
#define IMG4_CHIP_AP_HYBRID_MEDIUM (&_img4_chip_ap_hybrid_medium)
#else
#define IMG4_CHIP_AP_HYBRID_MEDIUM (img4if->i4if_v8.chip_ap_hybrid_medium)
#endif

/*!
 * @const IMG4_CHIP_AP_HYBRID_RELAXED
 * An Intel x86 processor whose chain of trust is rooted in an
 * {@link IMG4_CHIP_AP_SHA2_384} environment and is operating with no secure
 * boot enforcement due to a user-approved security degradation.
 *
 * This chip cannot be uniquely identified.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_ap_hybrid_relaxed;
#define IMG4_CHIP_AP_HYBRID_RELAXED (&_img4_chip_ap_hybrid_relaxed)
#else
#define IMG4_CHIP_AP_HYBRID_RELAXED (img4if->i4if_v8.chip_ap_hybrid_relaxed)
#endif

/*!
 * @const IMG4_CHIP_AP_SOFTWARE_FF00
 * A software-defined chip environment whose firmwares are executed on any
 * Application Processor on an Apple ARM SoC. The firmwares are loadable trust
 * caches shipped with OTA update brains.
 *
 * This chip cannot be uniquely identified.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_ap_software_ff00;
#define IMG4_CHIP_AP_SOFTWARE_FF00 (&_img4_chip_ap_software_ff00)
#else
#define IMG4_CHIP_AP_SOFTWARE_FF00 (img4if->i4if_v7.chip_ap_software_ff00)
#endif

/*!
 * @const IMG4_CHIP_AP_SOFTWARE_FF01
 * A software-defined chip environment whose firmwares are executed on any
 * Application Processor on an Apple ARM SoC. The firmwares are loadable trust
 * caches which are shipped in the Install Assistant and loaded by an
 * unprivileged trampoline.
 *
 * This chip cannot be uniquely identified.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_ap_software_ff01;
#define IMG4_CHIP_AP_SOFTWARE_FF01 (&_img4_chip_ap_software_ff01)
#else
#define IMG4_CHIP_AP_SOFTWARE_FF01 (img4if->i4if_v7.chip_ap_software_ff01)
#endif

/*!
 * @const IMG4_CHIP_X86
 * An Intel x86 processor which cannot be uniquely identified.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_x86;
#define IMG4_CHIP_X86 (&_img4_chip_x86)
#else
#define IMG4_CHIP_X86 (img4if->i4if_v7.chip_x86)
#endif

/*!
 * @const IMG4_CHIP_X86_SOFTWARE_8012
 * A software-defined chip environment describing a virtualized x86 processor.
 * Since the virtual machine is at the mercy of the VM, support for any sort of
 * chip identity may not be available. Therefore this environment is returned
 * from {@link img4_chip_select_personalized_ap} and
 * {@link img4_chip_select_effective_ap} when it is called on a virtual machine
 * so that the appropriate chip environment is present entirely in software.
 *
 * This environment provides an equivalent software identity to that of
 * the {@link IMG4_CHIP_X86} chip environment on non-Gibraltar Macs.
 *
 * @discussion
 * Do not use this environment directly.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_chip_t _img4_chip_x86_software_8012;
#define IMG4_CHIP_X86_SOFTWARE_8012 (&_img4_chip_x86_software_8012)
#else
#define IMG4_CHIP_X86_SOFTWARE_8012 (img4if->i4if_v7.chip_x86_software_8012)
#endif

/*!
 * @function img4_chip_init_from_buff
 * Initializes a buffer as a chip object.
 *
 * @param buff
 * A pointer to the storage to use for the chip object.
 *
 * @param len
 * The size of the buffer.
 *
 * @discussion
 * The caller is expected to pass a buffer that is "big enough". If the provided
 * buffer is too small, the implementation will abort the caller.
 *
 * @example
 *
 *     uint8_t _buff[IMG4_CHIP_SIZE_RECOMMENDED];
 *     img4_chip_t *chip = NULL;
 *
 *     chip = img4_chip_init_from_buff(_buff, sizeof(_buff));
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT OS_NONNULL1
img4_chip_t *
img4_chip_init_from_buff(void *buff, size_t len);
#else
#define img4_chip_init_from_buff (img4if->i4if_v7.chip_init_from_buff)
#endif

/*!
 * @function img4_chip_select_personalized_ap
 * Returns the chip appropriate for personalized verification against the host
 * AP.
 *
 * @result
 * The personalized chip environment for the host which corresponds to its
 * silicon identity.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT
const img4_chip_t *
img4_chip_select_personalized_ap(void);
#else
#define img4_chip_select_personalized_ap(...) \
		(img4if->i4if_v7.chip_select_personalized_ap(__VA_ARGS__))
#endif

/*!
 * @function img4_chip_select_effective_ap
 * Returns the chip appropriate for verification against the host AP.
 *
 * @result
 * The currently enforced chip environment for the host. This interface is
 * generally only useful on the AP.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT
const img4_chip_t *
img4_chip_select_effective_ap(void);
#else
#define img4_chip_select_effective_ap(...) \
		(img4if->i4if_v7.chip_select_effective_ap(__VA_ARGS__))
#endif

/*!
 * @function img4_chip_instantiate
 * Returns an instantiation of the given chip using the default runtime where
 * necessary.
 *
 * @param chip
 * The chip to instantiate.
 *
 * @param chip_instance
 * Upon successful return, storage to be populated with the instantiated chip.
 * Upon failure, the contents of this storage are undefined.
 *
 * @result
 * Upon success, zero is returned. Otherwise, one of the following error codes
 * will be returned:
 *
 *     [EXDEV]       There was an error querying the runtime's identity oracle
 *     [ENODATA]     The expected property in the runtime's identity oracle was
 *                   of an unexpected type
 *     [EOVERFLOW]   The expected property in the runtime's identity oracle had
 *                   a value that was too large to be represented in the
 *                   expected type
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
errno_t
img4_chip_instantiate(const img4_chip_t *chip,
		img4_chip_instance_t *chip_instance);
#else
#define img4_chip_instantiate(...) \
		(img4if->i4if_v7.chip_instantiate(__VA_ARGS__))
#endif

/*!
 * @function img4_chip_custom
 * Returns a custom chip derived from the given chip instance. The
 * {@link chid_chip_family} field of the given instance will be used as a
 * template from which to derive the new chip.
 *
 * @param chip_instance
 * The instance of the custom chip.
 *
 * The memory referenced by this pointer must be static or otherwise guaranteed
 * to be valid for the duration of the caller's use of the custom chip.
 *
 * @param chip
 * A pointer to storage for the new custom chip.
 *
 * The memory referenced by this pointer must be static or otherwise guaranteed
 * to be valid for the duration of the caller's use of the custom chip.
 *
 * This pointer should be obtained as the result of a call to
 * {@link img4_chip_init_from_buff}.
 *
 * @result
 * A new custom chip.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT OS_NONNULL1
const img4_chip_t *
img4_chip_custom(const img4_chip_instance_t *chip_instance, img4_chip_t *chip);
#else
#define img4_chip_custom(...) (img4if->i4if_v7.chip_custom(__VA_ARGS__))
#endif

OS_ASSUME_NONNULL_END

#endif // __IMG4_CHIP_H
Commit	Line	Data
f427ee49 A	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	#if IMG4_TAPI
	13	#include "tapi.h"
	14	#endif
	15
	16	OS_ASSUME_NONNULL_BEGIN
	17
	18	/*!
	19	* @typedef img4_chip_t
	20	* An opaque type describing a destination chip environment for the firmware
	21	* image.
	22	*/
	23	IMG4_API_AVAILABLE_20200508
	24	typedef struct _img4_chip img4_chip_t;
	25
	26	/*!
	27	* @typedef img4_chip_select_array_t
	28	* A type representing a list of chips from which the implementation may select.
	29	*/
	30	IMG4_API_AVAILABLE_20200724
	31	typedef const img4_chip_t _Nullable const img4_chip_select_array_t;
	32
	33	/*!
	34	* @const IMG4_CHIP_INSTANCE_STRUCT_VERSION
	35	* The version of the {@link img4_chip_instance_t} supported by the
	36	* implementation.
	37	*/
	38	#define IMG4_CHIP_INSTANCE_STRUCT_VERSION (1u)
	39
	40	/*!
	41	* @typedef img4_chip_instance_omit_t
	42	* A bitfield describing omitted identifiers from a chip instance.
	43	*
	44	* @const IMG4_CHIP_INSTANCE_OMIT_CEPO
	45	* The chip instance has no epoch.
	46	*
	47	* @const IMG4_CHIP_INSTANCE_OMIT_BORD
	48	* The chip instance has no board identifier.
	49	*
	50	* @const IMG4_CHIP_INSTANCE_OMIT_CHIP
	51	* The chip instance has no chip identifier.
	52	*
	53	* @const IMG4_CHIP_INSTANCE_OMIT_SDOM
	54	* The chip instance has no security domain.
	55	*
	56	* @const IMG4_CHIP_INSTANCE_OMIT_ECID
	57	* The chip instance has no unique chip identifier.
	58	*
	59	* @const IMG4_CHIP_INSTANCE_OMIT_CPRO
	60	* The chip instance has no certificate production status.
	61	*
	62	* @const IMG4_CHIP_INSTANCE_OMIT_CSEC
	63	* The chip instance has no certificate security mode.
	64	*
65	* @const IMG4_CHIP_INSTANCE_OMIT_EPRO
66	* The chip instance has no effective production status.
67	*
68	* @const IMG4_CHIP_INSTANCE_OMIT_ESEC
69	* The chip instance has no effective security mode.
70	*
71	* @const IMG4_CHIP_INSTANCE_OMIT_IUOU
72	* The chip instance has no internal-use-only-unit property.
73	*
74	* @const IMG4_CHIP_INSTANCE_OMIT_RSCH
75	* The chip instance has no research fusing state.
76	*
77	* @const IMG4_CHIP_INSTANCE_OMIT_EUOU
78	* The chip instance has no engineering-use-only-unit property.
79	*/
80	OS_CLOSED_OPTIONS(img4_chip_instance_omit, uint64_t,
81	IMG4_CHIP_INSTANCE_OMIT_CEPO = (1 << 0),
82	IMG4_CHIP_INSTANCE_OMIT_BORD = (1 << 1),
83	IMG4_CHIP_INSTANCE_OMIT_CHIP = (1 << 2),
84	IMG4_CHIP_INSTANCE_OMIT_SDOM = (1 << 3),
85	IMG4_CHIP_INSTANCE_OMIT_ECID = (1 << 4),
86	IMG4_CHIP_INSTANCE_OMIT_CPRO = (1 << 5),
87	IMG4_CHIP_INSTANCE_OMIT_CSEC = (1 << 6),
88	IMG4_CHIP_INSTANCE_OMIT_EPRO = (1 << 7),
89	IMG4_CHIP_INSTANCE_OMIT_ESEC = (1 << 8),
90	IMG4_CHIP_INSTANCE_OMIT_IUOU = (1 << 9),
91	IMG4_CHIP_INSTANCE_OMIT_RSCH = (1 << 10),
92	IMG4_CHIP_INSTANCE_OMIT_EUOU = (1 << 11),
93	);
94
95	/*!
96	* @typedef img4_chip_instance_t
97	* An structure describing an instance of a chip.
98	*
99	* @field chid_version
100	* The version of the structure. Initialize to
101	* {@link IMG4_CHIP_INSTANCE_STRUCT_VERSION}.
102	*
103	* @field chid_chip_family
104	* The chip family of which this is an instance.
105	*
106	* @field chid_omit
107	* The identifiers which are absent from the chip instance.
108	*
109	* @field chid_cepo
110	* The certificate epoch of the chip instance.
111	*
112	* @field chid_bord
113	* The board identifier of the chip instance.
114	*
115	* @field chid_chip
116	* The chip identifier of the chip instance.
117	*
118	* @field chid_sdom
119	* The security domain of the chip instance.
120	*
121	* @field chid_ecid
122	* The unique chip identifier of the chip instance.
123	*
124	* @field chid_cpro
125	* The certificate production status of the chip instance.
126	*
127	* @field chid_csec
128	* The certificate security mode of the chip instance.
129	*
130	* @field chid_epro
131	* The effective production status of the chip instance.
132	*
133	* @field chid_esec
134	* The effective security mode of the chip instance.
135	*
136	* @field chid_iuou
137	* The internal use-only unit status of the chip instance.
138	*
139	* @field chid_rsch
140	* The research mode of the chip instance.
141	*
142	* @field chid_euou
143	* The engineering use-only unit status of the chip instance.
144	*
145	* Added in version 1 of the structure.
146	*/
147	IMG4_API_AVAILABLE_20200508
148	typedef struct _img4_chip_instance {
149	img4_struct_version_t chid_version;
150	const img4_chip_t *chid_chip_family;
151	img4_chip_instance_omit_t chid_omit;
152	uint32_t chid_cepo;
153	uint32_t chid_bord;
154	uint32_t chid_chip;
155	uint32_t chid_sdom;
156	uint64_t chid_ecid;
157	bool chid_cpro;
158	bool chid_csec;
159	bool chid_epro;
160	bool chid_esec;
161	bool chid_iuou;
162	bool chid_rsch;
163	bool chid_euou;
164	} img4_chip_instance_t;
165
166	/*!
167	* @const IMG4_CHIP_AP_SHA1
168	* The Application Processor on an Apple ARM SoC with an embedded sha1
169	* certifcate chain.
170	*
171	* This chip environment represents one unique instance of such a chip.
172	*/
173	#if !XNU_KERNEL_PRIVATE
174	IMG4_API_AVAILABLE_20200508
175	OS_EXPORT
176	const img4_chip_t _img4_chip_ap_sha1;
177	#define IMG4_CHIP_AP_SHA1 (&_img4_chip_ap_sha1)
178	#else
179	#define IMG4_CHIP_AP_SHA1 (img4if->i4if_v7.chip_ap_sha1)
180	#endif
181
182	/*!
183	* @const IMG4_CHIP_AP_SHA2_384
184	* The Application Processor on an Apple ARM SoC with an embedded sha2-384
185	* certifcate chain.
186	*
187	* This chip environment represents one unique instance of such a chip.
188	*/
189	#if !XNU_KERNEL_PRIVATE
190	IMG4_API_AVAILABLE_20200508
191	OS_EXPORT
192	const img4_chip_t _img4_chip_ap_sha2_384;
193	#define IMG4_CHIP_AP_SHA2_384 (&_img4_chip_ap_sha2_384)
194	#else
195	#define IMG4_CHIP_AP_SHA2_384 (img4if->i4if_v7.chip_ap_sha2_384)
196	#endif
197
198	/*!
199	* @const IMG4_CHIP_AP_HYBRID
200	* An Intel x86 processor whose chain of trust is rooted in an
201	* {@link IMG4_CHIP_AP_SHA2_384} environment. Firmwares executed on this chip
202	* are authenticated against the characteristics of the corresponding AP chip
203	* environment.
204	*
205	* This chip environment represents one unique instance of such a chip pair.
206	*/
207	#if !XNU_KERNEL_PRIVATE
208	IMG4_API_AVAILABLE_20200508
209	OS_EXPORT
210	const img4_chip_t _img4_chip_ap_hybrid;
211	#define IMG4_CHIP_AP_HYBRID (&_img4_chip_ap_hybrid)
212	#else
213	#define IMG4_CHIP_AP_HYBRID (img4if->i4if_v7.chip_ap_hybrid)
214	#endif
215
216	/*!
217	* @const IMG4_CHIP_AP_REDUCED
218	* An Application Processor on an Apple ARM SoC operating in a reduced security
219	* configuration.
220	*
221	* This chip cannot be uniquely identified.
222	*/
223	#if !XNU_KERNEL_PRIVATE
224	IMG4_API_AVAILABLE_20200508
225	OS_EXPORT
226	const img4_chip_t _img4_chip_ap_reduced;
227	#define IMG4_CHIP_AP_REDUCED (&_img4_chip_ap_reduced)
228	#else
229	#define IMG4_CHIP_AP_REDUCED (img4if->i4if_v7.chip_ap_reduced)
230	#endif
231
232	/*!
233	* @const IMG4_CHIP_AP_PERMISSIVE
234	* An Application Processor on an Apple ARM SoC operating with no secure boot
235	* enforcement.
236	*
237	* This chip cannot be uniquely identified.
238	*/
239	#if !XNU_KERNEL_PRIVATE
240	IMG4_API_AVAILABLE_20200508
241	OS_EXPORT
242	const img4_chip_t _img4_chip_ap_permissive;
243	#define IMG4_CHIP_AP_PERMISSIVE (&_img4_chip_ap_permissive)
244	#else
245	#define IMG4_CHIP_AP_PERMISSIVE (img4if->i4if_v8.chip_ap_permissive)
246	#endif
247
248	/*!
249	* @const IMG4_CHIP_AP_HYBRID_MEDIUM
250	* An Intel x86 processor whose chain of trust is rooted in an
251	* {@link IMG4_CHIP_AP_SHA2_384} environment and is operating in a "medium
252	* security" mode due to a user-approved security degradation.
253	*
254	* This chip cannot be uniquely identified.
255	*/
256	#if !XNU_KERNEL_PRIVATE
257	IMG4_API_AVAILABLE_20200508
258	OS_EXPORT
259	const img4_chip_t _img4_chip_ap_hybrid_medium;
260	#define IMG4_CHIP_AP_HYBRID_MEDIUM (&_img4_chip_ap_hybrid_medium)
261	#else
262	#define IMG4_CHIP_AP_HYBRID_MEDIUM (img4if->i4if_v8.chip_ap_hybrid_medium)
263	#endif
264
265	/*!
266	* @const IMG4_CHIP_AP_HYBRID_RELAXED
267	* An Intel x86 processor whose chain of trust is rooted in an
268	* {@link IMG4_CHIP_AP_SHA2_384} environment and is operating with no secure
269	* boot enforcement due to a user-approved security degradation.
270	*
271	* This chip cannot be uniquely identified.
272	*/
273	#if !XNU_KERNEL_PRIVATE
274	IMG4_API_AVAILABLE_20200508
275	OS_EXPORT
276	const img4_chip_t _img4_chip_ap_hybrid_relaxed;
277	#define IMG4_CHIP_AP_HYBRID_RELAXED (&_img4_chip_ap_hybrid_relaxed)
278	#else
279	#define IMG4_CHIP_AP_HYBRID_RELAXED (img4if->i4if_v8.chip_ap_hybrid_relaxed)
280	#endif
281
282	/*!
283	* @const IMG4_CHIP_AP_SOFTWARE_FF00
284	* A software-defined chip environment whose firmwares are executed on any
285	* Application Processor on an Apple ARM SoC. The firmwares are loadable trust
286	* caches shipped with OTA update brains.
287	*
288	* This chip cannot be uniquely identified.
289	*/
290	#if !XNU_KERNEL_PRIVATE
291	IMG4_API_AVAILABLE_20200508
292	OS_EXPORT
293	const img4_chip_t _img4_chip_ap_software_ff00;
294	#define IMG4_CHIP_AP_SOFTWARE_FF00 (&_img4_chip_ap_software_ff00)
295	#else
296	#define IMG4_CHIP_AP_SOFTWARE_FF00 (img4if->i4if_v7.chip_ap_software_ff00)
297	#endif
298
299	/*!
300	* @const IMG4_CHIP_AP_SOFTWARE_FF01
301	* A software-defined chip environment whose firmwares are executed on any
302	* Application Processor on an Apple ARM SoC. The firmwares are loadable trust
303	* caches which are shipped in the Install Assistant and loaded by an
304	* unprivileged trampoline.
305	*
306	* This chip cannot be uniquely identified.
307	*/
308	#if !XNU_KERNEL_PRIVATE
309	IMG4_API_AVAILABLE_20200508
310	OS_EXPORT
311	const img4_chip_t _img4_chip_ap_software_ff01;
312	#define IMG4_CHIP_AP_SOFTWARE_FF01 (&_img4_chip_ap_software_ff01)
313	#else
314	#define IMG4_CHIP_AP_SOFTWARE_FF01 (img4if->i4if_v7.chip_ap_software_ff01)
315	#endif
316
317	/*!
318	* @const IMG4_CHIP_X86
319	* An Intel x86 processor which cannot be uniquely identified.
320	*/
321	#if !XNU_KERNEL_PRIVATE
322	IMG4_API_AVAILABLE_20200508
323	OS_EXPORT
324	const img4_chip_t _img4_chip_x86;
325	#define IMG4_CHIP_X86 (&_img4_chip_x86)
326	#else
327	#define IMG4_CHIP_X86 (img4if->i4if_v7.chip_x86)
328	#endif
329
330	/*!
331	* @const IMG4_CHIP_X86_SOFTWARE_8012
332	* A software-defined chip environment describing a virtualized x86 processor.
333	* Since the virtual machine is at the mercy of the VM, support for any sort of
334	* chip identity may not be available. Therefore this environment is returned
335	* from {@link img4_chip_select_personalized_ap} and
336	* {@link img4_chip_select_effective_ap} when it is called on a virtual machine
337	* so that the appropriate chip environment is present entirely in software.
338	*
339	* This environment provides an equivalent software identity to that of
340	* the {@link IMG4_CHIP_X86} chip environment on non-Gibraltar Macs.
341	*
342	* @discussion
343	* Do not use this environment directly.
344	*/
345	#if !XNU_KERNEL_PRIVATE
346	IMG4_API_AVAILABLE_20200508
347	OS_EXPORT
348	const img4_chip_t _img4_chip_x86_software_8012;
349	#define IMG4_CHIP_X86_SOFTWARE_8012 (&_img4_chip_x86_software_8012)
350	#else
351	#define IMG4_CHIP_X86_SOFTWARE_8012 (img4if->i4if_v7.chip_x86_software_8012)
352	#endif
353
354	/*!
355	* @function img4_chip_init_from_buff
356	* Initializes a buffer as a chip object.
357	*
358	* @param buff
359	* A pointer to the storage to use for the chip object.
360	*
361	* @param len
362	* The size of the buffer.
363	*
364	* @discussion
365	* The caller is expected to pass a buffer that is "big enough". If the provided
366	* buffer is too small, the implementation will abort the caller.
367	*
368	* @example
369	*
370	* uint8_t _buff[IMG4_CHIP_SIZE_RECOMMENDED];
371	* img4_chip_t *chip = NULL;
372	*
373	* chip = img4_chip_init_from_buff(_buff, sizeof(_buff));
374	*/
375	#if !XNU_KERNEL_PRIVATE
376	IMG4_API_AVAILABLE_20200508
377	OS_EXPORT OS_WARN_RESULT OS_NONNULL1
378	img4_chip_t *
379	img4_chip_init_from_buff(void *buff, size_t len);
380	#else
381	#define img4_chip_init_from_buff (img4if->i4if_v7.chip_init_from_buff)
382	#endif
383
384	/*!
385	* @function img4_chip_select_personalized_ap
386	* Returns the chip appropriate for personalized verification against the host
387	* AP.
388	*
389	* @result
390	* The personalized chip environment for the host which corresponds to its
391	* silicon identity.
392	*/
393	#if !XNU_KERNEL_PRIVATE
394	IMG4_API_AVAILABLE_20200508
395	OS_EXPORT OS_WARN_RESULT
396	const img4_chip_t *
397	img4_chip_select_personalized_ap(void);
398	#else
399	#define img4_chip_select_personalized_ap(...) \
400	(img4if->i4if_v7.chip_select_personalized_ap(__VA_ARGS__))
401	#endif
402
403	/*!
404	* @function img4_chip_select_effective_ap
405	* Returns the chip appropriate for verification against the host AP.
406	*
407	* @result
408	* The currently enforced chip environment for the host. This interface is
409	* generally only useful on the AP.
410	*/
411	#if !XNU_KERNEL_PRIVATE
412	IMG4_API_AVAILABLE_20200508
413	OS_EXPORT OS_WARN_RESULT
414	const img4_chip_t *
415	img4_chip_select_effective_ap(void);
416	#else
417	#define img4_chip_select_effective_ap(...) \
418	(img4if->i4if_v7.chip_select_effective_ap(__VA_ARGS__))
419	#endif
420
421	/*!
422	* @function img4_chip_instantiate
423	* Returns an instantiation of the given chip using the default runtime where
424	* necessary.
425	*
426	* @param chip
427	* The chip to instantiate.
428	*
429	* @param chip_instance
430	* Upon successful return, storage to be populated with the instantiated chip.
431	* Upon failure, the contents of this storage are undefined.
432	*
433	* @result
434	* Upon success, zero is returned. Otherwise, one of the following error codes
435	* will be returned:
436	*
437	* [EXDEV] There was an error querying the runtime's identity oracle
438	* [ENODATA] The expected property in the runtime's identity oracle was
439	* of an unexpected type
440	* [EOVERFLOW] The expected property in the runtime's identity oracle had
441	* a value that was too large to be represented in the
442	* expected type
443	*/
444	#if !XNU_KERNEL_PRIVATE
445	IMG4_API_AVAILABLE_20200508
446	OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
447	errno_t
448	img4_chip_instantiate(const img4_chip_t *chip,
449	img4_chip_instance_t *chip_instance);
450	#else
451	#define img4_chip_instantiate(...) \
452	(img4if->i4if_v7.chip_instantiate(__VA_ARGS__))
453	#endif
454
455	/*!
456	* @function img4_chip_custom
457	* Returns a custom chip derived from the given chip instance. The
458	* {@link chid_chip_family} field of the given instance will be used as a
459	* template from which to derive the new chip.
460	*
461	* @param chip_instance
462	* The instance of the custom chip.
463	*
464	* The memory referenced by this pointer must be static or otherwise guaranteed
465	* to be valid for the duration of the caller's use of the custom chip.
466	*
467	* @param chip
468	* A pointer to storage for the new custom chip.
469	*
470	* The memory referenced by this pointer must be static or otherwise guaranteed
471	* to be valid for the duration of the caller's use of the custom chip.
472	*
473	* This pointer should be obtained as the result of a call to
474	* {@link img4_chip_init_from_buff}.
475	*
476	* @result
477	* A new custom chip.
478	*/
479	#if !XNU_KERNEL_PRIVATE
480	IMG4_API_AVAILABLE_20200508
481	OS_EXPORT OS_WARN_RESULT OS_NONNULL1
482	const img4_chip_t *
483	img4_chip_custom(const img4_chip_instance_t chip_instance, img4_chip_t chip);
484	#else
485	#define img4_chip_custom(...) (img4if->i4if_v7.chip_custom(__VA_ARGS__))
486	#endif
487
488	OS_ASSUME_NONNULL_END
489
490	#endif // __IMG4_CHIP_H