archive mirror
 help / color / mirror / Atom feed
From: "Alejandro Colomar (man-pages)" <>
To: Jarkko Sakkinen <>
	Dave Hansen <>,, Michael Kerrisk <>,
	Reinette Chatre <>
Subject: Re: [PATCH v11] sgx.7: New page with overview of Software Guard eXtensions (SGX)
Date: Fri, 17 Dec 2021 02:50:56 +0100	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

Hi Jarkko,

Please see some comments below.


On 12/11/21 16:33, Jarkko Sakkinen wrote:
> Signed-off-by: Jarkko Sakkinen <>
> ---
> v11:
> * Address Reinette's remarks for v10:
> v10:
> * v9 was malformed, essentially a resend.
> v9:
> * Rename "Address Space" section as "Memory mapping", and refine the
>    text.
> * Rename "Ioctls" section as "Construction", and refine the text.
> v8:
> * Fix errors reported for the previous version.
> v7:
> * Added more meat about the address space and API.
> * Reorganized the text to have focus more on developer to have a big
>    picture of kernel provided interfaces.
> v6:
> * Small fixes based on Dave's and Reinette's feedback.
> * Extended the "Permissions" section to cover mmap()
> v5:
> * Taking away hardware concepts and focusing more on the interface.
> v4:
> * Did a heavy edit trying to streamline the story a bit and focus on
>    stuff important to the user (e.g. lighten up x86 details).
> v3:
> * Overhaul based on Michael's comments. Most likely needs to be refined
>    in various places but this is at least a small step forward for sure.
> v2:
> * Fixed the semantic newlines convention and various style errors etc.
>    that were reported by Alenjandro and Michael.
> * SGX was merged to v5.
> ---
>   man7/sgx.7 | 146 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 146 insertions(+)
>   create mode 100644 man7/sgx.7
> diff --git a/man7/sgx.7 b/man7/sgx.7
> new file mode 100644
> index 000000000..0b5aa87e9
> --- /dev/null
> +++ b/man7/sgx.7
> @@ -0,0 +1,146 @@
> +.\" Copyright (C) 2021 Intel Corporation
> +.\"
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein.  The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.TH SGX 7 2021\-02\-02 "Linux" "Linux Programmer's Manual"
> +.PP
> +sgx - overview of Software Guard eXtensions

Please, add .nf here (see any man2 or man3 pages as an example).

        .nf       No filling or adjusting of output lines.

> +.EX
> +.B #include <asm/sgx.h>
> +.PP
> +.IB enclave " = open(""/dev/sgx_enclave"", O_RDWR);"

