contrib/binutils-2.27/gas/doc/c-hppa.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 @page
   5 @node HPPA-Dependent
   6 @chapter HPPA Dependent Features
   7
   8 @cindex  support
   9 @menu
  10 * HPPA Notes::                Notes
  11 * HPPA Options::              Options
  12 * HPPA Syntax::               Syntax
  13 * HPPA Floating Point::       Floating Point
  14 * HPPA Directives::           HPPA Machine Directives
  15 * HPPA Opcodes::              Opcodes
  16 @end menu
  17
  18 @node HPPA Notes
  19 @section Notes
  20 As a back end for @sc{gnu} @sc{cc} @code{@value{AS}} has been throughly tested and should
  21 work extremely well.  We have tested it only minimally on hand written assembly
  22 code and no one has tested it much on the assembly output from the HP
  23 compilers.
  24
  25 The format of the debugging sections has changed since the original
  26 @code{@value{AS}} port (version 1.3X) was released; therefore,
  27 you must rebuild all HPPA objects and libraries with the new
  28 assembler so that you can debug the final executable.
  29
  30 The HPPA @code{@value{AS}} port generates a small subset of the relocations
  31 available in the SOM and ELF object file formats.  Additional relocation
  32 support will be added as it becomes necessary.
  33
  34 @node HPPA Options
  35 @section Options
  36 @code{@value{AS}} has no machine-dependent command-line options for the HPPA.
  37
  38 @cindex HPPA Syntax
  39 @node HPPA Syntax
  40 @section Syntax
  41 The assembler syntax closely follows the HPPA instruction set
  42 reference manual; assembler directives and general syntax closely follow the
  43 HPPA assembly language reference manual, with a few noteworthy differences.
  44
  45 First, a colon may immediately follow a label definition.  This is
  46 simply for compatibility with how most assembly language programmers
  47 write code.
  48
  49 Some obscure expression parsing problems may affect hand written code which
  50 uses the @code{spop} instructions, or code which makes significant
  51 use of the @code{!} line separator.
  52
  53 @code{@value{AS}} is much less forgiving about missing arguments and other
  54 similar oversights than the HP assembler.  @code{@value{AS}} notifies you
  55 of missing arguments as syntax errors; this is regarded as a feature, not a
  56 bug.
  57
  58 Finally, @code{@value{AS}} allows you to use an external symbol without
  59 explicitly importing the symbol.  @emph{Warning:} in the future this will be
  60 an error for HPPA targets.
  61
  62 Special characters for HPPA targets include:
  63
  64 @samp{;} is the line comment character.
  65
  66 @samp{!} can be used instead of a newline to separate statements.
  67
  68 Since @samp{$} has no special meaning, you may use it in symbol names.
  69
  70 @node HPPA Floating Point
  71 @section Floating Point
  72 @cindex floating point, HPPA (@sc{ieee})
  73 @cindex HPPA floating point (@sc{ieee})
  74 The HPPA family uses @sc{ieee} floating-point numbers.
  75
  76 @node HPPA Directives
  77 @section HPPA Assembler Directives
  78
  79 @code{@value{AS}} for the HPPA supports many additional directives for
  80 compatibility with the native assembler.  This section describes them only
  81 briefly.  For detailed information on HPPA-specific assembler directives, see
  82 @cite{HP9000 Series 800 Assembly Language Reference Manual} (HP 92432-90001).
  83
  84 @cindex HPPA directives not supported
  85 @code{@value{AS}} does @emph{not} support the following assembler directives
  86 described in the HP manual:
  87
  88 @example
  89 .endm           .liston
  90 .enter          .locct
  91 .leave          .macro
  92 .listoff
  93 @end example
  94
  95 @cindex @code{.param} on HPPA
  96 Beyond those implemented for compatibility, @code{@value{AS}} supports one
  97 additional assembler directive for the HPPA: @code{.param}.  It conveys
  98 register argument locations for static functions.  Its syntax closely follows
  99 the @code{.export} directive.
 100
 101 @cindex HPPA-only directives
 102 These are the additional directives in @code{@value{AS}} for the HPPA:
 103
 104 @table @code
 105 @item .block @var{n}
 106 @itemx .blockz @var{n}
 107 Reserve @var{n} bytes of storage, and initialize them to zero.
 108
 109 @item .call
 110 Mark the beginning of a procedure call.  Only the special case with @emph{no
 111 arguments} is allowed.
 112
 113 @item .callinfo [ @var{param}=@var{value}, @dots{} ]  [ @var{flag}, @dots{} ]
 114 Specify a number of parameters and flags that define the environment for a
 115 procedure.
 116
 117 @var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of
 118 general register range), @samp{entry_fr} (end of float register range),
 119 @samp{entry_sr} (end of space register range).
 120
 121 The values for @var{flag} are @samp{calls} or @samp{caller} (proc has
 122 subroutines), @samp{no_calls} (proc does not call subroutines), @samp{save_rp}
 123 (preserve return pointer), @samp{save_sp} (proc preserves stack pointer),
 124 @samp{no_unwind} (do not unwind this proc), @samp{hpux_int} (proc is interrupt
 125 routine).
 126
 127 @item .code
 128 Assemble into the standard section called @samp{$TEXT$}, subsection
 129 @samp{$CODE$}.
 130
 131 @ifset SOM
 132 @item .copyright "@var{string}"
 133 In the SOM object format, insert @var{string} into the object code, marked as a
 134 copyright string.
 135 @end ifset
 136
 137 @ifset ELF
 138 @item .copyright "@var{string}"
 139 In the ELF object format, insert @var{string} into the object code, marked as a
 140 version string.
 141 @end ifset
 142
 143 @item .enter
 144 Not yet supported; the assembler rejects programs containing this directive.
 145
 146 @item .entry
 147 Mark the beginning of a procedure.
 148
 149 @item .exit
 150 Mark the end of a procedure.
 151
 152 @item .export @var{name} [ ,@var{typ} ]  [ ,@var{param}=@var{r} ]
 153 Make a procedure @var{name} available to callers.  @var{typ}, if present, must
 154 be one of @samp{absolute}, @samp{code} (ELF only, not SOM), @samp{data},
 155 @samp{entry}, @samp{data}, @samp{entry}, @samp{millicode}, @samp{plabel},
 156 @samp{pri_prog}, or @samp{sec_prog}.
 157
 158 @var{param}, if present, provides either relocation information for the
 159 procedure arguments and result, or a privilege level.  @var{param} may be
 160 @samp{argw@var{n}} (where @var{n} ranges from @code{0} to @code{3}, and
 161 indicates one of four one-word arguments); @samp{rtnval} (the procedure's
 162 result); or @samp{priv_lev} (privilege level).  For arguments or the result,
 163 @var{r} specifies how to relocate, and must be one of @samp{no} (not
 164 relocatable), @samp{gr} (argument is in general register), @samp{fr} (in
 165 floating point register), or @samp{fu} (upper half of float register).
 166 For @samp{priv_lev}, @var{r} is an integer.
 167
 168 @item .half @var{n}
 169 Define a two-byte integer constant @var{n}; synonym for the portable
 170 @code{@value{AS}} directive @code{.short}.
 171
 172 @item .import @var{name} [ ,@var{typ} ]
 173 Converse of @code{.export}; make a procedure available to call.  The arguments
 174 use the same conventions as the first two arguments for @code{.export}.
 175
 176 @item .label @var{name}
 177 Define @var{name} as a label for the current assembly location.
 178
 179 @item .leave
 180 Not yet supported; the assembler rejects programs containing this directive.
 181
 182 @item .origin @var{lc}
 183 Advance location counter to @var{lc}. Synonym for the @code{@value{AS}}
 184 portable directive @code{.org}.
 185
 186 @item .param @var{name} [ ,@var{typ} ]  [ ,@var{param}=@var{r} ]
 187 @c Not in HP manual; @sc{gnu} HPPA extension
 188 Similar to @code{.export}, but used for static procedures.
 189
 190 @item .proc
 191 Use preceding the first statement of a procedure.
 192
 193 @item .procend
 194 Use following the last statement of a procedure.
 195
 196 @item @var{label} .reg @var{expr}
 197 @c ?? Not in HP manual (Jan 1988 vn)
 198 Synonym for @code{.equ}; define @var{label} with the absolute expression
 199 @var{expr} as its value.
 200
 201 @item .space @var{secname} [ ,@var{params} ]
 202 Switch to section @var{secname}, creating a new section by that name if
 203 necessary.  You may only use @var{params} when creating a new section, not
 204 when switching to an existing one.  @var{secname} may identify a section by
 205 number rather than by name.
 206
 207 If specified, the list @var{params} declares attributes of the section,
 208 identified by keywords.  The keywords recognized are @samp{spnum=@var{exp}}
 209 (identify this section by the number @var{exp}, an absolute expression),
 210 @samp{sort=@var{exp}} (order sections according to this sort key when linking;
 211 @var{exp} is an absolute expression), @samp{unloadable} (section contains no
 212 loadable data), @samp{notdefined} (this section defined elsewhere), and
 213 @samp{private} (data in this section not available to other programs).
 214
 215 @item .spnum @var{secnam}
 216 @c ?? Not in HP manual (Jan 1988)
 217 Allocate four bytes of storage, and initialize them with the section number of
 218 the section named @var{secnam}.  (You can define the section number with the
 219 HPPA @code{.space} directive.)
 220
 221 @cindex @code{string} directive on HPPA
 222 @item .string "@var{str}"
 223 Copy the characters in the string @var{str} to the object file.
 224 @xref{Strings,,Strings}, for information on escape sequences you can use in
 225 @code{@value{AS}} strings.
 226
 227 @emph{Warning!} The HPPA version of @code{.string} differs from the
 228 usual @code{@value{AS}} definition: it does @emph{not} write a zero byte
 229 after copying @var{str}.
 230
 231 @item .stringz "@var{str}"
 232 Like @code{.string}, but appends a zero byte after copying @var{str} to object
 233 file.
 234
 235 @item .subspa @var{name} [ ,@var{params} ]
 236 @itemx .nsubspa @var{name} [ ,@var{params} ]
 237 Similar to @code{.space}, but selects a subsection @var{name} within the
 238 current section.  You may only specify @var{params} when you create a
 239 subsection (in the first instance of @code{.subspa} for this @var{name}).
 240
 241 If specified, the list @var{params} declares attributes of the subsection,
 242 identified by keywords.  The keywords recognized are @samp{quad=@var{expr}}
 243 (``quadrant'' for this subsection), @samp{align=@var{expr}} (alignment for
 244 beginning of this subsection; a power of two), @samp{access=@var{expr}} (value
 245 for ``access rights'' field), @samp{sort=@var{expr}} (sorting order for this
 246 subspace in link), @samp{code_only} (subsection contains only code),
 247 @samp{unloadable} (subsection cannot be loaded into memory), @samp{comdat}
 248 (subsection is comdat), @samp{common} (subsection is common block),
 249 @samp{dup_comm} (subsection may have duplicate names), or @samp{zero}
 250 (subsection is all zeros, do not write in object file).
 251
 252 @code{.nsubspa} always creates a new subspace with the given name, even
 253 if one with the same name already exists.
 254
 255 @samp{comdat}, @samp{common} and @samp{dup_comm} can be used to implement
 256 various flavors of one-only support when using the SOM linker.  The SOM
 257 linker only supports specific combinations of these flags.  The details
 258 are not documented.  A brief description is provided here.
 259
 260 @samp{comdat} provides a form of linkonce support.  It is useful for
 261 both code and data subspaces.  A @samp{comdat} subspace has a key symbol
 262 marked by the @samp{is_comdat} flag or @samp{ST_COMDAT}.  Only the first
 263 subspace for any given key is selected.  The key symbol becomes universal
 264 in shared links.  This is similar to the behavior of @samp{secondary_def}
 265 symbols.
 266
 267 @samp{common} provides Fortran named common support.  It is only useful
 268 for data subspaces.  Symbols with the flag @samp{is_common} retain this
 269 flag in shared links.  Referencing a @samp{is_common} symbol in a shared
 270 library from outside the library doesn't work.  Thus, @samp{is_common}
 271 symbols must be output whenever they are needed.
 272
 273 @samp{common} and @samp{dup_comm} together provide Cobol common support.
 274 The subspaces in this case must all be the same length.  Otherwise, this
 275 support is similar to the Fortran common support.
 276
 277 @samp{dup_comm} by itself provides a type of one-only support for code.
 278 Only the first @samp{dup_comm} subspace is selected.  There is a rather
 279 complex algorithm to compare subspaces.  Code symbols marked with the
 280 @samp{dup_common} flag are hidden.  This support was intended for "C++
 281 duplicate inlines".
 282
 283 A simplified technique is used to mark the flags of symbols based on
 284 the flags of their subspace.  A symbol with the scope SS_UNIVERSAL and
 285 type ST_ENTRY, ST_CODE or ST_DATA is marked with the corresponding
 286 settings of @samp{comdat}, @samp{common} and @samp{dup_comm} from the
 287 subspace, respectively.  This avoids having to introduce additional
 288 directives to mark these symbols.  The HP assembler sets @samp{is_common}
 289 from @samp{common}.  However, it doesn't set the @samp{dup_common} from
 290 @samp{dup_comm}.  It doesn't have @samp{comdat} support.
 291
 292 @item .version "@var{str}"
 293 Write @var{str} as version identifier in object code.
 294 @end table
 295
 296 @node HPPA Opcodes
 297 @section Opcodes
 298 For detailed information on the HPPA machine instruction set, see
 299 @cite{PA-RISC Architecture and Instruction Set Reference Manual}
 300 (HP 09740-90039).