1============================ 2Kernel-provided User Helpers 3============================ 4 5These are segment of kernel provided user code reachable from user space 6at a fixed address in kernel memory. This is used to provide user space 7with some operations which require kernel help because of unimplemented 8native feature and/or instructions in many ARM CPUs. The idea is for this 9code to be executed directly in user mode for best efficiency but which is 10too intimate with the kernel counter part to be left to user libraries. 11In fact this code might even differ from one CPU to another depending on 12the available instruction set, or whether it is a SMP systems. In other 13words, the kernel reserves the right to change this code as needed without 14warning. Only the entry points and their results as documented here are 15guaranteed to be stable. 16 17This is different from (but doesn't preclude) a full blown VDSO 18implementation, however a VDSO would prevent some assembly tricks with 19constants that allows for efficient branching to those code segments. And 20since those code segments only use a few cycles before returning to user 21code, the overhead of a VDSO indirect far call would add a measurable 22overhead to such minimalistic operations. 23 24User space is expected to bypass those helpers and implement those things 25inline (either in the code emitted directly by the compiler, or part of 26the implementation of a library call) when optimizing for a recent enough 27processor that has the necessary native support, but only if resulting 28binaries are already to be incompatible with earlier ARM processors due to 29usage of similar native instructions for other things. In other words 30don't make binaries unable to run on earlier processors just for the sake 31of not using these kernel helpers if your compiled code is not going to 32use new instructions for other purpose. 33 34New helpers may be added over time, so an older kernel may be missing some 35helpers present in a newer kernel. For this reason, programs must check 36the value of __kuser_helper_version (see below) before assuming that it is 37safe to call any particular helper. This check should ideally be 38performed only once at process startup time, and execution aborted early 39if the required helpers are not provided by the kernel version that 40process is running on. 41 42kuser_helper_version 43-------------------- 44 45Location: 0xffff0ffc 46 47Reference declaration:: 48 49 extern int32_t __kuser_helper_version; 50 51Definition: 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 57Usage 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 69Notes: 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 76kuser_get_tls 77------------- 78 79Location: 0xffff0fe0 80 81Reference prototype:: 82 83 void * __kuser_get_tls(void); 84 85Input: 86 87 lr = return address 88 89Output: 90 91 r0 = TLS value 92 93Clobbered registers: 94 95 none 96 97Definition: 98 99 Get the TLS value as previously set via the __ARM_NR_set_tls syscall. 100 101Usage 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 112Notes: 113 114 - Valid only if __kuser_helper_version >= 1 (from kernel version 2.6.12). 115 116kuser_cmpxchg 117------------- 118 119Location: 0xffff0fc0 120 121Reference prototype:: 122 123 int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); 124 125Input: 126 127 r0 = oldval 128 r1 = newval 129 r2 = ptr 130 lr = return address 131 132Output: 133 134 r0 = success code (zero or non-zero) 135 C flag = set if r0 == 0, clear if r0 != 0 136 137Clobbered registers: 138 139 r3, ip, flags 140 141Definition: 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 148Usage 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 165Notes: 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 171kuser_memory_barrier 172-------------------- 173 174Location: 0xffff0fa0 175 176Reference prototype:: 177 178 void __kuser_memory_barrier(void); 179 180Input: 181 182 lr = return address 183 184Output: 185 186 none 187 188Clobbered registers: 189 190 none 191 192Definition: 193 194 Apply any needed memory barrier to preserve consistency with data modified 195 manually and __kuser_cmpxchg usage. 196 197Usage example:: 198 199 typedef void (__kuser_dmb_t)(void); 200 #define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) 201 202Notes: 203 204 - Valid only if __kuser_helper_version >= 3 (from kernel version 2.6.15). 205 206kuser_cmpxchg64 207--------------- 208 209Location: 0xffff0f60 210 211Reference prototype:: 212 213 int __kuser_cmpxchg64(const int64_t *oldval, 214 const int64_t *newval, 215 volatile int64_t *ptr); 216 217Input: 218 219 r0 = pointer to oldval 220 r1 = pointer to newval 221 r2 = pointer to target value 222 lr = return address 223 224Output: 225 226 r0 = success code (zero or non-zero) 227 C flag = set if r0 == 0, clear if r0 != 0 228 229Clobbered registers: 230 231 r3, lr, flags 232 233Definition: 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 242Usage 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 261Notes: 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). 269