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