Skip to content

Commit 16964f4

Browse files
aswatermanaswaterman
authored
Merge pull request #117 from lenary/lenary/c-types-alignments
Clarify Named ABIs and C type sizes and alignments
2 parents fc00ad4 + c1650c4 commit 16964f4

File tree

1 file changed

+163
-78
lines changed

1 file changed

+163
-78
lines changed

‎riscv-elf.md‎

Lines changed: 163 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,14 @@
77
2. [Procedure Calling Convention](#procedure-calling-convention)
88
* [Integer Calling Convention](#integer-calling-convention)
99
* [Hardware Floating-point Calling Convention](#hardware-floating-point-calling-convention)
10-
* [RV32E Calling Convention](#rv32e-calling-convention)
11-
* [Default ABIs and C type sizes](#default-abis-and-c-type-sizes)
10+
* [ILP32E Calling Convention](#ilp32e-calling-convention)
11+
* [Named ABIs](#named-abis)
12+
* [Default ABIs](#default-abis)
13+
3. [C type details](#c-types)
14+
* [C type sizes and alignments](#c-type-sizes)
15+
* [C type representations](#c-type-representation)
1216
* [va_list, va_start, and va_arg](#va-list-va-start-and-va-arg)
13-
3. [ELF Object Files](#elf-object-file)
17+
4. [ELF Object Files](#elf-object-file)
1418
* [File Header](#file-header)
1519
* [Sections](#sections)
1620
* [String Tables](#string-tables)
@@ -21,22 +25,26 @@
2125
* [Note Sections](#note-sections)
2226
* [Dynamic Table](#dynamic-table)
2327
* [Hash Table](#hash-table)
24-
4. [DWARF](#dwarf)
28+
5. [DWARF](#dwarf)
2529
* [Dwarf Register Numbers](#dwarf-register-numbers)
30+
6. [Linux-specific ABI](#linux-abi)
31+
* [Linux-specific C type sizes and alignments](#linux-c-type-sizes)
32+
* [Linux-specific C type representations](#linux-c-type-representations)
2633

2734
## Copyright and license information
2835

2936
This RISC-V ELF psABI specification document is
3037

31-
&copy; 2016 Palmer Dabbelt <[email protected]>
32-
&copy; 2016 Stefan O'Rear <[email protected]>
33-
&copy; 2016 Kito Cheng <[email protected]>
34-
&copy; 2016-2017 Andrew Waterman <[email protected]>
35-
&copy; 2016-2017 Michael Clark <[email protected]>
36-
&copy; 2017-2019 Alex Bradbury <[email protected]>
37-
&copy; 2017 David Horner <[email protected]>
38-
&copy; 2017 Max Nordlund <[email protected]>
39-
&copy; 2017 Karsten Merker <[email protected]>
38+
&copy; 2016 Palmer Dabbelt <[email protected]>
39+
&copy; 2016 Stefan O'Rear <[email protected]>
40+
&copy; 2016 Kito Cheng <[email protected]>
41+
&copy; 2016-2017 Andrew Waterman <[email protected]>
42+
&copy; 2016-2017 Michael Clark <[email protected]>
43+
&copy; 2017-2019 Alex Bradbury <[email protected]>
44+
&copy; 2017 David Horner <[email protected]>
45+
&copy; 2017 Max Nordlund <[email protected]>
46+
&copy; 2017 Karsten Merker <[email protected]>
47+
&copy; 2019 Sam Elliott <[email protected]>
4048

4149
It is licensed under the Creative Commons Attribution 4.0 International
4250
License (CC-BY 4.0). The full license text is available at
@@ -178,9 +186,9 @@ whether or not the integer registers have been exhausted.
178186
The remainder of this section applies only to named arguments. Variadic
179187
arguments are passed according to the integer calling convention.
180188

181-
For the purposes of this section, FLEN refers to the width of a
182-
floating-point register in the ABI. The ISA might have wider
183-
floating-point registers than the ABI.
189+
For the purposes of this section, FLEN refers to the width of a floating-point
190+
register in the ABI. The ABI's FLEN must be no wider than the ISA's FLEN. The
191+
ISA might have wider floating-point registers than the ABI.
184192

185193
For the purposes of this section, "struct" refers to a C struct with its
186194
hierarchy flattened, including any array fields. That is, `struct { struct
@@ -229,84 +237,135 @@ type would be passed.
229237
Floating-point registers fs0-fs11 shall be preserved across procedure calls,
230238
provided they hold values no more than FLEN bits wide.
231239

232-
## <a name=rv32e-calling-convention></a> RV32E Calling Convention
240+
## <a name=ilp32e-calling-convention></a> ILP32E Calling Convention
233241

234-
The RV32E calling convention is designed to be usable with the RV32E ISA.
235-
This calling convention is the same as the integer calling convention,
236-
except for the following differences. The stack pointer need only be aligned
237-
to a 32-bit boundary. Registers x16-x31 do not participate in the ABI, so
242+
The ILP32E calling convention is designed to be usable with the RV32E ISA. This
243+
calling convention is the same as the integer calling convention, except for the
244+
following differences. The stack pointer need only be aligned to a 32-bit
245+
boundary. Registers x16-x31 do not participate in the calling convention, so
238246
there are only six argument registers, a0-a5, only two callee-saved registers,
239247
s0-s1, and only three temporaries, t0-t2.
240248

241249
If used with an ISA that has any of the registers x16-x31 and f0-f31, then
242250
these registers are considered temporaries.
243251

244-
## <a name=default-abis-and-c-type-sizes></a> Default ABIs and C type sizes
252+
## <a name=named-abis></a> Named ABIs
253+
254+
This specification defines the following named ABIs:
255+
256+
* <a name=abi-ilp32></a> **ILP32**: Integer calling-convention only, hardware
257+
floating-point calling convention is not used (i.e. ELFCLASS32 and
258+
EF_RISCV_FLOAT_ABI_SOFT).
259+
260+
* <a name=abi-ilp32f></a> **ILP32F**: ILP32 with hardware floating-point calling
261+
convention for FLEN=32 (i.e. ELFCLASS32 and EF_RISCV_FLOAT_ABI_SINGLE).
262+
263+
* <a name=abi-ilp32d></a> **ILP32D**: ILP32 with hardware floating-point calling
264+
convention for FLEN=64 (i.e. ELFCLASS32 and EF_RISCV_FLOAT_ABI_DOUBLE).
265+
266+
* <a name=abi-ilp32e></a> **ILP32E**: [ILP32E
267+
calling-convention](#ilp32e-calling-convention) only, hardware floating-point
268+
calling convention is not used (i.e. ELFCLASS32, EF_RISCV_FLOAT_ABI_SOFT, and
269+
EF_RISCV_RVE).
270+
271+
* <a name=abi-lp64></a> **LP64**: Integer calling-convention only, hardware
272+
floating-point calling convention is not used (i.e. ELFCLASS64 and
273+
EF_RISCV_FLOAT_ABI_SOFT).
274+
275+
* <a name=abi-lp64f></a> **LP64F**: LP64 with hardware floating-point calling
276+
convention for FLEN=32 (i.e. ELFCLASS64 and EF_RISCV_FLOAT_ABI_SINGLE).
277+
278+
* <a name=abi-lp64d></a> **LP64D**: LP64 with hardware floating-point calling
279+
convention for FLEN=64 (i.e. ELFCLASS64 and EF_RISCV_FLOAT_ABI_DOUBLE).
280+
281+
* <a name=abi-lp64q></a> **LP64Q**: LP64 with hardware floating-point calling
282+
convention for FLEN=128 (i.e. ELFCLASS64 and EF_RISCV_FLOAT_ABI_QUAD).
283+
284+
The ILP32\* ABIs are only compatible with RV32\* ISAs, and the LP64\* ABIs are
285+
only compatible with RV64\* ISAs. A future version of this specification may
286+
define an ILP32 ABI for the RV64 ISA, but currently this is not a supported
287+
operating mode.
288+
289+
The \*F ABIs require the \*F ISA extension, the \*D ABIs require the \*D ISA
290+
extension, and the LP64Q ABI requires the Q ISA extension.
291+
292+
## <a name=default-abis></a> Default ABIs
245293

246294
While various different ABIs are technically possible, for software
247295
compatibility reasons it is strongly recommended to use the following
248-
default ABIs:
249-
250-
* **on RV64G**: LP64 with floats and doubles passed in floating point
251-
registers, i.e. ELFCLASS64 and EF_RISCV_FLOAT_ABI_DOUBLE, using the
252-
following C type sizes:
253-
254-
Type | Size (Bytes) | Alignment (Bytes)
255-
------------|---------------|------------------
256-
bool/_Bool | 1 | 1
257-
char | 1 | 1
258-
short | 2 | 2
259-
int | 4 | 4
260-
wchar_t | 4 | 4
261-
wint_t | 4 | 4
262-
long | 8 | 8
263-
long long | 8 | 8
264-
__int128 | 16 | 16
265-
void * | 8 | 8
266-
float | 4 | 4
267-
double | 8 | 8
268-
long double | 16 | 16
269-
270-
Although RV64GQ systems can technically use EF_RISCV_FLOAT_ABI_QUAD,
271-
it is strongly recommended to use EF_RISCV_FLOAT_ABI_DOUBLE on
272-
general-purpose RV64GQ systems for compatibility with standard RV64G
273-
software.
274-
275-
* **on RV32G**: ILP32 with floats and doubles passed in floating point
276-
registers, i.e. ELFCLASS32 and EF_RISCV_FLOAT_ABI_DOUBLE, using the
277-
following C type sizes:
278-
279-
Type | Size (Bytes) | Alignment (Bytes)
280-
------------|---------------|------------------
281-
bool/_Bool | 1 | 1
282-
char | 1 | 1
283-
short | 2 | 2
284-
int | 4 | 4
285-
wchar_t | 4 | 4
286-
wint_t | 4 | 4
287-
long | 4 | 4
288-
long long | 8 | 8
289-
void * | 4 | 4
290-
float | 4 | 4
291-
double | 8 | 8
292-
long double | 16 | 16
293-
294-
`char` is unsigned. `wchar_t` is signed. `wint_t` is unsigned.
295-
296-
`_Complex` types have the alignment and layout of a struct containing two
297-
fields of the corresponding real type (`float`, `double`, or `long double`),
298-
with the first field holding the real part and the second field holding
299-
the imaginary part.
300-
301-
A future version of this specification may define an ILP32 ABI for
302-
RV64G, but currently this is not a supported operating mode.
296+
default ABIs for specific architectures:
297+
298+
* **on RV64G**: [LP64D](#abi-lp64d)
299+
300+
Although RV64GQ systems can technically use [LP64Q](#abi-lp64q), it is
301+
strongly recommended to use LP64D on general-purpose RV64GQ systems for
302+
compatibility with standard RV64G software.
303+
304+
* **on RV32G**: [ILP32D](#abi-ilp32d)
305+
306+
# <a name=c-types></a> C type details
307+
## <a name=c-type-sizes></a> C type sizes and alignments
308+
309+
There are two conventions for C type sizes and alignments.
310+
311+
* **LP64, LP64F, LP64D, and LP64Q**: use the following type sizes and
312+
alignments (based on the LP64 convention):
313+
314+
Type | Size (Bytes) | Alignment (Bytes)
315+
---------------------|---------------|------------------
316+
bool/_Bool | 1 | 1
317+
char | 1 | 1
318+
short | 2 | 2
319+
int | 4 | 4
320+
long | 8 | 8
321+
long long | 8 | 8
322+
__int128 | 16 | 16
323+
void * | 8 | 8
324+
float | 4 | 4
325+
double | 8 | 8
326+
long double | 16 | 16
327+
float _Complex | 8 | 4
328+
double _Complex | 16 | 8
329+
long double _Complex | 32 | 16
330+
331+
* **ILP32, ILP32F, ILP32D, and ILP32E**: use the following type sizes and
332+
alignments (based on the ILP32 convention):
333+
334+
Type | Size (Bytes) | Alignment (Bytes)
335+
---------------------|---------------|------------------
336+
bool/_Bool | 1 | 1
337+
char | 1 | 1
338+
short | 2 | 2
339+
int | 4 | 4
340+
long | 4 | 4
341+
long long | 8 | 8
342+
void * | 4 | 4
343+
float | 4 | 4
344+
double | 8 | 8
345+
long double | 16 | 16
346+
float _Complex | 8 | 4
347+
double _Complex | 16 | 8
348+
long double _Complex | 32 | 16
349+
350+
The alignment of `max_align_t` is 16.
351+
352+
`CHAR_BITS` is 8.
353+
354+
Structs and unions are aligned to the alignment of their most strictly aligned
355+
member. The size of any object is a multiple of its alignment.
356+
357+
## <a name=c-type-representation></a> C type representations
358+
359+
`char` is unsigned.
303360

304361
Booleans (`bool`/`_Bool`) stored in memory or when being passed as scalar
305362
arguments are either `0` (`false`) or `1` (`true`).
306363

307364
A null pointer (for all types) has the value zero.
308365

309-
The value of `_Alignof(max_align_t)` is 16.
366+
`_Complex` types have the same layout as a struct containing two fields of the
367+
corresponding real type (`float`, `double`, or `long double`), with the first
368+
member holding the real part and the second member holding the imaginary part.
310369

311370
## <a name=va-list-va-start-and-va-arg></a> va_list, va_start, and va_arg
312371

@@ -813,3 +872,29 @@ Dwarf Number | Register Name | Description
813872
The alternate frame return column is meant to be used when unwinding from
814873
signal handlers, and stores the address where the signal handler will return
815874
to.
875+
876+
# <a name=linux-abi></a> Linux-specific ABI
877+
878+
**This section of the RISC-V ELF psABI specification only applies to Linux-based
879+
systems.**
880+
881+
In order to ensure compatibility between different implementations of the C
882+
library for Linux, we provide some extra definitions which only apply on those
883+
systems. These are noted in this section.
884+
885+
## <a name=linux-c-type-sizes></a> Linux-specific C type sizes and alignments
886+
887+
The following definitions apply for all ABIs defined in this document. Here
888+
there is no differentiation between ILP32 and LP64 abis.
889+
890+
Type | Size (Bytes) | Alignment (Bytes)
891+
------------|---------------|------------------
892+
wchar_t | 4 | 4
893+
wint_t | 4 | 4
894+
895+
## <a name=linux-c-type-representations></a> Linux-specific C type representations
896+
897+
The following definitions apply for all ABIs defined in this document. Here
898+
there is no differentiation between ILP32 and LP64 abis.
899+
900+
`wchar_t` is signed. `wint_t` is unsigned.

0 commit comments

Comments
 (0)