/*!
 * @header
 * Image4 runtime interfaces.
 */
#ifndef __IMG4_RUNTIME_H
#define __IMG4_RUNTIME_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_identifier_t
 * An enumeration describing identifiers in the Image4 specification.
 *
 * @const IMG4_IDENTIFIER_CEPO
 * The chip epoch as documented in 2.1.1. Authoritative manifests will specify a
 * certificate epoch which is greater than or equal to that of the chip.
 *
 * Unsigned 32-bit integer.
 *
 * @const IMG4_IDENTIFIER_BORD
 * The board identifier as documented in 2.1.3. Authoritative manifests will
 * specify a board identifier which is equal to that of the chip.
 *
 * Unsigned 32-bit integer.
 *
 * @const IMG4_IDENTIFIER_CHIP
 * The chip identifier as documented in 2.1.2. Authoritative manifests will
 * specify a chip identifier which is equal to that of the chip.
 *
 * Unsigned 32-bit integer.
 *
 * @const IMG4_IDENTIFIER_SDOM
 * The security domain as documented in 2.1.5. Authoritative manifests will
 * specify a security domain which is equal to that that of the chip.
 *
 * Unsigned 32-bit integer. Valid values are
 *
 *     0    Manufacturing
 *     1    Darwin
 *     2    Data Center (unsure)
 *     3    Unused
 *
 * @const IMG4_IDENTIFIER_ECID
 * The unique chip identifier as documented in 2.1.4. Authoritative manifests
 * will specify a unique chip identifier which is equal to that of the chip.
 *
 * Unsigned 64-bit integer.
 *
 * @const IMG4_IDENTIFIER_CPRO
 * The certificate production status as documented in 2.1.6. Authoritative
 * manifests will specify a certificate production status which is equal to that
 * of the chip.
 *
 * Boolean.
 *
 * @const IMG4_IDENTIFIER_CSEC
 * The certificate security mode as documented in 2.1.7. Authoritative manifests
 * will specify a certificate security mode which is equal to that of the chip.
 *
 * Boolean.
 *
 * @const IMG4_IDENTIFIER_EPRO
 * The effective production status as documented in 2.1.23. Unless the chip
 * environment supports demotion, this will always be the same as
 * {@link IMG4_IDENTIFIER_CPRO}. An executable firmware in an authoritative
 * manifest will specify an EPRO object property which is equal to that of the
 * chip post-demotion.
 *
 * Boolean.
 *
 * @const IMG4_IDENTIFIER_ESEC
 * The effective security mode as documented in 2.1.25. Unless the chip
 * environment supports demotion, this will always be the same as
 * {@link IMG4_IDENTIFIER_CSEC}. An executable firmware in an authoritative
 * manifest will specify an ESEC object property which is equal to that of the
 * chip post-demotion.
 *
 * Boolean.
 *
 * @const IMG4_IDENTIFIER_IUOU
 * The "internal use only unit" property. Indicates whether the chip is present
 * on a server-side authlist which permits installing builds which are otherwise
 * restricted to parts whose CPRO is 0. This property is only published by macOS
 * devices whose root of trust is in an arm coprocessor (e.g. T2).
 *
 * Authoritative manifests will specify an internal-use-only-build property
 * which, if true, is equal to the internal-use-only-unit property of the chip.
 * If the internal-use-only-build property is false, then there is no constraint
 * on the chip's internal-use-only-unit property.
 *
 * Boolean.
 *
 * @const IMG4_IDENTIFIER_RSCH
 * The research fusing status. Indicates whether the chip is intended for
 * security research to be performed by external parties. Authoritative
 * manifests will specify a research fusing state which is equal to that of the
 * chip.
 *
 * Boolean.
 *
 * This identifier was never recognized by SecureROM and has been obsoleted by
 * {@link IMG4_IDENTIFIER_ESDM}.
 *
 * @const IMG4_IDENTIFIER_CHMH
 * The chained manifest hash from the previous stage of secure boot as described
 * in 2.2.11. An authoritative manifest will either
 *
 *     - specify a manifest hash which is equal to that of the previous secure
 *       boot stage's manifest
 *     - itself have a manifest hash which is equal to that of the previous
 *       secure boot stage's manifest
 *
 * If the previous stage of secure boot enabled mix-n-match, there is no
 * constraint on the previous stage's manifest hash.
 *
 * Manifests which specify this property cannot be used to create new trust
 * chains -- they may only extend existing ones.
 *
 * Digest.
 *
 * @const IMG4_IDENTIFIER_AMNM
 * The allow-mix-n-match status of the chip. If mix-n-match is enabled, secure
 * boot will permit different manifests to be used at each stage of boot. If the
 * chip environment allows mix-n-match, evaluation will not require an anti-
 * replay token to be specified, and any chained manifest hash constraints are
 * ignored.
 *
 * Boolean.
 *
 * @const IMG4_IDENTIFIER_EUOU
 * The engineering-use-only-unit status of the chip. This is in effect an alias
 * for the {@link IMG4_IDENTIFIER_IUOU} property. Either property being present
 * in the environment will satisfy a manifest's iuob constraint.
 *
 * Boolean.
 *
 * @const IMG4_IDENTIFIER_LOVE
 * The long version of the OS currently booted on the chip (Long Os VErsion).
 *
 * Authoritative manifests will specify a version number which is greater than
 * that of the chip.
 *
 * C string.
 *
 * @const IMG4_IDENTIFIER_ESDM
 * The extended security domain of the chip. Authoritative manifests will
 * specify an extended security domain which is equal to that of the chip.
 *
 * Unsigned 32-bit integer. This integer represents 8 fusing bits, and therefore
 * the maximum valid value is 0xff.
 *
 * @const IMG4_IDENTIFIER_FPGT
 * The factory pre-release global trust status of the chip. This is in effect an
 * alias for the {@link IMG4_IDENTIFIER_IUOU} property. Either property being
 * present in the environment will satisfy a manifest's iuob constraint.
 *
 * Boolean.
 *
 * @const IMG4_IDENTIFIER_UDID
 * The universal device identifier of the chip. This uniquely identifies the SoC
 * globally across all SoCs. Authoritative manifests will specify a UDID which
 * is equal to that of the chip.
 *
 * 128-bit octet string.
 *
 * @const IMG4_IDENTIFIER_FCHP
 * The chip identifier of the Cryptex coprocessor associated with the chip. This
 * distinguishes the software Crytpex coprocessor instances which operate on the
 * AP. Authoritative manifests will specify a Cryptex chip identifier that is
 * equal to that of the chip.
 *
 * Runtimes are not capable of reporting this value, and queries for it should
 * return ENOENT. This invariant is defined for convenience to the
 * implementation.
 *
 * Unsigned 32-bit integer.
 *
 * @const IMG4_IDENTIFIER_TYPE
 * The type identifier of the Cryptex coprocessor associated with the chip. This
 * distinguishes software Cryptex coprocessor instances of the same chip
 * identifier which operate on the AP. Authoritative manifests will specify a
 * Cryptex type that is equal to that of the chip.
 *
 * Runtimes are not capable of reporting this value, and queries for it should
 * return ENOENT. This invariant is defined for convenience to the
 * implementation.
 *
 * Unsigned 32-bit integer.
 *
 * @const IMG4_IDENTIFIER_STYP
 * The subtype identifier of the Cryptex coprocessor associated with the chip.
 * This permits an additional level of granularity to distinguish Cryptex
 * coprocessor instances from one another. Authoritative manifests will specify
 * a Cryptex subtype that is equal to that of the chip.
 *
 * Runtimes are not capable of reporting this value, and queries for it should
 * return ENOENT. This invariant is defined for convenience to the
 * implementation.
 *
 * Unsigned 32-bit integer.
 *
 * @const IMG4_IDENTIFIER_CLAS
 * The product class of the Cryptex coprocessor associated with the chip.
 * Authoritative manifests will specify a product class that is equal to that of
 * the chip.
 *
 * Valid values for this property are:
 *
 *     0xf0 - Intel Mac (with or without T2 security chip)
 *     0xf1 - Apple Silicon Mac
 *     0xf2 - iPhone/iPad/iPod touch
 *     0xf3 - watch
 *     0xf4 - tv/HomePod
 *
 * Unsigned 32-bit integer.
 *
 * @const IMG4_IDENTIFIER_SPIH
 * The booted supplemental manifest hash.
 *
 * Digest.
 *
 * @const IMG4_IDENTIFIER_NSPH
 * The preboot supplemental manifest hash intended to become active at the next
 * boot.
 *
 * Digest.
 *
 * @const IMG4_IDENTIFIER_STNG
 * The generation number of the last-executed blessed local policy on the AP.
 *
 * Unsigned 64-bit integer.
 *
 * @const IMG4_IDENTIFIER_VUID
 * The volume group UUID that the chip is booting from.
 *
 * 128-bit octet string.
 *
 * @const _IMG4_IDENTIFIER_CNT
 * A convenience value representing the number of known identifiers.
 */
