← Back to branch summary

~ubuntu-branches/ubuntu/utopic/binutils-arm64-cross/utopic

« back to all changes in this revision

Viewing changes to binutils-2.23.52.20130611/gas/doc/c-cris.texi

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-06-20 17:38:09 UTC
  • Revision ID: package-import@ubuntu.com-20130620173809-app8lzgvymy5fg6c
Tags: 0.7
Build-depend on binutils-source (>= 2.23.52.20130620-1~).

Show diffs side-by-side

added added

removed removed

Lines of Context:
binutils-2.23.52.20130611/gas/doc/c-cris.texi
 
1
@c Copyright 2002, 2004 Free Software Foundation, Inc.
 
2
@c This is part of the GAS manual.
 
3
@c For copying conditions, see the file as.texinfo.
 
4
@c CRIS description contributed by Axis Communications.
 
5
@ifset GENERIC
 
6
@page
 
7
@node CRIS-Dependent
 
8
@chapter CRIS Dependent Features
 
9
@end ifset
 
10
@ifclear GENERIC
 
11
@node Machine Dependencies
 
12
@chapter CRIS Dependent Features
 
13
@end ifclear
 
14
 
 
15
@cindex CRIS support
 
16
@menu
 
17
* CRIS-Opts::              Command-line Options
 
18
* CRIS-Expand::            Instruction expansion
 
19
* CRIS-Symbols::           Symbols
 
20
* CRIS-Syntax::            Syntax
 
21
@end menu
 
22
 
 
23
@node CRIS-Opts
 
24
@section Command-line Options
 
25
 
 
26
@cindex options, CRIS
 
27
@cindex CRIS options
 
28
The CRIS version of @code{@value{AS}} has these
 
29
machine-dependent command-line options.
 
30
 
 
31
@cindex @option{--emulation=criself} command line option, CRIS
 
32
@cindex @option{--emulation=crisaout} command line option, CRIS
 
33
@cindex CRIS @option{--emulation=criself} command line option
 
34
@cindex CRIS @option{--emulation=crisaout} command line option
 
35
 
 
36
The format of the generated object files can be either ELF or
 
37
a.out, specified by the command-line options
 
38
@option{--emulation=crisaout} and @option{--emulation=criself}.
 
39
The default is ELF (criself), unless @code{@value{AS}} has been
 
40
configured specifically for a.out by using the configuration
 
41
name @code{cris-axis-aout}.
 
42
 
 
43
@cindex @option{--underscore} command line option, CRIS
 
44
@cindex @option{--no-underscore} command line option, CRIS
 
45
@cindex CRIS @option{--underscore} command line option
 
46
@cindex CRIS @option{--no-underscore} command line option
 
47
There are two different link-incompatible ELF object file
 
48
variants for CRIS, for use in environments where symbols are
 
49
expected to be prefixed by a leading @samp{_} character and for
 
50
environments without such a symbol prefix.  The variant used for
 
51
GNU/Linux port has no symbol prefix.  Which variant to produce
 
52
is specified by either of the options @option{--underscore} and
 
53
@option{--no-underscore}.  The default is @option{--underscore}.
 
54
Since symbols in CRIS a.out objects are expected to have a
 
55
@samp{_} prefix, specifying @option{--no-underscore} when
 
56
generating a.out objects is an error.  Besides the object format
 
57
difference, the effect of this option is to parse register names
 
58
differently (@pxref{crisnous}).  The @option{--no-underscore}
 
59
option makes a @samp{$} register prefix mandatory.
 
60
 
 
61
@cindex @option{--pic} command line option, CRIS
 
62
@cindex CRIS @option{--pic} command line option
 
63
@cindex Position-independent code, CRIS
 
64
@cindex CRIS position-independent code
 
65
The option @option{--pic} must be passed to @code{@value{AS}} in
 
66
order to recognize the symbol syntax used for ELF (SVR4 PIC)
 
67
position-independent-code (@pxref{crispic}).  This will also
 
68
affect expansion of instructions.  The expansion with
 
69
@option{--pic} will use PC-relative rather than (slightly
 
70
faster) absolute addresses in those expansions.  This option is only
 
