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

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

Documentation/x86/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -19,3 +19,4 @@ x86-specific Documentation 
   mtrr

   pat

   protection-keys

   intel_mpx

Documentation/x86/intel_mpx.txt→Documentation/x86/intel_mpx.rst

+64 −56
Original line number Diff line number Diff line 
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

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 
references, for those references whose compile-time normal intentions are

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 '
@@ -21,8 +27,8 @@ can be downloaded from 
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.

No source changes are required for applications, just a recompile.
@@ -84,14 +90,15 @@ Kernel MPX Code: 
   is unmapped.





3. How does MPX kernel code work

================================

How does MPX kernel code work

=============================



Handling #BR faults caused by MPX

---------------------------------



When MPX is enabled, there are 2 new situations that can generate

#BR faults.



  * new bounds tables (BT) need to be allocated to save bounds.

  * bounds violation caused by MPX instructions.
@@ -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

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?

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

    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
@@ -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

    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

    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.

    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

    (think libraries). The kernel is really the only place to intercept

    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?

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

    keep track of the allocation state there.
@@ -167,7 +174,7 @@ If a #BR is generated due to a bounds violation caused by MPX. 
We need to decode MPX instructions to get violation address and

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 */

  88		struct {
@@ -209,6 +216,7 @@ Adding new prctl commands 


Two new prctl commands are added to enable and disable MPX bounds tables

management in kernel.

::



  155	#define PR_MPX_ENABLE_MANAGEMENT	43

  156	#define PR_MPX_DISABLE_MANAGEMENT	44
@@ -223,8 +231,8 @@ into struct mm_struct to be used in future during PR_MPX_ENABLE_MANAGEMENT 
command execution.





4. Special rules

================

Special rules

=============



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.