Re: [PATCH v2 12/13] Document the x86 address spaces

[Sandra Loosemore <sandra at codesourcery dot com>]

On 10/20/2015 03:27 PM, Richard Henderson wrote:
> ---
>   gcc/doc/extend.texi | 46 ++++++++++++++++++++++++++++++++++++++++++++--
>   1 file changed, 44 insertions(+), 2 deletions(-)
>
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index bdbf513..677a4d4 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -1240,8 +1240,8 @@ As an extension, GNU C supports named address spaces as
>   defined in the N1275 draft of ISO/IEC DTR 18037.  Support for named
>   address spaces in GCC will evolve as the draft technical report
>   changes.  Calling conventions for any target might also change.  At
> -present, only the AVR, SPU, M32C, and RL78 targets support address
> -spaces other than the generic address space.
> +present, only the AVR, SPU, M32C, RL78, and i386/x86_64 targets support

We've previously decided that "x86-32", "x86-64" (hyphen instead of 
underscore), and "x86" (to refer inclusively to both variants) are the 
preferred terminology.  Please fix throughout the patch.

> +address spaces other than the generic address space.
>
>   Address space identifiers may be used exactly like any other C type
>   qualifier (e.g., @code{const} or @code{volatile}).  See the N1275
> @@ -1430,6 +1430,48 @@ It may use runtime library
>   support, or generate special machine instructions to access that address
>   space.
>
> +@subsection X86 Named Address Spaces

Other places use "x86", lowercase, even in section titles.

I'd add a "@cindex x86 named address spaces" here.  It looks like the 
convention is *not* to capitalize anything other than proper names in 
index entries....  please fix below as well.

> +
> +On the i386/x86_64 target, variables may be declared as being relative
> +to the @code{%fs} or @code{%gs} segments.
> +
> +@table @code
> +@item __seg_fs
> +@itemx __seg_gs
> +@cindex @code{__seg_fs} X86 Named Address Spaces
> +@cindex @code{__seg_gs} X86 Named Address Spaces
> +The object is accessed with the respective segment override prefix.
> +
> +The respective segment base must be set via some operating-system
> +specific method.

Either "operating-system-specific method", or "method specific to the 
operating system".  Here and below.

> Since an operating-system specific method would
> +also be required to find the segment base, these address spaces are

s/would also be/is/

> +not considered to be subspaces of the generic (flat) address space.
> +This means that explicit casts are required to convert pointers
> +between these address spaces and the generic address space.  In
> +practice one will need to cast to @code{uintptr_t} and apply the

s/one will need to/you should/

> +segment base offset known to the application.
> +
> +The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
> +defined when these address spaces are supported.
> +
> +@item __seg_tls
> +@cindex @code{__seg_tls} X86 Named Address Spaces
> +Some operating systems define either the @code{%fs} or @code{%gs}
> +segment as the thread-local storage base for each thread.  Objects
> +within this address space are accessed with the appropriate
> +segment override prefix.
> +
> +The pointer located at address 0 within the segment contains the
> +offset of the segment within the generic address space.  Thus this
> +address space is considered a subspace of the generic address space,
> +and the known segment offset is applied when converting addresses
> +to and from the generic address space.
> +
> +The preprocessor symbol @code{__SEG_TLS} is defined when this
> +address space is supported.
> +
> +@end table
> +
>   @node Zero Length
>   @section Arrays of Length Zero
>   @cindex arrays of length zero

-Sandra