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