Merge branch 'vendor/OPENSSL'
[dragonfly.git] / contrib / binutils-2.22 / 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