diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 0faa5323ce1..8dd0b3137bc 100644 --- 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 756af474310..fb69dc5fb80 100644 --- 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