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

   1 @c Copyright (C) 1991-2016 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 VAX/VMS description enhanced and corrected by Klaus K"aempf, kkaempf@progis.de
   5 @ifset GENERIC
   6 @node Vax-Dependent
   7 @chapter VAX Dependent Features
   8 @cindex VAX support
   9
  10 @end ifset
  11 @ifclear GENERIC
  12 @node Machine Dependencies
  13 @chapter VAX Dependent Features
  14 @cindex VAX support
  15
  16 @end ifclear
  17
  18 @menu
  19 * VAX-Opts::                    VAX Command-Line Options
  20 * VAX-float::                   VAX Floating Point
  21 * VAX-directives::              Vax Machine Directives
  22 * VAX-opcodes::                 VAX Opcodes
  23 * VAX-branch::                  VAX Branch Improvement
  24 * VAX-operands::                VAX Operands
  25 * VAX-no::                      Not Supported on VAX
  26 * VAX-Syntax::                  VAX Syntax
  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.
 359
 360 @node VAX-Syntax
 361 @section VAX Syntax
 362 @menu
 363 * VAX-Chars::                Special Characters
 364 @end menu
 365
 366 @node VAX-Chars
 367 @subsection Special Characters
 368
 369 @cindex line comment character, VAX
 370 @cindex VAX line comment character
 371 The presence of a @samp{#} appearing anywhere on a line indicates the
 372 start of a comment that extends to the end of that line.
 373
 374 If a @samp{#} appears as the first character of a line then the whole
 375 line is treated as a comment, but in this case the line can also be a
 376 logical line number directive (@pxref{Comments}) or a preprocessor
 377 control command (@pxref{Preprocessing}).
 378
 379 @cindex line separator, VAX
 380 @cindex statement separator, VAX
 381 @cindex VAX line separator
 382 The @samp{;} character can be used to separate statements on the same
 383 line.