Merge branch 'vendor/OPENSSL'
[dragonfly.git] / contrib / binutils-2.22 / gas / doc / c-tilegx.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 @c man end
6
7 @ifset GENERIC
8 @page
9 @node TILE-Gx-Dependent
10 @chapter TILE-Gx Dependent Features
11 @end ifset
12 @ifclear GENERIC
13 @node Machine Dependencies
14 @chapter TILE-Gx Dependent Features
15 @end ifclear
16
17 @cindex TILE-Gx support
18 @menu
19 * TILE-Gx Options::             TILE-Gx Options
20 * TILE-Gx Syntax::              TILE-Gx Syntax
21 * TILE-Gx Directives::          TILE-Gx Directives
22 @end menu
23
24 @node TILE-Gx Options
25 @section Options
26
27 The following table lists all available TILE-Gx specific options:
28
29 @c man begin OPTIONS
30 @table @gcctabopt
31 @cindex @samp{-m32} option, TILE-Gx
32 @cindex @samp{-m64} option, TILE-Gx
33 @item -m32 | -m64
34 Select the word size, either 32 bits or 64 bits.
35
36 @end table
37 @c man end
38
39 @node TILE-Gx Syntax
40 @section Syntax
41 @cindex TILE-Gx syntax
42 @cindex syntax, TILE-Gx
43
44 Block comments are delimited by @samp{/*} and @samp{*/}.  End of line
45 comments may be introduced by @samp{#}.
46
47 Instructions consist of a leading opcode or macro name followed by
48 whitespace and an optional comma-separated list of operands:
49
50 @smallexample
51 @var{opcode} [@var{operand}, @dots{}]
52 @end smallexample
53
54 Instructions must be separated by a newline or semicolon.
55
56 There are two ways to write code: either write naked instructions,
57 which the assembler is free to combine into VLIW bundles, or specify
58 the VLIW bundles explicitly.
59
60 Bundles are specified using curly braces:
61
62 @smallexample
63 @{ @var{add} r3,r4,r5 ; @var{add} r7,r8,r9 ; @var{lw} r10,r11 @}
64 @end smallexample
65
66 A bundle can span multiple lines. If you want to put multiple
67 instructions on a line, whether in a bundle or not, you need to
68 separate them with semicolons as in this example.
69
70 A bundle may contain one or more instructions, up to the limit
71 specified by the ISA (currently three). If fewer instructions are
72 specified than the hardware supports in a bundle, the assembler
73 inserts @code{fnop} instructions automatically.
74
75 The assembler will prefer to preserve the ordering of instructions
76 within the bundle, putting the first instruction in a lower-numbered
77 pipeline than the next one, etc.  This fact, combined with the
78 optional use of explicit @code{fnop} or @code{nop} instructions,
79 allows precise control over which pipeline executes each instruction.
80
81 If the instructions cannot be bundled in the listed order, the
82 assembler will automatically try to find a valid pipeline
83 assignment. If there is no way to bundle the instructions together,
84 the assembler reports an error.
85
86 The assembler does not yet auto-bundle (automatically combine multiple
87 instructions into one bundle), but it reserves the right to do so in
88 the future.  If you want to force an instruction to run by itself, put
89 it in a bundle explicitly with curly braces and use @code{nop}
90 instructions (not @code{fnop}) to fill the remaining pipeline slots in
91 that bundle.
92
93 @menu
94 * TILE-Gx Opcodes::              Opcode Naming Conventions.
95 * TILE-Gx Registers::            Register Naming.
96 * TILE-Gx Modifiers::            Symbolic Operand Modifiers.
97 @end menu
98
99 @node TILE-Gx Opcodes
100 @subsection Opcode Names
101 @cindex TILE-Gx opcode names
102 @cindex opcode names, TILE-Gx
103
104 For a complete list of opcodes and descriptions of their semantics,
105 see @cite{TILE-Gx Instruction Set Architecture}, available upon
106 request at www.tilera.com.
107
108 @node TILE-Gx Registers
109 @subsection Register Names
110 @cindex TILE-Gx register names
111 @cindex register names, TILE-Gx
112
113 General-purpose registers are represented by predefined symbols of the
114 form @samp{r@var{N}}, where @var{N} represents a number between
115 @code{0} and @code{63}.  However, the following registers have
116 canonical names that must be used instead:
117
118 @table @code
119 @item r54
120 sp
121
122 @item r55
123 lr
124
125 @item r56
126 sn
127
128 @item r57
129 idn0
130
131 @item r58
132 idn1
133
134 @item r59
135 udn0
136
137 @item r60
138 udn1
139
140 @item r61
141 udn2
142
143 @item r62
144 udn3
145
146 @item r63
147 zero
148
149 @end table
150
151 The assembler will emit a warning if a numeric name is used instead of
152 the non-numeric name.  The @code{.no_require_canonical_reg_names}
153 assembler pseudo-op turns off this
154 warning. @code{.require_canonical_reg_names} turns it back on.
155
156 @node TILE-Gx Modifiers
157 @subsection Symbolic Operand Modifiers
158 @cindex TILE-Gx modifiers
159 @cindex symbol modifiers, TILE-Gx
160
161 The assembler supports several modifiers when using symbol addresses
162 in TILE-Gx instruction operands.  The general syntax is the following:
163
164 @smallexample
165 modifier(symbol)
166 @end smallexample
167
168 The following modifiers are supported:
169
170 @table @code
171
172 @item hw0
173
174 This modifier is used to load bits 0-15 of the symbol's address.
175
176 @item hw1
177
178 This modifier is used to load bits 16-31 of the symbol's address.
179
180 @item hw2
181
182 This modifier is used to load bits 32-47 of the symbol's address.
183
184 @item hw3
185
186 This modifier is used to load bits 48-63 of the symbol's address.
187
188 @item hw0_last
189
190 This modifier yields the same value as @code{hw0}, but it also checks
191 that the value does not overflow.
192
193 @item hw1_last
194
195 This modifier yields the same value as @code{hw1}, but it also checks
196 that the value does not overflow.
197
198 @item hw2_last
199
200 This modifier yields the same value as @code{hw2}, but it also checks
201 that the value does not overflow.
202
203 A 48-bit symbolic value is constructed by using the following idiom:
204
205 @smallexample
206 moveli r0, hw2_last(sym)
207 shl16insli r0, r0, hw1(sym)
208 shl16insli r0, r0, hw0(sym)
209 @end smallexample
210
211 @item hw0_got
212
213 This modifier is used to load bits 0-15 of the symbol's offset in the
214 GOT entry corresponding to the symbol.
215
216 @item hw1_got
217
218 This modifier is used to load bits 16-31 of the symbol's offset in the
219 GOT entry corresponding to the symbol.
220
221 @item hw2_got
222
223 This modifier is used to load bits 32-47 of the symbol's offset in the
224 GOT entry corresponding to the symbol.
225
226 @item hw3_got
227
228 This modifier is used to load bits 48-63 of the symbol's offset in the
229 GOT entry corresponding to the symbol.
230
231 @item hw0_last_got
232
233 This modifier yields the same value as @code{hw0_got}, but it also
234 checks that the value does not overflow.
235
236 @item hw1_last_got
237
238 This modifier yields the same value as @code{hw1_got}, but it also
239 checks that the value does not overflow.
240
241 @item hw2_last_got
242
243 This modifier yields the same value as @code{hw2_got}, but it also
244 checks that the value does not overflow.
245
246 @item plt
247
248 This modifier is used for function symbols.  It causes a
249 @emph{procedure linkage table}, an array of code stubs, to be created
250 at the time the shared object is created or linked against, together
251 with a global offset table entry.  The value is a pc-relative offset
252 to the corresponding stub code in the procedure linkage table.  This
253 arrangement causes the run-time symbol resolver to be called to look
254 up and set the value of the symbol the first time the function is
255 called (at latest; depending environment variables).  It is only safe
256 to leave the symbol unresolved this way if all references are function
257 calls.
258
259 @item hw0_tls_gd
260
261 This modifier is used to load bits 0-15 of the offset of the GOT entry
262 of the symbol's TLS descriptor, to be used for general-dynamic TLS
263 accesses.
264
265 @item hw1_tls_gd
266
267 This modifier is used to load bits 16-31 of the offset of the GOT
268 entry of the symbol's TLS descriptor, to be used for general-dynamic
269 TLS accesses.
270
271 @item hw2_tls_gd
272
273 This modifier is used to load bits 32-47 of the offset of the GOT
274 entry of the symbol's TLS descriptor, to be used for general-dynamic
275 TLS accesses.
276
277 @item hw3_tls_gd
278
279 This modifier is used to load bits 48-63 of the offset of the GOT
280 entry of the symbol's TLS descriptor, to be used for general-dynamic
281 TLS accesses.
282
283 @item hw0_last_tls_gd
284
285 This modifier yields the same value as @code{hw0_tls_gd}, but it also
286 checks that the value does not overflow.
287
288 @item hw1_last_tls_gd
289
290 This modifier yields the same value as @code{hw1_tls_gd}, but it also
291 checks that the value does not overflow.
292
293 @item hw2_last_tls_gd
294
295 This modifier yields the same value as @code{hw2_tls_gd}, but it also
296 checks that the value does not overflow.
297
298 @item hw0_tls_ie
299
300 This modifier is used to load bits 0-15 of the offset of the GOT entry
301 containing the offset of the symbol's address from the TCB, to be used
302 for initial-exec TLS accesses.
303
304 @item hw1_tls_ie
305
306 This modifier is used to load bits 16-31 of the offset of the GOT
307 entry containing the offset of the symbol's address from the TCB, to
308 be used for initial-exec TLS accesses.
309
310 @item hw2_tls_ie
311
312 This modifier is used to load bits 32-47 of the offset of the GOT entry
313 containing the offset of the symbol's address from the TCB, to be used
314 for initial-exec TLS accesses.
315
316 @item hw3_tls_ie
317
318 This modifier is used to load bits 48-63 of the offset of the GOT
319 entry containing the offset of the symbol's address from the TCB, to
320 be used for initial-exec TLS accesses.
321
322 @item hw0_last_tls_ie
323
324 This modifier yields the same value as @code{hw0_tls_ie}, but it also
325 checks that the value does not overflow.
326
327 @item hw1_last_tls_ie
328
329 This modifier yields the same value as @code{hw1_tls_ie}, but it also
330 checks that the value does not overflow.
331
332 @item hw2_last_tls_ie
333
334 This modifier yields the same value as @code{hw2_tls_ie}, but it also
335 checks that the value does not overflow.
336
337 @end table
338
339 @node TILE-Gx Directives
340 @section TILE-Gx Directives
341 @cindex machine directives, TILE-Gx
342 @cindex TILE-Gx machine directives
343
344 @table @code
345
346 @cindex @code{.align} directive, TILE-Gx
347 @item .align @var{expression} [, @var{expression}]
348 This is the generic @var{.align} directive.  The first argument is the
349 requested alignment in bytes.
350
351 @cindex @code{.allow_suspicious_bundles} directive, TILE-Gx
352 @item .allow_suspicious_bundles
353 Turns on error checking for combinations of instructions in a bundle
354 that probably indicate a programming error.  This is on by default.
355
356 @item .no_allow_suspicious_bundles
357 Turns off error checking for combinations of instructions in a bundle
358 that probably indicate a programming error.
359
360 @cindex @code{.require_canonical_reg_names} directive, TILE-Gx
361 @item .require_canonical_reg_names
362 Require that canonical register names be used, and emit a warning if
363 the numeric names are used.  This is on by default.
364
365 @item .no_require_canonical_reg_names
366 Permit the use of numeric names for registers that have canonical
367 names.
368
369 @end table