Replace binutils 2.24 with latest binutils 2.27.
[dragonfly.git] / contrib / binutils-2.24 / gas / doc / c-tilepro.texi
blob5d80c4f05c4ce488bf7f775728008b25ba569496
1 @c Copyright 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 TILEPro-Dependent
8 @chapter TILEPro Dependent Features
9 @end ifset
10 @ifclear GENERIC
11 @node Machine Dependencies
12 @chapter TILEPro Dependent Features
13 @end ifclear
15 @cindex TILEPro support
16 @menu
17 * TILEPro Options::             TILEPro Options
18 * TILEPro Syntax::              TILEPro Syntax
19 * TILEPro Directives::          TILEPro Directives
20 @end menu
22 @node TILEPro Options
23 @section Options
25 @code{@value{AS}} has no machine-dependent command-line options for
26 TILEPro.
28 @node TILEPro Syntax
29 @section Syntax
30 @cindex TILEPro syntax
31 @cindex syntax, TILEPro
33 Block comments are delimited by @samp{/*} and @samp{*/}.  End of line
34 comments may be introduced by @samp{#}.
36 Instructions consist of a leading opcode or macro name followed by
37 whitespace and an optional comma-separated list of operands:
39 @smallexample
40 @var{opcode} [@var{operand}, @dots{}]
41 @end smallexample
43 Instructions must be separated by a newline or semicolon.
45 There are two ways to write code: either write naked instructions,
46 which the assembler is free to combine into VLIW bundles, or specify
47 the VLIW bundles explicitly.
49 Bundles are specified using curly braces:
51 @smallexample
52 @{ @var{add} r3,r4,r5 ; @var{add} r7,r8,r9 ; @var{lw} r10,r11 @}
53 @end smallexample
55 A bundle can span multiple lines. If you want to put multiple
56 instructions on a line, whether in a bundle or not, you need to
57 separate them with semicolons as in this example.
59 A bundle may contain one or more instructions, up to the limit
60 specified by the ISA (currently three). If fewer instructions are
61 specified than the hardware supports in a bundle, the assembler
62 inserts @code{fnop} instructions automatically.
64 The assembler will prefer to preserve the ordering of instructions
65 within the bundle, putting the first instruction in a lower-numbered
66 pipeline than the next one, etc.  This fact, combined with the
67 optional use of explicit @code{fnop} or @code{nop} instructions,
68 allows precise control over which pipeline executes each instruction.
70 If the instructions cannot be bundled in the listed order, the
71 assembler will automatically try to find a valid pipeline
72 assignment. If there is no way to bundle the instructions together,
73 the assembler reports an error.
75 The assembler does not yet auto-bundle (automatically combine multiple
76 instructions into one bundle), but it reserves the right to do so in
77 the future.  If you want to force an instruction to run by itself, put
78 it in a bundle explicitly with curly braces and use @code{nop}
79 instructions (not @code{fnop}) to fill the remaining pipeline slots in
80 that bundle.
82 @menu
83 * TILEPro Opcodes::              Opcode Naming Conventions.
84 * TILEPro Registers::            Register Naming.
85 * TILEPro Modifiers::            Symbolic Operand Modifiers.
86 @end menu
88 @node TILEPro Opcodes
89 @subsection Opcode Names
90 @cindex TILEPro opcode names
91 @cindex opcode names, TILEPro
93 For a complete list of opcodes and descriptions of their semantics,
94 see @cite{TILE Processor User Architecture Manual}, available upon
95 request at www.tilera.com.
97 @node TILEPro Registers
98 @subsection Register Names
99 @cindex TILEPro register names
100 @cindex register names, TILEPro
102 General-purpose registers are represented by predefined symbols of the
103 form @samp{r@var{N}}, where @var{N} represents a number between
104 @code{0} and @code{63}.  However, the following registers have
105 canonical names that must be used instead:
107 @table @code
108 @item r54
111 @item r55
114 @item r56
117 @item r57
118 idn0
120 @item r58
121 idn1
123 @item r59
124 udn0
126 @item r60
127 udn1
129 @item r61
130 udn2
132 @item r62
133 udn3
135 @item r63
136 zero
138 @end table
140 The assembler will emit a warning if a numeric name is used instead of
141 the canonical name.  The @code{.no_require_canonical_reg_names}
142 assembler pseudo-op turns off this
143 warning. @code{.require_canonical_reg_names} turns it back on.
145 @node TILEPro Modifiers
146 @subsection Symbolic Operand Modifiers
147 @cindex TILEPro modifiers
148 @cindex symbol modifiers, TILEPro
150 The assembler supports several modifiers when using symbol addresses
151 in TILEPro instruction operands.  The general syntax is the following:
153 @smallexample
154 modifier(symbol)
155 @end smallexample
157 The following modifiers are supported:
159 @table @code
161 @item lo16
163 This modifier is used to load the low 16 bits of the symbol's address,
164 sign-extended to a 32-bit value (sign-extension allows it to be
165 range-checked against signed 16 bit immediate operands without
166 complaint).
168 @item hi16
170 This modifier is used to load the high 16 bits of the symbol's
171 address, also sign-extended to a 32-bit value.
173 @item ha16
175 @code{ha16(N)} is identical to @code{hi16(N)}, except if
176 @code{lo16(N)} is negative it adds one to the @code{hi16(N)}
177 value. This way @code{lo16} and @code{ha16} can be added to create any
178 32-bit value using @code{auli}.  For example, here is how you move an
179 arbitrary 32-bit address into r3:
181 @smallexample
182 moveli r3, lo16(sym)
183 auli r3, r3, ha16(sym)
184 @end smallexample
186 @item got
188 This modifier is used to load the offset of the GOT entry
189 corresponding to the symbol.
191 @item got_lo16
193 This modifier is used to load the sign-extended low 16 bits of the
194 offset of the GOT entry corresponding to the symbol.
196 @item got_hi16
198 This modifier is used to load the sign-extended high 16 bits of the
199 offset of the GOT entry corresponding to the symbol.
201 @item got_ha16
203 This modifier is like @code{got_hi16}, but it adds one if
204 @code{got_lo16} of the input value is negative.
206 @item plt
208 This modifier is used for function symbols.  It causes a
209 @emph{procedure linkage table}, an array of code stubs, to be created
210 at the time the shared object is created or linked against, together
211 with a global offset table entry.  The value is a pc-relative offset
212 to the corresponding stub code in the procedure linkage table.  This
213 arrangement causes the run-time symbol resolver to be called to look
214 up and set the value of the symbol the first time the function is
215 called (at latest; depending environment variables).  It is only safe
216 to leave the symbol unresolved this way if all references are function
217 calls.
219 @item tls_gd
221 This modifier is used to load the offset of the GOT entry of the
222 symbol's TLS descriptor, to be used for general-dynamic TLS accesses.
224 @item tls_gd_lo16
226 This modifier is used to load the sign-extended low 16 bits of the
227 offset of the GOT entry of the symbol's TLS descriptor, to be used for
228 general dynamic TLS accesses.
230 @item tls_gd_hi16
232 This modifier is used to load the sign-extended high 16 bits of the
233 offset of the GOT entry of the symbol's TLS descriptor, to be used for
234 general dynamic TLS accesses.
236 @item tls_gd_ha16
238 This modifier is like @code{tls_gd_hi16}, but it adds one to the value
239 if @code{tls_gd_lo16} of the input value is negative.
241 @item tls_ie
243 This modifier is used to load the offset of the GOT entry containing
244 the offset of the symbol's address from the TCB, to be used for
245 initial-exec TLS accesses.
247 @item tls_ie_lo16
249 This modifier is used to load the low 16 bits of the offset of the GOT
250 entry containing the offset of the symbol's address from the TCB, to
251 be used for initial-exec TLS accesses.
253 @item tls_ie_hi16
255 This modifier is used to load the high 16 bits of the offset of the
256 GOT entry containing the offset of the symbol's address from the TCB,
257 to be used for initial-exec TLS accesses.
259 @item tls_ie_ha16
261 This modifier is like @code{tls_ie_hi16}, but it adds one to the value
262 if @code{tls_ie_lo16} of the input value is negative.
264 @item tls_le
266 This modifier is used to load the offset of the symbol's address from
267 the TCB, to be used for local-exec TLS accesses.
269 @item tls_le_lo16
271 This modifier is used to load the low 16 bits of the offset of the
272 symbol's address from the TCB, to be used for local-exec TLS accesses.
274 @item tls_le_hi16
276 This modifier is used to load the high 16 bits of the offset of the
277 symbol's address from the TCB, to be used for local-exec TLS accesses.
279 @item tls_le_ha16
281 This modifier is like @code{tls_le_hi16}, but it adds one to the value
282 if @code{tls_le_lo16} of the input value is negative.
284 @item tls_gd_call
286 This modifier is used to tag an instrution as the ``call'' part of a
287 calling sequence for a TLS GD reference of its operand.
289 @item tls_gd_add
291 This modifier is used to tag an instruction as the ``add'' part of a
292 calling sequence for a TLS GD reference of its operand.
294 @item tls_ie_load
296 This modifier is used to tag an instruction as the ``load'' part of a
297 calling sequence for a TLS IE reference of its operand.
299 @end table
301 @node TILEPro Directives
302 @section TILEPro Directives
303 @cindex machine directives, TILEPro
304 @cindex TILEPro machine directives
306 @table @code
308 @cindex @code{.align} directive, TILEPro
309 @item .align @var{expression} [, @var{expression}]
310 This is the generic @var{.align} directive.  The first argument is the
311 requested alignment in bytes.
313 @cindex @code{.allow_suspicious_bundles} directive, TILEPro
314 @item .allow_suspicious_bundles
315 Turns on error checking for combinations of instructions in a bundle
316 that probably indicate a programming error.  This is on by default.
318 @item .no_allow_suspicious_bundles
319 Turns off error checking for combinations of instructions in a bundle
320 that probably indicate a programming error.
322 @cindex @code{.require_canonical_reg_names} directive, TILEPro
323 @item .require_canonical_reg_names
324 Require that canonical register names be used, and emit a warning if
325 the numeric names are used.  This is on by default.
327 @item .no_require_canonical_reg_names
328 Permit the use of numeric names for registers that have canonical
329 names.
331 @end table