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