1===============================================
2Power Architecture 64-bit Linux system call ABI
3===============================================
4
5syscall
6=======
7
8syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
9specification C function calling sequence, including register preservation
10rules, with the following differences.
11
12[*] Some syscalls (typically low-level management functions) may have
13    different calling sequences (e.g., rt_sigreturn).
14
15Parameters and return value
16---------------------------
17The system call number is specified in r0.
18
19There is a maximum of 6 integer parameters to a syscall, passed in r3-r8.
20
21Both a return value and a return error code are returned. cr0.SO is the return
22error code, and r3 is the return value or error code. When cr0.SO is clear,
23the syscall succeeded and r3 is the return value. When cr0.SO is set, the
24syscall failed and r3 is the error code that generally corresponds to errno.
25
26Stack
27-----
28System calls do not modify the caller's stack frame. For example, the caller's
29stack frame LR and CR save fields are not used.
30
31Register preservation rules
32---------------------------
33Register preservation rules match the ELF ABI calling sequence with the
34following differences:
35
36r0:         Volatile.   (System call number.)
37r3:         Volatile.   (Parameter 1, and return value.)
38r4-r8:      Volatile.   (Parameters 2-6.)
39cr0:        Volatile    (cr0.SO is the return error condition)
40cr1, cr5-7: Nonvolatile.
41lr:         Nonvolatile.
42
43All floating point and vector data registers as well as control and status
44registers are nonvolatile.
45
46Invocation
47----------
48The syscall is performed with the sc instruction, and returns with execution
49continuing at the instruction following the sc instruction.
50
51Transactional Memory
52--------------------
53Syscall behavior can change if the processor is in transactional or suspended
54transaction state, and the syscall can affect the behavior of the transaction.
55
56If the processor is in suspended state when a syscall is made, the syscall
57will be performed as normal, and will return as normal. The syscall will be
58performed in suspended state, so its side effects will be persistent according
59to the usual transactional memory semantics. A syscall may or may not result
60in the transaction being doomed by hardware.
61
62If the processor is in transactional state when a syscall is made, then the
63behavior depends on the presence of PPC_FEATURE2_HTM_NOSC in the AT_HWCAP2 ELF
64auxiliary vector.
65
66- If present, which is the case for newer kernels, then the syscall will not
67  be performed and the transaction will be doomed by the kernel with the
68  failure code TM_CAUSE_SYSCALL | TM_CAUSE_PERSISTENT in the TEXASR SPR.
69
70- If not present (older kernels), then the kernel will suspend the
71  transactional state and the syscall will proceed as in the case of a
72  suspended state syscall, and will resume the transactional state before
73  returning to the caller. This case is not well defined or supported, so this
74  behavior should not be relied upon.
75
76
77vsyscall
78========
79
80vsyscall calling sequence matches the syscall calling sequence, with the
81following differences. Some vsyscalls may have different calling sequences.
82
83Parameters and return value
84---------------------------
85r0 is not used as an input. The vsyscall is selected by its address.
86
87Stack
88-----
89The vsyscall may or may not use the caller's stack frame save areas.
90
91Register preservation rules
92---------------------------
93r0: Volatile.
94cr1, cr5-7: Volatile.
95lr: Volatile.
96
97Invocation
98----------
99The vsyscall is performed with a branch-with-link instruction to the vsyscall
100function address.
101
102Transactional Memory
103--------------------
104vsyscalls will run in the same transactional state as the caller. A vsyscall
105may or may not result in the transaction being doomed by hardware.
106