/*!
 * @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

__BEGIN_DECLS
OS_ASSUME_NONNULL_BEGIN
OS_ASSUME_PTR_ABI_SINGLE_BEGIN

/*!
 * @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 (6u)

/*!
 * @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.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_ESDM
 * The chip instance has no extended security domain property.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_FPGT
 * The chip instance has no factory pre-release global trust property.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_UDID
 * The chip instance has no universal device identifier property.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_FCHP
 * The chip instance has no cryptex chip identifier property.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_TYPE
 * The chip instance has no cryptex type identifier property.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_STYP
 * The chip instance has no cryptex subtype identifier property.
 *
 * @const IMG4_CHIP_INSTANCE_OMIT_CLAS
 * The chip instance has no product class 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),
	IMG4_CHIP_INSTANCE_OMIT_ESDM = (1 << 12),
	IMG4_CHIP_INSTANCE_OMIT_FPGT = (1 << 13),
	IMG4_CHIP_INSTANCE_OMIT_UDID = (1 << 14),
	IMG4_CHIP_INSTANCE_OMIT_FCHP = (1 << 15),
	IMG4_CHIP_INSTANCE_OMIT_TYPE = (1 << 16),
	IMG4_CHIP_INSTANCE_OMIT_STYP = (1 << 17),
	IMG4_CHIP_INSTANCE_OMIT_CLAS = (1 << 18),
);

/*!
 * @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.
 *
 * @field chid_esdm
 * The extended security domain of the chip instance.
 *
 * Added in version 3 of the structure.
 *
 * @field chid_fpgt
 * The factory pre-release global trust status of the chip instance.
 *
 * Added in version 4 of the structure.
 *
 * @field chid_udid
 * The universal device identifier of the chip instance.
 *
 * Added in version 5 of the structure.
 *
 * @const chid_fchp
 * The cryptex chip identifier of the chip instance.
 *
 * Added in version 6 of the structure.
 *
 * @const chid_type
 * The cryptex type identifier of the chip instance.
 *
 * Added in version 6 of the structure.
 *
 * @const chid_styp
 * The cryptex subtype identifier of the chip instance.
 *
 * Added in version 6 of the structure.
 *
 * @field chid_clas
 * The product class of the chip instance.
 *
 * Added in version 6 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;
	uint32_t chid_esdm;
	bool chid_fpgt;
	img4_dgst_t chid_udid;
	uint32_t chid_fchp;
	uint32_t chid_type;
	uint32_t chid_styp;
	uint32_t chid_clas;
} img4_chip_instance_t;

/*!
 * @function IMG4_CHIP_INSTANCE_INIT
 * A convenience initializer which can be used to initialize a chip instance to
 * a given family.
 *
 * @param _family
 * The family of chip.
 *
 * @result
 * A fully-initialized structure of the appropriate version supported by the
 * implementation. The resulting chip instance omits no identifiers.
 */
#define IMG4_CHIP_INSTANCE_INIT(_family) (img4_chip_instance_t){ \
	.chid_version = IMG4_CHIP_INSTANCE_STRUCT_VERSION, \
	.chid_chip_family = (_family), \
	.chid_omit = 0, \
	.chid_cepo = 0, \
	.chid_bord = 0, \
	.chid_chip = 0, \
	.chid_sdom = 0, \
	.chid_ecid = 0, \
	.chid_cpro = false, \
	.chid_csec = false, \
	.chid_epro = false, \
	.chid_esec = false, \
	.chid_iuou = false, \
	.chid_rsch = false, \
	.chid_euou = false, \
	.chid_esdm = 0, \
	.chid_fpgt = false, \
	.chid_udid = {0}, \
	.chid_fchp = 0, \
	.chid_type = 0, \
	.chid_styp = 0, \
	.chid_clas = 0, \
}