IMG4_API_AVAILABLE_20200508
OS_CLOSED_ENUM(img4_identifier, uint64_t,
	IMG4_IDENTIFIER_CEPO,
	IMG4_IDENTIFIER_BORD,
	IMG4_IDENTIFIER_CHIP,
	IMG4_IDENTIFIER_SDOM,
	IMG4_IDENTIFIER_ECID,
	IMG4_IDENTIFIER_CPRO,
	IMG4_IDENTIFIER_CSEC,
	IMG4_IDENTIFIER_EPRO,
	IMG4_IDENTIFIER_ESEC,
	IMG4_IDENTIFIER_IUOU,
	IMG4_IDENTIFIER_RSCH,
	IMG4_IDENTIFIER_CHMH,
	IMG4_IDENTIFIER_AMNM,
	IMG4_IDENTIFIER_EUOU,
	IMG4_IDENTIFIER_LOVE,
	IMG4_IDENTIFIER_ESDM,
	IMG4_IDENTIFIER_FPGT,
	IMG4_IDENTIFIER_UDID,
	IMG4_IDENTIFIER_FCHP,
	IMG4_IDENTIFIER_TYPE,
	IMG4_IDENTIFIER_STYP,
	IMG4_IDENTIFIER_CLAS,
	IMG4_IDENTIFIER_SPIH,
	IMG4_IDENTIFIER_NSPH,
	IMG4_IDENTIFIER_STNG,
	IMG4_IDENTIFIER_VUID,
	_IMG4_IDENTIFIER_CNT,
);