71
valid when generating ELF format object files.
 
72
 
 
73
@cindex @option{--march=@var{architecture}} command line option, CRIS
 
74
@cindex CRIS @option{--march=@var{architecture}} command line option
 
75
@cindex Architecture variant option, CRIS
 
76
@cindex CRIS architecture variant option
 
77
The option @option{--march=@var{architecture}}
 
78
@anchor{march-option}specifies the recognized instruction set
 
79
and recognized register names.  It also controls the
 
80
architecture type of the object file.  Valid values for
 
81
@var{architecture} are:
 
82
@table @code
 
83
 
 
84
@item v0_v10
 
85
All instructions and register names for any architecture variant
 
86
in the set v0@dots{}v10 are recognized.  This is the
 
87
default if the target is configured as cris-*.
 
88
 
 
89
@item v10
 
90
Only instructions and register names for CRIS v10 (as found in
 
91
ETRAX 100 LX) are recognized.  This is the default if the target
 
92
is configured as crisv10-*.
 
93
 
 
94
@item v32
 
95
Only instructions and register names for CRIS v32 (code name
 
96
Guinness) are recognized.  This is the default if the target is
 
97
configured as crisv32-*.  This value implies
 
98
@option{--no-mul-bug-abort}.  (A subsequent
 
99
@option{--mul-bug-abort} will turn it back on.)
 
100
 
 
101
@item common_v10_v32
 
102
Only instructions with register names and addressing modes with
 
103
opcodes common to the v10 and v32 are recognized.
 
104
@end table
 
105
 
 
106
@cindex @option{-N} command line option, CRIS
 
107
@cindex CRIS @option{-N} command line option
 
108
When @option{-N} is specified, @code{@value{AS}} will emit a
 
109
warning when a 16-bit branch instruction is expanded into a
 
110
32-bit multiple-instruction construct (@pxref{CRIS-Expand}).
 
111
 
 
112
@cindex @option{--no-mul-bug-abort} command line option, CRIS
 
113
@cindex @option{--mul-bug-abort} command line option, CRIS
 
114
@cindex CRIS @option{--no-mul-bug-abort} command line option
 
115
@cindex CRIS @option{--mul-bug-abort} command line option
 
116
 
 
117
Some versions of the CRIS v10, for example in the Etrax 100 LX,
 
118
contain a bug that causes destabilizing memory accesses when a
 
119
multiply instruction is executed with certain values in the
 
120
first operand just before a cache-miss.  When the
 
121
@option{--mul-bug-abort} command line option is active (the
 
122
default value), @code{@value{AS}} will refuse to assemble a file
 
123
containing a multiply instruction at a dangerous offset, one
 
124
that could be the last on a cache-line, or is in a section with
 
125
insufficient alignment.  This placement checking does not catch
 
126
any case where the multiply instruction is dangerously placed
 
127
because it is located in a delay-slot.  The
 
128
@option{--mul-bug-abort} command line option turns off the
 
129
checking.
 
130
 
 
131
@node CRIS-Expand
 
132
@section Instruction expansion
 
133
 
 
134
@cindex instruction expansion, CRIS
 
135
@cindex CRIS instruction expansion
 
136
@code{@value{AS}} will silently choose an instruction that fits
 
137
the operand size for @samp{[register+constant]} operands.  For
 
138
example, the offset @code{127} in @code{move.d [r3+127],r4} fits
 
139
in an instruction using a signed-byte offset.  Similarly,
 
140
@code{move.d [r2+32767],r1} will generate an instruction using a
 
141
16-bit offset.  For symbolic expressions and constants that do
 
142
not fit in 16 bits including the sign bit, a 32-bit offset is
 
143
generated.
 
144
 
 
145
For branches, @code{@value{AS}} will expand from a 16-bit branch
 
146
instruction into a sequence of instructions that can reach a
 
147
full 32-bit address.  Since this does not correspond to a single
 
148
instruction, such expansions can optionally be warned about.
 
149
@xref{CRIS-Opts}.
 
