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