/*!
 * @typedef img4_pmap_data_t
 * An opaque type representing state protected by the host's page mapping layer
 * as it deems appropriate. Do not use directly.
 */
IMG4_API_AVAILABLE_20210521
typedef struct _img4_pmap_data img4_pmap_data_t;

/*!
 * @typedef img4_runtime_object_spec_index_t
 * An enumeration describing the executable objects recognized by runtimes.
 *
 * @const IMG4_RUNTIME_OBJECT_SPEC_INDEX_MANIFEST
 * The enumerated constant which refers to the internal manifest object.
 *
 * @const IMG4_RUNTIME_OBJECT_SPEC_INDEX_SUPPLEMENTAL_ROOT
 * The enumerated constant which refers to the
 * {@link IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT} object.
 *
 * @const IMG4_RUNTIME_OBJECT_SPEC_INDEX_SUPPLEMENTAL_OBJECT
 * The enumerated constant which refers to the
 * {@link IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_OBJECT} object.
 *
 * @const IMG4_RUNTIME_OBJECT_SPEC_INDEX_LOCAL_POLICY
 * The enumerated constant which refers to the
 * {@link IMG4_RUNTIME_OBJECT_SPEC_LOCAL_POLICY} object.
 *
 * @const _IMG4_RUNTIME_OBJECT_SPEC_INDEX_CNT
 * A sentinel value representing the total number of executable object
 * specifications.
 */
IMG4_API_AVAILABLE_20210521
OS_CLOSED_ENUM(img4_runtime_object_spec_index, uint64_t,
	IMG4_RUNTIME_OBJECT_SPEC_INDEX_MANIFEST,
	IMG4_RUNTIME_OBJECT_SPEC_INDEX_SUPPLEMENTAL_ROOT,
	IMG4_RUNTIME_OBJECT_SPEC_INDEX_SUPPLEMENTAL_OBJECT,
	IMG4_RUNTIME_OBJECT_SPEC_INDEX_LOCAL_POLICY,
	_IMG4_RUNTIME_OBJECT_SPEC_INDEX_CNT,
);

/*!
 * @typedef img4_runtime_object_spec_t
 * A specification for an object known to and executable by a runtime.
 */
IMG4_API_AVAILABLE_20210205
typedef struct _img4_runtime_object_spec img4_runtime_object_spec_t;

/*!
 * @typedef img4_runtime_init_t
 * A function which initializes the runtime.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @discussion
 * This function is called by the implementation prior to any other runtime
 * function being called. The implementation will ensure that it is called only
 * once. Any runtime with an initialization function must be registered with the
 * {@link IMG4_RUNTIME_REGISTER} macro.
 */
IMG4_API_AVAILABLE_20200508
typedef void (*img4_runtime_init_t)(
	const img4_runtime_t *rt
);

/*!
 * @typedef img4_runtime_alloc_t
 * An allocation function.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param n
 * The number of bytes to allocate.
 *
 * @result
 * A pointer to the new allocation, or NULL if there was an allocation failure.
 *
 * The memory returned by this function is expected to be zero-filled.
 */
IMG4_API_AVAILABLE_20200508
typedef void *_Nullable (*img4_runtime_alloc_t)(
	const img4_runtime_t *rt,
	size_t n
);

/*!
 * @typedef img4_runtime_dealloc_t
 * A deallocation function.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param p
 * A pointer to the allocation to free. The callee is expected to return
 * immediately if NULL is passed.
 *
 * @param n
 * The size of the allocation. Not all implementation may require this
 * information to be specified.
 */
IMG4_API_AVAILABLE_20200508
typedef void (*img4_runtime_dealloc_t)(
	const img4_runtime_t *rt,
	void *_Nullable p,
	size_t n
);

/*!
 * @typedef img4_log_level_t
 * An enumeration describing the importance/severity of a log message.
 *
 * @const IMG4_LOG_LEVEL_ERROR
 * A fatal condition which will cause the implementation to abort its current
 * operation.
 *
 * @const IMG4_LOG_LEVEL_INFO
 * Information that may be of interest to the system operator.
 *
 * @const IMG4_LOG_LEVEL_DEBUG
 * Information that may be of interest to the maintainer.
 *
 * @const _IMG4_LOG_LEVEL_CNT
 * A convenience constant indicating the number of log levels.
 */
