Quelle  nitro_enclaves.h   Sprache: C

/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
/*
 * Copyright 2020-2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 */

#ifndef _UAPI_LINUX_NITRO_ENCLAVES_H_
#define _UAPI_LINUX_NITRO_ENCLAVES_H_

#include <linux/types.h>

/**
 * DOC: Nitro Enclaves (NE) Kernel Driver Interface
 */

/**
 * NE_CREATE_VM - The command is used to create a slot that is associated with
 *    an enclave VM.
 *    The generated unique slot id is an output parameter.
 *    The ioctl can be invoked on the /dev/nitro_enclaves fd, before
 *    setting any resources, such as memory and vCPUs, for an
 *    enclave. Memory and vCPUs are set for the slot mapped to an enclave.
 *    A NE CPU pool has to be set before calling this function. The
 *    pool can be set after the NE driver load, using
 *    /sys/module/nitro_enclaves/parameters/ne_cpus.
 *    Its format is the detailed in the cpu-lists section:
 *    https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html
 *    CPU 0 and its siblings have to remain available for the
 *    primary / parent VM, so they cannot be set for enclaves. Full
 *    CPU core(s), from the same NUMA node, need(s) to be included
 *    in the CPU pool.
 *
 * Context: Process context.
 * Return:
 * * Enclave file descriptor  - Enclave file descriptor used with
 *       ioctl calls to set vCPUs and memory
 *       regions, then start the enclave.
 * *  -1    - There was a failure in the ioctl logic.
 * On failure, errno is set to:
 * * EFAULT    - copy_to_user() failure.
 * * ENOMEM    - Memory allocation failure for internal
 *       bookkeeping variables.
 * * NE_ERR_NO_CPUS_AVAIL_IN_POOL - No NE CPU pool set / no CPUs available
 *       in the pool.
 * * Error codes from get_unused_fd_flags() and anon_inode_getfile().
 * * Error codes from the NE PCI device request.
 */
#define NE_CREATE_VM   _IOR(0xAE, 0x20, __u64)

/**
 * NE_ADD_VCPU - The command is used to set a vCPU for an enclave. The vCPU can
 *   be auto-chosen from the NE CPU pool or it can be set by the
 *   caller, with the note that it needs to be available in the NE
 *   CPU pool. Full CPU core(s), from the same NUMA node, need(s) to
 *   be associated with an enclave.
 *   The vCPU id is an input / output parameter. If its value is 0,
 *   then a CPU is chosen from the enclave CPU pool and returned via
 *   this parameter.
 *   The ioctl can be invoked on the enclave fd, before an enclave
 *   is started.
 *
 * Context: Process context.
 * Return:
 * * 0     - Logic successfully completed.
 * *  -1    - There was a failure in the ioctl logic.
 * On failure, errno is set to:
 * * EFAULT    - copy_from_user() / copy_to_user() failure.
 * * ENOMEM    - Memory allocation failure for internal
 *       bookkeeping variables.
 * * EIO    - Current task mm is not the same as the one
 *       that created the enclave.
 * * NE_ERR_NO_CPUS_AVAIL_IN_POOL - No CPUs available in the NE CPU pool.
 * * NE_ERR_VCPU_ALREADY_USED  - The provided vCPU is already used.
 * * NE_ERR_VCPU_NOT_IN_CPU_POOL - The provided vCPU is not available in the
 *       NE CPU pool.
 * * NE_ERR_VCPU_INVALID_CPU_CORE - The core id of the provided vCPU is invalid
 *       or out of range.
 * * NE_ERR_NOT_IN_INIT_STATE  - The enclave is not in init state
 *       (init = before being started).
 * * NE_ERR_INVALID_VCPU  - The provided vCPU is not in the available
 *       CPUs range.
 * * Error codes from the NE PCI device request.
 */
#define NE_ADD_VCPU   _IOWR(0xAE, 0x21, __u32)

