Linux-Sgx Archive on lore.kernel.org
 help / color / Atom feed
From: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
To: linux-kernel@vger.kernel.org, x86@kernel.org, linux-sgx@vger.kernel.org
Cc: akpm@linux-foundation.org, dave.hansen@intel.com,
	sean.j.christopherson@intel.com, nhorman@redhat.com,
	npmccallum@redhat.com, serge.ayoun@intel.com,
	shay.katz-zamir@intel.com, haitao.huang@intel.com,
	andriy.shevchenko@linux.intel.com, tglx@linutronix.de,
	kai.svahn@intel.com, bp@alien8.de, josh@joshtriplett.org,
	luto@kernel.org, kai.huang@intel.com, rientjes@google.com,
	cedric.xing@intel.com,
	Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
Subject: [PATCH v21 28/28] docs: x86/sgx: Document the enclave API
Date: Sat, 13 Jul 2019 20:08:04 +0300
Message-ID: <20190713170804.2340-29-jarkko.sakkinen@linux.intel.com> (raw)
In-Reply-To: <20190713170804.2340-1-jarkko.sakkinen@linux.intel.com>

Document the enclave driver API i.e. the set of ioctl's used to create
and manage enclaves and set their privileges

Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
---
 Documentation/x86/sgx/3.API.rst | 27 +++++++++++++++++++++++++++
 Documentation/x86/sgx/index.rst |  1 +
 2 files changed, 28 insertions(+)
 create mode 100644 Documentation/x86/sgx/3.API.rst

diff --git a/Documentation/x86/sgx/3.API.rst b/Documentation/x86/sgx/3.API.rst
new file mode 100644
index 000000000000..b113aeb05f54
--- /dev/null
+++ b/Documentation/x86/sgx/3.API.rst
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===
+API
+===
+
+The enclave life-cycle starts by opening `/dev/sgx/enclave`. After this there is
+already a data structure inside kernel tracking the enclave that is initially
+uncreated. After this a set of ioctl's can be used to create, populate and
+initialize the enclave.
+
+You can close (if you want) the fd after you've mmap()'d. As long as the file is
+open the enclave stays alive so you might want to do that after you don't need
+it anymore. Even munmap() won't destruct the enclave if the file is open.
+Neither will closing the fd as long as you have mmap() done over the fd (even
+if it does not across the range defined in SECS).
+
+Finally, there is ioctl to authorize priviliged attributes:
+`SGX_IOC_ENCLAVE_SET_ATTRIBUTE`. Each of them is presented by a file inside
+`/dev/sgx/`. Right now there is only one such file `/dev/sgx/provision`, which
+controls the `PROVISON_KEY` attribute.
+
+.. kernel-doc:: arch/x86/kernel/cpu/sgx/driver/ioctl.c
+   :functions: sgx_ioc_enclave_create
+               sgx_ioc_enclave_add_page
+               sgx_ioc_enclave_init
+               sgx_ioc_enclave_set_attribute
diff --git a/Documentation/x86/sgx/index.rst b/Documentation/x86/sgx/index.rst
index 5d660e83d984..de0b78328611 100644
--- a/Documentation/x86/sgx/index.rst
+++ b/Documentation/x86/sgx/index.rst
@@ -15,3 +15,4 @@ potentially malicious.
 
    1.Architecture
    2.Kernel-internals
+   3.API
-- 
2.20.1


  parent reply index

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-07-13 17:07 [PATCH v21 00/28] Intel SGX foundations Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 01/28] x86/cpufeatures: Add Intel-defined SGX feature bit Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 02/28] x86/cpufeatures: Add SGX sub-features (as Linux-defined bits) Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 03/28] x86/msr: Add IA32_FEATURE_CONTROL.SGX_ENABLE definition Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 04/28] x86/cpufeatures: Add Intel-defined SGX_LC feature bit Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 05/28] x86/msr: Add SGX Launch Control MSR definitions Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 06/28] x86/mm: x86/sgx: Add new 'PF_SGX' page fault error code bit Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 07/28] x86/mm: x86/sgx: Signal SIGSEGV for userspace #PFs w/ PF_SGX Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 08/28] x86/cpu/intel: Detect SGX support and update caps appropriately Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 09/28] x86/sgx: Add ENCLS architectural error codes Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 10/28] x86/sgx: Add SGX1 and SGX2 architectural data structures Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 11/28] x86/sgx: Add wrappers for ENCLS leaf functions Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 12/28] x86/sgx: Enumerate and track EPC sections Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 13/28] x86/sgx: Add functions to allocate and free EPC pages Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 14/28] x86/sgx: Add sgx_einit() for initializing enclaves Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 15/28] mm: Introduce vm_ops->may_mprotect() Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 16/28] x86/sgx: Add the Linux SGX Enclave Driver Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 17/28] x86/sgx: Add provisioning Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 18/28] x86/sgx: Add swapping code to the core and SGX driver Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 19/28] x86/sgx: ptrace() support for the " Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 20/28] x86/vdso: Add support for exception fixup in vDSO functions Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 21/28] x86/fault: Add helper function to sanitize error code Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 22/28] x86/traps: Attempt to fixup exceptions in vDSO before signaling Jarkko Sakkinen
2019-07-13 17:07 ` [PATCH v21 23/28] x86/vdso: Add __vdso_sgx_enter_enclave() to wrap SGX enclave transitions Jarkko Sakkinen
2019-07-17 22:07   ` Xing, Cedric
2019-07-13 17:08 ` [PATCH v21 24/28] selftests/x86: Add a selftest for SGX Jarkko Sakkinen
2019-07-17 22:37   ` Xing, Cedric
2019-07-13 17:08 ` [PATCH v21 25/28] x86/sgx: Update MAINTAINERS Jarkko Sakkinen
2019-07-13 17:08 ` [PATCH v21 26/28] docs: x86/sgx: Add Architecture documentation Jarkko Sakkinen
2019-07-13 17:08 ` [PATCH v21 27/28] docs: x86/sgx: Document kernel internals Jarkko Sakkinen
2019-07-13 17:08 ` Jarkko Sakkinen [this message]
2019-07-14 14:36 ` [PATCH v21 00/28] Intel SGX foundations Jarkko Sakkinen

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:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

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

  git send-email \
    --in-reply-to=20190713170804.2340-29-jarkko.sakkinen@linux.intel.com \
    --to=jarkko.sakkinen@linux.intel.com \
    --cc=akpm@linux-foundation.org \
    --cc=andriy.shevchenko@linux.intel.com \
    --cc=bp@alien8.de \
    --cc=cedric.xing@intel.com \
    --cc=dave.hansen@intel.com \
    --cc=haitao.huang@intel.com \
    --cc=josh@joshtriplett.org \
    --cc=kai.huang@intel.com \
    --cc=kai.svahn@intel.com \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-sgx@vger.kernel.org \
    --cc=luto@kernel.org \
    --cc=nhorman@redhat.com \
    --cc=npmccallum@redhat.com \
    --cc=rientjes@google.com \
    --cc=sean.j.christopherson@intel.com \
    --cc=serge.ayoun@intel.com \
    --cc=shay.katz-zamir@intel.com \
    --cc=tglx@linutronix.de \
    --cc=x86@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

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

Linux-Sgx Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-sgx/0 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/ https://lore.kernel.org/linux-sgx \
		linux-sgx@vger.kernel.org linux-sgx@archiver.kernel.org
	public-inbox-index linux-sgx


Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-sgx


AGPL code for this site: git clone https://public-inbox.org/ public-inbox