IMG4_API_AVAILABLE_20200508
OS_CLOSED_ENUM(img4_log_level, uint64_t,
	IMG4_LOG_LEVEL_ERROR,
	IMG4_LOG_LEVEL_INFO,
	IMG4_LOG_LEVEL_DEBUG,
	_IMG4_LOG_LEVEL_CNT,
);

/*!
 * @typedef img4_runtime_log_t
 * A function which writes log messages.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param handle
 * An implementation-specific handle for the log message.
 *
 * @param level
 * The message of the log level. The implementation is free to determine whether
 * a given message is worthy of record.
 *
 * @param fmt
 * A printf(3)-style format string.
 *
 * @param ...
 * Arguments to be interpreted by the format string according to the
 * specifications in printf(3).
 */
OS_FORMAT_PRINTF(4, 5)
IMG4_API_AVAILABLE_20200508
typedef void (*img4_runtime_log_t)(
	const img4_runtime_t *rt,
	void *_Nullable handle,
	img4_log_level_t level,
	const char *fmt,
	...
);

/*!
 * @typedef img4_runtime_log_handle_t
 * A function which returns a log handle.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @result
 * A runtime-specific log handle that will be passed to the logging function.
 */
IMG4_API_AVAILABLE_20200508
typedef void *_Nullable (*img4_runtime_log_handle_t)(
	const img4_runtime_t *rt
);

/*!
 * @typedef img4_runtime_get_identifier_bool_t
 * A function which retrieves a Boolean Image4 identifier.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param chip
 * The chip for which to retrieve the identifier.
 *
 * @param identifier
 * The identifier to retrieve.
 *
 * @param value
 * Upon successful return, storage which is populated with the retrieved value.
 *
 * @result
 * Upon success, the callee is expected to return zero. Otherwise, the callee
 * may return one of the following error codes:
 *
 *     [ENOTSUP]     The identifier cannot be queried in the runtime
 *     [ENOENT]      The identifier was not found in the runtime's identity
 *                   oracle
 *     [ENODEV]      There was an error querying the runtime's identity oracle
 */
IMG4_API_AVAILABLE_20200508
typedef errno_t (*img4_runtime_get_identifier_bool_t)(
	const img4_runtime_t *rt,
	const img4_chip_t *chip,
	img4_identifier_t identifier,
	bool *value
);

/*!
 * @typedef img4_runtime_get_identifier_uint32_t
 * A function which retrieves an unsigned 32-bit integer Image4 identifier.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param chip
 * The chip for which to retrieve the identifier.
 *
 * @param identifier
 * The identifier to retrieve.
 *
 * @param value
 * Upon successful return, storage which is populated with the retrieved value.
 *
 * @result
 * Upon success, the callee is expected to return zero. Otherwise, the callee
 * may return one of the following error codes:
 *
 *     [ENOTSUP]     The identifier cannot be queried in the runtime
 *     [ENOENT]      The identifier was not found in the runtime's identity
 *                   oracle
 *     [ENODEV]      There was an error querying the runtime's identity oracle
 */
IMG4_API_AVAILABLE_20200508
typedef errno_t (*img4_runtime_get_identifier_uint32_t)(
	const img4_runtime_t *rt,
	const img4_chip_t *chip,
	img4_identifier_t identifier,
	uint32_t *value
);

/*!
 * @typedef img4_runtime_get_identifier_uint64_t
 * A function which retrieves an unsigned 64-bit integer Image4 identifier.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param chip
 * The chip for which to retrieve the identifier.
 *
 * @param identifier
 * The identifier to retrieve.
 *
 * @param value
 * Upon successful return, storage which is populated with the retrieved value.
 *
 * @result
 * Upon success, the callee is expected to return zero. Otherwise, the callee
 * may return one of the following error codes:
 *
 *     [ENOTSUP]     The identifier cannot be queried in the runtime
 *     [ENOENT]      The identifier was not found in the runtime's identity
 *                   oracle
 *     [ENODEV]      There was an error querying the runtime's identity oracle
 */
IMG4_API_AVAILABLE_20200508
typedef errno_t (*img4_runtime_get_identifier_uint64_t)(
	const img4_runtime_t *rt,
	const img4_chip_t *chip,
	img4_identifier_t identifier,
	uint64_t *value
);

/*!
 * @typedef img4_runtime_get_identifier_digest_t
 * A function which retrieves a digest Image4 identifier.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param chip
 * The chip for which to retrieve the identifier.
 *
 * @param identifier
 * The identifier to retrieve.
 *
 * @param value
 * Upon successful return, storage which is populated with the retrieved value.
 *
 * @result
 * Upon success, the callee is expected to return zero. Otherwise, the callee
 * may return one of the following error codes:
 *
 *     [ENOTSUP]     The identifier cannot be queried in the runtime
 *     [ENOENT]      The identifier was not found in the runtime's identity
 *                   oracle
 *     [ENODEV]      There was an error querying the runtime's identity oracle
 */
