[PATCH 7/8] Documentation: ABI: Describe nitro_enclaves cpu_pool sysfs

[Alexander Graf]

An operator or an orchestrator placing an enclave needs more than the
contents of these files: how far the partition between used and avail
goes, and which node the enclave allocates from when it does not name
one. Write both down.

Assisted-by: Kiro:claude-opus-5
Signed-off-by: Alexander Graf <graf@xxxxxxxxxx>
---
 .../sysfs-devices-virtual-misc-nitro_enclaves | 44 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 2 files changed, 45 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-devices-virtual-misc-nitro_enclaves

diff --git a/Documentation/ABI/testing/sysfs-devices-virtual-misc-nitro_enclaves b/Documentation/ABI/testing/sysfs-devices-virtual-misc-nitro_enclaves
new file mode 100644
index 000000000000..20b978c62244
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-virtual-misc-nitro_enclaves
@@ -0,0 +1,44 @@
+What:		/sys/devices/virtual/misc/nitro_enclaves/cpu_pool/mode
+Date:		July 2026
+KernelVersion:	7.3
+Contact:	aws-nitro-enclaves-devel@xxxxxxxxxx
+Description:
+		Read-only. Mode of the Nitro Enclaves CPU pool, one of:
+
+		  none     the pool is empty (ne_cpus is unset)
+		  static   ne_cpus is a CPU list; the listed CPUs are
+		           offlined and dedicated to the pool
+
+What:		/sys/devices/virtual/misc/nitro_enclaves/cpu_pool/total
+What:		/sys/devices/virtual/misc/nitro_enclaves/cpu_pool/used
+What:		/sys/devices/virtual/misc/nitro_enclaves/cpu_pool/avail
+Date:		July 2026
+KernelVersion:	7.3
+Contact:	aws-nitro-enclaves-devel@xxxxxxxxxx
+Description:
+		Read-only. CPU-list strings describing the Nitro Enclaves CPU
+		pool: total is every CPU thread dedicated to the pool, used is
+		the threads held on behalf of enclaves, and avail is the
+		threads free for allocation. A thread leaves used when the
+		enclave holding it is released; if that release fails part way
+		through, the thread stays in used until the driver is unloaded
+		or the machine reboots. used and avail partition total at any
+		instant, and each read is a consistent snapshot, so a thread
+		that changes hands between two reads can be absent from both.
+		total changes only when the pool is reconfigured, which
+		requires that no enclave exists.
+
+		These files report no error of their own. A read does take the
+		pool lock, so it can wait for a write to ne_cpus to finish.
+
+		By default, allocation for a new enclave targets the NUMA
+		node that owns the first core in total and does not spill to
+		another node. NE_SET_ALLOC_NUMA_NODE changes the target, and
+		its node-agnostic value lets one enclave take cores from
+		more than one node.
+
+		Pool threads are offline, so the threads free on a given
+		node come from intersecting avail with the nodeN/cpuM
+		symlinks under /sys/devices/system/node, which outlive a CPU
+		going offline. nodeN/cpulist is filtered against
+		cpu_online_mask and lists none of them.
diff --git a/MAINTAINERS b/MAINTAINERS
index 716acfc3d7c1..e573764d9cc2 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -19184,6 +19184,7 @@ R:	The AWS Nitro Enclaves Team <aws-nitro-enclaves-devel@xxxxxxxxxx>
 L:	linux-kernel@xxxxxxxxxxxxxxx
 S:	Supported
 W:	https://aws.amazon.com/ec2/nitro/nitro-enclaves/
+F:	Documentation/ABI/testing/sysfs-devices-virtual-misc-nitro_enclaves
 F:	Documentation/virt/ne_overview.rst
 F:	drivers/virt/nitro_enclaves/
 F:	include/linux/nitro_enclaves.h
-- 
2.47.1