Merge branch 'vendor/GCC44'
[dragonfly.git] / contrib / binutils-2.21 / gas / doc / c-vax.texi
1 @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1998, 2002
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 VAX/VMS description enhanced and corrected by Klaus K"aempf, kkaempf@progis.de
6 @ifset GENERIC
7 @node Vax-Dependent
8 @chapter VAX Dependent Features
9 @cindex VAX support
10
11 @end ifset
12 @ifclear GENERIC
13 @node Machine Dependencies
14 @chapter VAX Dependent Features
15 @cindex VAX support
16
17 @end ifclear
18
19 @menu
20 * VAX-Opts::                    VAX Command-Line Options
21 * VAX-float::                   VAX Floating Point
22 * VAX-directives::              Vax Machine Directives
23 * VAX-opcodes::                 VAX Opcodes
24 * VAX-branch::                  VAX Branch Improvement
25 * VAX-operands::                VAX Operands
26 * VAX-no::                      Not Supported on VAX
27 @end menu
28
29
30 @node VAX-Opts
31 @section VAX Command-Line Options
32
33 @cindex command-line options ignored, VAX
34 @cindex VAX command-line options ignored
35 The Vax version of @code{@value{AS}} accepts any of the following options,
36 gives a warning message that the option was ignored and proceeds.
37 These options are for compatibility with scripts designed for other
38 people's assemblers.
39
40 @table @code
41 @cindex @code{-D}, ignored on VAX
42 @cindex @code{-S}, ignored on VAX
43 @cindex @code{-T}, ignored on VAX
44 @item @code{-D} (Debug)
45 @itemx @code{-S} (Symbol Table)
46 @itemx @code{-T} (Token Trace)
47 These are obsolete options used to debug old assemblers.
48
49 @cindex @code{-d}, VAX option
50 @item @code{-d} (Displacement size for JUMPs)
51 This option expects a number following the @samp{-d}.  Like options
52 that expect filenames, the number may immediately follow the
53 @samp{-d} (old standard) or constitute the whole of the command line
54 argument that follows @samp{-d} (@sc{gnu} standard).
55
56 @cindex @code{-V}, redundant on VAX
57 @item @code{-V} (Virtualize Interpass Temporary File)
58 Some other assemblers use a temporary file.  This option
59 commanded them to keep the information in active memory rather
60 than in a disk file.  @code{@value{AS}} always does this, so this
61 option is redundant.
62
63 @cindex @code{-J}, ignored on VAX
64 @item @code{-J} (JUMPify Longer Branches)
65 Many 32-bit computers permit a variety of branch instructions
66 to do the same job.  Some of these instructions are short (and
67 fast) but have a limited range; others are long (and slow) but
68 can branch anywhere in virtual memory.  Often there are 3
69 flavors of branch: short, medium and long.  Some other
70 assemblers would emit short and medium branches, unless told by
71 this option to emit short and long branches.
72
73 @cindex @code{-t}, ignored on VAX
74 @item @code{-t} (Temporary File Directory)
75 Some other assemblers may use a temporary file, and this option
76 takes a filename being the directory to site the temporary
77 file.  Since @code{@value{AS}} does not use a temporary disk file, this
78 option makes no difference.  @samp{-t} needs exactly one
79 filename.
80 @end table
81
82 @cindex VMS (VAX) options
83 @cindex options for VAX/VMS
84 @cindex VAX/VMS options
85 @cindex Vax-11 C compatibility
86 @cindex symbols with uppercase, VAX/VMS
87 The Vax version of the assembler accepts additional options when
88 compiled for VMS:
89
90 @table @samp
91 @cindex @samp{-h} option, VAX/VMS
92 @item -h @var{n}
93 External symbol or section (used for global variables) names are not
94 case sensitive on VAX/VMS and always mapped to upper case.  This is
95 contrary to the C language definition which explicitly distinguishes
96 upper and lower case.  To implement a standard conforming C compiler,
97 names must be changed (mapped) to preserve the case information.  The
98 default mapping is to convert all lower case characters to uppercase and
99 adding an underscore followed by a 6 digit hex value, representing a 24
100 digit binary value.  The one digits in the binary value represent which
101 characters are uppercase in the original symbol name.
102
103 The @samp{-h @var{n}} option determines how we map names.  This takes
104 several values.  No @samp{-h} switch at all allows case hacking as
105 described above.  A value of zero (@samp{-h0}) implies names should be
106 upper case, and inhibits the case hack.  A value of 2 (@samp{-h2})
107 implies names should be all lower case, with no case hack.  A value of 3
108 (@samp{-h3}) implies that case should be preserved.  The value 1 is
109 unused.  The @code{-H} option directs @code{@value{AS}} to display
110 every mapped symbol during assembly.
111
112 Symbols whose names include a dollar sign @samp{$} are exceptions to the
113 general name mapping.  These symbols are normally only used to reference
114 VMS library names.  Such symbols are always mapped to upper case.
115
116 @cindex @samp{-+} option, VAX/VMS
117 @item -+
118 The @samp{-+} option causes @code{@value{AS}} to truncate any symbol
119 name larger than 31 characters.  The @samp{-+} option also prevents some
120 code following the @samp{_main} symbol normally added to make the object
121 file compatible with Vax-11 "C".
122
123 @cindex @samp{-1} option, VAX/VMS
124 @item -1
125 This option is ignored for backward compatibility with @code{@value{AS}}
126 version 1.x.
127
128 @cindex @samp{-H} option, VAX/VMS
129 @item -H
130 The @samp{-H} option causes @code{@value{AS}} to print every symbol
131 which was changed by case mapping.
132 @end table
133
134 @node VAX-float
135 @section VAX Floating Point
136
137 @cindex VAX floating point
138 @cindex floating point, VAX
139 Conversion of flonums to floating point is correct, and
140 compatible with previous assemblers.  Rounding is
141 towards zero if the remainder is exactly half the least significant bit.
142
143 @code{D}, @code{F}, @code{G} and @code{H} floating point formats
144 are understood.
145
146 Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
147 are rendered correctly.  Again, rounding is towards zero in the
148 boundary case.
149
150 @cindex @code{float} directive, VAX
151 @cindex @code{double} directive, VAX
152 The @code{.float} directive produces @code{f} format numbers.
153 The @code{.double} directive produces @code{d} format numbers.
154
155 @node VAX-directives
156 @section Vax Machine Directives
157
158 @cindex machine directives, VAX
159 @cindex VAX machine directives
160 The Vax version of the assembler supports four directives for
161 generating Vax floating point constants.  They are described in the
162 table below.
163
164 @cindex wide floating point directives, VAX
165 @table @code
166 @cindex @code{dfloat} directive, VAX
167 @item .dfloat
168 This expects zero or more flonums, separated by commas, and
169 assembles Vax @code{d} format 64-bit floating point constants.
170
171 @cindex @code{ffloat} directive, VAX
172 @item .ffloat
173 This expects zero or more flonums, separated by commas, and
174 assembles Vax @code{f} format 32-bit floating point constants.
175
176 @cindex @code{gfloat} directive, VAX
177 @item .gfloat
178 This expects zero or more flonums, separated by commas, and
179 assembles Vax @code{g} format 64-bit floating point constants.
180
181 @cindex @code{hfloat} directive, VAX
182 @item .hfloat
183 This expects zero or more flonums, separated by commas, and
184 assembles Vax @code{h} format 128-bit floating point constants.
185
186 @end table
187
188 @node VAX-opcodes
189 @section VAX Opcodes
190
191 @cindex VAX opcode mnemonics
192 @cindex opcode mnemonics, VAX
193 @cindex mnemonics for opcodes, VAX
194 All DEC mnemonics are supported.  Beware that @code{case@dots{}}
195 instructions have exactly 3 operands.  The dispatch table that
196 follows the @code{case@dots{}} instruction should be made with
197 @code{.word} statements.  This is compatible with all unix
198 assemblers we know of.
199
200 @node VAX-branch
201 @section VAX Branch Improvement
202
203 @cindex VAX branch improvement
204 @cindex branch improvement, VAX
205 @cindex pseudo-ops for branch, VAX
206 Certain pseudo opcodes are permitted.  They are for branch
207 instructions.  They expand to the shortest branch instruction that
208 reaches the target.  Generally these mnemonics are made by
209 substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
210 This feature is included both for compatibility and to help
211 compilers.  If you do not need this feature, avoid these
212 opcodes.  Here are the mnemonics, and the code they can expand into.
213
214 @table @code
215 @item jbsb
216 @samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}.
217 @table @asis
218 @item (byte displacement)
219 @kbd{bsbb @dots{}}
220 @item (word displacement)
221 @kbd{bsbw @dots{}}
222 @item (long displacement)
223 @kbd{jsb @dots{}}
224 @end table
225 @item jbr
226 @itemx jr
227 Unconditional branch.
228 @table @asis
229 @item (byte displacement)
230 @kbd{brb @dots{}}
231 @item (word displacement)
232 @kbd{brw @dots{}}
233 @item (long displacement)
234 @kbd{jmp @dots{}}
235 @end table
236 @item j@var{COND}
237 @var{COND} may be any one of the conditional branches
238 @code{neq}, @code{nequ}, @code{eql}, @code{eqlu}, @code{gtr},
239 @code{geq}, @code{lss}, @code{gtru}, @code{lequ}, @code{vc}, @code{vs},
240 @code{gequ}, @code{cc}, @code{lssu}, @code{cs}.
241 @var{COND} may also be one of the bit tests
242 @code{bs}, @code{bc}, @code{bss}, @code{bcs}, @code{bsc}, @code{bcc},
243 @code{bssi}, @code{bcci}, @code{lbs}, @code{lbc}.
244 @var{NOTCOND} is the opposite condition to @var{COND}.
245 @table @asis
246 @item (byte displacement)
247 @kbd{b@var{COND} @dots{}}
248 @item (word displacement)
249 @kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:}
250 @item (long displacement)
251 @kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:}
252 @end table
253 @item jacb@var{X}
254 @var{X} may be one of @code{b d f g h l w}.
255 @table @asis
256 @item (word displacement)
257 @kbd{@var{OPCODE} @dots{}}
258 @item (long displacement)
259 @example
260 @var{OPCODE} @dots{}, foo ;
261 brb bar ;
262 foo: jmp @dots{} ;
263 bar:
264 @end example
265 @end table
266 @item jaob@var{YYY}
267 @var{YYY} may be one of @code{lss leq}.
268 @item jsob@var{ZZZ}
269 @var{ZZZ} may be one of @code{geq gtr}.
270 @table @asis
271 @item (byte displacement)
272 @kbd{@var{OPCODE} @dots{}}
273 @item (word displacement)
274 @example
275 @var{OPCODE} @dots{}, foo ;
276 brb bar ;
277 foo: brw @var{destination} ;
278 bar:
279 @end example
280 @item (long displacement)
281 @example
282 @var{OPCODE} @dots{}, foo ;
283 brb bar ;
284 foo: jmp @var{destination} ;
285 bar:
286 @end example
287 @end table
288 @item aobleq
289 @itemx aoblss
290 @itemx sobgeq
291 @itemx sobgtr
292 @table @asis
293 @item (byte displacement)
294 @kbd{@var{OPCODE} @dots{}}
295 @item (word displacement)
296 @example
297 @var{OPCODE} @dots{}, foo ;
298 brb bar ;
299 foo: brw @var{destination} ;
300 bar:
301 @end example
302 @item (long displacement)
303 @example
304 @var{OPCODE} @dots{}, foo ;
305 brb bar ;
306 foo: jmp @var{destination} ;
307 bar:
308 @end example
309 @end table
310 @end table
311
312 @node VAX-operands
313 @section VAX Operands
314
315 @cindex VAX operand notation
316 @cindex operand notation, VAX
317 @cindex immediate character, VAX
318 @cindex VAX immediate character
319 The immediate character is @samp{$} for Unix compatibility, not
320 @samp{#} as DEC writes it.
321
322 @cindex indirect character, VAX
323 @cindex VAX indirect character
324 The indirect character is @samp{*} for Unix compatibility, not
325 @samp{@@} as DEC writes it.
326
327 @cindex displacement sizing character, VAX
328 @cindex VAX displacement sizing character
329 The displacement sizing character is @samp{`} (an accent grave) for
330 Unix compatibility, not @samp{^} as DEC writes it.  The letter
331 preceding @samp{`} may have either case.  @samp{G} is not
332 understood, but all other letters (@code{b i l s w}) are understood.
333
334 @cindex register names, VAX
335 @cindex VAX register names
336 Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
337 pc}.  Upper and lower case letters are equivalent.
338
339 For instance
340 @smallexample
341 tstb *w`$4(r5)
342 @end smallexample
343
344 Any expression is permitted in an operand.  Operands are comma
345 separated.
346
347 @c There is some bug to do with recognizing expressions
348 @c in operands, but I forget what it is.  It is
349 @c a syntax clash because () is used as an address mode
350 @c and to encapsulate sub-expressions.
351
352 @node VAX-no
353 @section Not Supported on VAX
354
355 @cindex VAX bitfields not supported
356 @cindex bitfields, not supported on VAX
357 Vax bit fields can not be assembled with @code{@value{AS}}.  Someone
358 can add the required code if they really need it.