* Makefile.am (libopcodes_la_DEPENDENCIES)
[binutils.git] / gas / doc / c-cris.texi
blob2551b18d438b19a73b6b41aca5224bf2c516bc0f
1 @c Copyright 2002 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
15 @cindex CRIS support
16 @menu
17 * CRIS-Opts::              Command-line Options
18 * CRIS-Expand::            Instruction expansion
19 * CRIS-Syntax::            Syntax
20 @end menu
22 @node CRIS-Opts
23 @section Command-line Options
25 @cindex options, CRIS
26 @cindex CRIS options
27 The CRIS version of @code{@value{AS}} has these
28 machine-dependent command-line options.
30 @cindex @option{--emulation=criself} command line option, CRIS
31 @cindex @option{--emulation=crisaout} command line option, CRIS
32 @cindex CRIS @option{--emulation=criself} command line option
33 @cindex CRIS @option{--emulation=crisaout} command line option
35 The format of the generated object files can be either ELF or
36 a.out, specified by the command-line options
37 @option{--emulation=crisaout} and @option{--emulation=criself}.
38 The default is ELF (criself), unless @code{@value{AS}} has been
39 configured specifically for a.out by using the configuration
40 name @code{cris-axis-aout}.
42 @cindex @option{--underscore} command line option, CRIS
43 @cindex @option{--no-underscore} command line option, CRIS
44 @cindex CRIS @option{--underscore} command line option
45 @cindex CRIS @option{--no-underscore} command line option
46 There are two different link-incompatible ELF object file
47 variants for CRIS, for use in environments where symbols are
48 expected to be prefixed by a leading @samp{_} character and for
49 environments without such a symbol prefix.  The variant used for
50 GNU/Linux port has no symbol prefix.  Which variant to produce
51 is specified by either of the options @option{--underscore} and
52 @option{--no-underscore}.  The default is @option{--underscore}.
53 Since symbols in CRIS a.out objects are expected to have a
54 @samp{_} prefix, specifying @option{--no-underscore} when
55 generating a.out objects is an error.  Besides the object format
56 difference, the effect of this option is to parse register names
57 differently (@pxref{crisnous}).  The @option{--no-underscore}
58 option makes a @samp{$} register prefix mandatory.
60 @cindex @option{--pic} command line option, CRIS
61 @cindex CRIS @option{--pic} command line option
62 @cindex Position-independent code, CRIS
63 @cindex CRIS position-independent code
64 The option @option{--pic} must be passed to @code{@value{AS}} in
65 order to recognize the symbol syntax used for ELF (SVR4 PIC)
66 position-independent-code (@pxref{crispic}).  This will also
67 affect expansion of instructions.  The expansion with
68 @option{--pic} will use PC-relative rather than (slightly
69 faster) absolute addresses in those expansions.
71 @cindex @option{-N} command line option, CRIS
72 @cindex CRIS @option{-N} command line option
73 When @option{-N} is specified, @code{@value{AS}} will emit a
74 warning when a 16-bit branch instruction is expanded into a
75 32-bit multiple-instruction construct (@pxref{CRIS-Expand}).
77 @node CRIS-Expand
78 @section Instruction expansion
80 @cindex instruction expansion, CRIS
81 @cindex CRIS instruction expansion
82 @code{@value{AS}} will silently choose an instruction that fits
83 the operand size for @samp{[register+constant]} operands.  For
84 example, the offset @code{127} in @code{move.d [r3+127],r4} fits
85 in an instruction using a signed-byte offset.  Similarly,
86 @code{move.d [r2+32767],r1} will generate an instruction using a
87 16-bit offset.  For symbolic expressions and constants that do
88 not fit in 16 bits including the sign bit, a 32-bit offset is
89 generated.
91 For branches, @code{@value{AS}} will expand from a 16-bit branch
92 instruction into a sequence of instructions that can reach a
93 full 32-bit address.  Since this does not correspond to a single
94 instruction, such expansions can optionally be warned about.
95 @xref{CRIS-Opts}.
97 @node CRIS-Syntax
98 @section Syntax
100 There are different aspects of the CRIS assembly syntax.
102 @menu
103 * CRIS-Chars::                  Special Characters
104 * CRIS-Pic::                    Position-Independent Code Symbols
105 * CRIS-Regs::                   Register Names
106 * CRIS-Pseudos::                Assembler Directives
107 @end menu
109 @node CRIS-Chars
110 @subsection Special Characters
111 @cindex line comment characters, CRIS
112 @cindex CRIS line comment characters
114 The character @samp{#} is a line comment character.  It starts a
115 comment if and only if it is placed at the beginning of a line.
117 A @samp{;} character starts a comment anywhere on the line,
118 causing all characters up to the end of the line to be ignored.
120 A @samp{@@} character is handled as a line separator equivalent
121 to a logical new-line character (except in a comment), so
122 separate instructions can be specified on a single line.
124 @node CRIS-Pic
125 @subsection Symbols in position-independent code
126 @cindex Symbols in position-independent code, CRIS
127 @cindex CRIS symbols in position-independent code
128 @cindex Position-independent code, symbols in, CRIS
130 When generating @anchor{crispic}position-independent code (SVR4
131 PIC) for use in cris-axis-linux-gnu shared libraries, symbol
132 suffixes are used to specify what kind of run-time symbol lookup
133 will be used, expressed in the object as different
134 @emph{relocation types}.  Usually, all absolute symbol values
135 must be located in a table, the @emph{global offset table},
136 leaving the code position-independent; independent of values of
137 global symbols and independent of the address of the code.  The
138 suffix modifies the value of the symbol, into for example an
139 index into the global offset table where the real symbol value
140 is entered, or a PC-relative value, or a value relative to the
141 start of the global offset table.  All symbol suffixes start
142 with the character @samp{:} (omitted in the list below).  Every
143 symbol use in code or a read-only section must therefore have a
144 PIC suffix to enable a useful shared library to be created.
145 Usually, these constructs must not be used with an additive
146 constant offset as is usually allowed, i.e.@: no 4 as in
147 @code{symbol + 4} is allowed.  This restriction is checked at
148 link-time, not at assembly-time.
150 @table @code
151 @item GOT
153 Attaching this suffix to a symbol in an instruction causes the
154 symbol to be entered into the global offset table.  The value is
155 a 32-bit index for that symbol into the global offset table.
156 The name of the corresponding relocation is
157 @samp{R_CRIS_32_GOT}.  Example: @code{move.d
158 [$r0+extsym:GOT],$r9}
160 @item GOT16
162 Same as for @samp{GOT}, but the value is a 16-bit index into the
163 global offset table.  The corresponding relocation is
164 @samp{R_CRIS_16_GOT}.  Example: @code{move.d
165 [$r0+asymbol:GOT16],$r10}
167 @item PLT
169 This suffix is used for function symbols.  It causes a
170 @emph{procedure linkage table}, an array of code stubs, to be
171 created at the time the shared object is created or linked
172 against, together with a global offset table entry.  The value
173 is a pc-relative offset to the corresponding stub code in the
174 procedure linkage table.  This arrangement causes the run-time
175 symbol resolver to be called to look up and set the value of the
176 symbol the first time the function is called (at latest;
177 depending environment variables).  It is only safe to leave the
178 symbol unresolved this way if all references are function calls.
179 The name of the relocation is @samp{R_CRIS_32_PLT_PCREL}.
180 Example: @code{add.d fnname:PLT,$pc}
182 @item PLTG
184 Like PLT, but the value is relative to the beginning of the
185 global offset table.  The relocation is
186 @samp{R_CRIS_32_PLT_GOTREL}.  Example: @code{move.d
187 fnname:PLTG,$r3}
189 @item GOTPLT
191 Similar to @samp{PLT}, but the value of the symbol is a 32-bit
192 index into the global offset table.  This is somewhat of a mix
193 between the effect of the @samp{GOT} and the @samp{PLT} suffix;
194 the difference to @samp{GOT} is that there will be a procedure
195 linkage table entry created, and that the symbol is assumed to
196 be a function entry and will be resolved by the run-time
197 resolver as with @samp{PLT}.  The relocation is
198 @samp{R_CRIS_32_GOTPLT}.  Example: @code{jsr
199 [$r0+fnname:GOTPLT]}
201 @item GOTPLT16
203 A variant of @samp{GOTPLT} giving a 16-bit value.  Its
204 relocation name is @samp{R_CRIS_16_GOTPLT}.  Example: @code{jsr
205 [$r0+fnname:GOTPLT16]}
207 @item GOTOFF
209 This suffix must only be attached to a local symbol, but may be
210 used in an expression adding an offset.  The value is the
211 address of the symbol relative to the start of the global offset
212 table.  The relocation name is @samp{R_CRIS_32_GOTREL}.
213 Example: @code{move.d [$r0+localsym:GOTOFF],r3}
214 @end table
216 @node CRIS-Regs
217 @subsection Register names
218 @cindex register names, CRIS
219 @cindex CRIS register names
221 A @samp{$} character may always prefix a general or special
222 register name in an instruction operand but is mandatory when
223 the option @option{--no-underscore} is specified or when the
224 @code{.syntax register_prefix} directive is in effect
225 (@pxref{crisnous}).  Register names are case-insensitive.
227 @node CRIS-Pseudos
228 @subsection Assembler Directives
229 @cindex assembler directives, CRIS
230 @cindex pseudo-ops, CRIS
231 @cindex CRIS assembler directives
232 @cindex CRIS pseudo-ops
234 There are a few CRIS-specific pseudo-directives in addition to
235 the generic ones.  @xref{Pseudo Ops}.  Constants emitted by
236 pseudo-directives are in little-endian order for CRIS.  There is
237 no support for floating-point-specific directives for CRIS.
239 @table @code
240 @item .dword EXPRESSIONS
241 @cindex assembler directive .dword, CRIS
242 @cindex pseudo-op .dword, CRIS
243 @cindex CRIS assembler directive .dword
244 @cindex CRIS pseudo-op .dword
246 The @code{.dword} directive is a synonym for @code{.int},
247 expecting zero or more EXPRESSIONS, separated by commas.  For
248 each expression, a 32-bit little-endian constant is emitted.
250 @item .syntax ARGUMENT
251 @cindex assembler directive .syntax, CRIS
252 @cindex pseudo-op .syntax, CRIS
253 @cindex CRIS assembler directive .syntax
254 @cindex CRIS pseudo-op .syntax
255 The @code{.syntax} directive takes as ARGUMENT one of the
256 following case-sensitive choices.
258 @table @code
259 @item no_register_prefix
261 The @code{.syntax no_register_prefix} @anchor{crisnous}directive
262 makes a @samp{$} character prefix on all registers optional.  It
263 overrides a previous setting, including the corresponding effect
264 of the option @option{--no-underscore}.  If this directive is
265 used when ordinary symbols do not have a @samp{_} character
266 prefix, care must be taken to avoid ambiguities whether an
267 operand is a register or a symbol; using symbols with names the
268 same as general or special registers then invoke undefined
269 behavior.
271 @item register_prefix
273 This directive makes a @samp{$} character prefix on all
274 registers mandatory.  It overrides a previous setting, including
275 the corresponding effect of the option @option{--underscore}.
277 @item leading_underscore
279 This is an assertion directive, emitting an error if the
280 @option{--no-underscore} option is in effect.
282 @item no_leading_underscore
284 This is the opposite of the @code{.syntax leading_underscore}
285 directive and emits an error if the option @option{--underscore}
286 is in effect.
287 @end table
289 @c If you compare with md_pseudo_table, you see that we don't
290 @c document ".file" and ".loc" here.  This is because we're just
291 @c wrapping the corresponding ELF function and emitting an error for
292 @c a.out.
293 @end table