Commit f10b07a0 authored by Changbin Du's avatar Changbin Du Committed by Jonathan Corbet

Documentation: x86: convert intel_mpx.txt to reST

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: default avatarChangbin Du <changbin.du@gmail.com>
Reviewed-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 28e21eac
...@@ -19,3 +19,4 @@ x86-specific Documentation ...@@ -19,3 +19,4 @@ x86-specific Documentation
mtrr mtrr
pat pat
protection-keys protection-keys
intel_mpx
1. Intel(R) MPX Overview .. SPDX-License-Identifier: GPL-2.0
========================
===========================================
Intel(R) Memory Protection Extensions (MPX)
===========================================
Intel(R) MPX Overview
=====================
Intel(R) Memory Protection Extensions (Intel(R) MPX) is a new capability Intel(R) Memory Protection Extensions (Intel(R) MPX) is a new capability
introduced into Intel Architecture. Intel MPX provides hardware features introduced into Intel Architecture. Intel MPX provides hardware features
...@@ -7,7 +13,7 @@ that can be used in conjunction with compiler changes to check memory ...@@ -7,7 +13,7 @@ that can be used in conjunction with compiler changes to check memory
references, for those references whose compile-time normal intentions are references, for those references whose compile-time normal intentions are
usurped at runtime due to buffer overflow or underflow. usurped at runtime due to buffer overflow or underflow.
You can tell if your CPU supports MPX by looking in /proc/cpuinfo: You can tell if your CPU supports MPX by looking in /proc/cpuinfo::
cat /proc/cpuinfo | grep ' mpx ' cat /proc/cpuinfo | grep ' mpx '
...@@ -21,8 +27,8 @@ can be downloaded from ...@@ -21,8 +27,8 @@ can be downloaded from
http://software.intel.com/en-us/articles/intel-software-development-emulator http://software.intel.com/en-us/articles/intel-software-development-emulator
2. How to get the advantage of MPX How to get the advantage of MPX
================================== ===============================
For MPX to work, changes are required in the kernel, binutils and compiler. For MPX to work, changes are required in the kernel, binutils and compiler.
No source changes are required for applications, just a recompile. No source changes are required for applications, just a recompile.
...@@ -84,14 +90,15 @@ Kernel MPX Code: ...@@ -84,14 +90,15 @@ Kernel MPX Code:
is unmapped. is unmapped.
3. How does MPX kernel code work How does MPX kernel code work
================================ =============================
Handling #BR faults caused by MPX Handling #BR faults caused by MPX
--------------------------------- ---------------------------------
When MPX is enabled, there are 2 new situations that can generate When MPX is enabled, there are 2 new situations that can generate
#BR faults. #BR faults.
* new bounds tables (BT) need to be allocated to save bounds. * new bounds tables (BT) need to be allocated to save bounds.
* bounds violation caused by MPX instructions. * bounds violation caused by MPX instructions.
...@@ -124,9 +131,9 @@ the kernel. It can theoretically be done completely from userspace. Here ...@@ -124,9 +131,9 @@ the kernel. It can theoretically be done completely from userspace. Here
are a few ways this could be done. We don't think any of them are practical are a few ways this could be done. We don't think any of them are practical
in the real-world, but here they are. in the real-world, but here they are.
Q: Can virtual space simply be reserved for the bounds tables so that we :Q: Can virtual space simply be reserved for the bounds tables so that we
never have to allocate them? never have to allocate them?
A: MPX-enabled application will possibly create a lot of bounds tables in :A: MPX-enabled application will possibly create a lot of bounds tables in
process address space to save bounds information. These tables can take process address space to save bounds information. These tables can take
up huge swaths of memory (as much as 80% of the memory on the system) up huge swaths of memory (as much as 80% of the memory on the system)
even if we clean them up aggressively. In the worst-case scenario, the even if we clean them up aggressively. In the worst-case scenario, the
...@@ -140,19 +147,19 @@ A: MPX-enabled application will possibly create a lot of bounds tables in ...@@ -140,19 +147,19 @@ A: MPX-enabled application will possibly create a lot of bounds tables in
consumes 2GB of virtual *AND* physical memory. IOW, it's completely consumes 2GB of virtual *AND* physical memory. IOW, it's completely
infeasible to prepopulate bounds directories. infeasible to prepopulate bounds directories.
Q: Can we preallocate bounds table space at the same time memory is :Q: Can we preallocate bounds table space at the same time memory is
allocated which might contain pointers that might eventually need allocated which might contain pointers that might eventually need
bounds tables? bounds tables?
A: This would work if we could hook the site of each and every memory :A: This would work if we could hook the site of each and every memory
allocation syscall. This can be done for small, constrained applications. allocation syscall. This can be done for small, constrained applications.
But, it isn't practical at a larger scale since a given app has no But, it isn't practical at a larger scale since a given app has no
way of controlling how all the parts of the app might allocate memory way of controlling how all the parts of the app might allocate memory
(think libraries). The kernel is really the only place to intercept (think libraries). The kernel is really the only place to intercept
these calls. these calls.
Q: Could a bounds fault be handed to userspace and the tables allocated :Q: Could a bounds fault be handed to userspace and the tables allocated
there in a signal handler instead of in the kernel? there in a signal handler instead of in the kernel?
A: mmap() is not on the list of safe async handler functions and even :A: mmap() is not on the list of safe async handler functions and even
if mmap() would work it still requires locking or nasty tricks to if mmap() would work it still requires locking or nasty tricks to
keep track of the allocation state there. keep track of the allocation state there.
...@@ -167,20 +174,20 @@ If a #BR is generated due to a bounds violation caused by MPX. ...@@ -167,20 +174,20 @@ If a #BR is generated due to a bounds violation caused by MPX.
We need to decode MPX instructions to get violation address and We need to decode MPX instructions to get violation address and
set this address into extended struct siginfo. set this address into extended struct siginfo.
The _sigfault field of struct siginfo is extended as follow: The _sigfault field of struct siginfo is extended as follow::
87 /* SIGILL, SIGFPE, SIGSEGV, SIGBUS */ 87 /* SIGILL, SIGFPE, SIGSEGV, SIGBUS */
88 struct { 88 struct {
89 void __user *_addr; /* faulting insn/memory ref. */ 89 void __user *_addr; /* faulting insn/memory ref. */
90 #ifdef __ARCH_SI_TRAPNO 90 #ifdef __ARCH_SI_TRAPNO
91 int _trapno; /* TRAP # which caused the signal */ 91 int _trapno; /* TRAP # which caused the signal */
92 #endif 92 #endif
93 short _addr_lsb; /* LSB of the reported address */ 93 short _addr_lsb; /* LSB of the reported address */
94 struct { 94 struct {
95 void __user *_lower; 95 void __user *_lower;
96 void __user *_upper; 96 void __user *_upper;
97 } _addr_bnd; 97 } _addr_bnd;
98 } _sigfault; 98 } _sigfault;
The '_addr' field refers to violation address, and new '_addr_and' The '_addr' field refers to violation address, and new '_addr_and'
field refers to the upper/lower bounds when a #BR is caused. field refers to the upper/lower bounds when a #BR is caused.
...@@ -209,9 +216,10 @@ Adding new prctl commands ...@@ -209,9 +216,10 @@ Adding new prctl commands
Two new prctl commands are added to enable and disable MPX bounds tables Two new prctl commands are added to enable and disable MPX bounds tables
management in kernel. management in kernel.
::
155 #define PR_MPX_ENABLE_MANAGEMENT 43 155 #define PR_MPX_ENABLE_MANAGEMENT 43
156 #define PR_MPX_DISABLE_MANAGEMENT 44 156 #define PR_MPX_DISABLE_MANAGEMENT 44
Runtime library in userspace is responsible for allocation of bounds Runtime library in userspace is responsible for allocation of bounds
directory. So kernel have to use XSAVE instruction to get the base directory. So kernel have to use XSAVE instruction to get the base
...@@ -223,8 +231,8 @@ into struct mm_struct to be used in future during PR_MPX_ENABLE_MANAGEMENT ...@@ -223,8 +231,8 @@ into struct mm_struct to be used in future during PR_MPX_ENABLE_MANAGEMENT
command execution. command execution.
4. Special rules Special rules
================ =============
1) If userspace is requesting help from the kernel to do the management 1) If userspace is requesting help from the kernel to do the management
of bounds tables, it may not create or modify entries in the bounds directory. of bounds tables, it may not create or modify entries in the bounds directory.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment