Import binutils-2.20
[dragonfly.git] / contrib / binutils-2.20 / gas / doc / c-vax.texi
CommitLineData
8e158dd0
SS
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
35The Vax version of @code{@value{AS}} accepts any of the following options,
36gives a warning message that the option was ignored and proceeds.
37These options are for compatibility with scripts designed for other
38people'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)
47These are obsolete options used to debug old assemblers.
48
49@cindex @code{-d}, VAX option
50@item @code{-d} (Displacement size for JUMPs)
51This option expects a number following the @samp{-d}. Like options
52that expect filenames, the number may immediately follow the
53@samp{-d} (old standard) or constitute the whole of the command line
54argument that follows @samp{-d} (@sc{gnu} standard).
55
56@cindex @code{-V}, redundant on VAX
57@item @code{-V} (Virtualize Interpass Temporary File)
58Some other assemblers use a temporary file. This option
59commanded them to keep the information in active memory rather
60than in a disk file. @code{@value{AS}} always does this, so this
61option is redundant.
62
63@cindex @code{-J}, ignored on VAX
64@item @code{-J} (JUMPify Longer Branches)
65Many 32-bit computers permit a variety of branch instructions
66to do the same job. Some of these instructions are short (and
67fast) but have a limited range; others are long (and slow) but
68can branch anywhere in virtual memory. Often there are 3
69flavors of branch: short, medium and long. Some other
70assemblers would emit short and medium branches, unless told by
71this option to emit short and long branches.
72
73@cindex @code{-t}, ignored on VAX
74@item @code{-t} (Temporary File Directory)
75Some other assemblers may use a temporary file, and this option
76takes a filename being the directory to site the temporary
77file. Since @code{@value{AS}} does not use a temporary disk file, this
78option makes no difference. @samp{-t} needs exactly one
79filename.
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
87The Vax version of the assembler accepts additional options when
88compiled for VMS:
89
90@table @samp
91@cindex @samp{-h} option, VAX/VMS
92@item -h @var{n}
93External symbol or section (used for global variables) names are not
94case sensitive on VAX/VMS and always mapped to upper case. This is
95contrary to the C language definition which explicitly distinguishes
96upper and lower case. To implement a standard conforming C compiler,
97names must be changed (mapped) to preserve the case information. The
98default mapping is to convert all lower case characters to uppercase and
99adding an underscore followed by a 6 digit hex value, representing a 24
100digit binary value. The one digits in the binary value represent which
101characters are uppercase in the original symbol name.
102
103The @samp{-h @var{n}} option determines how we map names. This takes
104several values. No @samp{-h} switch at all allows case hacking as
105described above. A value of zero (@samp{-h0}) implies names should be
106upper case, and inhibits the case hack. A value of 2 (@samp{-h2})
107implies 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
109unused. The @code{-H} option directs @code{@value{AS}} to display
110every mapped symbol during assembly.
111
112Symbols whose names include a dollar sign @samp{$} are exceptions to the
113general name mapping. These symbols are normally only used to reference
114VMS library names. Such symbols are always mapped to upper case.
115
116@cindex @samp{-+} option, VAX/VMS
117@item -+
118The @samp{-+} option causes @code{@value{AS}} to truncate any symbol
119name larger than 31 characters. The @samp{-+} option also prevents some
120code following the @samp{_main} symbol normally added to make the object
121file compatible with Vax-11 "C".
122
123@cindex @samp{-1} option, VAX/VMS
124@item -1
125This option is ignored for backward compatibility with @code{@value{AS}}
126version 1.x.
127
128@cindex @samp{-H} option, VAX/VMS
129@item -H
130The @samp{-H} option causes @code{@value{AS}} to print every symbol
131which 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
139Conversion of flonums to floating point is correct, and
140compatible with previous assemblers. Rounding is
141towards 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
144are understood.
145
146Immediate floating literals (@emph{e.g.} @samp{S`$6.9})
147are rendered correctly. Again, rounding is towards zero in the
148boundary case.
149
150@cindex @code{float} directive, VAX
151@cindex @code{double} directive, VAX
152The @code{.float} directive produces @code{f} format numbers.
153The @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
160The Vax version of the assembler supports four directives for
161generating Vax floating point constants. They are described in the
162table below.
163
164@cindex wide floating point directives, VAX
165@table @code
166@cindex @code{dfloat} directive, VAX
167@item .dfloat
168This expects zero or more flonums, separated by commas, and
169assembles Vax @code{d} format 64-bit floating point constants.
170
171@cindex @code{ffloat} directive, VAX
172@item .ffloat
173This expects zero or more flonums, separated by commas, and
174assembles Vax @code{f} format 32-bit floating point constants.
175
176@cindex @code{gfloat} directive, VAX
177@item .gfloat
178This expects zero or more flonums, separated by commas, and
179assembles Vax @code{g} format 64-bit floating point constants.
180
181@cindex @code{hfloat} directive, VAX
182@item .hfloat
183This expects zero or more flonums, separated by commas, and
184assembles 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
194All DEC mnemonics are supported. Beware that @code{case@dots{}}
195instructions have exactly 3 operands. The dispatch table that
196follows the @code{case@dots{}} instruction should be made with
197@code{.word} statements. This is compatible with all unix
198assemblers 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
206Certain pseudo opcodes are permitted. They are for branch
207instructions. They expand to the shortest branch instruction that
208reaches the target. Generally these mnemonics are made by
209substituting @samp{j} for @samp{b} at the start of a DEC mnemonic.
210This feature is included both for compatibility and to help
211compilers. If you do not need this feature, avoid these
212opcodes. 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
227Unconditional 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 ;
261brb bar ;
262foo: jmp @dots{} ;
263bar:
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 ;
276brb bar ;
277foo: brw @var{destination} ;
278bar:
279@end example
280@item (long displacement)
281@example
282@var{OPCODE} @dots{}, foo ;
283brb bar ;
284foo: jmp @var{destination} ;
285bar:
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 ;
298brb bar ;
299foo: brw @var{destination} ;
300bar:
301@end example
302@item (long displacement)
303@example
304@var{OPCODE} @dots{}, foo ;
305brb bar ;
306foo: jmp @var{destination} ;
307bar:
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
319The 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
324The 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
329The displacement sizing character is @samp{`} (an accent grave) for
330Unix compatibility, not @samp{^} as DEC writes it. The letter
331preceding @samp{`} may have either case. @samp{G} is not
332understood, but all other letters (@code{b i l s w}) are understood.
333
334@cindex register names, VAX
335@cindex VAX register names
336Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp
337pc}. Upper and lower case letters are equivalent.
338
339For instance
340@smallexample
341tstb *w`$4(r5)
342@end smallexample
343
344Any expression is permitted in an operand. Operands are comma
345separated.
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
357Vax bit fields can not be assembled with @code{@value{AS}}. Someone
358can add the required code if they really need it.