1 .\" Written by Mike Frysinger <vapier@gentoo.org>
3 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
4 .\" This page is in the public domain.
8 .\" http://articles.manugarg.com/systemcallinlinux2_6.html
9 .\" https://lwn.net/Articles/446528/
10 .\" http://www.linuxjournal.com/content/creating-vdso-colonels-other-chicken
11 .\" http://www.trilithium.com/johan/2005/08/linux-gate/
13 .TH VDSO 7 2015-12-28 "Linux" "Linux Programmer's Manual"
15 vdso \- overview of the virtual ELF dynamic shared object
17 .B #include <sys/auxv.h>
19 .B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR);
21 The "vDSO" (virtual dynamic shared object) is a small shared library that
22 the kernel automatically maps into the
23 address space of all user-space applications.
24 Applications usually do not need to concern themselves with these details
25 as the vDSO is most commonly called by the C library.
26 This way you can code in the normal way using standard functions
27 and the C library will take care
28 of using any functionality that is available via the vDSO.
30 Why does the vDSO exist at all?
31 There are some system calls the kernel provides that
32 user-space code ends up using frequently,
33 to the point that such calls can dominate overall performance.
34 This is due both to the frequency of the call as well as the
35 context-switch overhead that results
36 from exiting user space and entering the kernel.
38 The rest of this documentation is geared toward the curious and/or
39 C library writers rather than general developers.
40 If you're trying to call the vDSO in your own application rather than using
41 the C library, you're most likely doing it wrong.
42 .SS Example background
43 Making system calls can be slow.
44 In x86 32-bit systems, you can trigger a software interrupt
46 to tell the kernel you wish to make a system call.
47 However, this instruction is expensive: it goes through
48 the full interrupt-handling paths
49 in the processor's microcode as well as in the kernel.
50 Newer processors have faster (but backward incompatible) instructions to
51 initiate system calls.
52 Rather than require the C library to figure out if this functionality is
53 available at run time,
54 the C library can use functions provided by the kernel in
57 Note that the terminology can be confusing.
58 On x86 systems, the vDSO function
59 used to determine the preferred method of making a system call is
60 named "__kernel_vsyscall", but on x86_64,
61 the term "vsyscall" also refers to an obsolete way to ask the kernel
62 what time it is or what CPU the caller is on.
64 One frequently used system call is
66 This system call is called both directly by user-space applications
67 as well as indirectly by
69 Think timestamps or timing loops or polling\(emall of these
70 frequently need to know what time it is right now.
71 This information is also not secret\(emany application in any
72 privilege mode (root or any unprivileged user) will get the same answer.
73 Thus the kernel arranges for the information required to answer
74 this question to be placed in memory the process can access.
77 changes from a system call to a normal function
78 call and a few memory accesses.
80 The base address of the vDSO (if one exists) is passed by the kernel to
81 each program in the initial auxiliary vector (see
87 You must not assume the vDSO is mapped at any particular location in the
89 The base address will usually be randomized at run time every time a new
90 process image is created (at
93 This is done for security reasons,
94 to prevent "return-to-libc" attacks.
96 For some architectures, there is also an
99 This is used only for locating the vsyscall entry point and is frequently
100 omitted or set to 0 (meaning it's not available).
101 This tag is a throwback to the initial vDSO work (see
103 below) and its use should be avoided.
105 Since the vDSO is a fully formed ELF image, you can do symbol lookups on it.
106 This allows new symbols to be added with newer kernel releases,
107 and allows the C library to detect available functionality at
108 run time when running under different kernel versions.
109 Oftentimes the C library will do detection with the first call and then
110 cache the result for subsequent calls.
112 All symbols are also versioned (using the GNU version format).
113 This allows the kernel to update the function signature without breaking
114 backward compatibility.
115 This means changing the arguments that the function accepts as well as the
117 Thus, when looking up a symbol in the vDSO,
118 you must always include the version
119 to match the ABI you expect.
121 Typically the vDSO follows the naming convention of prefixing
122 all symbols with "__vdso_" or "__kernel_"
123 so as to distinguish them from other standard symbols.
124 For example, the "gettimeofday" function is named "__vdso_gettimeofday".
126 You use the standard C calling conventions when calling
127 any of these functions.
128 No need to worry about weird register or stack behavior.
131 When you compile the kernel,
132 it will automatically compile and link the vDSO code for you.
133 You will frequently find it under the architecture-specific directory:
135 find arch/$ARCH/ -name '*vdso*.so*' -o -name '*gate*.so*'
138 The name of the vDSO varies across architectures.
139 It will often show up in things like glibc's
142 The exact name should not matter to any code, so do not hardcode it.
150 aarch64 linux-vdso.so.1
153 ppc/32 linux-vdso32.so.1
154 ppc/64 linux-vdso64.so.1
155 s390 linux-vdso32.so.1
156 s390x linux-vdso64.so.1
159 x86_64 linux-vdso.so.1
160 x86/x32 linux-vdso.so.1
166 .SS strace(1) and the vDSO
167 When tracing systems calls with
169 symbols (system calls) that are exported by the vDSO will
171 appear in the trace output.
172 .SH ARCHITECTURE-SPECIFIC NOTES
173 The subsections below provide architecture-specific notes
176 Note that the vDSO that is used is based on the ABI of your user-space code
177 and not the ABI of the kernel.
179 when you run an i386 32-bit ELF binary,
180 you'll get the same vDSO regardless of whether you run it under
181 an i386 32-bit kernel or under an x86_64 64-bit kernel.
182 Therefore, the name of the user-space ABI should be used to determine
183 which of the sections below is relevant.
185 .\" See linux/arch/arm/vdso/vdso.lds.S
186 .\" Commit: 8512287a8165592466cb9cb347ba94892e9c56a5
187 The table below lists the symbols exported by the vDSO.
195 __vdso_gettimeofday LINUX_2.6 (exported since Linux 4.1)
196 __vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1)
203 .\" See linux/arch/arm/kernel/entry-armv.S
204 .\" See linux/Documentation/arm/kernel_user_helpers.txt
205 Additionally, the ARM port has a code page full of utility functions.
206 Since it's just a raw page of code, there is no ELF information for doing
207 symbol lookups or versioning.
208 It does provide support for different versions though.
210 For information on this code page,
211 it's best to refer to the kernel documentation
212 as it's extremely detailed and covers everything you need to know:
213 .IR Documentation/arm/kernel_user_helpers.txt .
214 .SS aarch64 functions
215 .\" See linux/arch/arm64/kernel/vdso/vdso.lds.S
216 The table below lists the symbols exported by the vDSO.
224 __kernel_rt_sigreturn LINUX_2.6.39
225 __kernel_gettimeofday LINUX_2.6.39
226 __kernel_clock_gettime LINUX_2.6.39
227 __kernel_clock_getres LINUX_2.6.39
233 .SS bfin (Blackfin) functions
234 .\" See linux/arch/blackfin/kernel/fixed_code.S
235 .\" See http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:fixed-code
236 As this CPU lacks a memory management unit (MMU),
237 it doesn't set up a vDSO in the normal sense.
238 Instead, it maps at boot time a few raw functions into
239 a fixed location in memory.
240 User-space applications then call directly into that region.
241 There is no provision for backward compatibility
242 beyond sniffing raw opcodes,
243 but as this is an embedded CPU, it can get away with things\(emsome of the
244 object formats it runs aren't even ELF based (they're bFLT/FLAT).
246 For information on this code page,
247 it's best to refer to the public documentation:
249 http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:fixed-code
250 .SS ia64 (Itanium) functions
251 .\" See linux/arch/ia64/kernel/gate.lds.S
252 .\" Also linux/arch/ia64/kernel/fsys.S and linux/Documentation/ia64/fsys.txt
253 The table below lists the symbols exported by the vDSO.
261 __kernel_sigtramp LINUX_2.5
262 __kernel_syscall_via_break LINUX_2.5
263 __kernel_syscall_via_epc LINUX_2.5
270 The Itanium port is somewhat tricky.
271 In addition to the vDSO above, it also has "light-weight system calls"
272 (also known as "fast syscalls" or "fsys").
273 You can invoke these via the
274 .I __kernel_syscall_via_epc
276 The system calls listed here have the same semantics as if you called them
279 so refer to the relevant
280 documentation for each.
281 The table below lists the functions available via this mechanism.
300 .SS parisc (hppa) functions
301 .\" See linux/arch/parisc/kernel/syscall.S
302 .\" See linux/Documentation/parisc/registers
303 The parisc port has a code page full of utility functions
304 called a gateway page.
305 Rather than use the normal ELF auxiliary vector approach,
306 it passes the address of
307 the page to the process via the SR2 register.
308 The permissions on the page are such that merely executing those addresses
309 automatically executes with kernel privileges and not in user space.
310 This is done to match the way HP-UX works.
312 Since it's just a raw page of code, there is no ELF information for doing
313 symbol lookups or versioning.
314 Simply call into the appropriate offset via the branch instruction,
317 ble <offset>(%sr2, %r0)
326 00e0 set_thread_pointer
327 0100 linux_gateway_entry (syscall)
332 03a0 tracesys_sigexit
336 03e4 lws_compare_and_swap64
337 03e8 lws_compare_and_swap
346 .\" See linux/arch/powerpc/kernel/vdso32/vdso32.lds.S
347 The table below lists the symbols exported by the vDSO.
348 The functions marked with a
350 are available only when the kernel is
351 a PowerPC64 (64-bit) kernel.
359 __kernel_clock_getres LINUX_2.6.15
360 __kernel_clock_gettime LINUX_2.6.15
361 __kernel_datapage_offset LINUX_2.6.15
362 __kernel_get_syscall_map LINUX_2.6.15
363 __kernel_get_tbfreq LINUX_2.6.15
364 __kernel_getcpu \fI*\fR LINUX_2.6.15
365 __kernel_gettimeofday LINUX_2.6.15
366 __kernel_sigtramp_rt32 LINUX_2.6.15
367 __kernel_sigtramp32 LINUX_2.6.15
368 __kernel_sync_dicache LINUX_2.6.15
369 __kernel_sync_dicache_p5 LINUX_2.6.15
376 .\" See linux/arch/powerpc/kernel/vdso64/vdso64.lds.S
377 The table below lists the symbols exported by the vDSO.
385 __kernel_clock_getres LINUX_2.6.15
386 __kernel_clock_gettime LINUX_2.6.15
387 __kernel_datapage_offset LINUX_2.6.15
388 __kernel_get_syscall_map LINUX_2.6.15
389 __kernel_get_tbfreq LINUX_2.6.15
390 __kernel_getcpu LINUX_2.6.15
391 __kernel_gettimeofday LINUX_2.6.15
392 __kernel_sigtramp_rt64 LINUX_2.6.15
393 __kernel_sync_dicache LINUX_2.6.15
394 __kernel_sync_dicache_p5 LINUX_2.6.15
401 .\" See linux/arch/s390/kernel/vdso32/vdso32.lds.S
402 The table below lists the symbols exported by the vDSO.
410 __kernel_clock_getres LINUX_2.6.29
411 __kernel_clock_gettime LINUX_2.6.29
412 __kernel_gettimeofday LINUX_2.6.29
419 .\" See linux/arch/s390/kernel/vdso64/vdso64.lds.S
420 The table below lists the symbols exported by the vDSO.
428 __kernel_clock_getres LINUX_2.6.29
429 __kernel_clock_gettime LINUX_2.6.29
430 __kernel_gettimeofday LINUX_2.6.29
436 .SS sh (SuperH) functions
437 .\" See linux/arch/sh/kernel/vsyscall/vsyscall.lds.S
438 The table below lists the symbols exported by the vDSO.
446 __kernel_rt_sigreturn LINUX_2.6
447 __kernel_sigreturn LINUX_2.6
448 __kernel_vsyscall LINUX_2.6
455 .\" See linux/arch/x86/vdso/vdso32/vdso32.lds.S
456 The table below lists the symbols exported by the vDSO.
464 __kernel_sigreturn LINUX_2.5
465 __kernel_rt_sigreturn LINUX_2.5
466 __kernel_vsyscall LINUX_2.5
467 .\" Added in 7a59ed415f5b57469e22e41fc4188d5399e0b194 and updated
468 .\" in 37c975545ec63320789962bf307f000f08fabd48.
469 __vdso_clock_gettime LINUX_2.6 (exported since Linux 3.15)
470 __vdso_gettimeofday LINUX_2.6 (exported since Linux 3.15)
471 __vdso_time LINUX_2.6 (exported since Linux 3.15)
478 .\" See linux/arch/x86/vdso/vdso.lds.S
479 The table below lists the symbols exported by the vDSO.
480 All of these symbols are also available without the "__vdso_" prefix, but
481 you should ignore those and stick to the names below.
489 __vdso_clock_gettime LINUX_2.6
490 __vdso_getcpu LINUX_2.6
491 __vdso_gettimeofday LINUX_2.6
492 __vdso_time LINUX_2.6
498 .SS x86/x32 functions
499 .\" See linux/arch/x86/vdso/vdso32.lds.S
500 The table below lists the symbols exported by the vDSO.
508 __vdso_clock_gettime LINUX_2.6
509 __vdso_getcpu LINUX_2.6
510 __vdso_gettimeofday LINUX_2.6
511 __vdso_time LINUX_2.6
518 The vDSO was originally just a single function\(emthe vsyscall.
519 In older kernels, you might see that name
520 in a process's memory map rather than "vdso".
521 Over time, people realized that this mechanism
522 was a great way to pass more functionality
523 to user space, so it was reconceived as a vDSO in the current format.
529 The documents, examples, and source code in the Linux source code tree:
533 Documentation/ABI/stable/vdso
534 Documentation/ia64/fsys.txt
535 Documentation/vDSO/* (includes examples of using the vDSO)
537 find arch/ -iname '*vdso*' -o -iname '*gate*'