contrib/binutils-2.25/gas/doc/c-i960.texi

   1 @c Copyright (C) 1991-2014 Free Software Foundation, Inc.
   2 @c This is part of the GAS manual.
   3 @c For copying conditions, see the file as.texinfo.
   4 @ifset GENERIC
   5 @page
   6 @node i960-Dependent
   7 @chapter Intel 80960 Dependent Features
   8 @end ifset
   9 @ifclear GENERIC
  10 @node Machine Dependencies
  11 @chapter Intel 80960 Dependent Features
  12 @end ifclear
  13
  14 @cindex i960 support
  15 @menu
  16 * Options-i960::                i960 Command-line Options
  17 * Floating Point-i960::         Floating Point
  18 * Directives-i960::             i960 Machine Directives
  19 * Opcodes for i960::            i960 Opcodes
  20 * Syntax of i960::              i960 Syntax
  21 @end menu
  22
  23 @c FIXME! Add Syntax sec with discussion of bitfields here, at least so
  24 @c long as they're not turned on for other machines than 960.
  25
  26 @node Options-i960
  27
  28 @section i960 Command-line Options
  29
  30 @cindex i960 options
  31 @cindex options, i960
  32 @table @code
  33
  34 @cindex i960 architecture options
  35 @cindex architecture options, i960
  36 @cindex @code{-A} options, i960
  37 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
  38 Select the 80960 architecture.  Instructions or features not supported
  39 by the selected architecture cause fatal errors.
  40
  41 @samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to
  42 @samp{-AMC}.  Synonyms are provided for compatibility with other tools.
  43
  44 If you do not specify any of these options, @code{@value{AS}} generates code
  45 for any instruction or feature that is supported by @emph{some} version of the
  46 960 (even if this means mixing architectures!).  In principle,
  47 @code{@value{AS}} attempts to deduce the minimal sufficient processor type if
  48 none is specified; depending on the object code format, the processor type may
  49 be recorded in the object file.  If it is critical that the @code{@value{AS}}
  50 output match a specific architecture, specify that architecture explicitly.
  51
  52 @cindex @code{-b} option, i960
  53 @cindex branch recording, i960
  54 @cindex i960 branch recording
  55 @item -b
  56 Add code to collect information about conditional branches taken, for
  57 later optimization using branch prediction bits.  (The conditional branch
  58 instructions have branch prediction bits in the CA, CB, and CC
  59 architectures.)  If @var{BR} represents a conditional branch instruction,
  60 the following represents the code generated by the assembler when
  61 @samp{-b} is specified:
  62
  63 @smallexample
  64         call    @var{increment routine}
  65         .word   0       # pre-counter
  66 Label:  @var{BR}
  67         call    @var{increment routine}
  68         .word   0       # post-counter
  69 @end smallexample
  70
  71 The counter following a branch records the number of times that branch
  72 was @emph{not} taken; the difference between the two counters is the
  73 number of times the branch @emph{was} taken.
  74
  75 @cindex @code{gbr960}, i960 postprocessor
  76 @cindex branch statistics table, i960
  77 A table of every such @code{Label} is also generated, so that the
  78 external postprocessor @code{gbr960} (supplied by Intel) can locate all
  79 the counters.  This table is always labeled @samp{__BRANCH_TABLE__};
  80 this is a local symbol to permit collecting statistics for many separate
  81 object files.  The table is word aligned, and begins with a two-word
  82 header.  The first word, initialized to 0, is used in maintaining linked
  83 lists of branch tables.  The second word is a count of the number of
  84 entries in the table, which follow immediately: each is a word, pointing
  85 to one of the labels illustrated above.
  86
  87 @c TEXI2ROFF-KILL
  88 @ifinfo
  89 @c END TEXI2ROFF-KILL
  90 @example
  91  +------------+------------+------------+ ... +------------+
  92  |            |            |            |     |            |
  93  |  *NEXT     |  COUNT: N  | *BRLAB 1   |     | *BRLAB N   |
  94  |            |            |            |     |            |
  95  +------------+------------+------------+ ... +------------+
  96
  97                __BRANCH_TABLE__ layout
  98 @end example
  99 @c TEXI2ROFF-KILL
 100 @end ifinfo
 101 @need 2000
 102 @tex
 103 \vskip 1pc
 104 \line{\leftskip=0pt\hskip\tableindent
 105 \boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt
 106 *BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil}
 107 \centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout}
 108 @end tex
 109 @c END TEXI2ROFF-KILL
 110
 111 The first word of the header is used to locate multiple branch tables,
 112 since each object file may contain one. Normally the links are
 113 maintained with a call to an initialization routine, placed at the
 114 beginning of each function in the file.  The @sc{gnu} C compiler
 115 generates these calls automatically when you give it a @samp{-b} option.
 116 For further details, see the documentation of @samp{gbr960}.
 117
 118 @cindex @code{-no-relax} option, i960
 119 @item -no-relax
 120 Normally, Compare-and-Branch instructions with targets that require
 121 displacements greater than 13 bits (or that have external targets) are
 122 replaced with the corresponding compare (or @samp{chkbit}) and branch
 123 instructions.  You can use the @samp{-no-relax} option to specify that
 124 @code{@value{AS}} should generate errors instead, if the target displacement
 125 is larger than 13 bits.
 126
 127 This option does not affect the Compare-and-Jump instructions; the code
 128 emitted for them is @emph{always} adjusted when necessary (depending on
 129 displacement size), regardless of whether you use @samp{-no-relax}.
 130 @end table
 131
 132 @node Floating Point-i960
 133 @section Floating Point
 134
 135 @cindex floating point, i960 (@sc{ieee})
 136 @cindex i960 floating point (@sc{ieee})
 137 @code{@value{AS}} generates @sc{ieee} floating-point numbers for the directives
 138 @samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}.
 139
 140 @node Directives-i960
 141 @section i960 Machine Directives
 142
 143 @cindex machine directives, i960
 144 @cindex i960 machine directives
 145
 146 @table @code
 147 @cindex @code{bss} directive, i960
 148 @item .bss @var{symbol}, @var{length}, @var{align}
 149 Reserve @var{length} bytes in the bss section for a local @var{symbol},
 150 aligned to the power of two specified by @var{align}.  @var{length} and
 151 @var{align} must be positive absolute expressions.  This directive
 152 differs from @samp{.lcomm} only in that it permits you to specify
 153 an alignment.  @xref{Lcomm,,@code{.lcomm}}.
 154 @end table
 155
 156 @table @code
 157 @cindex @code{extended} directive, i960
 158 @item .extended @var{flonums}
 159 @code{.extended} expects zero or more flonums, separated by commas; for
 160 each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit)
 161 floating-point number.
 162
 163 @cindex @code{leafproc} directive, i960
 164 @item .leafproc @var{call-lab}, @var{bal-lab}
 165 You can use the @samp{.leafproc} directive in conjunction with the
 166 optimized @code{callj} instruction to enable faster calls of leaf
 167 procedures.  If a procedure is known to call no other procedures, you
 168 may define an entry point that skips procedure prolog code (and that does
 169 not depend on system-supplied saved context), and declare it as the
 170 @var{bal-lab} using @samp{.leafproc}.  If the procedure also has an
 171 entry point that goes through the normal prolog, you can specify that
 172 entry point as @var{call-lab}.
 173
 174 A @samp{.leafproc} declaration is meant for use in conjunction with the
 175 optimized call instruction @samp{callj}; the directive records the data
 176 needed later to choose between converting the @samp{callj} into a
 177 @code{bal} or a @code{call}.
 178
 179 @var{call-lab} is optional; if only one argument is present, or if the
 180 two arguments are identical, the single argument is assumed to be the
 181 @code{bal} entry point.
 182
 183 @cindex @code{sysproc} directive, i960
 184 @item .sysproc @var{name}, @var{index}
 185 The @samp{.sysproc} directive defines a name for a system procedure.
 186 After you define it using @samp{.sysproc}, you can use @var{name} to
 187 refer to the system procedure identified by @var{index} when calling
 188 procedures with the optimized call instruction @samp{callj}.
 189
 190 Both arguments are required; @var{index} must be between 0 and 31
 191 (inclusive).
 192 @end table
 193
 194 @node Opcodes for i960
 195 @section i960 Opcodes
 196
 197 @cindex opcodes, i960
 198 @cindex i960 opcodes
 199 All Intel 960 machine instructions are supported;
 200 @pxref{Options-i960,,i960 Command-line Options} for a discussion of
 201 selecting the instruction subset for a particular 960
 202 architecture.@refill
 203
 204 Some opcodes are processed beyond simply emitting a single corresponding
 205 instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump
 206 instructions with target displacements larger than 13 bits.
 207
 208 @menu
 209 * callj-i960::                  @code{callj}
 210 * Compare-and-branch-i960::     Compare-and-Branch
 211 @end menu
 212
 213 @node callj-i960
 214 @subsection @code{callj}
 215
 216 @cindex @code{callj}, i960 pseudo-opcode
 217 @cindex i960 @code{callj} pseudo-opcode
 218 You can write @code{callj} to have the assembler or the linker determine
 219 the most appropriate form of subroutine call: @samp{call},
 220 @samp{bal}, or @samp{calls}.  If the assembly source contains
 221 enough information---a @samp{.leafproc} or @samp{.sysproc} directive
 222 defining the operand---then @code{@value{AS}} translates the
 223 @code{callj}; if not, it simply emits the @code{callj}, leaving it
 224 for the linker to resolve.
 225
 226 @node Compare-and-branch-i960
 227 @subsection Compare-and-Branch
 228
 229 @cindex i960 compare/branch instructions
 230 @cindex compare/branch instructions, i960
 231 The 960 architectures provide combined Compare-and-Branch instructions
 232 that permit you to store the branch target in the lower 13 bits of the
 233 instruction word itself.  However, if you specify a branch target far
 234 enough away that its address won't fit in 13 bits, the assembler can
 235 either issue an error, or convert your Compare-and-Branch instruction
 236 into separate instructions to do the compare and the branch.
 237
 238 @cindex compare and jump expansions, i960
 239 @cindex i960 compare and jump expansions
 240 Whether @code{@value{AS}} gives an error or expands the instruction depends
 241 on two choices you can make: whether you use the @samp{-no-relax} option,
 242 and whether you use a ``Compare and Branch'' instruction or a ``Compare
 243 and Jump'' instruction.  The ``Jump'' instructions are @emph{always}
 244 expanded if necessary; the ``Branch'' instructions are expanded when
 245 necessary @emph{unless} you specify @code{-no-relax}---in which case
 246 @code{@value{AS}} gives an error instead.
 247
 248 These are the Compare-and-Branch instructions, their ``Jump'' variants,
 249 and the instruction pairs they may expand into:
 250
 251 @c TEXI2ROFF-KILL
 252 @ifinfo
 253 @c END TEXI2ROFF-KILL
 254 @example
 255         Compare and
 256      Branch      Jump       Expanded to
 257      ------    ------       ------------
 258         bbc                 chkbit; bno
 259         bbs                 chkbit; bo
 260      cmpibe    cmpije       cmpi; be
 261      cmpibg    cmpijg       cmpi; bg
 262     cmpibge   cmpijge       cmpi; bge
 263      cmpibl    cmpijl       cmpi; bl
 264     cmpible   cmpijle       cmpi; ble
 265     cmpibno   cmpijno       cmpi; bno
 266     cmpibne   cmpijne       cmpi; bne
 267      cmpibo    cmpijo       cmpi; bo
 268      cmpobe    cmpoje       cmpo; be
 269      cmpobg    cmpojg       cmpo; bg
 270     cmpobge   cmpojge       cmpo; bge
 271      cmpobl    cmpojl       cmpo; bl
 272     cmpoble   cmpojle       cmpo; ble
 273     cmpobne   cmpojne       cmpo; bne
 274 @end example
 275 @c TEXI2ROFF-KILL
 276 @end ifinfo
 277 @tex
 278 \hskip\tableindent
 279 \halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr
 280 \omit{\hfil\it Compare and\hfil}\span\omit&\cr
 281 {\it Branch}&{\it Jump}&{\it Expanded to}\cr
 282         bbc&                 & chkbit; bno\cr
 283         bbs&                 & chkbit; bo\cr
 284      cmpibe&    cmpije&       cmpi; be\cr
 285      cmpibg&    cmpijg&       cmpi; bg\cr
 286     cmpibge&   cmpijge&       cmpi; bge\cr
 287      cmpibl&    cmpijl&       cmpi; bl\cr
 288     cmpible&   cmpijle&       cmpi; ble\cr
 289     cmpibno&   cmpijno&       cmpi; bno\cr
 290     cmpibne&   cmpijne&       cmpi; bne\cr
 291      cmpibo&    cmpijo&       cmpi; bo\cr
 292      cmpobe&    cmpoje&       cmpo; be\cr
 293      cmpobg&    cmpojg&       cmpo; bg\cr
 294     cmpobge&   cmpojge&       cmpo; bge\cr
 295      cmpobl&    cmpojl&       cmpo; bl\cr
 296     cmpoble&   cmpojle&       cmpo; ble\cr
 297     cmpobne&   cmpojne&       cmpo; bne\cr}
 298 @end tex
 299 @c END TEXI2ROFF-KILL
 300
 301 @node Syntax of i960
 302 @section Syntax for the i960
 303 @menu
 304 * i960-Chars::                Special Characters
 305 @end menu
 306
 307 @node i960-Chars
 308 @subsection Special Characters
 309
 310 @cindex line comment character, i960
 311 @cindex i960 line comment character
 312 The presence of a @samp{#} on a line indicates the start of a comment
 313 that extends to the end of the current line.
 314
 315 If a @samp{#} appears as the first character of a line, the whole line
 316 is treated as a comment, but in this case the line can also be a
 317 logical line number directive (@pxref{Comments}) or a
 318 preprocessor control command (@pxref{Preprocessing}).
 319
 320 @cindex line separator, i960
 321 @cindex statement separator, i960
 322 @cindex i960 line separator
 323 The @samp{;} character can be used to separate statements on the same
 324 line.