Mercurial > pub > dyncall > dyncall

comparison doc/manual/callconvs/callconv_arm32.tex @ 0:3e629dc19168

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial from svn dyncall-1745
author Daniel Adler
date Thu, 19 Mar 2015 22:24:28 +0100
parents
children 645307d37731
comparison
equal deleted inserted replaced
-1:000000000000 0:3e629dc19168
1 %
2 % Copyright (c) 2007,2010 Daniel Adler <dadler@uni-goettingen.de>,
3 % Tassilo Philipp <tphilipp@potion-studios.com>
4 %
5 % Permission to use, copy, modify, and distribute this software for any
6 % purpose with or without fee is hereby granted, provided that the above
7 % copyright notice and this permission notice appear in all copies.
8 %
9 % THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 % WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 % MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 % ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 % WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 %
17
18 % ==================================================
19 % ARM32
20 % ==================================================
21 \subsection{ARM32 Calling Convention}
22
23 \paragraph{Overview}
24
25 The ARM32 family of processors is based on
26 the Advanced RISC Machines (ARM) processor architecture (32 bit RISC).
27 The word size is 32 bits (and the programming model is LLP64).\\
28 Basically, this family of microprocessors can be run in 2 major modes:\\
29 \\
30 \begin{tabular}{2 B}
31 \hline
32 Mode & Description\\
33 \hline
34 {\bf ARM} & 32bit instruction set\\
35 {\bf THUMB} & compressed instruction set using 16bit wide instruction encoding\\
36 \hline
37 \end{tabular}
38 \\
39 \\
40 For more details, take a look at the ARM-THUMB Procedure Call Standard (ATPCS) \cite{ATPCS}, the Procedure Call Standard for the ARM Architecture (AAPCS) \cite{AAPCS}, as well as the Debian ARM EABI port wiki \cite{armeabi}.
41
42
43 \paragraph{\product{dyncall} support}
44
45 Currently, the \product{dyncall} library supports the ARM and THUMB mode of the ARM32 family (ATPCS \cite{ATPCS} and EABI \cite{armeabi}), excluding manually triggered ARM-THUMB interworking calls. Although it's quite possible that the current implementation runs on other ARM processor families as well, please note that only the ARMv4t family has been thoroughly tested at the time of writing. Please report if the code runs on other ARM families, too.\\
46 It is important to note, that dyncall supports the ARM architecture calling convention variant {\bf with floating point hardware disabled} (meaning that the FPA and the VFP (scalar mode) procedure call standards are not supported).
47 This processor family features some instruction sets accelerating DSP and multimedia application like the ARM Jazelle Technology (direct Java bytecode execution, providing acceleration for some bytecodes while calling software code for others), etc. that are not supported by the dyncall library.\\
48
49
50 \subsubsection{ATPCS ARM mode}
51
52
53 \paragraph{Registers and register usage}
54
55 In ARM mode, the ARM32 processor has sixteen 32 bit general purpose registers, namely r0-r15:\\
56 \\
57 \begin{table}[h]
58 \begin{tabular}{3 B}
59 \hline
60 Name & Brief description\\
61 \hline
62 {\bf r0} & parameter 0, scratch, return value\\
63 {\bf r1} & parameter 1, scratch, return value\\
64 {\bf r2-r3} & parameters 2 and 3, scratch\\
65 {\bf r4-r10} & permanent\\
66 {\bf r11} & frame pointer, permanent\\
67 {\bf r12} & scratch\\
68 {\bf r13} & stack pointer, permanent\\
69 {\bf r14} & link register, permanent\\
70 {\bf r15} & program counter (note: due to pipeline, r15 points to 2 instructions ahead)\\
71 \hline
72 \end{tabular}
73 \caption{Register usage on arm32}
74 \end{table}
75
76 \paragraph{Parameter passing}
77
78 \begin{itemize}
79 \item stack parameter order: right-to-left
80 \item caller cleans up the stack
81 \item first four words are passed using r0-r3
82 \item subsequent parameters are pushed onto the stack (in right to left order, such that the stack pointer points to the first of the remaining parameters)
83 \item if the callee takes the address of one of the parameters and uses it to address other parameters (e.g. varargs) it has to copy - in its prolog - the first four words to a reserved stack area adjacent to the other parameters on the stack
84 \item parameters \textless=\ 32 bits are passed as 32 bit words
85 \item 64 bit parameters are passed as two 32 bit parts (even partly via the register and partly via the stack), although this doesn't seem to be specified in the ATPCS), with the loword coming first
86 \item structures and unions are passed by value, with the first four words of the parameters in r0-r3
87 \item if return value is a structure, a pointer pointing to the return value's space is passed in r0, the first parameter in r1, etc... (see {\bf return values})
88 \item keeping the stack eight-byte aligned can improve memory access performance and is required by LDRD and STRD on ARMv5TE processors which are part of the ARM32 family, so, in order to avoid problems one should always align the stack (tests have shown, that GCC does care about the alignment when using the ellipsis)
89 \end{itemize}
90
91 \paragraph{Return values}
92 \begin{itemize}
93 \item return values \textless=\ 32 bits use r0
94 \item 64 bit return values use r0 and r1
95 \item if return value is a structure, the caller allocates space for the return value on the stack in its frame and passes a pointer to it in r0
96 \end{itemize}
97
98 \paragraph{Stack layout}
99
100 Stack directly after function prolog:\\
101
102 \begin{figure}[h]
103 \begin{tabular}{5|3|1 1}
104 \hhline{~-~~}
105 & \vdots & & \\
106 \hhline{~=~~}
107 register save area & & & \mrrbrace{5}{caller's frame} \\
108 \hhline{~-~~}
109 local data & & & \\
110 \hhline{~-~~}
111 \mrlbrace{7}{parameter area} & \ldots & \mrrbrace{3}{stack parameters} & \\
112 & \ldots & & \\
113 & \ldots & & \\
114 \hhline{~=~~}
115 & r3 & \mrrbrace{4}{spill area (if needed)} & \mrrbrace{7}{current frame} \\
116 & r2 & & \\
117 & r1 & & \\
118 & r0 & & \\
119 \hhline{~-~~}
120 register save area (with return address) & & & \\
121 \hhline{~-~~}
122 local data & & & \\
123 \hhline{~-~~}
124 parameter area & \vdots & & \\
125 \hhline{~-~~}
126 \end{tabular}
127 \caption{Stack layout on arm32}
128 \end{figure}
129
130
131 \newpage
132
133 \subsubsection{ATPCS THUMB mode}
134
135
136 \paragraph{Status}
137
138 \begin{itemize}
139 \item The ATPCS THUMB mode is untested.
140 \item Ellipse calls may not work.
141 \item C++ this calls do not work.
142 \end{itemize}
143
144 \paragraph{Registers and register usage}
145
146 In THUMB mode, the ARM32 processor family supports eight 32 bit general purpose registers r0-r7 and access to high order registers r8-r15:\\
147 \\
148 \begin{table}[h]
149 \begin{tabular}{3 B}
150 \hline
151 Name & Brief description\\
152 \hline
153 {\bf r0} & parameter 0, scratch, return value\\
154 {\bf r1} & parameter 1, scratch, return value\\
155 {\bf r2-r3} & parameters 2 and 3, scratch\\
156 {\bf r4-r6} & permanent\\
157 {\bf r7} & frame pointer, permanent\\
158 {\bf r8-r11} & permanent\\
159 {\bf r12} & scratch\\
160 {\bf r13} & stack pointer, permanent\\
161 {\bf r14} & link register, permanent\\
162 {\bf r15} & program counter (note: due to pipeline, r15 points to 2 instructions ahead)\\
163 \hline
164 \end{tabular}
165 \caption{Register usage on arm32 thumb mode}
166 \end{table}
167
168 \paragraph{Parameter passing}
169
170 \begin{itemize}
171 \item stack parameter order: right-to-left
172 \item caller cleans up the stack
173 \item first four words are passed using r0-r3
174 \item subsequent parameters are pushed onto the stack (in right to left order, such that the stack pointer points to the first of the remaining parameters)
175 \item if the callee takes the address of one of the parameters and uses it to address other parameters (e.g. varargs) it has to copy - in its prolog - the first four words to a reserved stack area adjacent to the other parameters on the stack
176 \item parameters \textless=\ 32 bits are passed as 32 bit words
177 \item 64 bit parameters are passed as two 32 bit parts (even partly via the register and partly via the stack), although this doesn't seem to be specified in the ATPCS), with the loword coming first
178 \item structures and unions are passed by value, with the first four words of the parameters in r0-r3
179 \item if return value is a structure, a pointer pointing to the return value's space is passed in r0, the first parameter in r1, etc. (see {\bf return values})
180 \item keeping the stack eight-byte aligned can improve memory access performance and is required by LDRD and STRD on ARMv5TE processors which are part of the ARM32 family, so, in order to avoid problems one should always align the stack (tests have shown, that GCC does care about the alignment when using the ellipsis)
181 \end{itemize}
182
183
184 \paragraph{Return values}
185 \begin{itemize}
186 \item return values \textless=\ 32 bits use r0
187 \item 64 bit return values use r0 and r1
188 \item if return value is a structure, the caller allocates space for the return value on the stack in its frame and passes a pointer to it in r0
189 \end{itemize}
190
191 \paragraph{Stack layout}
192
193 Stack directly after function prolog:\\
194
195 \begin{figure}[h]
196 \begin{tabular}{5|3|1 1}
197 \hhline{~-~~}
198 & \vdots & & \\
199 \hhline{~=~~}
200 register save area & & & \mrrbrace{5}{caller's frame} \\
201 \hhline{~-~~}
202 local data & & & \\
203 \hhline{~-~~}
204 \mrlbrace{7}{parameter area} & \ldots & \mrrbrace{3}{stack parameters} & \\
205 & \ldots & & \\
206 & \ldots & & \\
207 \hhline{~=~~}
208 & r3 & \mrrbrace{4}{spill area (if needed)} & \mrrbrace{7}{current frame} \\
209 & r2 & & \\
210 & r1 & & \\
211 & r0 & & \\
212 \hhline{~-~~}
213 register save area (with return address) & & & \\
214 \hhline{~-~~}
215 local data & & & \\
216 \hhline{~-~~}
217 parameter area & \vdots & & \\
218 \hhline{~-~~}
219 \end{tabular}
220 \caption{Stack layout on arm32 thumb mode}
221 \end{figure}
222
223
224
225 \newpage
226
227 \subsubsection{EABI (ARM and THUMB mode)}
228
229
230 The ARM EABI is very similar to the ABI outlined in ARM-THUMB procedure call
231 standard (ATPCS) \cite{ATPCS} - however, the EABI requires the stack to be
232 8-byte aligned at function entries, as well as 64 bit parameters. The latter
233 are aligned on 8-byte boundaries on the stack and 2-registers for parameters
234 passed via register. In order to achieve such an alignment, a register might
235 have to be skipped for parameters passed via registers, or 4-bytes on the stack
236 for parameters passed via the stack. Refer to the Debian ARM EABI port wiki for more information \cite{armeabi}.
237
238
239 \paragraph{Status}
240
241 \begin{itemize}
242 \item The EABI THUMB mode is tested and works fine (contrary to the ATPCS).
243 \item Ellipse calls do not work.
244 \item C++ this calls do not work.
245 \end{itemize}
246
247 \newpage
248
249 \subsubsection{ARM on Apple's iOS (Darwin) Platform}
250
251
252 The iOS runs on ARMv6 (iOS 2.0) and ARMv7 (iOS 3.0) architectures.
253 Typically code is compiled in Thumb mode.
254
255 \paragraph{Register usage}
256
257 \begin{table}[h]
258 \begin{tabular}{3 B}
259 \hline
260 Name & Brief description\\
261 \hline
262 {\bf R0} & parameter 0, scratch, return value\\
263 {\bf R1} & parameter 1, scratch, return value\\
264 {\bf R2-R3} & parameters 2 and 3, scratch\\
265 {\bf R4-R6} & permanent\\
266 {\bf R7} & frame pointer, permanent\\
267 {\bf R8} & permanent\\
268 {\bf R9} & permanent(iOS 2.0) and scratch (since iOS 3.0)\\
269 {\bf R10-R11}& permanent\\
270 {\bf R12} & scratch, intra-procedure scratch register (IP) used by dynamic linker\\
271 {\bf R13} & stack pointer, permanent\\
272 {\bf R14} & link register, permanent\\
273 {\bf R15} & program counter (note: due to pipeline, r15 points to 2 instructions ahead)\\
274 {\bf CPSR} & Program status register\\
275 {\bf D0-D7} & scratch. aliases S0-S15, on ARMv7 alsa as Q0-Q3. Not accessible from Thumb mode on ARMv6.\\
276 {\bf D8-D15} & permanent, aliases S16-S31, on ARMv7 alsa as Q4-A7. Not accesible from Thumb mode on ARMv6.\\
277 {\bf D16-D31}& Only available in ARMv7, aliases Q8-Q15.\\
278 {\bf FPSCR} & VFP status register.\\
279 \hline
280 \end{tabular}
281 \caption{Register usage on ARM Apple iOS}
282 \end{table}
283
284 The ABI is based on the AAPCS but with some important differences listed below:
285
286 \begin{itemize}
287 \item R7 instead of R11 is used as frame pointer
288 \item R9 is scratch since iOS 3.0, was preserved before.
289 \end{itemize}
290
291 \subsubsection{Architectures}
292
293 The ARM architecture family contains several revisions with capabilities and
294 extensions (such as thumb-interworking and more vector registers)
295 The following table summaries important properties of the various
296 architecture standards.
297
298 % iPhone 3GS : ARM Cortex-A8
299 % Nintendo DS: ARM 7 and ARM 9
300 % ARM 7: ARMv4T
301 % ARM 9: ARMv4T, HTC Wizard
302
303 \begin{table}[h]
304 \begin{tabular}{lll}
305 Arch & Platforms & Details \\
306 \hline
307 ARMv4 & & \\
308 \hline
309 ARMv4T & ARM 7, ARM 9, Neo FreeRunner (OpenMoko) & \\
310 \hline
311 ARMv5 & & BLX instruction available \\
312 \hline
313 ARMv6 & & No vector registers available in thumb \\
314 \hline
315 ARMv7 & iPod touch, iPhone 3GS/4 & \\
316 \hline
317 \end{tabular}
318 \caption{Overview of ARM Architecture, Platforms and Details}
319 \end{table}
320
321 \newpage
322