Merge branch 'vendor/OPENSSL'
[dragonfly.git] / contrib / binutils-2.24 / gas / doc / c-tilepro.texi
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
14
15 @cindex TILEPro support
16 @menu
17 * TILEPro Options::             TILEPro Options
18 * TILEPro Syntax::              TILEPro Syntax
19 * TILEPro Directives::          TILEPro Directives
20 @end menu
21
22 @node TILEPro Options
23 @section Options
24
25 @code{@value{AS}} has no machine-dependent command-line options for
26 TILEPro.
27
28 @node TILEPro Syntax
29 @section Syntax
30 @cindex TILEPro syntax
31 @cindex syntax, TILEPro
32
33 Block comments are delimited by @samp{/*} and @samp{*/}.  End of line
34 comments may be introduced by @samp{#}.
35
36 Instructions consist of a leading opcode or macro name followed by
37 whitespace and an optional comma-separated list of operands:
38
39 @smallexample
40 @var{opcode} [@var{operand}, @dots{}]
41 @end smallexample
42
43 Instructions must be separated by a newline or semicolon.
44
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.
48
49 Bundles are specified using curly braces:
50
51 @smallexample
52 @{ @var{add} r3,r4,r5 ; @var{add} r7,r8,r9 ; @var{lw} r10,r11 @}
53 @end smallexample
54
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.
58
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.
63
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.
69
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.
74
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.
81
82 @menu
83 * TILEPro Opcodes::              Opcode Naming Conventions.
84 * TILEPro Registers::            Register Naming.
85 * TILEPro Modifiers::            Symbolic Operand Modifiers.
86 @end menu
87
88 @node TILEPro Opcodes
89 @subsection Opcode Names
90 @cindex TILEPro opcode names
91 @cindex opcode names, TILEPro
92
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.
96
97 @node TILEPro Registers
98 @subsection Register Names
99 @cindex TILEPro register names
100 @cindex register names, TILEPro
101
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:
106
107 @table @code
108 @item r54
109 sp
110
111 @item r55
112 lr
113
114 @item r56
115 sn
116
117 @item r57
118 idn0
119
120 @item r58
121 idn1
122
123 @item r59
124 udn0
125
126 @item r60
127 udn1
128
129 @item r61
130 udn2
131
132 @item r62
133 udn3
134
135 @item r63
136 zero
137
138 @end table
139
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.
144
145 @node TILEPro Modifiers
146 @subsection Symbolic Operand Modifiers
147 @cindex TILEPro modifiers
148 @cindex symbol modifiers, TILEPro
149
150 The assembler supports several modifiers when using symbol addresses
151 in TILEPro instruction operands.  The general syntax is the following:
152
153 @smallexample
154 modifier(symbol)
155 @end smallexample
156
157 The following modifiers are supported:
158
159 @table @code
160
161 @item lo16
162
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).
167
168 @item hi16
169
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.
172
173 @item ha16
174
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:
180
181 @smallexample
182 moveli r3, lo16(sym)
183 auli r3, r3, ha16(sym)
184 @end smallexample
185
186 @item got
187
188 This modifier is used to load the offset of the GOT entry
189 corresponding to the symbol.
190
191 @item got_lo16
192
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.
195
196 @item got_hi16
197
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.
200
201 @item got_ha16
202
203 This modifier is like @code{got_hi16}, but it adds one if
204 @code{got_lo16} of the input value is negative.
205
206 @item plt
207
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.
218
219 @item tls_gd
220
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.
223
224 @item tls_gd_lo16
225
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.
229
230 @item tls_gd_hi16
231
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.
235
236 @item tls_gd_ha16
237
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.
240
241 @item tls_ie
242
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.
246
247 @item tls_ie_lo16
248
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.
252
253 @item tls_ie_hi16
254
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.
258
259 @item tls_ie_ha16
260
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.
263
264 @item tls_le
265
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.
268
269 @item tls_le_lo16
270
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.
273
274 @item tls_le_hi16
275
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.
278
279 @item tls_le_ha16
280
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.
283
284 @item tls_gd_call
285
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.
288
289 @item tls_gd_add
290
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.
293
294 @item tls_ie_load
295
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.
298
299 @end table
300
301 @node TILEPro Directives
302 @section TILEPro Directives
303 @cindex machine directives, TILEPro
304 @cindex TILEPro machine directives
305
306 @table @code
307
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.
312
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.
317
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.
321
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.
326
327 @item .no_require_canonical_reg_names
328 Permit the use of numeric names for registers that have canonical
329 names.
330
331 @end table
332