diff options
Diffstat (limited to 'gas/doc/c-xtensa.texi')
| -rw-r--r-- | gas/doc/c-xtensa.texi | 92 |
1 files changed, 92 insertions, 0 deletions
diff --git a/gas/doc/c-xtensa.texi b/gas/doc/c-xtensa.texi index 406e635..e763e36 100644 --- a/gas/doc/c-xtensa.texi +++ b/gas/doc/c-xtensa.texi @@ -91,6 +91,16 @@ instruction operands to be errors. @kindex --rename-section Rename the @var{oldname} section to @var{newname}. This option can be used multiple times to rename multiple sections. + +@item --trampolines | --no-trampolines +@kindex --trampolines +@kindex --no-trampolines +Enable or disable transformation of jump instructions to allow jumps +across a greater range of addresses. @xref{Xtensa Jump Relaxation, +,Jump Trampolines}. This option should be used when jump targets can +potentially be out of range. In the absence of such jumps this option +does not affect code size or performance. The default is +@samp{--trampolines}. @end table @c man end @@ -311,6 +321,7 @@ fields. @menu * Xtensa Branch Relaxation:: Relaxation of Branches. * Xtensa Call Relaxation:: Relaxation of Function Calls. +* Xtensa Jump Relaxation:: Relaxation of Jumps. * Xtensa Immediate Relaxation:: Relaxation of other Immediate Fields. @end menu @@ -398,6 +409,87 @@ 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 Jump Relaxation +@subsection Jump Relaxation +@cindex relaxation of jump instructions +@cindex jump instructions, relaxation + +Jump instruction may require relaxation because the Xtensa jump instruction +(@code{J}) provide a PC-relative offset of only 128 Kbytes in either +direction. One option is to use jump long (@code{J.L}) instruction, which +depending on jump distance may be assembled as jump (@code{J}) or indirect +jump (@code{JX}). However it needs a free register. When there's no spare +register it is possible to plant intermediate jump sites (trampolines) +between the jump instruction and its target. These sites may be located in +areas unreachable by normal code execution flow, in that case they only +contain intermediate jumps, or they may be inserted in the middle of code +block, in which case there's an additional jump from the beginning of the +trampoline to the instruction past its end. So, for example: + +@smallexample +@group + j 1f + ... + retw + ... + mov a10, a2 + call8 func + ... +1: + ... +@end group +@end smallexample + +might be relaxed to: + +@smallexample +@group + j .L0_TR_1 + ... + retw +.L0_TR_1: + j 1f + ... + mov a10, a2 + call8 func + ... +1: + ... +@end group +@end smallexample + +or to: + +@smallexample +@group + j .L0_TR_1 + ... + retw + ... + mov a10, a2 + j .L0_TR_0 +.L0_TR_1: + j 1f +.L0_TR_0: + call8 func + ... +1: + ... +@end group +@end smallexample + +The Xtensa assempler uses trampolines with jump around only when it cannot +find suitable unreachable trampoline. There may be multiple trampolines +between the jump instruction and its target. + +This relaxation does not apply to jumps to undefined symbols, assuming they +will reach their targets once resolved. + +Jump relaxation is enabled by default because it does not affect code size +or performance while the code itself is small. This relaxation may be +disabled completely with @samp{--no-trampolines} or @samp{--no-transform} +command-line options (@pxref{Xtensa Options, ,Command Line Options}). + @node Xtensa Immediate Relaxation @subsection Other Immediate Field Relaxation @cindex immediate fields, relaxation |