diff options
Diffstat (limited to 'gas/doc/c-xtensa.texi')
| -rw-r--r-- | gas/doc/c-xtensa.texi | 452 |
1 files changed, 240 insertions, 212 deletions
diff --git a/gas/doc/c-xtensa.texi b/gas/doc/c-xtensa.texi index 5e5f13a..5101d31 100644 --- a/gas/doc/c-xtensa.texi +++ b/gas/doc/c-xtensa.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2002 Free Software Foundation, Inc. +@c Copyright (C) 2002, 2004 Free Software Foundation, Inc. @c This is part of the GAS manual. @c For copying conditions, see the file as.texinfo. @c @@ -33,54 +33,30 @@ The Xtensa version of the @sc{gnu} assembler supports these special options: @table @code -@item --density | --no-density -@kindex --density -@kindex --no-density -@cindex Xtensa density option -@cindex density option, Xtensa -Enable or disable use of the Xtensa code density option (16-bit -instructions). @xref{Density Instructions, ,Using Density -Instructions}. If the processor is configured with the density option, -this is enabled by default; otherwise, it is always disabled. - -@item --relax | --no-relax -@kindex --relax -@kindex --no-relax -Enable or disable relaxation of instructions with immediate operands -that are outside the legal range for the instructions. @xref{Xtensa -Relaxation, ,Xtensa Relaxation}. The default is @samp{--relax} and this -default should almost always be used. If relaxation is disabled with -@samp{--no-relax}, instruction operands that are out of range will cause -errors. Note: In the current implementation, these options also control -whether assembler optimizations are performed, making these options -equivalent to @samp{--generics} and @samp{--no-generics}. - -@item --generics | --no-generics -@kindex --generics -@kindex --no-generics -Enable or disable all assembler transformations of Xtensa instructions, -including both relaxation and optimization. The default is -@samp{--generics}; @samp{--no-generics} should only be used in the rare -cases when the instructions must be exactly as specified in the assembly -source. -@c The @samp{--no-generics} option is like @samp{--no-relax} -@c except that it also disables assembler optimizations (@pxref{Xtensa -@c Optimizations}). -As with @samp{--no-relax}, using @samp{--no-generics} -causes out of range instruction operands to be errors. - @item --text-section-literals | --no-text-section-literals @kindex --text-section-literals @kindex --no-text-section-literals Control the treatment of literal pools. The default is @samp{--no-@-text-@-section-@-literals}, which places literals in a separate section in the output file. This allows the literal pool to be -placed in a data RAM/ROM, and it also allows the linker to combine literal -pools from separate object files to remove redundant literals and -improve code size. With @samp{--text-@-section-@-literals}, the +placed in a data RAM/ROM. With @samp{--text-@-section-@-literals}, the literals are interspersed in the text section in order to keep them as close as possible to their references. This may be necessary for large -assembly files. +assembly files, where the literals would otherwise be out of range of the +@code{L32R} instructions in the text section. These options only affect +literals referenced via PC-relative @code{L32R} instructions; literals +for absolute mode @code{L32R} instructions are handled separately. + +@item --absolute-literals | --no-absolute-literals +@kindex --absolute-literals +@kindex --no-absolute-literals +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. @item --target-align | --no-target-align @kindex --target-align @@ -97,14 +73,27 @@ have fixed alignment requirements. Enable or disable transformation of call instructions to allow calls across a greater range of addresses. @xref{Xtensa Call Relaxation, ,Function Call Relaxation}. This option should be used when call -targets can potentially be out of range, but it degrades both code size -and performance. The default is @samp{--no-@-longcalls}. +targets can potentially be out of range. It may degrade both code size +and performance, but the linker can generally optimize away the +unnecessary overhead when a call ends up within range. The default is +@samp{--no-@-longcalls}. + +@item --transform | --no-transform +@kindex --transform +@kindex --no-transform +Enable or disable all assembler transformations of Xtensa instructions, +including both relaxation and optimization. The default is +@samp{--transform}; @samp{--no-transform} should only be used in the +rare cases when the instructions must be exactly as specified in the +assembly source. Using @samp{--no-transform} causes out of range +instruction operands to be errors. @end table @node Xtensa Syntax @section Assembler Syntax @cindex syntax, Xtensa assembler @cindex Xtensa assembler syntax +@cindex FLIX syntax Block comments are delimited by @samp{/*} and @samp{*/}. End of line comments may be introduced with either @samp{#} or @samp{//}. @@ -113,11 +102,45 @@ Instructions consist of a leading opcode or macro name followed by whitespace and an optional comma-separated list of operands: @smallexample -@var{opcode} [@var{operand},@dots{}] +@var{opcode} [@var{operand}, @dots{}] @end smallexample Instructions must be separated by a newline or semicolon. +FLIX instructions, which bundle multiple opcodes together in a single +instruction, are specified by enclosing the bundled opcodes inside +braces: + +@smallexample +@{ +[@var{format}] +@var{opcode0} [@var{operands}] +@var{opcode1} [@var{operands}] +@var{opcode2} [@var{operands}] +@dots{} +@} +@end smallexample + +The opcodes in a FLIX instruction are listed in the same order as the +corresponding instruction slots in the TIE format declaration. +Directives and labels are not allowed inside the braces of a FLIX +instruction. A particular TIE format name can optionally be specified +immediately after the opening brace, but this is usually unnecessary. +The assembler will automatically search for a format that can encode the +specified opcodes, so the format name need only be specified in rare +cases where there is more than one applicable format and where it +matters which of those formats is used. A FLIX instruction can also be +specified on a single line by separating the opcodes with semicolons: + +@smallexample +@{ [@var{format};] @var{opcode0} [@var{operands}]; @var{opcode1} [@var{operands}]; @var{opcode2} [@var{operands}]; @dots{} @} +@end smallexample + +The assembler can automatically bundle opcodes into FLIX instructions. +It encodes the opcodes in order, one at a time, +choosing the smallest format where each opcode can be encoded and +filling unused instruction slots with no-ops. + @menu * Xtensa Opcodes:: Opcode Naming Conventions. * Xtensa Registers:: Register Naming. @@ -126,41 +149,30 @@ Instructions must be separated by a newline or semicolon. @node Xtensa Opcodes @subsection Opcode Names @cindex Xtensa opcode names -@cindex opcode names, Xtenxa +@cindex opcode names, Xtensa See the @cite{Xtensa Instruction Set Architecture (ISA) Reference Manual} for a complete list of opcodes and descriptions of their semantics. -@cindex generic opcodes -@cindex specific opcodes @cindex _ opcode prefix -The Xtensa assembler distinguishes between @dfn{generic} and -@dfn{specific} opcodes. Specific opcodes correspond directly to Xtensa -machine instructions. Prefixing an opcode with an underscore character -(@samp{_}) identifies it as a specific opcode. Opcodes without a -leading underscore are generic, which means the assembler is required to -preserve their semantics but may not translate them directly to the -specific opcodes with the same names. Instead, the assembler may -optimize a generic opcode and select a better instruction to use in its -place (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}), or the -assembler may relax the instruction to handle operands that are out of -range for the corresponding specific opcode (@pxref{Xtensa Relaxation, -,Xtensa Relaxation}). - -Only use specific opcodes when it is essential to select -the exact machine instructions produced by the assembler. -Using specific opcodes unnecessarily only makes the code less -efficient, by disabling assembler optimization, and less flexible, by -disabling relaxation. +If an opcode name is prefixed with an underscore character (@samp{_}), +@command{@value{AS}} will not transform that instruction in any way. The +underscore prefix disables both optimization (@pxref{Xtensa +Optimizations, ,Xtensa Optimizations}) and relaxation (@pxref{Xtensa +Relaxation, ,Xtensa Relaxation}) for that particular instruction. Only +use the underscore prefix when it is essential to select the exact +opcode produced by the assembler. Using this feature unnecessarily +makes the code less efficient by disabling assembler optimization and +less flexible by disabling relaxation. Note that this special handling of underscore prefixes only applies to Xtensa opcodes, not to either built-in macros or user-defined macros. -When an underscore prefix is used with a macro (e.g., @code{_NOP}), it +When an underscore prefix is used with a macro (e.g., @code{_MOV}), it refers to a different macro. The assembler generally provides built-in macros both with and without the underscore prefix, where the underscore versions behave as if the underscore carries through to the instructions -in the macros. For example, @code{_NOP} expands to @code{_OR a1,a1,a1}. +in the macros. For example, @code{_MOV} may expand to @code{_MOV.N}@. The underscore prefix only applies to individual instructions, not to series of instructions. For example, if a series of instructions have @@ -168,7 +180,7 @@ underscore prefixes, the assembler will not transform the individual instructions, but it may insert other instructions between them (e.g., to align a @code{LOOP} instruction). To prevent the assembler from modifying a series of instructions as a whole, use the -@code{no-generics} directive. @xref{Generics Directive, ,generics}. +@code{no-transform} directive. @xref{Transform Directive, ,transform}. @node Xtensa Registers @subsection Register Names @@ -176,20 +188,20 @@ modifying a series of instructions as a whole, use the @cindex register names, Xtensa @cindex sp register -An initial @samp{$} character is optional in all register names. -General purpose registers are named @samp{a0}@dots{}@samp{a15}. Additional -registers may be added by processor configuration options. In -particular, the @sc{mac16} option adds a @sc{mr} register bank. Its -registers are named @samp{m0}@dots{}@samp{m3}. - -As a special feature, @samp{sp} is also supported as a synonym for -@samp{a1}. +The assembly syntax for a register file entry is the ``short'' name for +a TIE register file followed by the index into that register file. For +example, the general-purpose @code{AR} register file has a short name of +@code{a}, so these registers are named @code{a0}@dots{}@code{a15}. +As a special feature, @code{sp} is also supported as a synonym for +@code{a1}. Additional registers may be added by processor configuration +options and by designer-defined TIE extensions. An initial @samp{$} +character is optional in all register names. @node Xtensa Optimizations @section Xtensa Optimizations @cindex optimizations -The optimizations currently supported by @code{@value{AS}} are +The optimizations currently supported by @command{@value{AS}} are generation of density instructions where appropriate and automatic branch target alignment. @@ -205,18 +217,18 @@ branch target alignment. The Xtensa instruction set has a code density option that provides 16-bit versions of some of the most commonly used opcodes. Use of these opcodes can significantly reduce code size. When possible, the -assembler automatically translates generic instructions from the core +assembler automatically translates instructions from the core Xtensa instruction set into equivalent instructions from the Xtensa code -density option. This translation can be disabled by using specific -opcodes (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the -@samp{--no-density} command-line option (@pxref{Xtensa Options, ,Command -Line Options}), or by using the @code{no-density} directive -(@pxref{Density Directive, ,density}). +density option. This translation can be disabled by using underscore +prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the +@samp{--no-transform} command-line option (@pxref{Xtensa Options, ,Command +Line Options}), or by using the @code{no-transform} directive +(@pxref{Transform Directive, ,transform}). It is a good idea @emph{not} to use the density instructions directly. The assembler will automatically select dense instructions where -possible. If you later need to avoid using the code density option, you -can disable it in the assembler without having to modify the code. +possible. If you later need to use an Xtensa processor without the code +density option, the same assembly code will then work without modification. @node Xtensa Automatic Alignment @subsection Automatic Instruction Alignment @@ -230,24 +242,42 @@ can disable it in the assembler without having to modify the code. The Xtensa assembler will automatically align certain instructions, both to optimize performance and to satisfy architectural requirements. -When the @code{--target-@-align} command-line option is enabled -(@pxref{Xtensa Options, ,Command Line Options}), the assembler attempts -to widen density instructions preceding a branch target so that the -target instruction does not cross a 4-byte boundary. Similarly, the -assembler also attempts to align each instruction following a call -instruction. If there are not enough preceding safe density -instructions to align a target, no widening will be performed. This -alignment has the potential to reduce branch penalties at some expense -in code size. The assembler will not attempt to align labels with the -prefixes @code{.Ln} and @code{.LM}, since these labels are used for -debugging information and are not typically branch targets. - -The @code{LOOP} family of instructions must be aligned on either a 1 or -2 mod 4 byte boundary. The assembler knows about this restriction and -inserts the minimal number of 2 or 3 byte no-op instructions -to satisfy it. When no-op instructions are added, any label immediately -preceding the original loop will be moved in order to refer to the loop -instruction, not the newly generated no-op instruction. +As an optimization to improve performance, the assembler attempts to +align branch targets so they do not cross instruction fetch boundaries. +(Xtensa processors can be configured with either 32-bit or 64-bit +instruction fetch widths.) An +instruction immediately following a call is treated as a branch target +in this context, because it will be the target of a return from the +call. This alignment has the potential to reduce branch penalties at +some expense in code size. The assembler will not attempt to align +labels with the prefixes @code{.Ln} and @code{.LM}, since these labels +are used for debugging information and are not typically branch targets. +This optimization is enabled by default. You can disable it with the +@samp{--no-target-@-align} command-line option (@pxref{Xtensa Options, +,Command Line Options}). + +The target alignment optimization is done without adding instructions +that could increase the execution time of the program. If there are +density instructions in the code preceding a target, the assembler can +change the target alignment by widening some of those instructions to +the equivalent 24-bit instructions. Extra bytes of padding can be +inserted immediately following unconditional jump and return +instructions. +This approach is usually successful in aligning many, but not all, +branch targets. + +The @code{LOOP} family of instructions must be aligned such that the +first instruction in the loop body does not cross an instruction fetch +boundary (e.g., with a 32-bit fetch width, a @code{LOOP} instruction +must be on either a 1 or 2 mod 4 byte boundary). The assembler knows +about this restriction and inserts the minimal number of 2 or 3 byte +no-op instructions to satisfy it. When no-op instructions are added, +any label immediately preceding the original loop will be moved in order +to refer to the loop instruction, not the newly generated no-op +instruction. To preserve binary compatibility across processors with +different fetch widths, the assembler conservatively assumes a 32-bit +fetch width when aligning @code{LOOP} instructions (except if the first +instruction in the loop is a 64-bit instruction). Similarly, the @code{ENTRY} instruction must be aligned on a 0 mod 4 byte boundary. The assembler satisfies this requirement by inserting @@ -260,7 +290,7 @@ location. @cindex relaxation When an instruction operand is outside the range allowed for that -particular instruction field, @code{@value{AS}} can transform the code +particular instruction field, @command{@value{AS}} can transform the code to use a functionally-equivalent instruction or sequence of instructions. This process is known as @dfn{relaxation}. This is typically done for branch instructions because the distance of the @@ -300,6 +330,19 @@ M: (The @code{BNEZ.N} instruction would be used in this example only if the density option is available. Otherwise, @code{BNEZ} would be used.) +This relaxation works well because the unconditional jump instruction +has a much larger offset range than the various conditional branches. +However, an error will occur if a branch target is beyond the range of a +jump instruction. @command{@value{AS}} cannot relax unconditional jumps. +Similarly, an error will occur if the original input contains an +unconditional jump to a target that is out of range. + +Branch relaxation is enabled by default. It can be disabled by using +underscore prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), the +@samp{--no-transform} command-line option (@pxref{Xtensa Options, +,Command Line Options}), or the @code{no-transform} directive +(@pxref{Transform Directive, ,transform}). + @node Xtensa Call Relaxation @subsection Function Call Relaxation @cindex relaxation of call instructions @@ -332,21 +375,27 @@ Because the addresses of targets of function calls are not generally known until link-time, the assembler must assume the worst and relax all the calls to functions in other source files, not just those that really will be out of range. The linker can recognize calls that were -unnecessarily relaxed, but it can only partially remove the overhead -introduced by the assembler. +unnecessarily relaxed, and it will remove the overhead introduced by the +assembler for those cases where direct calls are sufficient. -Call relaxation has a negative effect -on both code size and performance, so this relaxation is disabled by -default. If a program is too large and some of the calls are out of -range, function call relaxation can be enabled using the -@samp{--longcalls} command-line option or the @code{longcalls} directive -(@pxref{Longcalls Directive, ,longcalls}). +Call relaxation is disabled by default because it can have a negative +effect on both code size and performance, although the linker can +usually eliminate the unnecessary overhead. If a program is too large +and some of the calls are out of range, function call relaxation can be +enabled using the @samp{--longcalls} command-line option or the +@code{longcalls} directive (@pxref{Longcalls Directive, ,longcalls}). @node Xtensa Immediate Relaxation @subsection Other Immediate Field Relaxation @cindex immediate fields, relaxation @cindex relaxation of immediate fields +The assembler normally performs the following other relaxations. They +can be disabled by using underscore prefixes (@pxref{Xtensa Opcodes, +,Opcode Names}), the @samp{--no-transform} command-line option +(@pxref{Xtensa Options, ,Command Line Options}), or the +@code{no-transform} directive (@pxref{Transform Directive, ,transform}). + @cindex @code{MOVI} instructions, relaxation @cindex relaxation of @code{MOVI} instructions The @code{MOVI} machine instruction can only materialize values in the @@ -401,7 +450,7 @@ out-of-range offset causes an error. @cindex relaxation of @code{ADDI} instructions The Xtensa @code{ADDI} instruction only allows immediate operands in the range from -128 to 127. There are a number of alternate instruction -sequences for the generic @code{ADDI} operation. First, if the +sequences for the @code{ADDI} operation. First, if the immediate is 0, the @code{ADDI} will be turned into a @code{MOV.N} instruction (or the equivalent @code{OR} instruction if the code density option is not available). If the @code{ADDI} immediate is outside of @@ -456,87 +505,49 @@ change the state of the directive without having to be aware of its outer state. For example, consider: @smallexample - .begin no-density + .begin no-transform L: add a0, a1, a2 - .begin density + .begin transform M: add a0, a1, a2 - .end density + .end transform N: add a0, a1, a2 - .end no-density + .end no-transform @end smallexample -The generic @code{ADD} opcodes at @code{L} and @code{N} in the outer -@code{no-density} region both result in @code{ADD} machine instructions, -but the assembler selects an @code{ADD.N} instruction for the generic -@code{ADD} at @code{M} in the inner @code{density} region. +The @code{ADD} opcodes at @code{L} and @code{N} in the outer +@code{no-transform} region both result in @code{ADD} machine instructions, +but the assembler selects an @code{ADD.N} instruction for the +@code{ADD} at @code{M} in the inner @code{transform} region. The advantage of this style is that it works well inside macros which can preserve the context of their callers. -@cindex precedence of directives -@cindex directives, precedence -When command-line options and assembler directives are used at the same -time and conflict, the one that overrides a default behavior takes -precedence over one that is the same as the default. For example, if -the code density option is available, the default is to select density -instructions whenever possible. So, if the above is assembled with the -@samp{--no-density} flag, which overrides the default, all the generic -@code{ADD} instructions result in @code{ADD} machine instructions. If -assembled with the @samp{--density} flag, which is already the default, -the @code{no-density} directive takes precedence and only one of -the generic @code{ADD} instructions is optimized to be a @code{ADD.N} -machine instruction. An underscore prefix identifying a specific opcode -always takes precedence over directives and command-line flags. - The following directives are available: @menu -* Density Directive:: Disable Use of Density Instructions. -* Relax Directive:: Disable Assembler Relaxation. +* Schedule Directive:: Enable instruction scheduling. * Longcalls Directive:: Use Indirect Calls for Greater Range. -* Generics Directive:: Disable All Assembler Transformations. +* Transform Directive:: Disable All Assembler Transformations. * Literal Directive:: Intermix Literals with Instructions. * Literal Position Directive:: Specify Inline Literal Pool Locations. * Literal Prefix Directive:: Specify Literal Section Name Prefix. -* Freeregs Directive:: List Registers Available for Assembler Use. +* Absolute Literals Directive:: Control PC-Relative vs. Absolute Literals. * Frame Directive:: Describe a stack frame. @end menu -@node Density Directive -@subsection density -@cindex @code{density} directive -@cindex @code{no-density} directive +@node Schedule Directive +@subsection schedule +@cindex @code{schedule} directive +@cindex @code{no-schedule} directive -The @code{density} and @code{no-density} directives enable or disable -optimization of generic instructions into density instructions within -the region. @xref{Density Instructions, ,Using Density Instructions}. +The @code{schedule} directive is recognized only for compatibility with +Tensilica's assembler. @smallexample - .begin [no-]density - .end [no-]density + .begin [no-]schedule + .end [no-]schedule @end smallexample -This optimization is enabled by default unless the Xtensa configuration -does not support the code density option or the @samp{--no-density} -command-line option was specified. - -@node Relax Directive -@subsection relax -@cindex @code{relax} directive -@cindex @code{no-relax} directive - -The @code{relax} directive enables or disables relaxation -within the region. @xref{Xtensa Relaxation, ,Xtensa Relaxation}. -Note: In the current implementation, these directives also control -whether assembler optimizations are performed, making them equivalent to -the @code{generics} and @code{no-generics} directives. - -@smallexample - .begin [no-]relax - .end [no-]relax -@end smallexample - -Relaxation is enabled by default unless the @samp{--no-relax} -command-line option was specified. +This directive is ignored and has no effect on @command{@value{AS}}. @node Longcalls Directive @subsection longcalls @@ -552,27 +563,28 @@ relaxation. @xref{Xtensa Call Relaxation, ,Function Call Relaxation}. @end smallexample Call relaxation is disabled by default unless the @samp{--longcalls} -command-line option is specified. +command-line option is specified. The @code{longcalls} directive +overrides the default determined by the command-line options. -@node Generics Directive -@subsection generics -@cindex @code{generics} directive -@cindex @code{no-generics} directive +@node Transform Directive +@subsection transform +@cindex @code{transform} directive +@cindex @code{no-transform} directive This directive enables or disables all assembler transformation, including relaxation (@pxref{Xtensa Relaxation, ,Xtensa Relaxation}) and optimization (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}). @smallexample - .begin [no-]generics - .end [no-]generics + .begin [no-]transform + .end [no-]transform @end smallexample -Disabling generics is roughly equivalent to adding an underscore prefix -to every opcode within the region, so that every opcode is treated as a -specific opcode. @xref{Xtensa Opcodes, ,Opcode Names}. In the current -implementation of @code{@value{AS}}, built-in macros are also disabled -within a @code{no-generics} region. +Transformations are enabled by default unless the @samp{--no-transform} +option is used. The @code{transform} directive overrides the default +determined by the command-line options. An underscore opcode prefix, +disabling transformation of that opcode, always takes precedence over +both directives and command-line flags. @node Literal Directive @subsection literal @@ -603,17 +615,19 @@ can be used to load a pointer to the symbol @code{sym} into register @code{ENTRY} and @code{L32R} instructions; instead, the assembler puts the data in a literal pool. -By default literal pools are placed in a separate section; however, when +Literal pools for absolute mode @code{L32R} instructions +(@pxref{Absolute Literals Directive}) are always placed in the +@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 or @code{.literal_position} directives, the assembler will -print a warning and place the literal pool at the beginning of the -current section. In such cases, explicit @code{.literal_position} -directives should be used to place the literal pools. +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 @subsection literal_position @@ -628,7 +642,8 @@ can be used to mark a potential location for a literal pool. @end smallexample The @code{.literal_position} directive is ignored when the -@samp{--text-@-section-@-literals} option is not used. +@samp{--text-@-section-@-literals} option is not used or when +@code{L32R} instructions use the absolute addressing mode. The assembler will automatically place text section literal pools before @code{ENTRY} instructions, so the @code{.literal_position} @@ -642,7 +657,8 @@ place to put a literal pool. Moreover, the code for the interrupt vector must be at a specific starting address, so the literal pool cannot come before the start of the code. The literal pool for the vector must be explicitly positioned in the middle of the vector (before -any uses of the literals, of course). The @code{.literal_position} +any uses of the literals, due to the negative offsets used by +PC-relative @code{L32R} instructions). The @code{.literal_position} directive can be used to do this. In the following code, the literal for @samp{M} will automatically be aligned correctly and is placed after the unconditional jump. @@ -663,6 +679,9 @@ 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. @@ -679,31 +698,40 @@ the ``default'' for the file. This default is usually @code{.literal} but can be changed with the @samp{--rename-section} command-line argument. -@node Freeregs Directive -@subsection freeregs -@cindex @code{freeregs} directive - -This directive tells the assembler that the given registers are unused -in the region. - -@smallexample - .begin freeregs @var{ri}[,@var{ri}@dots{}] - .end freeregs -@end smallexample - -This allows the assembler to use these registers for relaxations or -optimizations. (They are actually only for relaxations at present, but -the possibility of optimizations exists in the future.) +@node Absolute Literals Directive +@subsection absolute-literals +@cindex @code{absolute-literals} directive +@cindex @code{no-absolute-literals} directive -Nested @code{freeregs} directives can be used to add additional registers -to the list of those available to the assembler. For example: +The @code{absolute-@-literals} and @code{no-@-absolute-@-literals} +directives control the absolute vs.@: PC-relative mode for @code{L32R} +instructions. These are relevant only for Xtensa configurations that +include the absolute addressing option for @code{L32R} instructions. @smallexample - .begin freeregs a3, a4 - .begin freeregs a5 + .begin [no-]absolute-literals + .end [no-]absolute-literals @end smallexample -has the effect of declaring @code{a3}, @code{a4}, and @code{a5} all free. +These directives do not change the @code{L32R} mode---they only cause +the assembler to emit the appropriate kind of relocation for @code{L32R} +instructions and to place the literal values in the appropriate section. +To change the @code{L32R} mode, the program must write the +@code{LITBASE} special register. It is the programmer's responsibility +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. +Otherwise, the default is to assume PC-relative @code{L32R} addressing. +The @code{absolute-@-literals} directive can then be used to override +the default determined by the command-line options. @node Frame Directive @subsection frame @@ -719,9 +747,9 @@ debugger to locate a function's stack frame. The syntax is: where @var{reg} is the register used to hold the frame pointer (usually the same as the stack pointer) and @var{size} is the size in bytes of the stack frame. The @code{.frame} directive is typically placed -immediately after the @code{ENTRY} instruction for a function. +near the @code{ENTRY} instruction for a function. -In almost all circumstances, this information just duplicates the +In many circumstances, this information just duplicates the information given in the function's @code{ENTRY} instruction; however, there are two cases where this is not true: |