gas/doc/c-hppa.texi

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