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