1===============================================
2Power Architecture 64-bit Linux system call ABI
3===============================================
4
5syscall
6=======
7
8syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
9specification C function calling sequence, including register preservation
10rules, with the following differences.
11
12.. [1] 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
36=========== ============= ========================================
37r0          Volatile      (System call number.)
38r3          Volatile      (Parameter 1, and return value.)
39r4-r8       Volatile      (Parameters 2-6.)
40cr0         Volatile      (cr0.SO is the return error condition)
41cr1, cr5-7  Nonvolatile
42lr          Nonvolatile
43=========== ============= ========================================
44
45All floating point and vector data registers as well as control and status
46registers are nonvolatile.
47
48Invocation
49----------
50The syscall is performed with the sc instruction, and returns with execution
51continuing at the instruction following the sc instruction.
52
53Transactional Memory
54--------------------
55Syscall behavior can change if the processor is in transactional or suspended
56transaction state, and the syscall can affect the behavior of the transaction.
57
58If the processor is in suspended state when a syscall is made, the syscall
59will be performed as normal, and will return as normal. The syscall will be
60performed in suspended state, so its side effects will be persistent according
61to the usual transactional memory semantics. A syscall may or may not result
62in the transaction being doomed by hardware.
63
64If the processor is in transactional state when a syscall is made, then the
65behavior depends on the presence of PPC_FEATURE2_HTM_NOSC in the AT_HWCAP2 ELF
66auxiliary vector.
67
68- If present, which is the case for newer kernels, then the syscall will not
69  be performed and the transaction will be doomed by the kernel with the
70  failure code TM_CAUSE_SYSCALL | TM_CAUSE_PERSISTENT in the TEXASR SPR.
71
72- If not present (older kernels), then the kernel will suspend the
73  transactional state and the syscall will proceed as in the case of a
74  suspended state syscall, and will resume the transactional state before
75  returning to the caller. This case is not well defined or supported, so this
76  behavior should not be relied upon.
77
78
79vsyscall
80========
81
82vsyscall calling sequence matches the syscall calling sequence, with the
83following differences. Some vsyscalls may have different calling sequences.
84
85Parameters and return value
86---------------------------
87r0 is not used as an input. The vsyscall is selected by its address.
88
89Stack
90-----
91The vsyscall may or may not use the caller's stack frame save areas.
92
93Register preservation rules
94---------------------------
95
96=========== ========
97r0          Volatile
98cr1, cr5-7  Volatile
99lr          Volatile
100=========== ========
101
102Invocation
103----------
104The vsyscall is performed with a branch-with-link instruction to the vsyscall
105function address.
106
107Transactional Memory
108--------------------
109vsyscalls will run in the same transactional state as the caller. A vsyscall
110may or may not result in the transaction being doomed by hardware.
111