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 _UAPI_LINUX_NITRO_ENCLAVES_H_ 7 #define _UAPI_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 */ 302 struct 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 */ 326 struct 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 */ 354 struct ne_enclave_start_info { 355 __u64 flags; 356 __u64 enclave_cid; 357 }; 358 359 #endif /* _UAPI_LINUX_NITRO_ENCLAVES_H_ */ 360