/**
 * NE_GET_IMAGE_LOAD_INFO - The command is used to get information needed for
 *       in-memory enclave image loading e.g. offset in
 *       enclave memory to start placing the enclave image.
 *       The image load info is an input / output parameter.
 *       It includes info provided by the caller - flags -
 *       and returns the offset in enclave memory where to
 *       start placing the enclave image.
 *       The ioctl can be invoked on the enclave fd, before
 *       an enclave is started.
 *
 * Context: Process context.
 * Return:
 * * 0    - Logic successfully completed.
 * *  -1   - There was a failure in the ioctl logic.
 * On failure, errno is set to:
 * * EFAULT   - copy_from_user() / copy_to_user() failure.
 * * NE_ERR_NOT_IN_INIT_STATE - The enclave is not in init state (init =
 *      before being started).
 * * NE_ERR_INVALID_FLAG_VALUE - The value of the provided flag is invalid.
 */
#define NE_GET_IMAGE_LOAD_INFO  _IOWR(0xAE, 0x22, struct ne_image_load_info)

/**
 * NE_SET_USER_MEMORY_REGION - The command is used to set a memory region for an
 *          enclave, given the allocated memory from the
 *          userspace. Enclave memory needs to be from the
 *          same NUMA node as the enclave CPUs.
 *          The user memory region is an input parameter. It
 *          includes info provided by the caller - flags,
 *          memory size and userspace address.
 *          The ioctl can be invoked on the enclave fd,
 *          before an enclave is started.
 *
 * Context: Process context.
 * Return:
 * * 0     - Logic successfully completed.
 * *  -1    - There was a failure in the ioctl logic.
 * On failure, errno is set to:
 * * EFAULT    - copy_from_user() failure.
 * * EINVAL    - Invalid physical memory region(s) e.g.
 *       unaligned address.
 * * EIO    - Current task mm is not the same as
 *       the one that created the enclave.
 * * ENOMEM    - Memory allocation failure for internal
 *       bookkeeping variables.
 * * NE_ERR_NOT_IN_INIT_STATE  - The enclave is not in init state
 *       (init = before being started).
 * * NE_ERR_INVALID_MEM_REGION_SIZE - The memory size of the region is not
 *       multiple of 2 MiB.
 * * NE_ERR_INVALID_MEM_REGION_ADDR - Invalid user space address given.
 * * NE_ERR_UNALIGNED_MEM_REGION_ADDR - Unaligned user space address given.
 * * NE_ERR_MEM_REGION_ALREADY_USED - The memory region is already used.
 * * NE_ERR_MEM_NOT_HUGE_PAGE  - The memory region is not backed by
 *       huge pages.
 * * NE_ERR_MEM_DIFFERENT_NUMA_NODE - The memory region is not from the same
 *       NUMA node as the CPUs.
 * * NE_ERR_MEM_MAX_REGIONS  - The number of memory regions set for
 *       the enclave reached maximum.
 * * NE_ERR_INVALID_PAGE_SIZE  - The memory region is not backed by
 *       pages multiple of 2 MiB.
 * * NE_ERR_INVALID_FLAG_VALUE  - The value of the provided flag is invalid.
 * * Error codes from get_user_pages().
 * * Error codes from the NE PCI device request.
 */
#define NE_SET_USER_MEMORY_REGION _IOW(0xAE, 0x23, struct ne_user_memory_region)

