[PATCH V9 09/45] Documentation/pkeys: Add initial PKS documentation

From: ira.weiny@intel.com
To: Dave Hansen <dave.hansen@linux.intel.com>,
	"H. Peter Anvin" <hpa@zytor.com>,
	Dan Williams <dan.j.williams@intel.com>
Cc: Ira Weiny <ira.weiny@intel.com>,
	Fenghua Yu <fenghua.yu@intel.com>,
	Rick Edgecombe <rick.p.edgecombe@intel.com>,
	"Shankar, Ravi V" <ravi.v.shankar@intel.com>,
	linux-kernel@vger.kernel.org
Subject: [PATCH V9 09/45] Documentation/pkeys: Add initial PKS documentation
Date: Thu, 10 Mar 2022 09:19:43 -0800	[thread overview]
Message-ID: <20220310172019.850939-10-ira.weiny@intel.com> (raw)
In-Reply-To: <20220310172019.850939-1-ira.weiny@intel.com>

From: Ira Weiny <ira.weiny@intel.com>

Add initial overview and configuration information about PKS.

Cc: "Moger, Babu" <Babu.Moger@amd.com>
Signed-off-by: Ira Weiny <ira.weiny@intel.com>

---
Changes for V9
	Feedback from Dave Hansen
		Remove overview and move relevant text to the main pkey
		overview which covers both user ans kernel keys.
		Add an example of using Kconfig
		Move MSR details to later patches
---
 Documentation/core-api/protection-keys.rst | 43 ++++++++++++++++++++--
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/Documentation/core-api/protection-keys.rst b/Documentation/core-api/protection-keys.rst
index bf28ac0401f3..13eedb0119e1 100644
--- a/Documentation/core-api/protection-keys.rst
+++ b/Documentation/core-api/protection-keys.rst
@@ -13,6 +13,11 @@ Pkeys Userspace (PKU) is a feature which can be found on:
         * Intel client CPUs, Tiger Lake (11th Gen Core) and later
         * Future AMD CPUs
 
+Protection Keys Supervisor (PKS) is a feature which can be found on:
+        * Sapphire Rapids (and later) "Scalable Processor" Server CPUs
+        * Future non-server Intel parts.
+        * qemu: https://www.qemu.org/2021/04/30/qemu-6-0-0/
+
 Pkeys work by dedicating 4 previously Reserved bits in each page table entry to
 a "protection key", giving 16 possible keys.
 
@@ -23,13 +28,20 @@ and Write Disable) for each of 16 keys.
 Being a CPU register, PKRU is inherently thread-local, potentially giving each
 thread a different set of protections from every other thread.
 
-There are two instructions (RDPKRU/WRPKRU) for reading and writing to the
-register.  The feature is only available in 64-bit mode, even though there is
+For Userspace (PKU), there are two instructions (RDPKRU/WRPKRU) for reading and
+writing to the register.
+
+For Supervisor (PKS), the register (MSR_IA32_PKRS) is accessible only to the
+kernel through rdmsr and wrmsr.
+
+The feature is only available in 64-bit mode, even though there is
 theoretically space in the PAE PTEs.  These permissions are enforced on data
 access only and have no effect on instruction fetches.
 
-Syscalls
-========
+
+
+Syscalls for user space keys
+============================
 
 There are 3 system calls which directly interact with pkeys::
 
@@ -96,3 +108,26 @@ with a read()::
 The kernel will send a SIGSEGV in both cases, but si_code will be set
 to SEGV_PKERR when violating protection keys versus SEGV_ACCERR when
 the plain mprotect() permissions are violated.
+
+
+Kernel API for PKS support
+==========================
+
+Kconfig
+-------
+
+Kernel users intending to use PKS support should depend on
+ARCH_HAS_SUPERVISOR_PKEYS, and select ARCH_ENABLE_SUPERVISOR_PKEYS to turn on
+this support within the core.  For example:
+
+.. code-block:: c
+
+        config MY_NEW_FEATURE
+                depends on ARCH_HAS_SUPERVISOR_PKEYS
+                select ARCH_ENABLE_SUPERVISOR_PKEYS
+
+This will make "MY_NEW_FEATURE" unavailable unless the architecture sets
+ARCH_HAS_SUPERVISOR_PKEYS.  It also makes it possible for multiple independent
+features to "select ARCH_ENABLE_SUPERVISOR_PKEYS".  If no features enable PKS
+by selecting ARCH_ENABLE_SUPERVISOR_PKEYS, PKS support will not be compiled
+into the kernel.
-- 
2.35.1

