drm/nouveau: fix kernel-doc comments
[drm/drm-misc.git] / Documentation / core-api / protection-keys.rst
blob7eb7c6023e0969f7598081fe1432a0a565473950
1 .. SPDX-License-Identifier: GPL-2.0
3 ======================
4 Memory Protection Keys
5 ======================
7 Memory Protection Keys provide a mechanism for enforcing page-based
8 protections, but without requiring modification of the page tables when an
9 application changes protection domains.
11 Pkeys Userspace (PKU) is a feature which can be found on:
12         * Intel server CPUs, Skylake and later
13         * Intel client CPUs, Tiger Lake (11th Gen Core) and later
14         * Future AMD CPUs
15         * arm64 CPUs implementing the Permission Overlay Extension (FEAT_S1POE)
17 x86_64
18 ======
19 Pkeys work by dedicating 4 previously Reserved bits in each page table entry to
20 a "protection key", giving 16 possible keys.
22 Protections for each key are defined with a per-CPU user-accessible register
23 (PKRU).  Each of these is a 32-bit register storing two bits (Access Disable
24 and Write Disable) for each of 16 keys.
26 Being a CPU register, PKRU is inherently thread-local, potentially giving each
27 thread a different set of protections from every other thread.
29 There are two instructions (RDPKRU/WRPKRU) for reading and writing to the
30 register.  The feature is only available in 64-bit mode, even though there is
31 theoretically space in the PAE PTEs.  These permissions are enforced on data
32 access only and have no effect on instruction fetches.
34 arm64
35 =====
37 Pkeys use 3 bits in each page table entry, to encode a "protection key index",
38 giving 8 possible keys.
40 Protections for each key are defined with a per-CPU user-writable system
41 register (POR_EL0).  This is a 64-bit register encoding read, write and execute
42 overlay permissions for each protection key index.
44 Being a CPU register, POR_EL0 is inherently thread-local, potentially giving
45 each thread a different set of protections from every other thread.
47 Unlike x86_64, the protection key permissions also apply to instruction
48 fetches.
50 Syscalls
51 ========
53 There are 3 system calls which directly interact with pkeys::
55         int pkey_alloc(unsigned long flags, unsigned long init_access_rights)
56         int pkey_free(int pkey);
57         int pkey_mprotect(unsigned long start, size_t len,
58                           unsigned long prot, int pkey);
60 Before a pkey can be used, it must first be allocated with pkey_alloc().  An
61 application writes to the architecture specific CPU register directly in order
62 to change access permissions to memory covered with a key.  In this example
63 this is wrapped by a C function called pkey_set().
66         int real_prot = PROT_READ|PROT_WRITE;
67         pkey = pkey_alloc(0, PKEY_DISABLE_WRITE);
68         ptr = mmap(NULL, PAGE_SIZE, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0);
69         ret = pkey_mprotect(ptr, PAGE_SIZE, real_prot, pkey);
70         ... application runs here
72 Now, if the application needs to update the data at 'ptr', it can
73 gain access, do the update, then remove its write access::
75         pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE
76         *ptr = foo; // assign something
77         pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again
79 Now when it frees the memory, it will also free the pkey since it
80 is no longer in use::
82         munmap(ptr, PAGE_SIZE);
83         pkey_free(pkey);
85 .. note:: pkey_set() is a wrapper around writing to the CPU register.
86           Example implementations can be found in
87           tools/testing/selftests/mm/pkey-{arm64,powerpc,x86}.h
89 Behavior
90 ========
92 The kernel attempts to make protection keys consistent with the
93 behavior of a plain mprotect().  For instance if you do this::
95         mprotect(ptr, size, PROT_NONE);
96         something(ptr);
98 you can expect the same effects with protection keys when doing this::
100         pkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ);
101         pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey);
102         something(ptr);
104 That should be true whether something() is a direct access to 'ptr'
105 like::
107         *ptr = foo;
109 or when the kernel does the access on the application's behalf like
110 with a read()::
112         read(fd, ptr, 1);
114 The kernel will send a SIGSEGV in both cases, but si_code will be set
115 to SEGV_PKERR when violating protection keys versus SEGV_ACCERR when
116 the plain mprotect() permissions are violated.
118 Note that kernel accesses from a kthread (such as io_uring) will use a default
119 value for the protection key register and so will not be consistent with
120 userspace's value of the register or mprotect().