/**
 * NE_START_ENCLAVE - The command is used to trigger enclave start after the
 *        enclave resources, such as memory and CPU, have been set.
 *        The enclave start info is an input / output parameter. It
 *        includes info provided by the caller - enclave cid and
 *        flags - and returns the cid (if input cid is 0).
 *        The ioctl can be invoked on the enclave fd, after an
 *        enclave slot is created and resources, such as memory and
 *        vCPUs are set for an enclave.
 *
 * Context: Process context.
 * Return:
 * * 0     - Logic successfully completed.
 * *  -1    - There was a failure in the ioctl logic.
 * On failure, errno is set to:
 * * EFAULT    - copy_from_user() / copy_to_user() failure.
 * * NE_ERR_NOT_IN_INIT_STATE  - The enclave is not in init state
 *       (init = before being started).
 * * NE_ERR_NO_MEM_REGIONS_ADDED - No memory regions are set.
 * * NE_ERR_NO_VCPUS_ADDED  - No vCPUs are set.
 * *  NE_ERR_FULL_CORES_NOT_USED - Full core(s) not set for the enclave.
 * * NE_ERR_ENCLAVE_MEM_MIN_SIZE - Enclave memory is less than minimum
 *       memory size (64 MiB).
 * * NE_ERR_INVALID_FLAG_VALUE  - The value of the provided flag is invalid.
 * *  NE_ERR_INVALID_ENCLAVE_CID - The provided enclave CID is invalid.
 * * Error codes from the NE PCI device request.
 */
#define NE_START_ENCLAVE  _IOWR(0xAE, 0x24, struct ne_enclave_start_info)

/**
 * DOC: NE specific error codes
 */

/**
 * NE_ERR_VCPU_ALREADY_USED - The provided vCPU is already used.
 */
#define NE_ERR_VCPU_ALREADY_USED  (256)
/**
 * NE_ERR_VCPU_NOT_IN_CPU_POOL - The provided vCPU is not available in the
 *     NE CPU pool.
 */
#define NE_ERR_VCPU_NOT_IN_CPU_POOL  (257)
/**
 * NE_ERR_VCPU_INVALID_CPU_CORE - The core id of the provided vCPU is invalid
 *      or out of range of the NE CPU pool.
 */
#define NE_ERR_VCPU_INVALID_CPU_CORE  (258)
/**
 * NE_ERR_INVALID_MEM_REGION_SIZE - The user space memory region size is not
 *        multiple of 2 MiB.
 */
#define NE_ERR_INVALID_MEM_REGION_SIZE  (259)
/**
 * NE_ERR_INVALID_MEM_REGION_ADDR - The user space memory region address range
 *        is invalid.
 */
#define NE_ERR_INVALID_MEM_REGION_ADDR  (260)
/**
 * NE_ERR_UNALIGNED_MEM_REGION_ADDR - The user space memory region address is
 *          not aligned.
 */
#define NE_ERR_UNALIGNED_MEM_REGION_ADDR (261)
/**
 * NE_ERR_MEM_REGION_ALREADY_USED - The user space memory region is already used.
 */
#define NE_ERR_MEM_REGION_ALREADY_USED  (262)
/**
 * NE_ERR_MEM_NOT_HUGE_PAGE - The user space memory region is not backed by
 *         contiguous physical huge page(s).
 */
#define NE_ERR_MEM_NOT_HUGE_PAGE  (263)
/**
 * NE_ERR_MEM_DIFFERENT_NUMA_NODE - The user space memory region is backed by
 *        pages from different NUMA nodes than the CPUs.
 */
#define NE_ERR_MEM_DIFFERENT_NUMA_NODE  (264)
/**
 * NE_ERR_MEM_MAX_REGIONS - The supported max memory regions per enclaves has
 *       been reached.
 */
#define NE_ERR_MEM_MAX_REGIONS   (265)
/**
 * NE_ERR_NO_MEM_REGIONS_ADDED - The command to start an enclave is triggered
 *     and no memory regions are added.
 */
#define NE_ERR_NO_MEM_REGIONS_ADDED  (266)
/**
 * NE_ERR_NO_VCPUS_ADDED - The command to start an enclave is triggered and no
 *      vCPUs are added.
 */
#define NE_ERR_NO_VCPUS_ADDED   (267)
/**
 * NE_ERR_ENCLAVE_MEM_MIN_SIZE - The enclave memory size is lower than the
 *     minimum supported.
 */
#define NE_ERR_ENCLAVE_MEM_MIN_SIZE  (268)
/**
 * NE_ERR_FULL_CORES_NOT_USED - The command to start an enclave is triggered and
 *    full CPU cores are not set.
 */
