NE_ADD_VCPU(9)

💅 ne_add_vcpu(9) — Kernel API Manual 🎀

okay bestie, welcome to the NE_ADD_VCPU glow-up ✨ this is from the Kernel API Manual and it's literally the ioctl that gives your enclave a vCPU. let's get into it 🫶

---

✨ NAME ✨

NE_ADD_VCPU — the command used to set a vCPU for an enclave 🔥

so here's the vibe: the vCPU can either be auto-chosen from the NE CPU pool, or set by the caller — but heads up, if you're picking it yourself it needs to be available in the NE CPU pool. also, full CPU core(s), from the same NUMA node, need(s) to be associated with an enclave. no mixing, no matching, periodt 💅

the vCPU id is an input / output parameter — iconic behavior honestly. 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. iykyk 🦋

---

🌸 SYNOPSIS 🌸

NE_ADD_VCPU

---

💜 CONTEXT 💜

Process context. that's it, that's the whole mood 😌

---

🌈 RETURN 🌈

• 0 — logic successfully completed. slay, we ate 👑
• -1 — there was a failure in the ioctl logic. on failure, errno is set to one of these besties:
  • 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. not the main character, not allowed 🙈
  • 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. someone got there first, bestie ✋
  • 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. (the PCI device said what it said 💀)

---

🦋 SEE ALSO 🦋

• Kernel file ./include/uapi/linux/nitro_enclaves.h
• Nitro Enclaves (NE) Kernel Driver Interface(9)
• NE_CREATE_VM(9)
• NE_GET_IMAGE_LOAD_INFO(9)
• NE_SET_USER_MEMORY_REGION(9)
• NE_START_ENCLAVE(9)
• NE specific error codes(9)
• NE_ERR_VCPU_ALREADY_USED(9)
• NE_ERR_VCPU_NOT_IN_CPU_POOL(9)
• NE_ERR_VCPU_INVALID_CPU_CORE(9)
• NE_ERR_INVALID_MEM_REGION_SIZE(9)
• NE_ERR_INVALID_MEM_REGION_ADDR(9)
• NE_ERR_UNALIGNED_MEM_REGION_ADDR(9)
• NE_ERR_MEM_REGION_ALREADY_USED(9)
• NE_ERR_MEM_NOT_HUGE_PAGE(9)
• NE_ERR_MEM_DIFFERENT_NUMA_NODE(9)
• NE_ERR_MEM_MAX_REGIONS(9)
• NE_ERR_NO_MEM_REGIONS_ADDED(9)
• NE_ERR_NO_VCPUS_ADDED(9)
• NE_ERR_ENCLAVE_MEM_MIN_SIZE(9)
• NE_ERR_FULL_CORES_NOT_USED(9)
• NE_ERR_NOT_IN_INIT_STATE(9)
• NE_ERR_INVALID_VCPU(9)
• NE_ERR_NO_CPUS_AVAIL_IN_POOL(9)
• NE_ERR_INVALID_PAGE_SIZE(9)
• NE_ERR_INVALID_FLAG_VALUE(9)
• NE_ERR_INVALID_ENCLAVE_CID(9)
• Image load info flags(9)
• NE_EIF_IMAGE(9)
• struct ne_image_load_info(9)
• User memory region flags(9)
• NE_DEFAULT_MEMORY_REGION(9)
• struct ne_user_memory_region(9)
• Enclave start info flags(9)
• NE_ENCLAVE_PRODUCTION_MODE(9)
• NE_ENCLAVE_DEBUG_MODE(9)
• struct ne_enclave_start_info(9)

---

💖 reminder bestie: the vCPU you hand over has to live in the NE CPU pool, on the same NUMA node, and the enclave has to still be in init state. don't come at it with a rogue core, it's not gonna go well 😭

that's the whole page, no cap 🌟 this one ships out of ./include/uapi/linux and the date on it is October 2026 — mwah, go read the whole enclave saga, it's giving lore 🎀💜