doc: Document several "force_l32" features for Xtensa

This patch adds documentation for the "force_l32" features of the Xtensa
target that were added in recent patches.

gcc/ChangeLog:

	* doc/extend.texi (Xtensa Named Address Spaces):
	Document '__force_l32'.
	(Xtensa Attributes): Document 'force_l32'.
	* doc/invoke.texi (Xtensa Options):
	Document '-m[no-]force-l32'.

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 0faa5323ce167411effa87c5827b48c9f371f6f9..8dd0b3137bc1253aa547d1eae9fe1182518b57f9 100644 (file)
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -1379,7 +1379,7 @@ 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, M32C, PRU, RL78, and x86 targets support
+present, only the AVR, M32C, PRU, RL78, x86 and Xtensa targets support
 address spaces other than the generic address space.
 
 Address space identifiers may be used exactly like any other C type
@@ -1618,6 +1618,55 @@ The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
 defined when these address spaces are supported.
 @end table
 
+@anchor{Xtensa Named Address Spaces}
+@subsection Xtensa Named Address Spaces
+@cindex @code{__force_l32} Xtensa Named Address Spaces
+
+On the Xtensa target, when a variable qualified with @code{__force_l32}
+is loaded from memory, it is always read aligned to a 4-byte width
+regardless of whether its width is 1 or 2 bytes, and a bit-extraction
+instruction is applied to the read to obtain the desired result; writing
+with a width of 1 or 2 bytes is not supported (see also @code{force_l32}
+attribute described in @ref{Xtensa Attributes}, and command-line option
+@option{-mforce-l32} described in @ref{Xtensa Options}).
+
+@smallexample
+char *strcpy_irom (char *dst, __force_l32 const char *src)
+@{
+  char *p = dst;
+  /* "*src" is always read as an aligned 4-byte width, and then
+     the desired one byte is extracted using bitwise operations.  */
+  while (*p = *src)
+    ++p, ++src;
+  return dst;
+@}
+@end smallexample
+
+Qualifying a variable with @code{__force_l32} affects how that variable
+is read as mentioned above, but it does not affect the memory section in
+which the variable is placed (this can be specified separately using the
+@code{section} attribute).
+
+@smallexample
+/* Instruction ROM reading requires aligned 4-byte width access.  */
+__force_l32 const char IROM_message[] __attribute__((section(".irom.text")))
+    = "placed within the instruction ROM area.";
+@end smallexample
+
+A pointer qualified with @code{__force_l32} can read memory regions in
+the generic address space (though not very efficiently), but not vice
+versa.  Therefore, the conversion from a pointer for the generic address
+space to a pointer qualified with @code{__force_l32} is implicit, but not
+the other way around.
+
+@smallexample
+extern char *strcpy_irom (char *, __force_l32 const char *);
+char buf[80], alt_buf[80];
+
+strcpy_irom (buf, IROM_message);
+strcpy_irom (alt_buf, "placed within read-only RAM area.");
+@end smallexample
+
 @anchor{Function Attributes}
 @anchor{Variable Attributes}
 @anchor{Type Attributes}
@@ -5729,6 +5778,7 @@ The default for the attribute is controlled by @option{-fzero-call-used-regs}.
 * Visium Attributes::
 * x86 Attributes::
 * Xstormy16 Attributes::
+* Xtensa Attributes::
 @end menu
 
 @anchor{AArch64 Function Attributes}
@@ -9810,6 +9860,27 @@ placed in either the @code{.bss_below100} section or the
 @code{.data_below100} section.
 @end table
 
+@node Xtensa Attributes
+@subsubsection Xtensa Attributes
+
+These attributes are supported by the Xtensa back end:
+
+@table @code
+@atindex @code{force_l32}, Xtensa
+@item force_l32
+This attribute can be applied to variables, function parameters and
+types.
+
+When this attribute is specified in a declaration, any memory loads of 1-
+or 2-byte width objects for the type (in the declaration) itself and all
+the underlying types contained within it are performed by a combination
+of aligned 4-byte load and bit-extraction instructions, rather than by
+instructions dedicated to those objects; storing memory with a width of 1
+or 2 bytes is not supported (see also @code{__force_l32} address spaces
+described in @ref{Xtensa Named Address Spaces}, and command-line option
+@option{-mforce-l32} described in @ref{Xtensa Options}).
+
+@end table
 
 @node Attribute Syntax
 @subsection GNU Attribute Syntax

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 756af474310c57c0549a7b0b5c846a3ce3fa5fe8..fb69dc5fb8058a6f3f3c842bfd009772ac6eddfa 100644 (file)
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1593,7 +1593,7 @@ See Cygwin and MinGW Options.
 @gccoptlist{-mconst16  -mforce-no-pic  -mno-serialize-volatile
 -mtext-section-literals  -mauto-litpools  -mno-target-align
 -mlongcalls  -mabi=@var{abi-type}
--mextra-l32r-costs=@var{cycles}  -mstrict-align}
+-mextra-l32r-costs=@var{cycles}  -mstrict-align  -mforce-l32}
 
 @emph{zSeries Options}
 See S/390 and zSeries Options.
@@ -37518,6 +37518,19 @@ The default is @option{-mno-strict-align} for cores that support both
 unaligned loads and stores in hardware and @option{-mstrict-align} for all
 other cores.
 
+@opindex mforce-l32
+@opindex mno-force-l32
+@item -mforce-l32
+@itemx -mno-force-l32
+When this option is enabled, GCC performs 1- or 2-byte loads in the generic
+address space (ie., default memory references) by bit-extracting the desired
+portion from the result of an aligned 4-byte load, instead of the instructions
+originally provided for those purposes.  This option does not affect memory
+stores of such byte width, or the placement of those memory sections (see
+also @code{__force_l32} address spaces described in
+@ref{Xtensa Named Address Spaces}, and @code{force_l32} attribute described
+in @ref{Xtensa Attributes}).  The default is @option{-mno-force-l32}.
+
 @end table
 
 @node zSeries Options