1/*!
2 * @header
3 * Supported coprocessors.
4 */
5#ifndef __IMAGE4_API_COPROCESSOR_H
6#define __IMAGE4_API_COPROCESSOR_H
7
8#include <image4/image4.h>
9#include <image4/types.h>
10
11__BEGIN_DECLS
12OS_ASSUME_NONNULL_BEGIN
13OS_ASSUME_PTR_ABI_SINGLE_BEGIN
14
15/*!
16 * @const IMAGE4_COPROCESSOR_HOST
17 * The host execution environment. This environment does not support handles.
18 */
19IMAGE4_API_AVAILABLE_SPRING_2024
20OS_EXPORT
21const image4_coprocessor_t _image4_coprocessor_host;
22#define IMAGE4_COPROCESSOR_HOST (&_image4_coprocessor_host)
23IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_coprocessor_host);
24
25/*!
26 * @const IMAGE4_COPROCESSOR_AP
27 * The Application Processor executing payloads signed by the Secure Boot CA.
28 *
29 * Handles for this environment are enumerated in the
30 * {@link image4_coprocessor_ap_handle_t} type.
31 */
32IMAGE4_API_AVAILABLE_SPRING_2024
33OS_EXPORT
34const image4_coprocessor_t _image4_coprocessor_ap;
35#define IMAGE4_COPROCESSOR_AP (&_image4_coprocessor_ap)
36IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_coprocessor_ap);
37
38/*!
39 * @typedef image4_coprocessor_handle_ap_t
40 * Handles describing supported AP execution environments.
41 *
42 * @const IMAGE4_COPROCESSOR_HANDLE_AP
43 * The host's Application Processor environment.
44 *
45 * @const IMAGE4_COPROCESSOR_HANDLE_AP_FF00
46 * The software AP environment used for loading globally-signed OTA update brain
47 * trust caches.
48 *
49 * @const IMAGE4_COPROCESSOR_HANDLE_AP_FF01
50 * The software AP environment used for loading globally-signed Install
51 * Assistant brain trust caches.
52 *
53 * @const IMAGE4_COPROCESSOR_HANDLE_AP_FF06
54 * The software AP environment used for loading globally-signed Bootability
55 * brain trust caches.
56 *
57 * @const IMAGE4_COPROCESSOR_HANDLE_AP_PDI
58 * The sideloading AP environment used to load a personalized disk image.
59 *
60 * @const IMAGE4_COPROCESSOR_HANDLE_AP_SRDP
61 * The sideloading AP environment used to load firmware which has been
62 * authorized as part of the Security Research Device Program.
63 *
64 * @const IMAGE4_COPROCESSOR_HANDLE_AP_DDI
65 * The sideloading AP environment used to load a personalized disk image which
66 * is automatically mounted at boot.
67 *
68 * This handle is available starting in API version 20231027.
69 */
70OS_CLOSED_ENUM(image4_coprocessor_handle_ap, image4_coprocessor_handle_t,
71 IMAGE4_COPROCESSOR_HANDLE_AP = 0,
72 IMAGE4_COPROCESSOR_HANDLE_AP_FF00,
73 IMAGE4_COPROCESSOR_HANDLE_AP_FF01,
74 IMAGE4_COPROCESSOR_HANDLE_AP_FF06,
75 IMAGE4_COPROCESSOR_HANDLE_AP_PDI,
76 IMAGE4_COPROCESSOR_HANDLE_AP_SRDP,
77 IMAGE4_COPROCESSOR_HANDLE_AP_RESERVED_0,
78 IMAGE4_COPROCESSOR_HANDLE_AP_RESERVED_1,
79 IMAGE4_COPROCESSOR_HANDLE_AP_RESERVED_2,
80 IMAGE4_COPROCESSOR_HANDLE_AP_DDI,
81 _IMAGE4_COPROCESSOR_HANDLE_AP_CNT,
82);
83
84/*!
85 * @const IMAGE4_COPROCESSOR_AP_LOCAL
86 * The Application Processor executing payloads signed by the Basic Attestation
87 * Authority.
88 *
89 * Handles for this environment are enumerated in the
90 * {@link image4_coprocessor_handle_ap_local_t} type.
91 */
92IMAGE4_API_AVAILABLE_SPRING_2024
93OS_EXPORT
94const image4_coprocessor_t _image4_coprocessor_ap_local;
95#define IMAGE4_COPROCESSOR_AP_LOCAL (&_image4_coprocessor_ap_local)
96IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_coprocessor_ap_local);
97
98/*!
99 * @typedef image4_coprocessor_handle_ap_local_t
100 * Handles describing supported local policy execution environments.
101 *
102 * @const IMAGE4_COPROCESSOR_HANDLE_AP_LOCAL
103 * The host's local policy environment.
104 */
105
106OS_CLOSED_ENUM(image4_coprocessor_handle_ap_local, image4_coprocessor_handle_t,
107 IMAGE4_COPROCESSOR_HANDLE_AP_LOCAL = 0,
108 IMAGE4_COPROCESSOR_HANDLE_AP_LOCAL_RESERVED_0,
109 IMAGE4_COPROCESSOR_HANDLE_AP_LOCAL_RESERVED_1,
110 IMAGE4_COPROCESSOR_HANDLE_AP_LOCAL_RESERVED_2,
111 _IMAGE4_COPROCESSOR_HANDLE_AP_LOCAL_CNT,
112);
113
114/*!
115 * @const IMAGE4_COPROCESSOR_CRYPTEX1
116 * The Cryptex1 coprocessor executing payloads signed by the Secure Boot CA.
117 *
118 * Handles for this environment are enumerated in the
119 * {@link image4_coprocessor_handle_cryptex1_t} type.
120 */
121IMAGE4_API_AVAILABLE_SPRING_2024
122OS_EXPORT
123const image4_coprocessor_t _image4_coprocessor_cryptex1;
124#define IMAGE4_COPROCESSOR_CRYPTEX1 (&_image4_coprocessor_cryptex1)
125IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_coprocessor_cryptex1);
126
127/*!
128 * @typedef image4_coprocessor_handle_cryptex1_t
129 * Handles describing supported Cryptex1 execution environments.
130 *
131 * @const IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_BOOT
132 * The host's Cryptex1 boot coprocessor.
133 *
134 * @const IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_BOOT_LIVE
135 * The host's Cryptex1 boot coprocessor used for executing newly-authorized
136 * firmware prior to that firmware being evaluated by Secure Boot.
137 *
138 * @const IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_ASSET_BRAIN
139 * The host's Cryptex1 coprocessor used for loading MobileAsset brain firmware.
140 *
141 * @const IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_GENERIC
142 * The host's Cryptex1 coprocessor used for loading generic supplemental
143 * content.
144 */
145OS_CLOSED_ENUM(image4_coprocessor_handle_cryptex1, image4_coprocessor_handle_t,
146 IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_BOOT = 0,
147 IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_BOOT_LIVE,
148 IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_ASSET_BRAIN,
149 IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_GENERIC,
150 IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_RESERVED_0,
151 IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_RESERVED_1,
152 IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_RESERVED_2,
153 _IMAGE4_COPROCESSOR_HANDLE_CRYPTEX1_CNT,
154);
155
156/*!
157 * @const IMAGE4_COPROCESSOR_SEP
158 * The Secure Enclave Processor executing payloads signed by the Secure Boot CA.
159 *
160 * Handles for this environment are enumerated in the
161 * {@link image4_coprocessor_handle_sep_t} type.
162 */
163IMAGE4_API_AVAILABLE_SPRING_2024
164OS_EXPORT
165const image4_coprocessor_t _image4_coprocessor_sep;
166#define IMAGE4_COPROCESSOR_SEP (&_image4_coprocessor_sep)
167IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_coprocessor_sep);
168
169/*!
170 * @typedef image4_coprocessor_handle_sep_t
171 * Handles describing supported SEP execution environments.
172 *
173 * @const IMAGE4_COPROCESSOR_HANDLE_SEP
174 * The host's SEP environment.
175 */
176OS_CLOSED_ENUM(image4_coprocessor_handle_sep, image4_coprocessor_handle_t,
177 IMAGE4_COPROCESSOR_HANDLE_SEP = 0,
178 _IMAGE4_COPROCESSOR_HANDLE_SEP_CNT,
179);
180
181/*!
182 * @const IMAGE4_COPROCESSOR_X86
183 * An x86 processor executing payloads signed by the x86 Secure Boot CA.
184 *
185 * Handles for this environment are enumerated in the
186 * {@link image4_coprocessor_handle_x86_t} type.
187 */
188IMAGE4_API_AVAILABLE_SPRING_2024
189OS_EXPORT
190const image4_coprocessor_t _image4_coprocessor_x86;
191#define IMAGE4_COPROCESSOR_X86 (&_image4_coprocessor_x86)
192IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_coprocessor_x86);
193
194/*!
195 * @typedef image4_coprocessor_handle_x86_t
196 * Handles describing supported x86 execution environments.
197 *
198 * @const IMAGE4_COPROCESSOR_HANDLE_X86
199 * The host's x86 environment.
200 */
201OS_CLOSED_ENUM(image4_coprocessor_handle_x86, image4_coprocessor_handle_t,
202 IMAGE4_COPROCESSOR_HANDLE_X86 = 0,
203 _IMAGE4_COPROCESSOR_HANDLE_X86_CNT,
204);
205
206OS_ASSUME_PTR_ABI_SINGLE_END
207OS_ASSUME_NONNULL_END
208__END_DECLS
209
210#endif // __IMAGE4_API_COPROCESSOR_H
211