1/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
2/*
3 * Copyright 2020-2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 */
5
6#ifndef _LINUX_NITRO_ENCLAVES_H_
7#define _LINUX_NITRO_ENCLAVES_H_
8
9#include <linux/types.h>
10
11/**
12 * DOC: Nitro Enclaves (NE) Kernel Driver Interface
13 */
14
15/**
16 * NE_CREATE_VM - The command is used to create a slot that is associated with
17 * an enclave VM.
18 * The generated unique slot id is an output parameter.
19 * The ioctl can be invoked on the /dev/nitro_enclaves fd, before
20 * setting any resources, such as memory and vCPUs, for an
21 * enclave. Memory and vCPUs are set for the slot mapped to an enclave.
22 * A NE CPU pool has to be set before calling this function. The
23 * pool can be set after the NE driver load, using
24 * /sys/module/nitro_enclaves/parameters/ne_cpus.
25 * Its format is the detailed in the cpu-lists section:
26 * https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html
27 * CPU 0 and its siblings have to remain available for the
28 * primary / parent VM, so they cannot be set for enclaves. Full
29 * CPU core(s), from the same NUMA node, need(s) to be included
30 * in the CPU pool.
31 *
32 * Context: Process context.
33 * Return:
34 * * Enclave file descriptor - Enclave file descriptor used with
35 * ioctl calls to set vCPUs and memory
36 * regions, then start the enclave.
37 * * -1 - There was a failure in the ioctl logic.
38 * On failure, errno is set to:
39 * * EFAULT - copy_to_user() failure.
40 * * ENOMEM - Memory allocation failure for internal
41 * bookkeeping variables.
42 * * NE_ERR_NO_CPUS_AVAIL_IN_POOL - No NE CPU pool set / no CPUs available
43 * in the pool.
44 * * Error codes from get_unused_fd_flags() and anon_inode_getfile().
45 * * Error codes from the NE PCI device request.
46 */
47#define NE_CREATE_VM _IOR(0xAE, 0x20, __u64)
48
49/**
50 * NE_ADD_VCPU - The command is used to set a vCPU for an enclave. The vCPU can
51 * be auto-chosen from the NE CPU pool or it can be set by the
52 * caller, with the note that it needs to be available in the NE
53 * CPU pool. Full CPU core(s), from the same NUMA node, need(s) to
54 * be associated with an enclave.
55 * The vCPU id is an input / output parameter. If its value is 0,
56 * then a CPU is chosen from the enclave CPU pool and returned via
57 * this parameter.
58 * The ioctl can be invoked on the enclave fd, before an enclave
59 * is started.
60 *
61 * Context: Process context.
62 * Return:
63 * * 0 - Logic successfully completed.
64 * * -1 - There was a failure in the ioctl logic.
65 * On failure, errno is set to:
66 * * EFAULT - copy_from_user() / copy_to_user() failure.
67 * * ENOMEM - Memory allocation failure for internal
68 * bookkeeping variables.
69 * * EIO - Current task mm is not the same as the one
70 * that created the enclave.
71 * * NE_ERR_NO_CPUS_AVAIL_IN_POOL - No CPUs available in the NE CPU pool.
72 * * NE_ERR_VCPU_ALREADY_USED - The provided vCPU is already used.
73 * * NE_ERR_VCPU_NOT_IN_CPU_POOL - The provided vCPU is not available in the
74 * NE CPU pool.
75 * * NE_ERR_VCPU_INVALID_CPU_CORE - The core id of the provided vCPU is invalid
76 * or out of range.
77 * * NE_ERR_NOT_IN_INIT_STATE - The enclave is not in init state
78 * (init = before being started).
79 * * NE_ERR_INVALID_VCPU - The provided vCPU is not in the available
80 * CPUs range.
81 * * Error codes from the NE PCI device request.
82 */
83#define NE_ADD_VCPU _IOWR(0xAE, 0x21, __u32)
84
85/**
86 * NE_GET_IMAGE_LOAD_INFO - The command is used to get information needed for
87 * in-memory enclave image loading e.g. offset in
88 * enclave memory to start placing the enclave image.
89 * The image load info is an input / output parameter.
90 * It includes info provided by the caller - flags -
91 * and returns the offset in enclave memory where to
92 * start placing the enclave image.
93 * The ioctl can be invoked on the enclave fd, before
94 * an enclave is started.
95 *
96 * Context: Process context.
97 * Return:
98 * * 0 - Logic successfully completed.
99 * * -1 - There was a failure in the ioctl logic.
100 * On failure, errno is set to:
101 * * EFAULT - copy_from_user() / copy_to_user() failure.
102 * * NE_ERR_NOT_IN_INIT_STATE - The enclave is not in init state (init =
103 * before being started).
104 * * NE_ERR_INVALID_FLAG_VALUE - The value of the provided flag is invalid.
105 */
106#define NE_GET_IMAGE_LOAD_INFO _IOWR(0xAE, 0x22, struct ne_image_load_info)
107
108/**
109 * NE_SET_USER_MEMORY_REGION - The command is used to set a memory region for an
110 * enclave, given the allocated memory from the
111 * userspace. Enclave memory needs to be from the
112 * same NUMA node as the enclave CPUs.
113 * The user memory region is an input parameter. It
114 * includes info provided by the caller - flags,
115 * memory size and userspace address.
116 * The ioctl can be invoked on the enclave fd,
117 * before an enclave is started.
118 *
119 * Context: Process context.
120 * Return:
121 * * 0 - Logic successfully completed.
122 * * -1 - There was a failure in the ioctl logic.
123 * On failure, errno is set to:
124 * * EFAULT - copy_from_user() failure.
125 * * EINVAL - Invalid physical memory region(s) e.g.
126 * unaligned address.
127 * * EIO - Current task mm is not the same as
128 * the one that created the enclave.
129 * * ENOMEM - Memory allocation failure for internal
130 * bookkeeping variables.
131 * * NE_ERR_NOT_IN_INIT_STATE - The enclave is not in init state
132 * (init = before being started).
133 * * NE_ERR_INVALID_MEM_REGION_SIZE - The memory size of the region is not
134 * multiple of 2 MiB.
135 * * NE_ERR_INVALID_MEM_REGION_ADDR - Invalid user space address given.
136 * * NE_ERR_UNALIGNED_MEM_REGION_ADDR - Unaligned user space address given.
137 * * NE_ERR_MEM_REGION_ALREADY_USED - The memory region is already used.
138 * * NE_ERR_MEM_NOT_HUGE_PAGE - The memory region is not backed by
139 * huge pages.
140 * * NE_ERR_MEM_DIFFERENT_NUMA_NODE - The memory region is not from the same
141 * NUMA node as the CPUs.
142 * * NE_ERR_MEM_MAX_REGIONS - The number of memory regions set for
143 * the enclave reached maximum.
144 * * NE_ERR_INVALID_PAGE_SIZE - The memory region is not backed by
145 * pages multiple of 2 MiB.
146 * * NE_ERR_INVALID_FLAG_VALUE - The value of the provided flag is invalid.
147 * * Error codes from get_user_pages().
148 * * Error codes from the NE PCI device request.
149 */
150#define NE_SET_USER_MEMORY_REGION _IOW(0xAE, 0x23, struct ne_user_memory_region)
151
152/**
153 * NE_START_ENCLAVE - The command is used to trigger enclave start after the
154 * enclave resources, such as memory and CPU, have been set.
155 * The enclave start info is an input / output parameter. It
156 * includes info provided by the caller - enclave cid and
157 * flags - and returns the cid (if input cid is 0).
158 * The ioctl can be invoked on the enclave fd, after an
159 * enclave slot is created and resources, such as memory and
160 * vCPUs are set for an enclave.
161 *
162 * Context: Process context.
163 * Return:
164 * * 0 - Logic successfully completed.
165 * * -1 - There was a failure in the ioctl logic.
166 * On failure, errno is set to:
167 * * EFAULT - copy_from_user() / copy_to_user() failure.
168 * * NE_ERR_NOT_IN_INIT_STATE - The enclave is not in init state
169 * (init = before being started).
170 * * NE_ERR_NO_MEM_REGIONS_ADDED - No memory regions are set.
171 * * NE_ERR_NO_VCPUS_ADDED - No vCPUs are set.
172 * * NE_ERR_FULL_CORES_NOT_USED - Full core(s) not set for the enclave.
173 * * NE_ERR_ENCLAVE_MEM_MIN_SIZE - Enclave memory is less than minimum
174 * memory size (64 MiB).
175 * * NE_ERR_INVALID_FLAG_VALUE - The value of the provided flag is invalid.
176 * * NE_ERR_INVALID_ENCLAVE_CID - The provided enclave CID is invalid.
177 * * Error codes from the NE PCI device request.
178 */
179#define NE_START_ENCLAVE _IOWR(0xAE, 0x24, struct ne_enclave_start_info)
180
181/**
182 * DOC: NE specific error codes
183 */
184
185/**
186 * NE_ERR_VCPU_ALREADY_USED - The provided vCPU is already used.
187 */
188#define NE_ERR_VCPU_ALREADY_USED (256)
189/**
190 * NE_ERR_VCPU_NOT_IN_CPU_POOL - The provided vCPU is not available in the
191 * NE CPU pool.
192 */
193#define NE_ERR_VCPU_NOT_IN_CPU_POOL (257)
194/**
195 * NE_ERR_VCPU_INVALID_CPU_CORE - The core id of the provided vCPU is invalid
196 * or out of range of the NE CPU pool.
197 */
198#define NE_ERR_VCPU_INVALID_CPU_CORE (258)
199/**
200 * NE_ERR_INVALID_MEM_REGION_SIZE - The user space memory region size is not
201 * multiple of 2 MiB.
202 */
203#define NE_ERR_INVALID_MEM_REGION_SIZE (259)
204/**
205 * NE_ERR_INVALID_MEM_REGION_ADDR - The user space memory region address range
206 * is invalid.
207 */
208#define NE_ERR_INVALID_MEM_REGION_ADDR (260)
209/**
210 * NE_ERR_UNALIGNED_MEM_REGION_ADDR - The user space memory region address is
211 * not aligned.
212 */
213#define NE_ERR_UNALIGNED_MEM_REGION_ADDR (261)
214/**
215 * NE_ERR_MEM_REGION_ALREADY_USED - The user space memory region is already used.
216 */
217#define NE_ERR_MEM_REGION_ALREADY_USED (262)
218/**
219 * NE_ERR_MEM_NOT_HUGE_PAGE - The user space memory region is not backed by
220 * contiguous physical huge page(s).
221 */
222#define NE_ERR_MEM_NOT_HUGE_PAGE (263)
223/**
224 * NE_ERR_MEM_DIFFERENT_NUMA_NODE - The user space memory region is backed by
225 * pages from different NUMA nodes than the CPUs.
226 */
227#define NE_ERR_MEM_DIFFERENT_NUMA_NODE (264)
228/**
229 * NE_ERR_MEM_MAX_REGIONS - The supported max memory regions per enclaves has
230 * been reached.
231 */
232#define NE_ERR_MEM_MAX_REGIONS (265)
233/**
234 * NE_ERR_NO_MEM_REGIONS_ADDED - The command to start an enclave is triggered
235 * and no memory regions are added.
236 */
237#define NE_ERR_NO_MEM_REGIONS_ADDED (266)
238/**
239 * NE_ERR_NO_VCPUS_ADDED - The command to start an enclave is triggered and no
240 * vCPUs are added.
241 */
242#define NE_ERR_NO_VCPUS_ADDED (267)
243/**
244 * NE_ERR_ENCLAVE_MEM_MIN_SIZE - The enclave memory size is lower than the
245 * minimum supported.
246 */
247#define NE_ERR_ENCLAVE_MEM_MIN_SIZE (268)
248/**
249 * NE_ERR_FULL_CORES_NOT_USED - The command to start an enclave is triggered and
250 * full CPU cores are not set.
251 */
252#define NE_ERR_FULL_CORES_NOT_USED (269)
253/**
254 * NE_ERR_NOT_IN_INIT_STATE - The enclave is not in init state when setting
255 * resources or triggering start.
256 */
257#define NE_ERR_NOT_IN_INIT_STATE (270)
258/**
259 * NE_ERR_INVALID_VCPU - The provided vCPU is out of range of the available CPUs.
260 */
261#define NE_ERR_INVALID_VCPU (271)
262/**
263 * NE_ERR_NO_CPUS_AVAIL_IN_POOL - The command to create an enclave is triggered
264 * and no CPUs are available in the pool.
265 */
266#define NE_ERR_NO_CPUS_AVAIL_IN_POOL (272)
267/**
268 * NE_ERR_INVALID_PAGE_SIZE - The user space memory region is not backed by pages
269 * multiple of 2 MiB.
270 */
271#define NE_ERR_INVALID_PAGE_SIZE (273)
272/**
273 * NE_ERR_INVALID_FLAG_VALUE - The provided flag value is invalid.
274 */
275#define NE_ERR_INVALID_FLAG_VALUE (274)
276/**
277 * NE_ERR_INVALID_ENCLAVE_CID - The provided enclave CID is invalid, either
278 * being a well-known value or the CID of the
279 * parent / primary VM.
280 */
281#define NE_ERR_INVALID_ENCLAVE_CID (275)
282
283/**
284 * DOC: Image load info flags
285 */
286
287/**
288 * NE_EIF_IMAGE - Enclave Image Format (EIF)
289 */
290#define NE_EIF_IMAGE (0x01)
291
292#define NE_IMAGE_LOAD_MAX_FLAG_VAL (0x02)
293
294/**
295 * struct ne_image_load_info - Info necessary for in-memory enclave image
296 * loading (in / out).
297 * @flags: Flags to determine the enclave image type
298 * (e.g. Enclave Image Format - EIF) (in).
299 * @memory_offset: Offset in enclave memory where to start placing the
300 * enclave image (out).
301 */
302struct ne_image_load_info {
303 __u64 flags;
304 __u64 memory_offset;
305};
306
307/**
308 * DOC: User memory region flags
309 */
310
311/**
312 * NE_DEFAULT_MEMORY_REGION - Memory region for enclave general usage.
313 */
314#define NE_DEFAULT_MEMORY_REGION (0x00)
315
316#define NE_MEMORY_REGION_MAX_FLAG_VAL (0x01)
317
318/**
319 * struct ne_user_memory_region - Memory region to be set for an enclave (in).
320 * @flags: Flags to determine the usage for the memory region (in).
321 * @memory_size: The size, in bytes, of the memory region to be set for
322 * an enclave (in).
323 * @userspace_addr: The start address of the userspace allocated memory of
324 * the memory region to set for an enclave (in).
325 */
326struct ne_user_memory_region {
327 __u64 flags;
328 __u64 memory_size;
329 __u64 userspace_addr;
330};
331
332/**
333 * DOC: Enclave start info flags
334 */
335
336/**
337 * NE_ENCLAVE_PRODUCTION_MODE - Start enclave in production mode.
338 */
339#define NE_ENCLAVE_PRODUCTION_MODE (0x00)
340/**
341 * NE_ENCLAVE_DEBUG_MODE - Start enclave in debug mode.
342 */
343#define NE_ENCLAVE_DEBUG_MODE (0x01)
344
345#define NE_ENCLAVE_START_MAX_FLAG_VAL (0x02)
346
347/**
348 * struct ne_enclave_start_info - Setup info necessary for enclave start (in / out).
349 * @flags: Flags for the enclave to start with (e.g. debug mode) (in).
350 * @enclave_cid: Context ID (CID) for the enclave vsock device. If 0 as
351 * input, the CID is autogenerated by the hypervisor and
352 * returned back as output by the driver (in / out).
353 */
354struct ne_enclave_start_info {
355 __u64 flags;
356 __u64 enclave_cid;
357};
358
359#endif /* _LINUX_NITRO_ENCLAVES_H_ */