Linux-Sgx Archive on
 help / color / Atom feed
From: Jarkko Sakkinen <>
	Jarkko Sakkinen <>
Subject: [PATCH v24 24/24] docs: x86/sgx: Document kernel internals
Date: Sat, 30 Nov 2019 01:13:26 +0200
Message-ID: <> (raw)
In-Reply-To: <>

From: Sean Christopherson <>

Document some of the more tricky parts of the kernel implementation

Signed-off-by: Sean Christopherson <>
Co-developed-by: Jarkko Sakkinen <>
Signed-off-by: Jarkko Sakkinen <>
 Documentation/x86/sgx/2.Kernel-internals.rst | 78 ++++++++++++++++++++
 Documentation/x86/sgx/index.rst              |  1 +
 2 files changed, 79 insertions(+)
 create mode 100644 Documentation/x86/sgx/2.Kernel-internals.rst

diff --git a/Documentation/x86/sgx/2.Kernel-internals.rst b/Documentation/x86/sgx/2.Kernel-internals.rst
new file mode 100644
index 000000000000..7bfd5cb19b8e
--- /dev/null
+++ b/Documentation/x86/sgx/2.Kernel-internals.rst
@@ -0,0 +1,78 @@
+.. SPDX-License-Identifier: GPL-2.0
+Kernel Internals
+CPU configuration
+Because SGX has an ever evolving and expanding feature set, it's possible for
+a BIOS or VMM to configure a system in such a way that not all CPUs are equal,
+e.g. where Launch Control is only enabled on a subset of CPUs.  Linux does
+*not* support such a heterogeneous system configuration, nor does it even
+attempt to play nice in the face of a misconfigured system.  With the exception
+of Launch Control's hash MSRs, which can vary per CPU, Linux assumes that all
+CPUs have a configuration that is identical to the boot CPU.
+EPC management
+Because the kernel can't arbitrarily read EPC memory or share RO backing pages
+between enclaves, traditional memory models such as CoW and fork() do not work
+with enclaves.  In other words, the architectural rules of EPC force it to be
+treated as MAP_SHARED at all times.
+The inability to employ traditional memory models also means that EPC memory
+must be isolated from normal memory pools, e.g. attempting to use EPC memory
+for normal mappings would result in faults and/or perceived data corruption.
+Furthermore, EPC is not enumerated as normal memory, e.g. BIOS enumerates
+EPC as reserved memory in the e820 tables, or not at all.  As a result, EPC
+memory is directly managed by the SGX subsystem, e.g. SGX employs VM_PFNMAP to
+manually insert/zap/swap page table entries, and exposes EPC to userspace via
+a well known device, /dev/sgx/enclave.
+The net effect is that all enclave VMAs must be MAP_SHARED and are backed by
+a single file, /dev/sgx/enclave.
+EPC oversubscription
+SGX allows to have larger enclaves the than amount of available EPC by providing
+a subset of leaf instructions for swapping EPC pages to the system memory. The
+details of these instructions are discussed in the architecture document. Due to
+the unique requirements for swapping EPC pages, and because EPC pages do not
+have associated page structures, management of the EPC is not handled by the
+standard memory subsystem.
+SGX directly handles swapping of EPC pages, including a thread to initiate the
+reclaiming process and a rudimentary LRU mechanism. When the amount of free EPC
+pages goes below a low watermark the swapping thread starts reclaiming pages.
+The pages that have not been recently accessed (i.e. do not have the A bit set)
+are selected as victim pages. Each enclave holds an shmem file as a backing
+storage for reclaimed pages.
+Launch Control
+The current kernel implementation supports only writable MSRs. The launch is
+performed by setting the MSRs to the hash of the public key modulus of the
+enclave signer and a token with the valid bit set to zero.
+If the MSRs were read-only, the platform would need to provide a launch enclave
+(LE), which would be signed with the key matching the MSRs. The LE creates
+cryptographic tokens for other enclaves that they can pass together with their
+signature to the ENCLS(EINIT) opcode, which is used to initialize enclaves.
+The use of provisioning must be controlled because it allows to get access to
+the provisioning keys to attest to a remote party that the software is running
+inside a legitimate enclave. This could be used by a malware network to ensure
+that its nodes are running inside legitimate enclaves.
+The driver introduces a special device file /dev/sgx/provision and a special
+ioctl SGX_IOC_ENCLAVE_SET_ATTRIBUTE to accomplish this. A file descriptor
+pointing to /dev/sgx/provision is passed to ioctl from which kernel authorizes
+the PROVISION_KEY attribute to the enclave.
diff --git a/Documentation/x86/sgx/index.rst b/Documentation/x86/sgx/index.rst
index c5dfef62e612..5d660e83d984 100644
--- a/Documentation/x86/sgx/index.rst
+++ b/Documentation/x86/sgx/index.rst
@@ -14,3 +14,4 @@ potentially malicious.
    :maxdepth: 1
+   2.Kernel-internals

      parent reply index

Thread overview: 34+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-11-29 23:13 [PATCH v24 00/24] Intel SGX foundations Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 01/24] x86/sgx: Update MAINTAINERS Jarkko Sakkinen
2019-11-30  1:38   ` Neil Horman
2019-11-30 14:37     ` Dr. Greg
2019-12-02  9:24       ` Jethro Beekman
2019-12-06 21:23     ` Jarkko Sakkinen
2019-12-06 21:24       ` Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 02/24] x86/cpufeatures: x86/msr: Add Intel SGX hardware bits Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 03/24] x86/cpufeatures: x86/msr: Intel SGX Launch Control " Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 04/24] x86/mm: x86/sgx: Signal SIGSEGV with PF_SGX Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 05/24] x86/sgx: Add SGX microarchitectural data structures Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 06/24] x86/sgx: Add wrappers for ENCLS leaf functions Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 07/24] x86/cpu/intel: Detect SGX supprt Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 08/24] x86/sgx: Enumerate and track EPC sections Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 09/24] x86/sgx: Add functions to allocate and free EPC pages Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 10/24] x86/sgx: Add sgx_einit() for wrapping ENCLS[EINIT] Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 11/24] mm: Introduce vm_ops->may_mprotect() Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 12/24] x86/sgx: Linux Enclave Driver Jarkko Sakkinen
2019-12-02 15:48   ` Haitao Huang
2019-12-02 18:21     ` Sean Christopherson
2019-12-09 19:38       ` Jarkko Sakkinen
2019-12-09 19:08     ` Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 13/24] selftests/x86: Recurse into subdirectories Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 14/24] selftests/x86: Add a selftest for SGX Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 15/24] x86/sgx: Add provisioning Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 16/24] x86/sgx: Add a page reclaimer Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 17/24] x86/sgx: ptrace() support for the SGX driver Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 18/24] x86/vdso: Add support for exception fixup in vDSO functions Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 19/24] x86/fault: Add helper function to sanitize error code Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 20/24] x86/traps: Attempt to fixup exceptions in vDSO before signaling Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 21/24] x86/vdso: Add __vdso_sgx_enter_enclave() to wrap SGX enclave transitions Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 22/24] selftests/x86: Add vDSO selftest for SGX Jarkko Sakkinen
2019-11-29 23:13 ` [PATCH v24 23/24] docs: x86/sgx: Document microarchitecture Jarkko Sakkinen
2019-11-29 23:13 ` Jarkko Sakkinen [this message]

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-Sgx Archive on

Archives are clonable:
	git clone --mirror linux-sgx/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-sgx linux-sgx/ \
	public-inbox-index linux-sgx

Example config snippet for mirrors

Newsgroup available over NNTP:

AGPL code for this site: git clone