* doc/c-xtensa.texi (Xtensa Options, Absolute Literals Directive):

	Remove comments about placement of literal pools.
	(Literal Directive): Update description of literal placement.
	(Literal Prefix Directive): Remove statement that this does not apply
	to absolute-mode literals.  Describe new section naming scheme.

1 files changed, 39 insertions, 28 deletions

diff --git a/gas/doc/c-xtensa.texi b/gas/doc/c-xtensa.texi
index 5101d31..25065f8 100644
--- a/gas/doc/c-xtensa.texi
+++ b/gas/doc/c-xtensa.texi
@@ -54,9 +54,7 @@ Indicate to the assembler whether @code{L32R} instructions use absolute
 or PC-relative addressing.  If the processor includes the absolute
 addressing option, the default is to use absolute @code{L32R}
 relocations.  Otherwise, only the PC-relative @code{L32R} relocations
-can be used.  Literals referenced with absolute @code{L32R} relocations
-are always placed in the @code{.lit4} section, independent of the
-placement of PC-relative literals.
+can be used.
 
 @item --target-align | --no-target-align
 @kindex --target-align
@@ -616,17 +614,17 @@ can be used to load a pointer to the symbol @code{sym} into register
 the data in a literal pool.
 
 Literal pools for absolute mode @code{L32R} instructions
-(@pxref{Absolute Literals Directive}) are always placed in the
+(@pxref{Absolute Literals Directive}) are placed in a seperate
 @code{.lit4} section.  By default literal pools for PC-relative mode
-@code{L32R} instructions are placed in a separate section; however, when
-using the @samp{--text-@-section-@-literals} option (@pxref{Xtensa
-Options, ,Command Line Options}), the literal pools are placed in the
-current section.  These text section literal pools are created
-automatically before @code{ENTRY} instructions and manually after
-@samp{.literal_position} directives (@pxref{Literal Position Directive,
-,literal_position}).  If there are no preceding @code{ENTRY}
-instructions, explicit @code{.literal_position} directives
-must be used to place the text section literal pools; otherwise, 
+@code{L32R} instructions are placed in a separate @code{.literal}
+section; however, when using the @samp{--text-@-section-@-literals}
+option (@pxref{Xtensa Options, ,Command Line Options}), the literal
+pools are placed in the current section.  These text section literal
+pools are created automatically before @code{ENTRY} instructions and
+manually after @samp{.literal_position} directives (@pxref{Literal
+Position Directive, ,literal_position}).  If there are no preceding
+@code{ENTRY} instructions, explicit @code{.literal_position} directives
+must be used to place the text section literal pools; otherwise,
 @command{@value{AS}} will report an error.
 
 @node Literal Position Directive
@@ -679,9 +677,6 @@ continue:
 
 The @code{literal_prefix} directive allows you to specify different
 sections to hold literals from different portions of an assembly file.
-This directive only applies to literals referenced from PC-relative
-@code{L32R} instructions; it has no effect for absolute literals
-(@pxref{Absolute Literals Directive}).
 With this directive, a single assembly file can be used to generate code
 into multiple sections, including literals generated by the assembler.
 
@@ -690,13 +685,34 @@ into multiple sections, including literals generated by the assembler.
     .end literal_prefix
 @end smallexample
 
-For the code inside the delimited region, the assembler puts literals in
-the section @code{@var{name}.literal}. If this section does not yet
-exist, the assembler creates it.  The @var{name} parameter is
-optional. If @var{name} is not specified, the literal prefix is set to
-the ``default'' for the file.  This default is usually @code{.literal}
-but can be changed with the @samp{--rename-section} command-line
-argument.
+By default the assembler places literal pools in sections separate from
+the instructions, using the default literal section names of
+@code{.literal} for PC-relative mode @code{L32R} instructions and
+@code{.lit4} for absolute mode @code{L32R} instructions (@pxref{Absolute
+Literals Directive}).  The @code{literal_prefix} directive causes
+different literal sections to be used for the code inside the delimited
+region.  The new literal sections are determined by including @var{name}
+as a prefix to the default literal section names.  If the @var{name}
+argument is omitted, the literal sections revert to the defaults.  This
+directive has no effect when using the
+@samp{--text-@-section-@-literals} option (@pxref{Xtensa Options,
+,Command Line Options}).
+
+Except for two special cases, the assembler determines the new literal
+sections by simply prepending @var{name} to the default section names,
+resulting in @code{@var{name}.literal} and @code{@var{name}.lit4}
+sections.  The @code{literal_prefix} directive is often used with the
+name of the current text section as the prefix argument.  To facilitate
+this usage, the assembler uses special case rules when it recognizes
+@var{name} as a text section name.  First, if @var{name} ends with
+@code{.text}, that suffix is not included in the literal section name.
+For example, if @var{name} is @code{.iram0.text}, then the literal
+sections will be @code{.iram0.literal} and @code{.iram0.lit4}.  Second,
+if @var{name} begins with @code{.gnu.linkonce.t.}, then the literal
+section names are formed by replacing the @code{.t} substring with
+@code{.literal} and @code{.lit4}.  For example, if @var{name} is
+@code{.gnu.linkonce.t.func}, the literal sections will be
+@code{.gnu.linkonce.literal.func} and @code{.gnu.linkonce.lit4.func}.
 
 @node Absolute Literals Directive
 @subsection absolute-literals
@@ -721,11 +737,6 @@ To change the @code{L32R} mode, the program must write the
 to keep track of the mode and indicate to the assembler which mode is
 used in each region of code.
 
-Literals referenced with absolute @code{L32R} instructions are always
-placed in the @code{.lit4} section.  PC-relative literals may be placed
-in the current text section or in a separate literal section, as
-described elsewhere (@pxref{Literal Directive}).
-
 If the Xtensa configuration includes the absolute @code{L32R} addressing
 option, the default is to assume absolute @code{L32R} addressing unless
 the @samp{--no-@-absolute-@-literals} command-line option is specified.