IMG4_API_AVAILABLE_20200508
typedef errno_t (*img4_runtime_get_identifier_digest_t)(
	const img4_runtime_t *rt,
	const img4_chip_t *chip,
	img4_identifier_t identifier,
	img4_dgst_t *value
);

/*!
 * @typedef img4_runtime_get_identifier_cstr_t
 * A function which retrieves a C-string Image4 identifier.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param chip
 * The chip for which to retrieve the identifier.
 *
 * @param identifier
 * The identifier to retrieve.
 *
 * @param value
 * Upon successful return, storage which is populated with the retrieved value.
 *
 * @result
 * Upon success, the callee is expected to return zero. Otherwise, the callee
 * may return one of the following error codes:
 *
 *     [ENOTSUP]     The identifier cannot be queried in the runtime
 *     [ENOENT]      The identifier was not found in the runtime's identity
 *                   oracle
 *     [ENODEV]      There was an error querying the runtime's identity oracle
 */
IMG4_API_AVAILABLE_20210113
typedef errno_t (*img4_runtime_get_identifier_cstr_t)(
	const img4_runtime_t *rt,
	const img4_chip_t *chip,
	img4_identifier_t identifier,
	img4_cstr_t *value
);

/*!
 * @typedef img4_runtime_execute_object_t
 * A function which executes an object type known to the runtime.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param obj_spec
 * The object specification for the payload being executed.
 *
 * @param payload
 * The payload bytes to execute. These bytes are delivered in their raw form,
 * i.e. without any Image4 payload wrapping.
 *
 * @param manifest
 * The manifest which authenticats the payload. If the payload is intended to be
 * used without authentication (or with alternate means of authentication), this
 * may be NULL.
 *
 * @result
 * Upon success, the callee is expected to return zero. Otherwise, the callee
 * may return any appropriate POSIX error code.
 *
 * @discussion
 * This function is only called if the payload has been successfully
 * authenticated; the callee can consider the bytes as trusted.
 */
IMG4_API_AVAILABLE_20210205
typedef errno_t (*img4_runtime_execute_object_t)(
	const img4_runtime_t *rt,
	const img4_runtime_object_spec_t *obj_spec,
	const img4_buff_t *payload,
	const img4_buff_t *_Nullable manifest
);

/*!
 * @typedef img4_runtime_copy_object_t
 * A function which obtains the payload of a previously-executed object.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param obj_spec
 * The object specification for the payload being obtained.
 *
 * @param payload
 * A pointer to a buffer object in which to copy the object.
 *
 * @param payload_len
 * Upon successful return, a pointer to the total number of bytes coped into the
 * buffer referred to by {@link payload}. This parameter may be NULL.
 *
 * In the event that buffer referred to be {@link payload} is insufficient to,
 * accommodate the object, the callee is expected to set this parameter to the
 * total number of bytes required.
 *
 * @result
 * Upon success, the callee is expected to return zero. Otherwise, the callee
 * may return one of the following error codes:
 *
 *     [EOVERFLOW]     The provided buffer is not large enough for the payload;
 *                     in this case the callee is expected to set the
 *                     {@link i4b_len} of the given buffer to the required
 *                     length
 *     [ENOENT]        The object has not yet been executed
 */
IMG4_API_AVAILABLE_20210205
typedef errno_t (*img4_runtime_copy_object_t)(
	const img4_runtime_t *rt,
	const img4_runtime_object_spec_t *obj_spec,
	img4_buff_t *payload,
	size_t *_Nullable payload_len
);

/*!
 * @typedef img4_runtime_alloc_type_t
 * A function which allocates a single object of a given type.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param handle
 * The domain-specific handle describing the object and the allocation site.
 *
 * @result
 * A pointer to the new allocation, or NULL if there was an allocation failure.
 * The memory returned by this function is expected to be zero-filled.
 */
IMG4_API_AVAILABLE_20210226
typedef void *_Nullable (*img4_runtime_alloc_type_t)(
	const img4_runtime_t *rt,
	void *_Nullable handle
);

/*!
 * @typedef img4_runtime_dealloc_type_t
 * A function which deallocates a single object of a given type.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param handle
 * The domain-specific handle describing the object and the deallocation site.
 *
 * @param p
 * The address of the object to deallocate.
 */
IMG4_API_AVAILABLE_20210226
typedef void (*img4_runtime_dealloc_type_t)(
	const img4_runtime_t *rt,
	void *_Nullable handle,
	void *p
);

/*!
 * @typedef img4_runtime_set_nonce_t
 * A function which sets the value of a nonce managed by the runtime.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param ndi
 * The index of the nonce domain whose nonce should be set.
 *
 * @param n
 * The value of the nonce indicated by {@link nd}.
 */
IMG4_API_AVAILABLE_20210521
typedef void (*img4_runtime_set_nonce_t)(
	const img4_runtime_t *rt,
	img4_nonce_domain_index_t ndi,
	const img4_nonce_t *n
);

