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