Documentation/arm/kernel_user_helpers.rst

   1 ============================
   2 Kernel-provided User Helpers
   3 ============================
   4
   5 These are segment of kernel provided user code reachable from user space
   6 at a fixed address in kernel memory.  This is used to provide user space
   7 with some operations which require kernel help because of unimplemented
   8 native feature and/or instructions in many ARM CPUs. The idea is for this
   9 code to be executed directly in user mode for best efficiency but which is
  10 too intimate with the kernel counter part to be left to user libraries.
  11 In fact this code might even differ from one CPU to another depending on
  12 the available instruction set, or whether it is a SMP systems. In other
  13 words, the kernel reserves the right to change this code as needed without
  14 warning. Only the entry points and their results as documented here are
  15 guaranteed to be stable.
  16
  17 This is different from (but doesn't preclude) a full blown VDSO
  18 implementation, however a VDSO would prevent some assembly tricks with
  19 constants that allows for efficient branching to those code segments. And
  20 since those code segments only use a few cycles before returning to user
  21 code, the overhead of a VDSO indirect far call would add a measurable
  22 overhead to such minimalistic operations.
  23
  24 User space is expected to bypass those helpers and implement those things
  25 inline (either in the code emitted directly by the compiler, or part of
  26 the implementation of a library call) when optimizing for a recent enough
  27 processor that has the necessary native support, but only if resulting
  28 binaries are already to be incompatible with earlier ARM processors due to
  29 usage of similar native instructions for other things.  In other words
  30 don't make binaries unable to run on earlier processors just for the sake
  31 of not using these kernel helpers if your compiled code is not going to
  32 use new instructions for other purpose.
  33
  34 New helpers may be added over time, so an older kernel may be missing some
  35 helpers present in a newer kernel.  For this reason, programs must check
  36 the value of __kuser_helper_version (see below) before assuming that it is
  37 safe to call any particular helper.  This check should ideally be
  38 performed only once at process startup time, and execution aborted early
  39 if the required helpers are not provided by the kernel version that
  40 process is running on.
  41
  42 kuser_helper_version
  43 --------------------
  44
  45 Location:       0xffff0ffc
  46
  47 Reference declaration::
  48
  49   extern int32_t __kuser_helper_version;
  50
  51 Definition:
  52
  53   This field contains the number of helpers being implemented by the
  54   running kernel.  User space may read this to determine the availability
  55   of a particular helper.
  56
  57 Usage example::
  58
  59   #define __kuser_helper_version (*(int32_t *)0xffff0ffc)
  60
  61   void check_kuser_version(void)
  62   {
  63         if (__kuser_helper_version < 2) {
  64                 fprintf(stderr, "can't do atomic operations, kernel too old\n");
  65                 abort();
  66         }
  67   }
  68
  69 Notes:
  70
  71   User space may assume that the value of this field never changes
  72   during the lifetime of any single process.  This means that this
  73   field can be read once during the initialisation of a library or
  74   startup phase of a program.
  75
  76 kuser_get_tls
  77 -------------
  78
  79 Location:       0xffff0fe0
  80
  81 Reference prototype::
  82
  83   void * __kuser_get_tls(void);
  84
  85 Input:
  86
  87   lr = return address
  88
  89 Output:
  90
  91   r0 = TLS value
  92
  93 Clobbered registers:
  94
  95   none
  96
  97 Definition:
  98
  99   Get the TLS value as previously set via the __ARM_NR_set_tls syscall.
 100
 101 Usage example::
 102
 103   typedef void * (__kuser_get_tls_t)(void);
 104   #define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0)
 105
 106   void foo()
 107   {
 108         void *tls = __kuser_get_tls();
 109         printf("TLS = %p\n", tls);
 110   }
 111
 112 Notes:
 113
 114   - Valid only if __kuser_helper_version >= 1 (from kernel version 2.6.12).
 115
 116 kuser_cmpxchg
 117 -------------
 118
 119 Location:       0xffff0fc0
 120
 121 Reference prototype::
 122
 123   int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr);
 124
 125 Input:
 126
 127   r0 = oldval
 128   r1 = newval
 129   r2 = ptr
 130   lr = return address
 131
 132 Output:
 133
 134   r0 = success code (zero or non-zero)
 135   C flag = set if r0 == 0, clear if r0 != 0
 136
 137 Clobbered registers:
 138
 139   r3, ip, flags
 140
 141 Definition:
 142
 143   Atomically store newval in `*ptr` only if `*ptr` is equal to oldval.
 144   Return zero if `*ptr` was changed or non-zero if no exchange happened.
 145   The C flag is also set if `*ptr` was changed to allow for assembly
 146   optimization in the calling code.
 147
 148 Usage example::
 149
 150   typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr);
 151   #define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0)
 152
 153   int atomic_add(volatile int *ptr, int val)
 154   {
 155         int old, new;
 156
 157         do {
 158                 old = *ptr;
 159                 new = old + val;
 160         } while(__kuser_cmpxchg(old, new, ptr));
 161
 162         return new;
 163   }
 164
 165 Notes:
 166
 167   - This routine already includes memory barriers as needed.
 168
 169   - Valid only if __kuser_helper_version >= 2 (from kernel version 2.6.12).
 170
 171 kuser_memory_barrier
 172 --------------------
 173
 174 Location:       0xffff0fa0
 175
 176 Reference prototype::
 177
 178   void __kuser_memory_barrier(void);
 179
 180 Input:
 181
 182   lr = return address
 183
 184 Output:
 185
 186   none
 187
 188 Clobbered registers:
 189
 190   none
 191
 192 Definition:
 193
 194   Apply any needed memory barrier to preserve consistency with data modified
 195   manually and __kuser_cmpxchg usage.
 196
 197 Usage example::
 198
 199   typedef void (__kuser_dmb_t)(void);
 200   #define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0)
 201
 202 Notes:
 203
 204   - Valid only if __kuser_helper_version >= 3 (from kernel version 2.6.15).
 205
 206 kuser_cmpxchg64
 207 ---------------
 208
 209 Location:       0xffff0f60
 210
 211 Reference prototype::
 212
 213   int __kuser_cmpxchg64(const int64_t *oldval,
 214                         const int64_t *newval,
 215                         volatile int64_t *ptr);
 216
 217 Input:
 218
 219   r0 = pointer to oldval
 220   r1 = pointer to newval
 221   r2 = pointer to target value
 222   lr = return address
 223
 224 Output:
 225
 226   r0 = success code (zero or non-zero)
 227   C flag = set if r0 == 0, clear if r0 != 0
 228
 229 Clobbered registers:
 230
 231   r3, lr, flags
 232
 233 Definition:
 234
 235   Atomically store the 64-bit value pointed by `*newval` in `*ptr` only if `*ptr`
 236   is equal to the 64-bit value pointed by `*oldval`.  Return zero if `*ptr` was
 237   changed or non-zero if no exchange happened.
 238
 239   The C flag is also set if `*ptr` was changed to allow for assembly
 240   optimization in the calling code.
 241
 242 Usage example::
 243
 244   typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval,
 245                                     const int64_t *newval,
 246                                     volatile int64_t *ptr);
 247   #define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60)
 248
 249   int64_t atomic_add64(volatile int64_t *ptr, int64_t val)
 250   {
 251         int64_t old, new;
 252
 253         do {
 254                 old = *ptr;
 255                 new = old + val;
 256         } while(__kuser_cmpxchg64(&old, &new, ptr));
 257
 258         return new;
 259   }
 260
 261 Notes:
 262
 263   - This routine already includes memory barriers as needed.
 264
 265   - Due to the length of this sequence, this spans 2 conventional kuser
 266     "slots", therefore 0xffff0f80 is not used as a valid entry point.
 267
 268   - Valid only if __kuser_helper_version >= 5 (from kernel version 3.1).