contrib/binutils-2.22/gas/doc/c-vax.texi

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