Update year range in copyright notice of binutils files

[binutils.git] / gas / doc / c-hppa.texi

@c Copyright (C) 1991-2021 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.
@page
@node HPPA-Dependent
@chapter HPPA Dependent Features

@cindex  support
@menu
* HPPA Notes::                Notes
* HPPA Options::              Options
* HPPA Syntax::               Syntax
* HPPA Floating Point::       Floating Point
* HPPA Directives::           HPPA Machine Directives
* HPPA Opcodes::              Opcodes
@end menu

@node HPPA Notes
@section Notes
As a back end for @sc{gnu} @sc{cc} @code{@value{AS}} has been thoroughly tested and should
work extremely well.  We have tested it only minimally on hand written assembly
code and no one has tested it much on the assembly output from the HP
compilers.

The format of the debugging sections has changed since the original
@code{@value{AS}} port (version 1.3X) was released; therefore,
you must rebuild all HPPA objects and libraries with the new
assembler so that you can debug the final executable.

The HPPA @code{@value{AS}} port generates a small subset of the relocations
available in the SOM and ELF object file formats.  Additional relocation
support will be added as it becomes necessary.

@node HPPA Options
@section Options
@code{@value{AS}} has no machine-dependent command-line options for the HPPA.

@cindex HPPA Syntax
@node HPPA Syntax
@section Syntax
The assembler syntax closely follows the HPPA instruction set
reference manual; assembler directives and general syntax closely follow the
HPPA assembly language reference manual, with a few noteworthy differences.

First, a colon may immediately follow a label definition.  This is
simply for compatibility with how most assembly language programmers
write code.

Some obscure expression parsing problems may affect hand written code which
uses the @code{spop} instructions, or code which makes significant
use of the @code{!} line separator.

@code{@value{AS}} is much less forgiving about missing arguments and other
similar oversights than the HP assembler.  @code{@value{AS}} notifies you
of missing arguments as syntax errors; this is regarded as a feature, not a
bug.

Finally, @code{@value{AS}} allows you to use an external symbol without
explicitly importing the symbol.  @emph{Warning:} in the future this will be
an error for HPPA targets.

Special characters for HPPA targets include:

@samp{;} is the line comment character.

@samp{!} can be used instead of a newline to separate statements.

Since @samp{$} has no special meaning, you may use it in symbol names.

@node HPPA Floating Point
@section Floating Point
@cindex floating point, HPPA (@sc{ieee})
@cindex HPPA floating point (@sc{ieee})
The HPPA family uses @sc{ieee} floating-point numbers.

@node HPPA Directives
@section HPPA Assembler Directives

@code{@value{AS}} for the HPPA supports many additional directives for
compatibility with the native assembler.  This section describes them only
briefly.  For detailed information on HPPA-specific assembler directives, see
@cite{HP9000 Series 800 Assembly Language Reference Manual} (HP 92432-90001).

@cindex HPPA directives not supported
@code{@value{AS}} does @emph{not} support the following assembler directives
described in the HP manual:

@example
.endm           .liston
.enter          .locct
.leave          .macro
.listoff
@end example

@cindex @code{.param} on HPPA
Beyond those implemented for compatibility, @code{@value{AS}} supports one
additional assembler directive for the HPPA: @code{.param}.  It conveys
register argument locations for static functions.  Its syntax closely follows
the @code{.export} directive.

@cindex HPPA-only directives
These are the additional directives in @code{@value{AS}} for the HPPA:

@table @code
@item .block @var{n}
@itemx .blockz @var{n}
Reserve @var{n} bytes of storage, and initialize them to zero.

@item .call
Mark the beginning of a procedure call.  Only the special case with @emph{no
arguments} is allowed.

@item .callinfo [ @var{param}=@var{value}, @dots{} ]  [ @var{flag}, @dots{} ]
Specify a number of parameters and flags that define the environment for a
procedure.

@var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of
general register range), @samp{entry_fr} (end of float register range),
@samp{entry_sr} (end of space register range).

