uapi/linux/nitro_enclaves.h

0001 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
0002 /*
0003  * Copyright 2020-2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
0004  */
0005
0006 #ifndef _UAPI_LINUX_NITRO_ENCLAVES_H_
0007 #define _UAPI_LINUX_NITRO_ENCLAVES_H_
0008
0009 #include <linux/types.h>
0010
0011 /**
0012  * DOC: Nitro Enclaves (NE) Kernel Driver Interface
0013  */
0014
0015 /**
0016  * NE_CREATE_VM - The command is used to create a slot that is associated with
0017  *        an enclave VM.
0018  *        The generated unique slot id is an output parameter.
0019  *        The ioctl can be invoked on the /dev/nitro_enclaves fd, before
0020  *        setting any resources, such as memory and vCPUs, for an
0021  *        enclave. Memory and vCPUs are set for the slot mapped to an enclave.
0022  *        A NE CPU pool has to be set before calling this function. The
0023  *        pool can be set after the NE driver load, using
0024  *        /sys/module/nitro_enclaves/parameters/ne_cpus.
0025  *        Its format is the detailed in the cpu-lists section:
0026  *        https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html
0027  *        CPU 0 and its siblings have to remain available for the
0028  *        primary / parent VM, so they cannot be set for enclaves. Full
0029  *        CPU core(s), from the same NUMA node, need(s) to be included
0030  *        in the CPU pool.
0031  *
0032  * Context: Process context.
0033  * Return:
0034  * * Enclave file descriptor        - Enclave file descriptor used with
0035  *                    ioctl calls to set vCPUs and memory
0036  *                    regions, then start the enclave.
0037  * *  -1                - There was a failure in the ioctl logic.
0038  * On failure, errno is set to:
0039  * * EFAULT             - copy_to_user() failure.
0040  * * ENOMEM             - Memory allocation failure for internal
0041  *                    bookkeeping variables.
0042  * * NE_ERR_NO_CPUS_AVAIL_IN_POOL   - No NE CPU pool set / no CPUs available
0043  *                    in the pool.
0044  * * Error codes from get_unused_fd_flags() and anon_inode_getfile().
0045  * * Error codes from the NE PCI device request.
0046  */
0047 #define NE_CREATE_VM            _IOR(0xAE, 0x20, __u64)
0048
0049 /**
0050  * NE_ADD_VCPU - The command is used to set a vCPU for an enclave. The vCPU can
0051  *       be auto-chosen from the NE CPU pool or it can be set by the
0052  *       caller, with the note that it needs to be available in the NE
0053  *       CPU pool. Full CPU core(s), from the same NUMA node, need(s) to
0054  *       be associated with an enclave.
0055  *       The vCPU id is an input / output parameter. If its value is 0,
0056  *       then a CPU is chosen from the enclave CPU pool and returned via
0057  *       this parameter.
0058  *       The ioctl can be invoked on the enclave fd, before an enclave
0059  *       is started.
0060  *
0061  * Context: Process context.
0062  * Return:
0063  * * 0                  - Logic successfully completed.
0064  * *  -1                - There was a failure in the ioctl logic.
0065  * On failure, errno is set to:
0066  * * EFAULT             - copy_from_user() / copy_to_user() failure.
0067  * * ENOMEM             - Memory allocation failure for internal
0068  *                    bookkeeping variables.
0069  * * EIO                - Current task mm is not the same as the one
0070  *                    that created the enclave.
0071  * * NE_ERR_NO_CPUS_AVAIL_IN_POOL   - No CPUs available in the NE CPU pool.
0072  * * NE_ERR_VCPU_ALREADY_USED       - The provided vCPU is already used.
0073  * * NE_ERR_VCPU_NOT_IN_CPU_POOL    - The provided vCPU is not available in the
0074  *                    NE CPU pool.
0075  * * NE_ERR_VCPU_INVALID_CPU_CORE   - The core id of the provided vCPU is invalid
0076  *                    or out of range.
0077  * * NE_ERR_NOT_IN_INIT_STATE       - The enclave is not in init state
0078  *                    (init = before being started).
0079  * * NE_ERR_INVALID_VCPU        - The provided vCPU is not in the available
0080  *                    CPUs range.
0081  * * Error codes from the NE PCI device request.
0082  */
0083 #define NE_ADD_VCPU         _IOWR(0xAE, 0x21, __u32)
0084
0085 /**
0086  * NE_GET_IMAGE_LOAD_INFO - The command is used to get information needed for
0087  *              in-memory enclave image loading e.g. offset in
0088  *              enclave memory to start placing the enclave image.
0089  *              The image load info is an input / output parameter.
0090  *              It includes info provided by the caller - flags -
0091  *              and returns the offset in enclave memory where to
0092  *              start placing the enclave image.
0093  *              The ioctl can be invoked on the enclave fd, before
0094  *              an enclave is started.
0095  *
0096  * Context: Process context.
0097  * Return:
0098  * * 0              - Logic successfully completed.
0099  * *  -1            - There was a failure in the ioctl logic.
0100  * On failure, errno is set to:
0101  * * EFAULT         - copy_from_user() / copy_to_user() failure.
0102  * * NE_ERR_NOT_IN_INIT_STATE   - The enclave is not in init state (init =
0103  *                before being started).
0104  * * NE_ERR_INVALID_FLAG_VALUE  - The value of the provided flag is invalid.
0105  */
0106 #define NE_GET_IMAGE_LOAD_INFO      _IOWR(0xAE, 0x22, struct ne_image_load_info)
0107
0108 /**
0109  * NE_SET_USER_MEMORY_REGION - The command is used to set a memory region for an
0110  *                 enclave, given the allocated memory from the
0111  *                 userspace. Enclave memory needs to be from the
0112  *                 same NUMA node as the enclave CPUs.
0113  *                 The user memory region is an input parameter. It
0114  *                 includes info provided by the caller - flags,
0115  *                 memory size and userspace address.
0116  *                 The ioctl can be invoked on the enclave fd,
0117  *                 before an enclave is started.
0118  *
0119  * Context: Process context.
0120  * Return:
0121  * * 0                  - Logic successfully completed.
0122  * *  -1                - There was a failure in the ioctl logic.
0123  * On failure, errno is set to:
0124  * * EFAULT             - copy_from_user() failure.
0125  * * EINVAL             - Invalid physical memory region(s) e.g.
0126  *                    unaligned address.
0127  * * EIO                - Current task mm is not the same as
0128  *                    the one that created the enclave.
0129  * * ENOMEM             - Memory allocation failure for internal
0130  *                    bookkeeping variables.
0131  * * NE_ERR_NOT_IN_INIT_STATE       - The enclave is not in init state
0132  *                    (init = before being started).
0133  * * NE_ERR_INVALID_MEM_REGION_SIZE - The memory size of the region is not
0134  *                    multiple of 2 MiB.
0135  * * NE_ERR_INVALID_MEM_REGION_ADDR - Invalid user space address given.
0136  * * NE_ERR_UNALIGNED_MEM_REGION_ADDR   - Unaligned user space address given.
0137  * * NE_ERR_MEM_REGION_ALREADY_USED - The memory region is already used.
0138  * * NE_ERR_MEM_NOT_HUGE_PAGE       - The memory region is not backed by
0139  *                    huge pages.
0140  * * NE_ERR_MEM_DIFFERENT_NUMA_NODE - The memory region is not from the same
0141  *                    NUMA node as the CPUs.
0142  * * NE_ERR_MEM_MAX_REGIONS     - The number of memory regions set for
0143  *                    the enclave reached maximum.
0144  * * NE_ERR_INVALID_PAGE_SIZE       - The memory region is not backed by
0145  *                    pages multiple of 2 MiB.
0146  * * NE_ERR_INVALID_FLAG_VALUE      - The value of the provided flag is invalid.
0147  * * Error codes from get_user_pages().
0148  * * Error codes from the NE PCI device request.
0149  */
0150 #define NE_SET_USER_MEMORY_REGION   _IOW(0xAE, 0x23, struct ne_user_memory_region)
0151
0152 /**
0153  * NE_START_ENCLAVE - The command is used to trigger enclave start after the
0154  *            enclave resources, such as memory and CPU, have been set.
0155  *            The enclave start info is an input / output parameter. It
0156  *            includes info provided by the caller - enclave cid and
0157  *            flags - and returns the cid (if input cid is 0).
0158  *            The ioctl can be invoked on the enclave fd, after an
0159  *            enclave slot is created and resources, such as memory and
0160  *            vCPUs are set for an enclave.
0161  *
0162  * Context: Process context.
0163  * Return:
0164  * * 0                  - Logic successfully completed.
0165  * *  -1                - There was a failure in the ioctl logic.
0166  * On failure, errno is set to:
0167  * * EFAULT             - copy_from_user() / copy_to_user() failure.
0168  * * NE_ERR_NOT_IN_INIT_STATE       - The enclave is not in init state
0169  *                    (init = before being started).
0170  * * NE_ERR_NO_MEM_REGIONS_ADDED    - No memory regions are set.
0171  * * NE_ERR_NO_VCPUS_ADDED      - No vCPUs are set.
0172  * *  NE_ERR_FULL_CORES_NOT_USED    - Full core(s) not set for the enclave.
0173  * * NE_ERR_ENCLAVE_MEM_MIN_SIZE    - Enclave memory is less than minimum
0174  *                    memory size (64 MiB).
0175  * * NE_ERR_INVALID_FLAG_VALUE      - The value of the provided flag is invalid.
0176  * *  NE_ERR_INVALID_ENCLAVE_CID    - The provided enclave CID is invalid.
0177  * * Error codes from the NE PCI device request.
0178  */
0179 #define NE_START_ENCLAVE        _IOWR(0xAE, 0x24, struct ne_enclave_start_info)
0180
0181 /**
0182  * DOC: NE specific error codes
0183  */
0184
0185 /**
0186  * NE_ERR_VCPU_ALREADY_USED - The provided vCPU is already used.
0187  */
0188 #define NE_ERR_VCPU_ALREADY_USED        (256)
0189 /**
0190  * NE_ERR_VCPU_NOT_IN_CPU_POOL - The provided vCPU is not available in the
0191  *               NE CPU pool.
0192  */
0193 #define NE_ERR_VCPU_NOT_IN_CPU_POOL     (257)
0194 /**
0195  * NE_ERR_VCPU_INVALID_CPU_CORE - The core id of the provided vCPU is invalid
0196  *                or out of range of the NE CPU pool.
0197  */
0198 #define NE_ERR_VCPU_INVALID_CPU_CORE        (258)
0199 /**
0200  * NE_ERR_INVALID_MEM_REGION_SIZE - The user space memory region size is not
0201  *                  multiple of 2 MiB.
0202  */
0203 #define NE_ERR_INVALID_MEM_REGION_SIZE      (259)
0204 /**
0205  * NE_ERR_INVALID_MEM_REGION_ADDR - The user space memory region address range
0206  *                  is invalid.
0207  */
0208 #define NE_ERR_INVALID_MEM_REGION_ADDR      (260)
0209 /**
0210  * NE_ERR_UNALIGNED_MEM_REGION_ADDR - The user space memory region address is
0211  *                    not aligned.
0212  */
0213 #define NE_ERR_UNALIGNED_MEM_REGION_ADDR    (261)
0214 /**
0215  * NE_ERR_MEM_REGION_ALREADY_USED - The user space memory region is already used.
0216  */
0217 #define NE_ERR_MEM_REGION_ALREADY_USED      (262)
0218 /**
0219  * NE_ERR_MEM_NOT_HUGE_PAGE - The user space memory region is not backed by
0220  *                contiguous physical huge page(s).
0221  */
0222 #define NE_ERR_MEM_NOT_HUGE_PAGE        (263)
0223 /**
0224  * NE_ERR_MEM_DIFFERENT_NUMA_NODE - The user space memory region is backed by
0225  *                  pages from different NUMA nodes than the CPUs.
0226  */
0227 #define NE_ERR_MEM_DIFFERENT_NUMA_NODE      (264)
0228 /**
0229  * NE_ERR_MEM_MAX_REGIONS - The supported max memory regions per enclaves has
0230  *              been reached.
0231  */
0232 #define NE_ERR_MEM_MAX_REGIONS          (265)
0233 /**
0234  * NE_ERR_NO_MEM_REGIONS_ADDED - The command to start an enclave is triggered
0235  *               and no memory regions are added.
0236  */
0237 #define NE_ERR_NO_MEM_REGIONS_ADDED     (266)
0238 /**
0239  * NE_ERR_NO_VCPUS_ADDED - The command to start an enclave is triggered and no
0240  *             vCPUs are added.
0241  */
0242 #define NE_ERR_NO_VCPUS_ADDED           (267)
0243 /**
0244  * NE_ERR_ENCLAVE_MEM_MIN_SIZE - The enclave memory size is lower than the
0245  *               minimum supported.
0246  */
0247 #define NE_ERR_ENCLAVE_MEM_MIN_SIZE     (268)
0248 /**
0249  * NE_ERR_FULL_CORES_NOT_USED - The command to start an enclave is triggered and
0250  *              full CPU cores are not set.
0251  */
0252 #define NE_ERR_FULL_CORES_NOT_USED      (269)
0253 /**
0254  * NE_ERR_NOT_IN_INIT_STATE - The enclave is not in init state when setting
0255  *                resources or triggering start.
0256  */
0257 #define NE_ERR_NOT_IN_INIT_STATE        (270)
0258 /**
0259  * NE_ERR_INVALID_VCPU - The provided vCPU is out of range of the available CPUs.
0260  */
0261 #define NE_ERR_INVALID_VCPU         (271)
0262 /**
0263  * NE_ERR_NO_CPUS_AVAIL_IN_POOL - The command to create an enclave is triggered
0264  *                and no CPUs are available in the pool.
0265  */
0266 #define NE_ERR_NO_CPUS_AVAIL_IN_POOL        (272)
0267 /**
0268  * NE_ERR_INVALID_PAGE_SIZE - The user space memory region is not backed by pages
0269  *                multiple of 2 MiB.
0270  */
0271 #define NE_ERR_INVALID_PAGE_SIZE        (273)
0272 /**
0273  * NE_ERR_INVALID_FLAG_VALUE - The provided flag value is invalid.
0274  */
0275 #define NE_ERR_INVALID_FLAG_VALUE       (274)
0276 /**
0277  * NE_ERR_INVALID_ENCLAVE_CID - The provided enclave CID is invalid, either
0278  *              being a well-known value or the CID of the
0279  *              parent / primary VM.
0280  */
0281 #define NE_ERR_INVALID_ENCLAVE_CID      (275)
0282
0283 /**
0284  * DOC: Image load info flags
0285  */
0286
0287 /**
0288  * NE_EIF_IMAGE - Enclave Image Format (EIF)
0289  */
0290 #define NE_EIF_IMAGE            (0x01)
0291
0292 #define NE_IMAGE_LOAD_MAX_FLAG_VAL  (0x02)
0293
0294 /**
0295  * struct ne_image_load_info - Info necessary for in-memory enclave image
0296  *                 loading (in / out).
0297  * @flags:      Flags to determine the enclave image type
0298  *          (e.g. Enclave Image Format - EIF) (in).
0299  * @memory_offset:  Offset in enclave memory where to start placing the
0300  *          enclave image (out).
0301  */
0302 struct ne_image_load_info {
0303     __u64   flags;
0304     __u64   memory_offset;
0305 };
0306
0307 /**
0308  * DOC: User memory region flags
0309  */
0310
0311 /**
0312  * NE_DEFAULT_MEMORY_REGION - Memory region for enclave general usage.
0313  */
0314 #define NE_DEFAULT_MEMORY_REGION    (0x00)
0315
0316 #define NE_MEMORY_REGION_MAX_FLAG_VAL   (0x01)
0317
0318 /**
0319  * struct ne_user_memory_region - Memory region to be set for an enclave (in).
0320  * @flags:      Flags to determine the usage for the memory region (in).
0321  * @memory_size:    The size, in bytes, of the memory region to be set for
0322  *          an enclave (in).
0323  * @userspace_addr: The start address of the userspace allocated memory of
0324  *          the memory region to set for an enclave (in).
0325  */
0326 struct ne_user_memory_region {
0327     __u64   flags;
0328     __u64   memory_size;
0329     __u64   userspace_addr;
0330 };
0331
0332 /**
0333  * DOC: Enclave start info flags
0334  */
0335
0336 /**
0337  * NE_ENCLAVE_PRODUCTION_MODE - Start enclave in production mode.
0338  */
0339 #define NE_ENCLAVE_PRODUCTION_MODE  (0x00)
0340 /**
0341  * NE_ENCLAVE_DEBUG_MODE - Start enclave in debug mode.
0342  */
0343 #define NE_ENCLAVE_DEBUG_MODE       (0x01)
0344
0345 #define NE_ENCLAVE_START_MAX_FLAG_VAL   (0x02)
0346
0347 /**
0348  * struct ne_enclave_start_info - Setup info necessary for enclave start (in / out).
0349  * @flags:      Flags for the enclave to start with (e.g. debug mode) (in).
0350  * @enclave_cid:    Context ID (CID) for the enclave vsock device. If 0 as
0351  *          input, the CID is autogenerated by the hypervisor and
0352  *          returned back as output by the driver (in / out).
0353  */
0354 struct ne_enclave_start_info {
0355     __u64   flags;
0356     __u64   enclave_cid;
0357 };
0358
0359 #endif /* _UAPI_LINUX_NITRO_ENCLAVES_H_ */