Document .nsubspa.

1 files changed, 263 insertions, 0 deletions

diff --git a/gas/doc/c-hppa.texi b/gas/doc/c-hppa.texi
new file mode 100644
index 0000000..c432b8d
--- /dev/null
+++ b/gas/doc/c-hppa.texi
@@ -0,0 +1,263 @@
+@c Copyright (C) 1991, 1992, 1993, 1994, 1995 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 throughly 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; 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.)
+
+@item .string "@var{str}"
+@cindex @code{string} directive on HPPA
+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} ]
+@item .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{common}
+(subsection is common block), @samp{dup_comm} (initialized data 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.
+
+@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).