Sorry for not jumping here before.  I read the thread but didn't have 
the time to reply.  What you wanted to use here is \(dq.

        \(dq   ASCII  double-quote.  Sometimes needed after macro
               calls to prevent the interpretation of  the  ASCII
               quotation  mark  character '"' as the beginning or
               end of a macro argument.


.IB enclave " = open(" \dq/dev/sgx_enclave\(dq ", O_RDWR);"

> +.EE

Please, add .fi here.

        .fi       Fill output lines.

> +Intel Software Guard eXtensions (SGX) allow applications to host
> +enclaves,
> +protected executable objects in memory.
> +.PP
> +Enclaves are blobs of executable code,
> +running inside a CPU enforced container,
> +which is mapped to the process address space.
> +They are represented as the instances of
> +.IR /dev/sgx_enclave .
> +They have a fixed set of entry points,
> +defined when the enclave is built.
> +.PP
> +SGX can only be available if the kernel is configured and built with the
> +option.
> +If CPU, BIOS and kernel have SGX enabled,
> +.I sgx
> +appears in the
> +.I flags
> +field of
> +.IR /proc/cpuinfo .
> +.PP
> +If SGX appears not to be available,
> +ensure that SGX is enabled in the BIOS.
> +If a BIOS presents a choice between
> +.I Enabled
> +and
> +.I Software Enabled
> +modes for SGX,
> +choose
> +.IR Enabled .
> +.PP

.PP not necessary just before .SS or .SH.  Please remove it.

> +.SS Memory mapping
> +The file descriptor for an enclave can be shared among multiple processes.
> +An enclave is required by the CPU to be placed to an address,
> +which is a multiple of its size.
> +An address range containing a reasonable base address can be probed with an anonymous
> +.BR mmap(2)
> +call:
> +.PP
> +.EX
> +void *area = mmap(NULL, size * 2, PROT_NONE, MAP_PRIVATE | MAP_ANONYMOUS,
> +                  -1, 0);
> +
> +void *base = ((uint64_t)area + size - 1) & ~(size - 1);

Wouldn't uintptr_t(3) be better here (instead of uint64_t(3))?

Also, please add a space just after the cast, just for consistency with 
other manual pages.

> +.EE
> +.PP

Please indent the above.

    Indentation of structure definitions, shell session logs, and so on
        When  structure  definitions, shell session logs, and so on are
        included in running text, indent them  by  4  spaces  (i.e.,  a
        block  enclosed  by .in +4n and .in), format them using the .EX
        and EE macros, and surround them with suitable paragraph  mark-
        ers (either .PP or .IP).  For example:

                .in +4n
                main(int argc, char *argv[])
                    return 0;

> +The enclave file descriptor itself can be then mapped with the

This should be .B

        .B [text]
               Set text in bold.  If the macro is given no  argu-
               ments,  the  text of the next input line is set in

               Use bold for literal portions of syntax  synopses,
               for  command-line options in running text, and for
               literals that are major topics of the subject  un-
               der  discussion;  for example, this page uses bold
               for macro and register names.  In .EX/.EE examples
               of  interactive I/O (such as a shell session), set
               only the user-typed input in bold.


        .BR bold-text roman-text ...
               Set each argument in bold and roman, alternately.

                      Any such change becomes effective with the first 
use of
                      .BR .NH ,
                      .I after
                      the new alias is defined.

> +flag set to the carved out memory.
> +.SS Construction
> +An enclave instance is created by opening
> +.IR /dev/sgx_enclave .
> +Its contents are populated with the
> +.BR ioctl (2)
> +interface in
> +.IR <asm/sgx.h> :
> +.TP

This should be .B

> +Create SGX Enclave Control Structure (SECS) for the enclave.
> +SECS is a hardware defined structure,
> +which contains the global properties of an enclave.

Same here

> +is a one-shot call that fixes the enclave's address and
> +size for the rest of its life-cycle.
> +.TP

Same here.

> +Fill a range of the enclave's pages with the caller provided data and protection bits.
> +Memory mappings of the enclave can only set protection bits that are defined in this ioctl.
> +The pages added are either regular pages for code and data,
> +or thread control structures (TCS).
> +The latter define the entry points to the enclave,
> +which can be entered after the initialization.
> +.TP

Same here.

> +Initialize the enclave for the run-time.
> +After a successful initialization,
> +no new pages can be added to the enclave.
> +.SS Invocation
> +Thread control structure (TCS) pages are the entry points to the enclave,
> +which further define an offset inside the enclave where the execution begins.
> +The entry points are invoked with
> +.IR __vdso_sgx_enter_enclave .
> +The prototype for the vDSO is defined by
> +.BR vdso_sgx_enter_enclave_t


Types go in italics.  This is to be added to a future manual page 
groff_man_style(7).  Discussed here: 

> +in
> +.IR <asm/sgx.h> .
> +.SS Permissions
> +.PP
> +During the build process each enclave page is assigned protection bits,
> +as part of

Function calls go in italics.

        Expressions, if not written on a separate indented  line,
        should  be  specified in italics.  Again, the use of non-
        breaking spaces may be appropriate if the  expression  is
        inlined with normal text.

So this should use .IR, not .BR.

Also, a space before the period.

        .IR italic-text roman-text ...
               Set  each  argument  in  italics and roman, alter-

                      This is the first command of the
                      .IR prologue .

> +These protections are also the maximum protections with which the page can be be mapped.
> +If
> +.BR mmap (2)
> +is called with higher protections than those defined during the build,
> +it will return
> +.B -EACCES.

.BR and a space.

        .BR bold-text roman-text ...
               Set each argument in bold and roman, alternately.

                      Any such change becomes effective with the first 
use of
                      .BR .NH ,
                      .I after
                      the new alias is defined.

> +If


        .I [text]
               Set text in italics.  If the macro is given no ar-
               guments, the text of the next input line is set in

               Use italics for file and path names, for  environ-
               ment  variables,  for  enumeration or preprocessor
               constants in  C,  for  variable  (user-determined)
               portions  of syntax synopses, for the first occur-
               rence only of a  technical  concept  being  intro-
               duced,  for  names of works of software (including
               commands and functions, but excluding names of op-
               erating  systems or their kernels), and anywhere a
               parameter requiring replacement by the user is en-
               countered.  An exception involves variable text in
               a context that is already marked  up  in  italics,
               such  as  file  or path names with variable compo-
               nents; in such cases,  follow  the  convention  of
               mathematical typography: set the file or path name
               in italics as usual (see .IR below), but use roman
               for  the  variable part, and italics again in run-
               ning roman text when referring to the variable ma-

> +is called after
> +.BR mmap (2)
> +with lower protections,
> +the caller receives

A space before the comma.

> +once it accesses the page for the first time.
> +The SGX feature was added in Linux 5.11.
> +.BR ioctl (2),
> +.BR mmap (2),
> +.BR mprotect (2)

Alejandro Colomar
Linux man-pages comaintainer;

  reply	other threads:[~2021-12-17  1:51 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-12-11 15:33 [PATCH v11] sgx.7: New page with overview of Software Guard eXtensions (SGX) Jarkko Sakkinen
2021-12-17  1:50 ` Alejandro Colomar (man-pages) [this message]
2022-01-28  1:19   ` Jarkko Sakkinen
2022-02-09 20:19     ` Alejandro Colomar (man-pages)
2022-02-20 20:05       ` Jarkko Sakkinen
2023-03-30 22:29         ` Alejandro Colomar
2023-04-21 21:13           ` Jarkko Sakkinen

Reply instructions:

You may reply publicly 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
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).