/*!
 * @typedef img4_runtime_roll_nonce_t
 * A function which rolls a nonce managed by the runtime.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param ndi
 * The index of the nonce domain whose nonce should be rolled.
 */
IMG4_API_AVAILABLE_20210521
typedef void (*img4_runtime_roll_nonce_t)(
	const img4_runtime_t *rt,
	img4_nonce_domain_index_t ndi
);

/*!
 * @typedef img4_runtime_copy_nonce_t
 * A function which retrieve the value of a nonce managed by the runtime.
 *
 * @param rt
 * The runtime for which the function is being invoked.
 *
 * @param ndi
 * The index of the nonce domain whose nonce should be queried.
 *
 * @param n
 * Upon successful return, the value of the nonce indicated by {@link nd}. If
 * the caller simply wishes to check if the nonce has been invalidated, this
 * parameter may be NULL, and the caller can check for ESTALE.
 *
 * @result
 * Upon success, zero is returned. The implementation may also return one of the
 * following error codes directly:
 *
 *     [ESTALE]     The nonce for the given domain has been invalidated, and the
 *                  host must reboot in order to generate a new one
 */
IMG4_API_AVAILABLE_20210521
typedef errno_t (*img4_runtime_copy_nonce_t)(
	const img4_runtime_t *rt,
	img4_nonce_domain_index_t ndi,
	img4_nonce_t *_Nullable n
);

/*!
 * @define IMG4_BUFF_STRUCT_VERSION
 * The version of the {@link img4_buff_t} structure supported by the
 * implementation.
 */
#define IMG4_BUFF_STRUCT_VERSION (0u)

/*!
 * @struct _img4_buff
 * A structure describing a buffer.
 *
 * @field i4b_version
 * The version of the structure. Initialize to {@link IMG4_BUFF_STRUCT_VERSION}.
 *
 * @field i4b_bytes
 * A pointer to the buffer.
 *
 * @field i4b_len
 * The length of the buffer.
 *
 * @field i4b_dealloc
 * The deallocation function for the buffer. May be NULL if the underlying
 * memory does not require cleanup. When the implementation invokes this
 * function, it will always pass {@link IMG4_RUNTIME_DEFAULT}, and the callee
 * should not consult this parameter for any reason.
 */
struct _img4_buff {
	img4_struct_version_t i4b_version;
	uint8_t *__counted_by(i4b_len) i4b_bytes;
	size_t i4b_len;
	img4_runtime_dealloc_t _Nullable i4b_dealloc;
} IMG4_API_AVAILABLE_20200508;

/*!
 * @const IMG4_BUFF_INIT
 * A convenience initializer for the {@link img4_buff_t} structure.
 */
#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
#define IMG4_BUFF_INIT (img4_buff_t){ \
	.i4b_version = IMG4_BUFF_STRUCT_VERSION, \
	.i4b_len = 0, \
	.i4b_bytes = NULL, \
	.i4b_dealloc = NULL, \
}
#elif defined(__cplusplus) && __cplusplus >= 201103L
#define IMG4_BUFF_INIT (img4_buff_t{ \
	IMG4_BUFF_STRUCT_VERSION, \
	NULL, \
	0, \
	NULL, \
})
#elif defined(__cplusplus)
#define IMG4_BUFF_INIT (img4_buff_t((img4_buff_t){ \
	IMG4_BUFF_STRUCT_VERSION, \
	NULL, \
	0, \
	NULL, \
}))
#else
#define IMG4_BUFF_INIT {IMG4_BUFF_STRUCT_VERSION}
#endif

/*!
 * @define IMG4_RUNTIME_STRUCT_VERSION
 * The version of the {@link img4_runtime_t} structure supported by the
 * implementation.
 */
#define IMG4_RUNTIME_STRUCT_VERSION (5u)

