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
20As a back end for @sc{gnu} @sc{cc} @code{@value{AS}} has been throughly tested and should
21work extremely well.  We have tested it only minimally on hand written assembly
22code and no one has tested it much on the assembly output from the HP
23compilers.
24
25The format of the debugging sections has changed since the original
26@code{@value{AS}} port (version 1.3X) was released; therefore,
27you must rebuild all HPPA objects and libraries with the new
28assembler so that you can debug the final executable.
29
30The HPPA @code{@value{AS}} port generates a small subset of the relocations
31available in the SOM and ELF object file formats.  Additional relocation
32support 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
41The assembler syntax closely follows the HPPA instruction set
42reference manual; assembler directives and general syntax closely follow the
43HPPA assembly language reference manual, with a few noteworthy differences.
44
45First, a colon may immediately follow a label definition.  This is
46simply for compatibility with how most assembly language programmers
47write code.
48
49Some obscure expression parsing problems may affect hand written code which
50uses the @code{spop} instructions, or code which makes significant
51use of the @code{!} line separator.
52
53@code{@value{AS}} is much less forgiving about missing arguments and other
54similar oversights than the HP assembler.  @code{@value{AS}} notifies you
55of missing arguments as syntax errors; this is regarded as a feature, not a
56bug.
57
58Finally, @code{@value{AS}} allows you to use an external symbol without
59explicitly importing the symbol.  @emph{Warning:} in the future this will be
60an error for HPPA targets.
61
62Special 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
68Since @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})
74The 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
80compatibility with the native assembler.  This section describes them only
81briefly.  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
86described 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
96Beyond those implemented for compatibility, @code{@value{AS}} supports one
97additional assembler directive for the HPPA: @code{.param}.  It conveys
98register argument locations for static functions.  Its syntax closely follows
99the @code{.export} directive.
100
101@cindex HPPA-only directives
102These 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}
107Reserve @var{n} bytes of storage, and initialize them to zero.
108
109@item .call
110Mark the beginning of a procedure call.  Only the special case with @emph{no
111arguments} is allowed.
112
113@item .callinfo [ @var{param}=@var{value}, @dots{} ]  [ @var{flag}, @dots{} ]
114Specify a number of parameters and flags that define the environment for a
115procedure.
116
117@var{param} may be any of @samp{frame} (frame size), @samp{entry_gr} (end of
118general register range), @samp{entry_fr} (end of float register range),
119@samp{entry_sr} (end of space register range).
120
121The values for @var{flag} are @samp{calls} or @samp{caller} (proc has
122subroutines), @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
125routine).
126
127@item .code
128Assemble into the standard section called @samp{$TEXT$}, subsection
129@samp{$CODE$}.
130
131@ifset SOM
132@item .copyright "@var{string}"
133In the SOM object format, insert @var{string} into the object code, marked as a
134copyright string.
135@end ifset
136
137@ifset ELF
138@item .copyright "@var{string}"
139In the ELF object format, insert @var{string} into the object code, marked as a
140version string.
141@end ifset
142
143@item .enter
144Not yet supported; the assembler rejects programs containing this directive.
145
146@item .entry
147Mark the beginning of a procedure.
148
149@item .exit
150Mark the end of a procedure.
151
152@item .export @var{name} [ ,@var{typ} ]  [ ,@var{param}=@var{r} ]
153Make a procedure @var{name} available to callers.  @var{typ}, if present, must
154be 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
159procedure 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
161indicates one of four one-word arguments); @samp{rtnval} (the procedure's
162result); 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
164relocatable), @samp{gr} (argument is in general register), @samp{fr} (in
165floating point register), or @samp{fu} (upper half of float register).
166For @samp{priv_lev}, @var{r} is an integer.
167
168@item .half @var{n}
169Define 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} ]
173Converse of @code{.export}; make a procedure available to call.  The arguments
174use the same conventions as the first two arguments for @code{.export}.
175
176@item .label @var{name}
177Define @var{name} as a label for the current assembly location.
178
179@item .leave
180Not yet supported; the assembler rejects programs containing this directive.
181
182@item .origin @var{lc}
183Advance location counter to @var{lc}. Synonym for the @code{@value{AS}}
184portable 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
188Similar to @code{.export}, but used for static procedures.
189
190@item .proc
191Use preceding the first statement of a procedure.
192
193@item .procend
194Use following the last statement of a procedure.
195
196@item @var{label} .reg @var{expr}
197@c ?? Not in HP manual (Jan 1988 vn)
198Synonym for @code{.equ}; define @var{label} with the absolute expression
199@var{expr} as its value.
200
201@item .space @var{secname} [ ,@var{params} ]
202Switch to section @var{secname}, creating a new section by that name if
203necessary.  You may only use @var{params} when creating a new section, not
204when switching to an existing one.  @var{secname} may identify a section by
205number rather than by name.
206
207If specified, the list @var{params} declares attributes of the section,
208identified 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
212loadable 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)
217Allocate four bytes of storage, and initialize them with the section number of
218the section named @var{secnam}.  (You can define the section number with the
219HPPA @code{.space} directive.)
220
221@cindex @code{string} directive on HPPA
222@item .string "@var{str}"
223Copy 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
228usual @code{@value{AS}} definition: it does @emph{not} write a zero byte
229after copying @var{str}.
230
231@item .stringz "@var{str}"
232Like @code{.string}, but appends a zero byte after copying @var{str} to object
233file.
234
235@item .subspa @var{name} [ ,@var{params} ]
236@itemx .nsubspa @var{name} [ ,@var{params} ]
237Similar to @code{.space}, but selects a subsection @var{name} within the
238current section.  You may only specify @var{params} when you create a
239subsection (in the first instance of @code{.subspa} for this @var{name}).
240
241If specified, the list @var{params} declares attributes of the subsection,
242identified by keywords.  The keywords recognized are @samp{quad=@var{expr}}
243(``quadrant'' for this subsection), @samp{align=@var{expr}} (alignment for
244beginning of this subsection; a power of two), @samp{access=@var{expr}} (value
245for ``access rights'' field), @samp{sort=@var{expr}} (sorting order for this
246subspace 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
253if one with the same name already exists.
254
255@samp{comdat}, @samp{common} and @samp{dup_comm} can be used to implement
256various flavors of one-only support when using the SOM linker.  The SOM
257linker only supports specific combinations of these flags.  The details
258are not documented.  A brief description is provided here.
259
260@samp{comdat} provides a form of linkonce support.  It is useful for
261both code and data subspaces.  A @samp{comdat} subspace has a key symbol
262marked by the @samp{is_comdat} flag or @samp{ST_COMDAT}.  Only the first
263subspace for any given key is selected.  The key symbol becomes universal
264in shared links.  This is similar to the behavior of @samp{secondary_def}
265symbols.
266
267@samp{common} provides Fortran named common support.  It is only useful
268for data subspaces.  Symbols with the flag @samp{is_common} retain this
269flag in shared links.  Referencing a @samp{is_common} symbol in a shared
270library from outside the library doesn't work.  Thus, @samp{is_common}
271symbols must be output whenever they are needed.
272
273@samp{common} and @samp{dup_comm} together provide Cobol common support.
274The subspaces in this case must all be the same length.  Otherwise, this
275support is similar to the Fortran common support.
276
277@samp{dup_comm} by itself provides a type of one-only support for code.
278Only the first @samp{dup_comm} subspace is selected.  There is a rather
279complex algorithm to compare subspaces.  Code symbols marked with the
280@samp{dup_common} flag are hidden.  This support was intended for "C++
281duplicate inlines".
282
283A simplified technique is used to mark the flags of symbols based on
284the flags of their subspace.  A symbol with the scope SS_UNIVERSAL and
285type ST_ENTRY, ST_CODE or ST_DATA is marked with the corresponding
286settings of @samp{comdat}, @samp{common} and @samp{dup_comm} from the
287subspace, respectively.  This avoids having to introduce additional
288directives to mark these symbols.  The HP assembler sets @samp{is_common}
289from @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}"
293Write @var{str} as version identifier in object code.
294@end table
295
296@node HPPA Opcodes
297@section Opcodes
298For detailed information on the HPPA machine instruction set, see
299@cite{PA-RISC Architecture and Instruction Set Reference Manual}
300(HP 09740-90039).
301