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