Import binutils-2.20
[dragonfly.git] / contrib / binutils-2.20 / gas / doc / c-i960.texi
1 @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 2002, 2006
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 @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