Documentation/powerpc/syscall64-abi.rst

   1 ===============================================
   2 Power Architecture 64-bit Linux system call ABI
   3 ===============================================
   4
   5 syscall
   6 =======
   7
   8 Invocation
   9 ----------
  10 The syscall is made with the sc instruction, and returns with execution
  11 continuing at the instruction following the sc instruction.
  12
  13 If PPC_FEATURE2_SCV appears in the AT_HWCAP2 ELF auxiliary vector, the
  14 scv 0 instruction is an alternative that may provide better performance,
  15 with some differences to calling sequence.
  16
  17 syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
  18 specification C function calling sequence, including register preservation
  19 rules, 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
  24 Parameters
  25 ----------
  26 The system call number is specified in r0.
  27
  28 There is a maximum of 6 integer parameters to a syscall, passed in r3-r8.
  29
  30 Return 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
  42 Stack
  43 -----
  44 System calls do not modify the caller's stack frame. For example, the caller's
  45 stack frame LR and CR save fields are not used.
  46
  47 Register preservation rules
  48 ---------------------------
  49 Register preservation rules match the ELF ABI calling sequence with the
  50 following differences:
  51
  52 =========== ============= ========================================
  53 --- For the sc instruction, differences with the ELF ABI ---
  54 r0          Volatile      (System call number.)
  55 r3          Volatile      (Parameter 1, and return value.)
  56 r4-r8       Volatile      (Parameters 2-6.)
  57 cr0         Volatile      (cr0.SO is the return error condition.)
  58 cr1, cr5-7  Nonvolatile
  59 lr          Nonvolatile
  60
  61 --- For the scv 0 instruction, differences with the ELF ABI ---
  62 r0          Volatile      (System call number.)
  63 r3          Volatile      (Parameter 1, and return value.)
  64 r4-r8       Volatile      (Parameters 2-6.)
  65 =========== ============= ========================================
  66
  67 All floating point and vector data registers as well as control and status
  68 registers are nonvolatile.
  69
  70 Transactional Memory
  71 --------------------
  72 Syscall behavior can change if the processor is in transactional or suspended
  73 transaction state, and the syscall can affect the behavior of the transaction.
  74
  75 If the processor is in suspended state when a syscall is made, the syscall
  76 will be performed as normal, and will return as normal. The syscall will be
  77 performed in suspended state, so its side effects will be persistent according
  78 to the usual transactional memory semantics. A syscall may or may not result
  79 in the transaction being doomed by hardware.
  80
  81 If the processor is in transactional state when a syscall is made, then the
  82 behavior depends on the presence of PPC_FEATURE2_HTM_NOSC in the AT_HWCAP2 ELF
  83 auxiliary 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
  95 scv 0 syscalls will always behave as PPC_FEATURE2_HTM_NOSC.
  96
  97 vsyscall
  98 ========
  99
 100 vsyscall calling sequence matches the syscall calling sequence, with the
 101 following differences. Some vsyscalls may have different calling sequences.
 102
 103 Parameters and return value
 104 ---------------------------
 105 r0 is not used as an input. The vsyscall is selected by its address.
 106
 107 Stack
 108 -----
 109 The vsyscall may or may not use the caller's stack frame save areas.
 110
 111 Register preservation rules
 112 ---------------------------
 113
 114 =========== ========
 115 r0          Volatile
 116 cr1, cr5-7  Volatile
 117 lr          Volatile
 118 =========== ========
 119
 120 Invocation
 121 ----------
 122 The vsyscall is performed with a branch-with-link instruction to the vsyscall
 123 function address.
 124
 125 Transactional Memory
 126 --------------------
 127 vsyscalls will run in the same transactional state as the caller. A vsyscall
 128 may or may not result in the transaction being doomed by hardware.