/*!
 * @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 *__sized_by(len) 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_personalized_sep
 * Returns the chip appropriate for personalized verification against the host
 * SEP.
 *
 * @result
 * The personalized chip environment for the host's SEP which corresponds to its
 * silicon identity. This will return NULL when called outside of the SEP
 * runtime.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20211119
OS_EXPORT OS_WARN_RESULT
const img4_chip_t *_Nullable
img4_chip_select_personalized_sep(void);
#else
#define img4_chip_select_personalized_sep(...) \
		(img4if->i4if_v16.chip_select_personalized_sep(__VA_ARGS__))
#endif

/*!
 * @function img4_chip_select_categorized_ap
 * Returns the chip appropriate for categorized verification against the host
 * AP.
 *
 * @result
 * The categorized chip environment for the host which corresponds to its
 * silicon identity. If the host has no AP category defined for it, NULL will be
 * returned.
 *
 * @discussion
 * Categorized chip environments have been scuttled and were never used. Please
 * remove all uses of this function.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20210305
OS_EXPORT OS_WARN_RESULT
const img4_chip_t *_Nullable
img4_chip_select_categorized_ap(void);
#else
#define img4_chip_select_categorized_ap(...) \
		(img4if->i4if_v12.chip_select_categorized_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_select_cryptex1_boot
 * Returns the appropriate Cryptex1 boot chip environment for the currently-
 * booted effective AP environment.
 *
 * @result
 * The chip environment to use for verification.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20211126
OS_EXPORT OS_WARN_RESULT
const img4_chip_t *
img4_chip_select_cryptex1_boot(void);
#else
#define img4_chip_select_cryptex1_boot(...) \
		(img4if->i4if_v17.chip_select_cryptex1_boot(__VA_ARGS__))
#endif

/*!
 * @function img4_chip_select_cryptex1_preboot
 * Returns the appropriate Cryptex1 pre-reboot chip environment for the
 * currently-booted effective AP environment.
 *
 * @result
 * The chip environment to use for verification.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20211126
OS_EXPORT OS_WARN_RESULT
const img4_chip_t *
img4_chip_select_cryptex1_preboot(void);
#else
#define img4_chip_select_cryptex1_preboot(...) \
		(img4if->i4if_v17.chip_select_cryptex1_preboot(__VA_ARGS__))
#endif

/*!
 * @function img4_chip_get_cryptex1_boot
 * Returns the appropriate Cryptex1 boot chip environment associated with a
 * given AP environment.
 *
 * @param chip
 * The AP environment for which to obtain the associated Cryptex1 environment.
 *
 * @result
 * The Cryptex1 chip environment associated with {@link chip}. If there is no
 * Cryptex1 association, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20220401
OS_EXPORT OS_WARN_RESULT OS_NONNULL1
const img4_chip_t *_Nullable
img4_chip_get_cryptex1_boot(const img4_chip_t *chip);
#else
#define img4_chip_get_cryptex1_boot(...) \
		(img4if->i4if_v18.chip_get_cryptex1_boot(__VA_ARGS__))
#endif

/*!
 * @function img4_chip_get_cryptex1_boot_proposal
 * Returns the appropriate Cryptex1 boot proposal chip environment associated
 * with a given AP environment.
 *
 * @param chip
 * The AP environment for which to obtain the associated Cryptex1 proposal
 * environment.
 *
 * @result
 * The Cryptex1 proposal chip environment associated with {@link chip}. If
 * there is no Cryptex1 association, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20220401
OS_EXPORT OS_WARN_RESULT OS_NONNULL1
const img4_chip_t *_Nullable
img4_chip_get_cryptex1_boot_proposal(const img4_chip_t *chip);
#else
#define img4_chip_get_cryptex1_boot_proposal(...) \
		(img4if->i4if_v18.chip_get_cryptex1_boot_proposal(__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_PTR_ABI_SINGLE_END
OS_ASSUME_NONNULL_END
__END_DECLS

#endif // __IMG4_CHIP_H