gas/doc/c-hppa.texi - binutils-gdb - Git at Google

 @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).
	@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).