150
 
 
151
If the operand is found to fit the range, a @code{lapc} mnemonic
 
152
will translate to a @code{lapcq} instruction.  Use @code{lapc.d}
 
153
to force the 32-bit @code{lapc} instruction.
 
154
 
 
155
Similarly, the @code{addo} mnemonic will translate to the
 
156
shortest fitting instruction of @code{addoq}, @code{addo.w} and
 
157
@code{addo.d}, when used with a operand that is a constant known
 
158
at assembly time.
 
159
 
 
160
@node CRIS-Symbols
 
161
@section Symbols
 
162
@cindex Symbols, built-in, CRIS
 
163
@cindex Symbols, CRIS, built-in
 
164
@cindex CRIS built-in symbols
 
165
@cindex Built-in symbols, CRIS
 
166
 
 
167
Some symbols are defined by the assembler.  They're intended to
 
168
be used in conditional assembly, for example:
 
169
@smallexample
 
170
 .if ..asm.arch.cris.v32
 
171
 @var{code for CRIS v32}
 
172
 .elseif ..asm.arch.cris.common_v10_v32
 
173
 @var{code common to CRIS v32 and CRIS v10}
 
174
 .elseif ..asm.arch.cris.v10 | ..asm.arch.cris.any_v0_v10
 
175
 @var{code for v10}
 
176
 .else
 
177
 .error "Code needs to be added here."
 
178
 .endif
 
179
@end smallexample
 
180
 
 
181
These symbols are defined in the assembler, reflecting
 
182
command-line options, either when specified or the default.
 
183
They are always defined, to 0 or 1.
 
184
@table @code
 
185
 
 
186
@item ..asm.arch.cris.any_v0_v10
 
187
This symbol is non-zero when @option{--march=v0_v10} is specified
 
188
or the default.
 
189
 
 
190
@item ..asm.arch.cris.common_v10_v32
 
191
Set according to the option @option{--march=common_v10_v32}.
 
192
 
 
193
@item ..asm.arch.cris.v10
 
194
Reflects the option @option{--march=v10}.
 
195
 
 
196
@item ..asm.arch.cris.v32
 
197
Corresponds to @option{--march=v10}.
 
198
@end table
 
199
 
 
200
Speaking of symbols, when a symbol is used in code, it can have
 
201
a suffix modifying its value for use in position-independent
 
202
code. @xref{CRIS-Pic}.
 
203
 
 
204
@node CRIS-Syntax
 
205
@section Syntax
 
206
 
 
207
There are different aspects of the CRIS assembly syntax.
 
208
 
 
209
@menu
 
210
* CRIS-Chars::                  Special Characters
 
211
* CRIS-Pic::                    Position-Independent Code Symbols
 
212
* CRIS-Regs::                   Register Names
 
213
* CRIS-Pseudos::                Assembler Directives
 
214
@end menu
 
215
 
 
216
@node CRIS-Chars
 
217
@subsection Special Characters
 
218
@cindex line comment characters, CRIS
 
219
@cindex CRIS line comment characters
 