The values for @var{flag} are @samp{calls} or @samp{caller} (proc has
subroutines), @samp{no_calls} (proc does not call subroutines), @samp{save_rp}
(preserve return pointer), @samp{save_sp} (proc preserves stack pointer),
@samp{no_unwind} (do not unwind this proc), @samp{hpux_int} (proc is interrupt
routine).

@item .code
Assemble into the standard section called @samp{$TEXT$}, subsection
@samp{$CODE$}.

@ifset SOM
@item .copyright "@var{string}"
In the SOM object format, insert @var{string} into the object code, marked as a
copyright string.
@end ifset

@ifset ELF
@item .copyright "@var{string}"
In the ELF object format, insert @var{string} into the object code, marked as a
version string.
@end ifset

@item .enter
Not yet supported; the assembler rejects programs containing this directive.

@item .entry
Mark the beginning of a procedure.

@item .exit
Mark the end of a procedure.

@item .export @var{name} [ ,@var{typ} ]  [ ,@var{param}=@var{r} ]
Make a procedure @var{name} available to callers.  @var{typ}, if present, must
be one of @samp{absolute}, @samp{code} (ELF only, not SOM), @samp{data},
@samp{entry}, @samp{data}, @samp{entry}, @samp{millicode}, @samp{plabel},
@samp{pri_prog}, or @samp{sec_prog}.

@var{param}, if present, provides either relocation information for the
procedure arguments and result, or a privilege level.  @var{param} may be
@samp{argw@var{n}} (where @var{n} ranges from @code{0} to @code{3}, and
indicates one of four one-word arguments); @samp{rtnval} (the procedure's
result); or @samp{priv_lev} (privilege level).  For arguments or the result,
@var{r} specifies how to relocate, and must be one of @samp{no} (not
relocatable), @samp{gr} (argument is in general register), @samp{fr} (in
floating point register), or @samp{fu} (upper half of float register).
For @samp{priv_lev}, @var{r} is an integer.

@item .half @var{n}
Define a two-byte integer constant @var{n}; synonym for the portable
@code{@value{AS}} directive @code{.short}.

@item .import @var{name} [ ,@var{typ} ]
Converse of @code{.export}; make a procedure available to call.  The arguments
use the same conventions as the first two arguments for @code{.export}.

@item .label @var{name}
Define @var{name} as a label for the current assembly location.

@item .leave
Not yet supported; the assembler rejects programs containing this directive.

@item .origin @var{lc}
Advance location counter to @var{lc}. Synonym for the @code{@value{AS}}
portable directive @code{.org}.

@item .param @var{name} [ ,@var{typ} ]  [ ,@var{param}=@var{r} ]
@c Not in HP manual; @sc{gnu} HPPA extension
Similar to @code{.export}, but used for static procedures.

@item .proc
Use preceding the first statement of a procedure.

@item .procend
Use following the last statement of a procedure.

@item @var{label} .reg @var{expr}
@c ?? Not in HP manual (Jan 1988 vn)
Synonym for @code{.equ}; define @var{label} with the absolute expression
@var{expr} as its value.

@item .space @var{secname} [ ,@var{params} ]
Switch to section @var{secname}, creating a new section by that name if
necessary.  You may only use @var{params} when creating a new section, not
when switching to an existing one.  @var{secname} may identify a section by
number rather than by name.

If specified, the list @var{params} declares attributes of the section,
identified by keywords.  The keywords recognized are @samp{spnum=@var{exp}}
(identify this section by the number @var{exp}, an absolute expression),
@samp{sort=@var{exp}} (order sections according to this sort key when linking;
@var{exp} is an absolute expression), @samp{unloadable} (section contains no
loadable data), @samp{notdefined} (this section defined elsewhere), and
@samp{private} (data in this section not available to other programs).

@item .spnum @var{secnam}
@c ?? Not in HP manual (Jan 1988)
Allocate four bytes of storage, and initialize them with the section number of
the section named @var{secnam}.  (You can define the section number with the
HPPA @code{.space} directive.)

