Documentation/powerpc/syscall64-abi.rst

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