#define NE_ERR_FULL_CORES_NOT_USED  (269)
/**
 * NE_ERR_NOT_IN_INIT_STATE - The enclave is not in init state when setting
 *         resources or triggering start.
 */
#define NE_ERR_NOT_IN_INIT_STATE  (270)
/**
 * NE_ERR_INVALID_VCPU - The provided vCPU is out of range of the available CPUs.
 */
#define NE_ERR_INVALID_VCPU   (271)
/**
 * NE_ERR_NO_CPUS_AVAIL_IN_POOL - The command to create an enclave is triggered
 *      and no CPUs are available in the pool.
 */
#define NE_ERR_NO_CPUS_AVAIL_IN_POOL  (272)
/**
 * NE_ERR_INVALID_PAGE_SIZE - The user space memory region is not backed by pages
 *         multiple of 2 MiB.
 */
#define NE_ERR_INVALID_PAGE_SIZE  (273)
/**
 * NE_ERR_INVALID_FLAG_VALUE - The provided flag value is invalid.
 */
#define NE_ERR_INVALID_FLAG_VALUE  (274)
/**
 * NE_ERR_INVALID_ENCLAVE_CID - The provided enclave CID is invalid, either
 *    being a well-known value or the CID of the
 *    parent / primary VM.
 */
#define NE_ERR_INVALID_ENCLAVE_CID  (275)

/**
 * DOC: Image load info flags
 */

/**
 * NE_EIF_IMAGE - Enclave Image Format (EIF)
 */
#define NE_EIF_IMAGE   (0x01)

#define NE_IMAGE_LOAD_MAX_FLAG_VAL (0x02)

/**
 * struct ne_image_load_info - Info necessary for in-memory enclave image
 *          loading (in / out).
 * @flags:  Flags to determine the enclave image type
 *   (e.g. Enclave Image Format - EIF) (in).
 * @memory_offset: Offset in enclave memory where to start placing the
 *   enclave image (out).
 */
struct ne_image_load_info {
 __u64 flags;
 __u64 memory_offset;
};

/**
 * DOC: User memory region flags
 */

/**
 * NE_DEFAULT_MEMORY_REGION - Memory region for enclave general usage.
 */
#define NE_DEFAULT_MEMORY_REGION (0x00)

#define NE_MEMORY_REGION_MAX_FLAG_VAL (0x01)

/**
 * struct ne_user_memory_region - Memory region to be set for an enclave (in).
 * @flags:  Flags to determine the usage for the memory region (in).
 * @memory_size: The size, in bytes, of the memory region to be set for
 *   an enclave (in).
 * @userspace_addr: The start address of the userspace allocated memory of
 *   the memory region to set for an enclave (in).
 */
struct ne_user_memory_region {
 __u64 flags;
 __u64 memory_size;
 __u64 userspace_addr;
};

/**
 * DOC: Enclave start info flags
 */

/**
 * NE_ENCLAVE_PRODUCTION_MODE - Start enclave in production mode.
 */
#define NE_ENCLAVE_PRODUCTION_MODE (0x00)
/**
 * NE_ENCLAVE_DEBUG_MODE - Start enclave in debug mode.
 */
#define NE_ENCLAVE_DEBUG_MODE  (0x01)

#define NE_ENCLAVE_START_MAX_FLAG_VAL (0x02)

/**
 * struct ne_enclave_start_info - Setup info necessary for enclave start (in / out).
 * @flags:  Flags for the enclave to start with (e.g. debug mode) (in).
 * @enclave_cid: Context ID (CID) for the enclave vsock device. If 0 as
 *   input, the CID is autogenerated by the hypervisor and
 *   returned back as output by the driver (in / out).
 */
struct ne_enclave_start_info {
 __u64 flags;
 __u64 enclave_cid;
};

#endif /* _UAPI_LINUX_NITRO_ENCLAVES_H_ */