/*!
 * @struct _img4_runtime
 * A structure describing required primitives in the operating environment's
 * runtime.
 *
 * @field i4rt_version
 * The version of the structure supported by the implementation. In a custom
 * execution context, initialize to {@link IMG4_RUNTIME_STRUCT_VERSION}.
 *
 * @field i4rt_name
 * A string describing the environment.
 *
 * @field i4rt_init
 * The runtime initialization function. See discussion in
 * {@link img4_runtime_init_t}.
 *
 * @field i4rt_alloc
 * The allocation function for the environment (e.g. in Darwin userspace, this
 * would be a pointer to malloc(3)). The memory returned is expected to be zero-
 * filled.
 *
 * @field i4rt_dealloc
 * The deallocation function for the environment (e.g. in Darwin userspace, this
 * would be a pointer to free(3)).
 *
 * @field i4rt_log
 * The function which logs messages from the implementation.
 *
 * @field i4rt_log_handle
 * The function which returns the handle to be passed to the logging function.
 *
 * @field i4rt_get_identifier_bool
 * The function which returns Boolean identifiers.
 *
 * @field i4rt_get_identifier_uint32
 * The function which returns unsigned 32-bit integer identifiers.
 *
 * @field i4rt_get_identifier_uint64
 * The function which returns unsigned 64-bit integer identifiers.
 *
 * @field i4rt_get_identifier_digest
 * The function which returns digest identifiers.
 *
 * @field i4rt_context
 * A user-defined context pointer. Introduced in version 1 of the structure.
 *
 * @field i4rt_get_identifier_cstr
 * The function which returns C-string identifiers. Introduced in version 2 of
 * the structure.
 *
 * @field i4rt_execute_object
 * The function which executes objects. Introduced in version 3 of the
 * structure.
 *
 * @field i4rt_copy_object
 * The function which copies objects. Introduced in version 3 of the structure.
 *
 * @field i4rt_alloc_type
 * The typed allocation function for the environment. This allocator should be
 * used for any fixed-size, structured allocation that may contain pointers.
 *
 * The memory returned is expected to be zero-filled. Introduced in version 4 of
 * the structure.
 *
 * @field i4rt_dealloc_type
 * The typed deallocation function for the environment. Introduced in version 4
 * of the structure.
 *
 * @field i4rt_set_nonce
 * The nonce-set function for the environment. Introduced in version 5 of the
 * structure.
 *
 * @field i4rt_roll_nonce
 * The nonce-roll function for the environment. Introduced in version 5 of the
 * structure.
 *
 * @field i4rt_roll_nonce
 * The nonce-copy function for the environment. Introduced in version 5 of the
 * structure.
 */
struct _img4_runtime {
	img4_struct_version_t i4rt_version;
	const char *i4rt_name;
	img4_runtime_init_t _Nullable i4rt_init;
	img4_runtime_alloc_t i4rt_alloc;
	img4_runtime_dealloc_t i4rt_dealloc;
	img4_runtime_log_t i4rt_log;
	img4_runtime_log_handle_t i4rt_log_handle;
	img4_runtime_get_identifier_bool_t i4rt_get_identifier_bool;
	img4_runtime_get_identifier_uint32_t i4rt_get_identifier_uint32;
	img4_runtime_get_identifier_uint64_t i4rt_get_identifier_uint64;
	img4_runtime_get_identifier_digest_t i4rt_get_identifier_digest;
	void *_Nullable i4rt_context;
	img4_runtime_get_identifier_cstr_t i4rt_get_identifier_cstr;
	img4_runtime_execute_object_t i4rt_execute_object;
	img4_runtime_copy_object_t i4rt_copy_object;
	img4_runtime_alloc_type_t i4rt_alloc_type;
	img4_runtime_dealloc_type_t i4rt_dealloc_type;
	img4_runtime_set_nonce_t i4rt_set_nonce;
	img4_runtime_roll_nonce_t i4rt_roll_nonce;
	img4_runtime_copy_nonce_t i4rt_copy_nonce;
} IMG4_API_AVAILABLE_20200508;

/*!
 * @function IMG4_RUNTIME_REGISTER
 * Registers a runtime with the module implementation such that its
 * initialization function can be called. In environments which support dynamic
 * library linkage, only runtimes registered from the main executable image can
 * be discovered by the implementation.
 *
 * @param _rt
 * The img4_runtime_t structure to register.
 */
#define IMG4_RUNTIME_REGISTER(_rt) LINKER_SET_ENTRY(__img4_rt, _rt);

/*!
 * @const IMG4_RUNTIME_DEFAULT
 * The default runtime for the current operating environment.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_runtime_t _img4_runtime_default;
#define IMG4_RUNTIME_DEFAULT (&_img4_runtime_default)
#else
#define IMG4_RUNTIME_DEFAULT (img4if->i4if_v7.runtime_default)
#endif

/*!
 * @const IMG4_RUNTIME_PMAP_CS
 * The runtime for the xnu pmap layer which is safe to be executed in a
 * supervisor execution level if supported by hardware. This runtime is not
 * available outside the kernel-proper.
 */
#if XNU_KERNEL_PRIVATE
#define IMG4_RUNTIME_PMAP_CS (img4if->i4if_v7.runtime_pmap_cs)
#elif _DARWIN_BUILDING_TARGET_APPLEIMAGE4
#define IMG4_RUNTIME_PMAP_CS (&_img4_runtime_pmap_cs)
#endif

/*!
 * @const IMG4_RUNTIME_RESTORE
 * The runtime for the restore ramdisk. This runtime is not available outside
 * of the Darwin userspace library.
 */
#if !KERNEL
IMG4_API_AVAILABLE_20200508
OS_EXPORT
const img4_runtime_t _img4_runtime_restore;
#define IMG4_RUNTIME_RESTORE (&_img4_runtime_restore)
#endif

