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