220
 
 
221
The character @samp{#} is a line comment character.  It starts a
 
222
comment if and only if it is placed at the beginning of a line.
 
223
 
 
224
A @samp{;} character starts a comment anywhere on the line,
 
225
causing all characters up to the end of the line to be ignored.
 
226
 
 
227
A @samp{@@} character is handled as a line separator equivalent
 
228
to a logical new-line character (except in a comment), so
 
229
separate instructions can be specified on a single line.
 
230
 
 
231
@node CRIS-Pic
 
232
@subsection Symbols in position-independent code
 
233
@cindex Symbols in position-independent code, CRIS
 
234
@cindex CRIS symbols in position-independent code
 
235
@cindex Position-independent code, symbols in, CRIS
 
236
 
 
237
When generating @anchor{crispic}position-independent code (SVR4
 
238
PIC) for use in cris-axis-linux-gnu or crisv32-axis-linux-gnu
 
239
shared libraries, symbol
 
240
suffixes are used to specify what kind of run-time symbol lookup
 
241
will be used, expressed in the object as different
 
242
@emph{relocation types}.  Usually, all absolute symbol values
 
243
must be located in a table, the @emph{global offset table},
 
244
leaving the code position-independent; independent of values of
 
245
global symbols and independent of the address of the code.  The
 
246
suffix modifies the value of the symbol, into for example an
 
247
index into the global offset table where the real symbol value
 
248
is entered, or a PC-relative value, or a value relative to the
 
249
start of the global offset table.  All symbol suffixes start
 
250
with the character @samp{:} (omitted in the list below).  Every
 
251
symbol use in code or a read-only section must therefore have a
 
252
PIC suffix to enable a useful shared library to be created.
 
253
Usually, these constructs must not be used with an additive
 
254
constant offset as is usually allowed, i.e.@: no 4 as in
 
255
@code{symbol + 4} is allowed.  This restriction is checked at
 
256
link-time, not at assembly-time.
 
257
 
 
258
@table @code
 
259
@item GOT
 
260
 
 
261
Attaching this suffix to a symbol in an instruction causes the
 
262
symbol to be entered into the global offset table.  The value is
 
263
a 32-bit index for that symbol into the global offset table.
 
264
The name of the corresponding relocation is
 
265
@samp{R_CRIS_32_GOT}.  Example: @code{move.d
 
266
[$r0+extsym:GOT],$r9}
 
267
 
 
268
@item GOT16
 
269
 
 
270
Same as for @samp{GOT}, but the value is a 16-bit index into the
 
271
global offset table.  The corresponding relocation is
 
272
@samp{R_CRIS_16_GOT}.  Example: @code{move.d
 
273
[$r0+asymbol:GOT16],$r10}
 
274
 
 
275
@item PLT
 
276
 
 
277
This suffix is used for function symbols.  It causes a
 
278
@emph{procedure linkage table}, an array of code stubs, to be
 
279
created at the time the shared object is created or linked
 
280
against, together with a global offset table entry.  The value
 
281
is a pc-relative offset to the corresponding stub code in the
 
282
procedure linkage table.  This arrangement causes the run-time
 
283
symbol resolver to be called to look up and set the value of the
 
284
symbol the first time the function is called (at latest;
 
285
depending environment variables).  It is only safe to leave the
 
286
symbol unresolved this way if all references are function calls.
 
287
The name of the relocation is @samp{R_CRIS_32_PLT_PCREL}.
 
288
Example: @code{add.d fnname:PLT,$pc}
 
289
 
 
290
@item PLTG
 
291
 
 
292
Like PLT, but the value is relative to the beginning of the
 
293
global offset table.  The relocation is
 
294
@samp{R_CRIS_32_PLT_GOTREL}.  Example: @code{move.d
 
295
fnname:PLTG,$r3}
 
296
 
 
297
@item GOTPLT
 
298
 
 
299
Similar to @samp{PLT}, but the value of the symbol is a 32-bit
 
300
index into the global offset table.  This is somewhat of a mix
 
301
between the effect of the @samp{GOT} and the @samp{PLT} suffix;
 
302
the difference to @samp{GOT} is that there will be a procedure
 
303
linkage table entry created, and that the symbol is assumed to
 
304
be a function entry and will be resolved by the run-time
 
305
resolver as with @samp{PLT}.  The relocation is
 
306
@samp{R_CRIS_32_GOTPLT}.  Example: @code{jsr
 
307
[$r0+fnname:GOTPLT]}
 
308
 
 
309
@item GOTPLT16
 
310
 
 
311
A variant of @samp{GOTPLT} giving a 16-bit value.  Its
 
312
relocation name is @samp{R_CRIS_16_GOTPLT}.  Example: @code{jsr
 
313
[$r0+fnname:GOTPLT16]}
 
314
 
 
315
@item GOTOFF
 
316
 
 
317
This suffix must only be attached to a local symbol, but may be
 
318
used in an expression adding an offset.  The value is the
 
319
address of the symbol relative to the start of the global offset
 
320
table.  The relocation name is @samp{R_CRIS_32_GOTREL}.
 
321
Example: @code{move.d [$r0+localsym:GOTOFF],r3}
 
322
@end table
 
323
 
 
324
@node CRIS-Regs
 
325
@subsection Register names
 
326
@cindex register names, CRIS
 
327
@cindex CRIS register names
 
328
 
 
329
A @samp{$} character may always prefix a general or special
 
330
register name in an instruction operand but is mandatory when
 
331
the option @option{--no-underscore} is specified or when the
 
332
@code{.syntax register_prefix} directive is in effect
 
333
(@pxref{crisnous}).  Register names are case-insensitive.
 
334
 
 
335
@node CRIS-Pseudos
 
336
@subsection Assembler Directives
 
337
@cindex assembler directives, CRIS
 
338
@cindex pseudo-ops, CRIS
 
339
@cindex CRIS assembler directives
 
340
@cindex CRIS pseudo-ops
 
341
 
 
342
There are a few CRIS-specific pseudo-directives in addition to
 
343
the generic ones.  @xref{Pseudo Ops}.  Constants emitted by
 
344
pseudo-directives are in little-endian order for CRIS.  There is
 
345
no support for floating-point-specific directives for CRIS.
 
346
 
 
347
@table @code
 
348
@item .dword EXPRESSIONS
 
349
@cindex assembler directive .dword, CRIS
 
350
@cindex pseudo-op .dword, CRIS
 
351
@cindex CRIS assembler directive .dword
 
352
@cindex CRIS pseudo-op .dword
 
353
 
 
354
The @code{.dword} directive is a synonym for @code{.int},
 
355
expecting zero or more EXPRESSIONS, separated by commas.  For
 
356
each expression, a 32-bit little-endian constant is emitted.
 
357
 
 
358
@item .syntax ARGUMENT
 
359
@cindex assembler directive .syntax, CRIS
 
360
@cindex pseudo-op .syntax, CRIS
 
361
@cindex CRIS assembler directive .syntax
 
362
@cindex CRIS pseudo-op .syntax
 
363
The @code{.syntax} directive takes as @var{ARGUMENT} one of the
 
364
following case-sensitive choices.
 
365
 
 
366
@table @code
 
367
@item no_register_prefix
 
368
 
 
369
The @code{.syntax no_register_prefix} @anchor{crisnous}directive
 
370
makes a @samp{$} character prefix on all registers optional.  It
 
371
overrides a previous setting, including the corresponding effect
 
372
of the option @option{--no-underscore}.  If this directive is
 
373
used when ordinary symbols do not have a @samp{_} character
 
374
prefix, care must be taken to avoid ambiguities whether an
 
375
operand is a register or a symbol; using symbols with names the
 
376
same as general or special registers then invoke undefined
 
377
behavior.
 
378
 
 
379
@item register_prefix
 
380
 
 
381
This directive makes a @samp{$} character prefix on all
 
382
registers mandatory.  It overrides a previous setting, including
 
383
the corresponding effect of the option @option{--underscore}.
 
384
 
 
385
@item leading_underscore
 
386
 
 
387
This is an assertion directive, emitting an error if the
 
388
@option{--no-underscore} option is in effect.
 
389
 
 
390
@item no_leading_underscore
 
391
 
 
392
This is the opposite of the @code{.syntax leading_underscore}
 
393
directive and emits an error if the option @option{--underscore}
 
394
is in effect.
 
395
@end table
 
396
 
 
397
@item .arch ARGUMENT
 
398
@cindex assembler directive .arch, CRIS
 
399
@cindex pseudo-op .arch, CRIS
 
400
@cindex CRIS assembler directive .arch
 
401
@cindex CRIS pseudo-op .arch
 
402
This is an assertion directive, giving an error if the specified
 
403
@var{ARGUMENT} is not the same as the specified or default value
 
404
for the @option{--march=@var{architecture}} option
 
405
(@pxref{march-option}).
 
406
 
 
407
@c If you compare with md_pseudo_table, you see that we don't
 
408
@c document ".file" and ".loc" here.  This is because we're just
 
409
@c wrapping the corresponding ELF function and emitting an error for
 
410
@c a.out.
 
411
@end table