Import binutils-2.20
[dragonfly.git] / contrib / binutils-2.20 / gas / doc / c-i370.texi
CommitLineData
8e158dd0
SS
1@c Copyright 2000, 2002 Free Software Foundation, Inc.
2@c This is part of the GAS manual.
3@c For copying conditions, see the file as.texinfo.
4@ifset GENERIC
5@page
6@node ESA/390-Dependent
7@chapter ESA/390 Dependent Features
8@end ifset
9@ifclear GENERIC
10@node Machine Dependencies
11@chapter ESA/390 Dependent Features
12@end ifclear
13
14@cindex i370 support
15@cindex ESA/390 support
16
17@menu
18* ESA/390 Notes:: Notes
19* ESA/390 Options:: Options
20* ESA/390 Syntax:: Syntax
21* ESA/390 Floating Point:: Floating Point
22* ESA/390 Directives:: ESA/390 Machine Directives
23* ESA/390 Opcodes:: Opcodes
24@end menu
25
26@node ESA/390 Notes
27@section Notes
28The ESA/390 @code{@value{AS}} port is currently intended to be a back-end
29for the @sc{gnu} @sc{cc} compiler. It is not HLASM compatible, although
30it does support a subset of some of the HLASM directives. The only
31supported binary file format is ELF; none of the usual MVS/VM/OE/USS
32object file formats, such as ESD or XSD, are supported.
33
34When used with the @sc{gnu} @sc{cc} compiler, the ESA/390 @code{@value{AS}}
35will produce correct, fully relocated, functional binaries, and has been
36used to compile and execute large projects. However, many aspects should
37still be considered experimental; these include shared library support,
38dynamically loadable objects, and any relocation other than the 31-bit
39relocation.
40
41@node ESA/390 Options
42@section Options
43@code{@value{AS}} has no machine-dependent command-line options for the ESA/390.
44
45@cindex ESA/390 Syntax
46@node ESA/390 Syntax
47@section Syntax
48The opcode/operand syntax follows the ESA/390 Principles of Operation
49manual; assembler directives and general syntax are loosely based on the
50prevailing AT&T/SVR4/ELF/Solaris style notation. HLASM-style directives
51are @emph{not} supported for the most part, with the exception of those
52described herein.
53
54A leading dot in front of directives is optional, and the case of
55directives is ignored; thus for example, .using and USING have the same
56effect.
57
58A colon may immediately follow a label definition. This is
59simply for compatibility with how most assembly language programmers
60write code.
61
62@samp{#} is the line comment character.
63
64@samp{;} can be used instead of a newline to separate statements.
65
66Since @samp{$} has no special meaning, you may use it in symbol names.
67
68Registers can be given the symbolic names r0..r15, fp0, fp2, fp4, fp6.
69By using thesse symbolic names, @code{@value{AS}} can detect simple
70syntax errors. The name rarg or r.arg is a synonym for r11, rtca or r.tca
71for r12, sp, r.sp, dsa r.dsa for r13, lr or r.lr for r14, rbase or r.base
72for r3 and rpgt or r.pgt for r4.
73
74@samp{*} is the current location counter. Unlike @samp{.} it is always
75relative to the last USING directive. Note that this means that
76expressions cannot use multiplication, as any occurrence of @samp{*}
77will be interpreted as a location counter.
78
79All labels are relative to the last USING. Thus, branches to a label
80always imply the use of base+displacement.
81
82Many of the usual forms of address constants / address literals
83are supported. Thus,
84@example
85 .using *,r3
86 L r15,=A(some_routine)
87 LM r6,r7,=V(some_longlong_extern)
88 A r1,=F'12'
89 AH r0,=H'42'
90 ME r6,=E'3.1416'
91 MD r6,=D'3.14159265358979'
92 O r6,=XL4'cacad0d0'
93 .ltorg
94@end example
95should all behave as expected: that is, an entry in the literal
96pool will be created (or reused if it already exists), and the
97instruction operands will be the displacement into the literal pool
98using the current base register (as last declared with the @code{.using}
99directive).
100
101@node ESA/390 Floating Point
102@section Floating Point
103@cindex floating point, ESA/390 (@sc{ieee})
104@cindex ESA/390 floating point (@sc{ieee})
105The assembler generates only @sc{ieee} floating-point numbers. The older
106floating point formats are not supported.
107
108
109@node ESA/390 Directives
110@section ESA/390 Assembler Directives
111
112@code{@value{AS}} for the ESA/390 supports all of the standard ELF/SVR4
113assembler directives that are documented in the main part of this
114documentation. Several additional directives are supported in order
115to implement the ESA/390 addressing model. The most important of these
116are @code{.using} and @code{.ltorg}
117
118@cindex ESA/390-only directives
119These are the additional directives in @code{@value{AS}} for the ESA/390:
120
121@table @code
122@item .dc
123A small subset of the usual DC directive is supported.
124
125@item .drop @var{regno}
126Stop using @var{regno} as the base register. The @var{regno} must
127have been previously declared with a @code{.using} directive in the
128same section as the current section.
129
130@item .ebcdic @var{string}
131Emit the EBCDIC equivalent of the indicated string. The emitted string
132will be null terminated. Note that the directives @code{.string} etc. emit
133ascii strings by default.
134
135@item EQU
136The standard HLASM-style EQU directive is not supported; however, the
137standard @code{@value{AS}} directive .equ can be used to the same effect.
138
139@item .ltorg
140Dump the literal pool accumulated so far; begin a new literal pool.
141The literal pool will be written in the current section; in order to
142generate correct assembly, a @code{.using} must have been previously
143specified in the same section.
144
145@item .using @var{expr},@var{regno}
146Use @var{regno} as the base register for all subsequent RX, RS, and SS form
147instructions. The @var{expr} will be evaluated to obtain the base address;
148usually, @var{expr} will merely be @samp{*}.
149
150This assembler allows two @code{.using} directives to be simultaneously
151outstanding, one in the @code{.text} section, and one in another section
152(typically, the @code{.data} section). This feature allows
153dynamically loaded objects to be implemented in a relatively
154straightforward way. A @code{.using} directive must always be specified
155in the @code{.text} section; this will specify the base register that
156will be used for branches in the @code{.text} section. A second
157@code{.using} may be specified in another section; this will specify
158the base register that is used for non-label address literals.
159When a second @code{.using} is specified, then the subsequent
160@code{.ltorg} must be put in the same section; otherwise an error will
161result.
162
163Thus, for example, the following code uses @code{r3} to address branch
164targets and @code{r4} to address the literal pool, which has been written
165to the @code{.data} section. The is, the constants @code{=A(some_routine)},
166@code{=H'42'} and @code{=E'3.1416'} will all appear in the @code{.data}
167section.
168
169@example
170.data
171 .using LITPOOL,r4
172.text
173 BASR r3,0
174 .using *,r3
175 B START
176 .long LITPOOL
177START:
178 L r4,4(,r3)
179 L r15,=A(some_routine)
180 LTR r15,r15
181 BNE LABEL
182 AH r0,=H'42'
183LABEL:
184 ME r6,=E'3.1416'
185.data
186LITPOOL:
187 .ltorg
188@end example
189
190
191Note that this dual-@code{.using} directive semantics extends
192and is not compatible with HLASM semantics. Note that this assembler
193directive does not support the full range of HLASM semantics.
194
195@end table
196
197@node ESA/390 Opcodes
198@section Opcodes
199For detailed information on the ESA/390 machine instruction set, see
200@cite{ESA/390 Principles of Operation} (IBM Publication Number DZ9AR004).