@cindex @code{string} directive on HPPA
@item .string "@var{str}"
Copy the characters in the string @var{str} to the object file.
@xref{Strings,,Strings}, for information on escape sequences you can use in
@code{@value{AS}} strings.

@emph{Warning!} The HPPA version of @code{.string} differs from the
usual @code{@value{AS}} definition: it does @emph{not} write a zero byte
after copying @var{str}.

@item .stringz "@var{str}"
Like @code{.string}, but appends a zero byte after copying @var{str} to object
file.

@item .subspa @var{name} [ ,@var{params} ]
@itemx .nsubspa @var{name} [ ,@var{params} ]
Similar to @code{.space}, but selects a subsection @var{name} within the
current section.  You may only specify @var{params} when you create a
subsection (in the first instance of @code{.subspa} for this @var{name}).

If specified, the list @var{params} declares attributes of the subsection,
identified by keywords.  The keywords recognized are @samp{quad=@var{expr}}
(``quadrant'' for this subsection), @samp{align=@var{expr}} (alignment for
beginning of this subsection; a power of two), @samp{access=@var{expr}} (value
for ``access rights'' field), @samp{sort=@var{expr}} (sorting order for this
subspace in link), @samp{code_only} (subsection contains only code),
@samp{unloadable} (subsection cannot be loaded into memory), @samp{comdat}
(subsection is comdat), @samp{common} (subsection is common block),
@samp{dup_comm} (subsection may have duplicate names), or @samp{zero}
(subsection is all zeros, do not write in object file).

@code{.nsubspa} always creates a new subspace with the given name, even
if one with the same name already exists.

@samp{comdat}, @samp{common} and @samp{dup_comm} can be used to implement
various flavors of one-only support when using the SOM linker.  The SOM
linker only supports specific combinations of these flags.  The details
are not documented.  A brief description is provided here.

@samp{comdat} provides a form of linkonce support.  It is useful for
both code and data subspaces.  A @samp{comdat} subspace has a key symbol
marked by the @samp{is_comdat} flag or @samp{ST_COMDAT}.  Only the first
subspace for any given key is selected.  The key symbol becomes universal
in shared links.  This is similar to the behavior of @samp{secondary_def}
symbols.

@samp{common} provides Fortran named common support.  It is only useful
for data subspaces.  Symbols with the flag @samp{is_common} retain this
flag in shared links.  Referencing a @samp{is_common} symbol in a shared
library from outside the library doesn't work.  Thus, @samp{is_common}
symbols must be output whenever they are needed.

@samp{common} and @samp{dup_comm} together provide Cobol common support.
The subspaces in this case must all be the same length.  Otherwise, this
support is similar to the Fortran common support.

@samp{dup_comm} by itself provides a type of one-only support for code.
Only the first @samp{dup_comm} subspace is selected.  There is a rather
complex algorithm to compare subspaces.  Code symbols marked with the
@samp{dup_common} flag are hidden.  This support was intended for "C++
duplicate inlines".

A simplified technique is used to mark the flags of symbols based on
the flags of their subspace.  A symbol with the scope SS_UNIVERSAL and
type ST_ENTRY, ST_CODE or ST_DATA is marked with the corresponding
settings of @samp{comdat}, @samp{common} and @samp{dup_comm} from the
subspace, respectively.  This avoids having to introduce additional
directives to mark these symbols.  The HP assembler sets @samp{is_common}
from @samp{common}.  However, it doesn't set the @samp{dup_common} from
@samp{dup_comm}.  It doesn't have @samp{comdat} support.

@item .version "@var{str}"
Write @var{str} as version identifier in object code.
@end table

@node HPPA Opcodes
@section Opcodes
For detailed information on the HPPA machine instruction set, see
@cite{PA-RISC Architecture and Instruction Set Reference Manual}
(HP 09740-90039).