(@cindex @samp{--pcrel}): Rewrite option description.

1 files changed, 64 insertions, 30 deletions

diff --git a/gas/doc/c-m68k.texi b/gas/doc/c-m68k.texi
index 877c166..4328f71 100644
--- a/gas/doc/c-m68k.texi
+++ b/gas/doc/c-m68k.texi
@@ -27,9 +27,12 @@
 @cindex options, M680x0
 @cindex M680x0 options
 The Motorola 680x0 version of @code{@value{AS}} has a few machine
-dependent options.
+dependent options:
+
+@table @samp
 
 @cindex @samp{-l} option, M680x0
+@item -l
 You can use the @samp{-l} option to shorten the size of references to undefined
 symbols.  If you do not use the @samp{-l} option, references to undefined
 symbols are wide enough for a full @code{long} (32 bits).  (Since
@@ -41,6 +44,7 @@ This may be useful if you want the object file to be as small as possible, and
 you know that the relevant symbols are always less than 17 bits away.
 
 @cindex @samp{--register-prefix-optional} option, M680x0
+@item --register-prefix-optional
 For some configurations, especially those where the compiler normally
 does not prepend an underscore to the names of user variables, the
 assembler requires a @samp{%} before any use of a register name.  This
@@ -54,6 +58,7 @@ refer to C variables and functions with the same names as register
 names.
 
 @cindex @samp{--bitwise-or} option, M680x0
+@item --bitwise-or
 Normally the character @samp{|} is treated as a comment character, which
 means that it can not be used in expressions.  The @samp{--bitwise-or}
 option turns @samp{|} into a normal character.  In this mode, you must
@@ -62,6 +67,7 @@ at the beginning of a line.
 
 @cindex @samp{--base-size-default-16}
 @cindex @samp{--base-size-default-32}
+@item --base-size-default-16  --base-size-default-32 
 If you use an addressing mode with a base register without specifying
 the size, @code{@value{AS}} will normally use the full 32 bit value.
 For example, the addressing mode @samp{%a0@@(%d0)} is equivalent to
@@ -73,6 +79,7 @@ default behaviour.
 
 @cindex @samp{--disp-size-default-16}
 @cindex @samp{--disp-size-default-32}
+@item --disp-size-default-16  --disp-size-default-32
 If you use an addressing mode with a displacement, and the value of the
 displacement is not known, @code{@value{AS}} will normally assume that
 the value is 32 bits.  For example, if the symbol @samp{disp} has not
@@ -85,15 +92,21 @@ to instead assume that the displacement is 16 bits.  In this case,
 @samp{--disp-size-default-32} option to restore the default behaviour.
 
 @cindex @samp{--pcrel}
-Always generate PC relative branches.  Actually what this option really
-does is to prevent PC relative branches from being turned into absolute
-jumps.  If this cannot be done (because the specific architecture does
-not have a suitable PC relative branch instruction), the assembler will
-generate an error message.
+@item --pcrel
+Always keep branches PC-relative.  In the M680x0 architecture all branches
+are defined as PC-relative.  However, on some processors they are limited
+to word displacements maximum.  When @code{@value{AS}} needs a long branch
+that is not available, it normally emits an absolute jump instead.  This
+option disables this substitution.  When this option is given and no long
+branches are available, only word branches will be emitted.  An error
+message will be generated if a word branch cannot reach its target.  This
+option has no effect on 68020 and other processors that have long branches.
+@pxref{M68K-Branch,,Branch Improvement}.
 
 @cindex @samp{-m68000} and related options
 @cindex architecture options, M680x0
 @cindex M680x0 architecture options
+@item -m68000
 @code{@value{AS}} can assemble code for several different members of the
 Motorola 680x0 family.  The default depends upon how @code{@value{AS}}
 was configured when it was built; normally, the default is to assemble
@@ -175,6 +188,7 @@ Do not assemble 68851 MMU instructions.  This is the default for the
 68000, 68010, and the CPU32.  The 68040 accepts a somewhat different set
 of MMU instructions.
 @end table
+@end table
 
 @node M68K-Syntax
 @section Syntax
@@ -410,28 +424,39 @@ cases that are more fully described after the table:
 
 @smallexample
           Displacement
-          +-------------------------------------------------
-          |                68020   68000/10
-Pseudo-Op |BYTE    WORD    LONG    LONG      non-PC relative
-          +-------------------------------------------------
-     jbsr |bsrs    bsr     bsrl    jsr       jsr
-      jra |bras    bra     bral    jmp       jmp
-*     jXX |bXXs    bXX     bXXl    bNXs;jmpl bNXs;jmp
-*    dbXX |dbXX    dbXX        dbXX; bra; jmpl
-*    fjXX |fbXXw   fbXXw   fbXXl             fbNXw;jmp
+          +------------------------------------------------------------
+          |                68020           68000/10, not PC-relative OK
+Pseudo-Op |BYTE    WORD    LONG            ABSOLUTE LONG JUMP    **
+          +------------------------------------------------------------
+     jbsr |bsrs    bsrw    bsrl            jsr
+      jra |bras    braw    bral            jmp
+*     jXX |bXXs    bXXw    bXXl            bNXs;jmp
+*    dbXX | N/A    dbXXw   dbXX;bras;bral  dbXX;bras;jmp
+     fjXX | N/A    fbXXw   fbXXl            N/A
 
 XX: condition
 NX: negative of condition XX
 
 @end smallexample
 @center @code{*}---see full description below
+@center @code{**}---this expansion mode is disallowed by @samp{--pcrel}
 
 @table @code
 @item jbsr
 @itemx jra
 These are the simplest jump pseudo-operations; they always map to one
 particular machine instruction, depending on the displacement to the
-branch target.
+branch target.  This instruction will be a byte or word branch is that
+is sufficient.  Otherwise, a long branch will be emitted if available.
+If no long branches are available and the @samp{--pcrel} option is not
+given, an absolute long jump will be emitted instead.  If no long
+branches are available, the @samp{--pcrel} option is given, and a word
+branch cannot reach the target, an error message is generated.
+
+In addition to standard branch operands, @code{@value{AS}} allows these
+pseudo-operations to have all operands that are allowed for jsr and jmp,
+substituting these instructions if the operand given is not valid for a
+branch instruction.
 
 @item j@var{XX}
 Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations,
@@ -442,10 +467,11 @@ list of pseudo-ops in this family is:
  jvs   jpl   jmi   jge   jlt   jgt   jle
 @end smallexample
 
-For the cases of non-PC relative displacements and long displacements on
-the 68000 or 68010, @code{@value{AS}} issues a longer code fragment in terms of
-@var{NX}, the opposite condition to @var{XX}.  For example, for the
-non-PC relative case:
+Usually, each of these pseudo-operations expands to a single branch
+instruction.  However, if a word branch is not sufficient, no long branches
+are available, and the @samp{--pcrel} option is not given, @code{@value{AS}}
+issues a longer code fragment in terms of @var{NX}, the opposite condition
+to @var{XX}.  For example, under these conditions:
 @smallexample
     j@var{XX} foo
 @end smallexample
@@ -464,12 +490,24 @@ The full family of pseudo-operations covered here is
  dbf    dbra   dbt
 @end smallexample
 
-Other than for word and byte displacements, when the source reads
+Motorola @samp{db@var{XX}} instructions allow word displacements only.  When
+a word displacement is sufficient, each of these pseudo-operations expands
+to the corresponding Motorola instruction.  When a word displacement is not
+sufficient and long branches are available, when the source reads
 @samp{db@var{XX} foo}, @code{@value{AS}} emits
 @smallexample
      db@var{XX} oo1
-     bra oo2
- oo1:jmpl foo
+     bras oo2
+ oo1:bral foo
+ oo2:
+@end smallexample
+
+If, however, long branches are not available and the @samp{--pcrel} option is
+not given, @code{@value{AS}} emits
+@smallexample
+     db@var{XX} oo1
+     bras oo2
+ oo1:jmp foo
  oo2:
 @end smallexample
 
@@ -483,13 +521,9 @@ This family includes
  fjugt  fjule  fjult  fjun
 @end smallexample
 
-For branch targets that are not PC relative, @code{@value{AS}} emits
-@smallexample
-     fb@var{NX} oof
-     jmp foo
- oof:
-@end smallexample
-when it encounters @samp{fj@var{XX} foo}.
+Each of these pseudo-operations always expands to a single Motorola
+coprocessor branch instruction, word or long.  All Motorola coprocessor
+branch instructions allow both word and long displacements.
 
 @end table