/*!
 * @function img4_buff_dealloc
 * Deallocates a buffer according to its deallocation function.
 *
 * @param buff
 * A pointer to the a pointer to the buffer. This parameter may be NULL, in
 * which case the implementation will return immediately.
 *
 * @discussion
 * This interface will always invoke the deallocation callback with
 * {@link IMG4_RUNTIME_DEFAULT}. The callee should not consult this parameter
 * for any reason.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT
void
img4_buff_dealloc(img4_buff_t *_Nullable buff);
#else
#define img4_buff_dealloc(...) (img4if->i4if_v7.buff_dealloc(__VA_ARGS__))
#endif

#pragma mark Object Specifications
/*!
 * @const IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT
 * The DER representation of the certificate to use as the root of trust for
 * evaluating the supplemental software package. This object can only be
 * executed once for any given boot session.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20210205
OS_EXPORT
const img4_runtime_object_spec_t _img4_runtime_object_spec_supplemental_root;
#define IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT \
		(&_img4_runtime_object_spec_supplemental_root)
#else
#define IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT \
		(img4if->i4if_v11.runtime_object_spec_supplemental_root)
#endif

/*!
 * @const IMG4_RUNTIME_OBJECT_SPEC_LOCAL_POLICY
 * The local policy object which has been authorized by the user for a
 * subsequent boot of the system. This object may be executed multiple times in
 * a given boot session. A subsequent local policy must have been authorized by
 * the user after the currently-active one in order to successfully execute.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20210205
OS_EXPORT
const img4_runtime_object_spec_t _img4_runtime_object_spec_local_policy;
#define IMG4_RUNTIME_OBJECT_SPEC_LOCAL_POLICY \
		(&_img4_runtime_object_spec_local_policy)
#else
#define IMG4_RUNTIME_OBJECT_SPEC_LOCAL_POLICY \
		(img4if->i4if_v18.runtime_object_spec_local_policy)
#endif

#pragma mark API
/*!
 * @function img4_runtime_find_object_spec
 * Returns the object specification for the given four-character code.
 *
 * @param _4cc
 * The four-character code for which to find the object specification.
 *
 * @result
 * The object specification, or NULL if the four-character code is not an
 * executable object known to the implementation.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20210205
OS_EXPORT OS_WARN_RESULT
const img4_runtime_object_spec_t *_Nullable
img4_runtime_find_object_spec(img4_4cc_t _4cc);
#else
#define img4_runtime_find_object_spec(...) \
		(img4if->i4if_v11.runtime_find_object_spec(__VA_ARGS__))
#endif

/*!
 * @function img4_runtime_execute_object
 * Executes an object within the runtime.
 *
 * @param rt
 * The runtime in which to execute the object.
 *
 * @param obj_spec
 * The specification for the object.
 *
 * @param obj
 * The buffer representing the object. The structure and form of the bytes
 * is dictated by the object specification. Usually, these bytes are a wrapped
 * Image4 payload.
 *
 * @param manifest
 * The Image4 manifest authenticating the object. If the object has a manifest
 * stitched to it, this parameter may be NULL.
 *
 * @result
 * Upon success, zero is returned. Otherwise, one of the following error codes:
 *
 *     [EPERM]     The caller does not have permission to set the object
 *     [EALREADY]  The object may only be set once, and it has already been set
 *
 * Any error code returned by {@link img4_firmware_evaluate} may also be
 * returned.
 *
 * Any error code returned by the runtime's {@link i4rt_execute_object} callback
 * will also be returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20210205
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2 OS_NONNULL3
errno_t
img4_runtime_execute_object(const img4_runtime_t *rt,
		const img4_runtime_object_spec_t *obj_spec,
		const img4_buff_t *obj,
		const img4_buff_t *_Nullable manifest);
#else
#define img4_runtime_execute_object(...) \
		(img4if->i4if_v11.runtime_execute_object(__VA_ARGS__))
#endif

/*!
 * @function img4_runtime_copy_object
 * Copies the payload of an object executed within the runtime.
 *
 * @param rt
 * The runtime in which to query the object.
 *
 * @param obj_spec
 * The specification for the object.
 *
 * @param payload
 * Upon successful return, a pointer to a buffer object which refers to storage
 * that will hold the payload.
 *
 * @param payload_len
 * Upon successful return, a pointer to the total number of bytes coped into the
 * buffer referred to by {@link payload}. This parameter may be NULL.
 *
 * In the event that buffer referred to be {@link payload} is not large enough,
 * this parameter will be set to the total number of bytes required.
 *
 * @result
 * Upon success, zero is returned. Otherwise, one of the following error codes:
 *
 *     [EPERM]    The caller does not have permission to copy the object
 *     [ENOENT]   The requested object is not present
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20210205
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2 OS_NONNULL3
errno_t
img4_runtime_copy_object(const img4_runtime_t *rt,
		const img4_runtime_object_spec_t *obj_spec,
		img4_buff_t *payload,
		size_t *_Nullable payload_len);
#else
#define img4_runtime_copy_object(...) \
		(img4if->i4if_v11.runtime_copy_object(__VA_ARGS__))
#endif

OS_ASSUME_PTR_ABI_SINGLE_END
OS_ASSUME_NONNULL_END
__END_DECLS

#endif // __IMG4_RUNTIME_H