| blob | de5f300cd219fc535405b2eb66321b3b3147ba56 |
1 '\" t
2 .\" Written by Mike Frysinger <vapier@gentoo.org>
3 .\"
4 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
5 .\" This page is in the public domain.
6 .\" %%%LICENSE_END
7 .\"
8 .\" Useful background:
9 .\" http://articles.manugarg.com/systemcallinlinux2_6.html
10 .\" https://lwn.net/Articles/446528/
11 .\" http://www.linuxjournal.com/content/creating-vdso-colonels-other-chicken
12 .\" http://www.trilithium.com/johan/2005/08/linux-gate/
13 .\"
14 .TH vDSO 7 (date) "Linux man-pages (unreleased)"
15 .SH NAME
16 vdso \- overview of the virtual ELF dynamic shared object
17 .SH SYNOPSIS
18 .nf
19 .B #include <sys/auxv.h>
20 .P
21 .B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR);
22 .fi
23 .SH DESCRIPTION
24 The "vDSO" (virtual dynamic shared object) is a small shared library that
25 the kernel automatically maps into the
26 address space of all user-space applications.
27 Applications usually do not need to concern themselves with these details
28 as the vDSO is most commonly called by the C library.
29 This way you can code in the normal way using standard functions
30 and the C library will take care
31 of using any functionality that is available via the vDSO.
32 .P
33 Why does the vDSO exist at all?
34 There are some system calls the kernel provides that
35 user-space code ends up using frequently,
36 to the point that such calls can dominate overall performance.
37 This is due both to the frequency of the call as well as the
38 context-switch overhead that results
39 from exiting user space and entering the kernel.
40 .P
41 The rest of this documentation is geared toward the curious and/or
42 C library writers rather than general developers.
43 If you're trying to call the vDSO in your own application rather than using
44 the C library, you're most likely doing it wrong.
45 .SS Example background
46 Making system calls can be slow.
47 In x86 32-bit systems, you can trigger a software interrupt
48 .RI ( "int $0x80" )
49 to tell the kernel you wish to make a system call.
50 However, this instruction is expensive: it goes through
51 the full interrupt-handling paths
52 in the processor's microcode as well as in the kernel.
53 Newer processors have faster (but backward incompatible) instructions to
54 initiate system calls.
55 Rather than require the C library to figure out if this functionality is
56 available at run time,
57 the C library can use functions provided by the kernel in
58 the vDSO.
59 .P
60 Note that the terminology can be confusing.
61 On x86 systems, the vDSO function
62 used to determine the preferred method of making a system call is
63 named "__kernel_vsyscall", but on x86-64,
64 the term "vsyscall" also refers to an obsolete way to ask the kernel
65 what time it is or what CPU the caller is on.
66 .P
67 One frequently used system call is
68 .BR gettimeofday (2).
69 This system call is called both directly by user-space applications
70 as well as indirectly by
71 the C library.
72 Think timestamps or timing loops or polling\[em]all of these
73 frequently need to know what time it is right now.
74 This information is also not secret\[em]any application in any
75 privilege mode (root or any unprivileged user) will get the same answer.
76 Thus the kernel arranges for the information required to answer
77 this question to be placed in memory the process can access.
78 Now a call to
79 .BR gettimeofday (2)
80 changes from a system call to a normal function
81 call and a few memory accesses.
82 .SS Finding the vDSO
83 The base address of the vDSO (if one exists) is passed by the kernel to
84 each program in the initial auxiliary vector (see
85 .BR getauxval (3)),
86 via the
87 .B AT_SYSINFO_EHDR
88 tag.
89 .P
90 You must not assume the vDSO is mapped at any particular location in the
91 user's memory map.
92 The base address will usually be randomized at run time every time a new
93 process image is created (at
94 .BR execve (2)
95 time).
96 This is done for security reasons,
97 to prevent "return-to-libc" attacks.
98 .P
99 For some architectures, there is also an
100 .B AT_SYSINFO
101 tag.
102 This is used only for locating the vsyscall entry point and is frequently
103 omitted or set to 0 (meaning it's not available).
104 This tag is a throwback to the initial vDSO work (see
105 .I History
106 below) and its use should be avoided.
107 .SS File format
108 Since the vDSO is a fully formed ELF image, you can do symbol lookups on it.
109 This allows new symbols to be added with newer kernel releases,
110 and allows the C library to detect available functionality at
111 run time when running under different kernel versions.
112 Oftentimes the C library will do detection with the first call and then
113 cache the result for subsequent calls.
114 .P
115 All symbols are also versioned (using the GNU version format).
116 This allows the kernel to update the function signature without breaking
117 backward compatibility.
118 This means changing the arguments that the function accepts as well as the
119 return value.
120 Thus, when looking up a symbol in the vDSO,
121 you must always include the version
122 to match the ABI you expect.
123 .P
124 Typically the vDSO follows the naming convention of prefixing
125 all symbols with "__vdso_" or "__kernel_"
126 so as to distinguish them from other standard symbols.
127 For example, the "gettimeofday" function is named "__vdso_gettimeofday".
128 .P
129 You use the standard C calling conventions when calling
130 any of these functions.
131 No need to worry about weird register or stack behavior.
132 .SH NOTES
133 .SS Source
134 When you compile the kernel,
135 it will automatically compile and link the vDSO code for you.
136 You will frequently find it under the architecture-specific directory:
137 .P
138 .in +4n
139 .EX
140 find arch/$ARCH/ \-name \[aq]*vdso*.so*\[aq] \-o \-name \[aq]*gate*.so*\[aq]
141 .EE
142 .in
143 .\"
144 .SS vDSO names
145 The name of the vDSO varies across architectures.
146 It will often show up in things like glibc's
147 .BR ldd (1)
148 output.
149 The exact name should not matter to any code, so do not hardcode it.
150 .if t \{\
151 .ft CW
152 \}
153 .TS
154 l l.
155 user ABI vDSO name
156 _
157 aarch64 linux\-vdso.so.1
158 arm linux\-vdso.so.1
159 ia64 linux\-gate.so.1
160 mips linux\-vdso.so.1
161 ppc/32 linux\-vdso32.so.1
162 ppc/64 linux\-vdso64.so.1
163 riscv linux\-vdso.so.1
164 s390 linux\-vdso32.so.1
165 s390x linux\-vdso64.so.1
166 sh linux\-gate.so.1
167 i386 linux\-gate.so.1
168 x86-64 linux\-vdso.so.1
169 x86/x32 linux\-vdso.so.1
170 .TE
171 .if t \{\
172 .in
173 .ft P
174 \}
175 .SS strace(1), seccomp(2), and the vDSO
176 When tracing system calls with
177 .BR strace (1),
178 symbols (system calls) that are exported by the vDSO will
179 .I not
180 appear in the trace output.
181 Those system calls will likewise not be visible to
182 .BR seccomp (2)
183 filters.
184 .SH ARCHITECTURE-SPECIFIC NOTES
185 The subsections below provide architecture-specific notes
186 on the vDSO.
187 .P
188 Note that the vDSO that is used is based on the ABI of your user-space code
189 and not the ABI of the kernel.
190 Thus, for example,
191 when you run an i386 32-bit ELF binary,
192 you'll get the same vDSO regardless of whether you run it under
193 an i386 32-bit kernel or under an x86-64 64-bit kernel.
194 Therefore, the name of the user-space ABI should be used to determine
195 which of the sections below is relevant.
196 .SS ARM functions
197 .\" See linux/arch/arm/vdso/vdso.lds.S
198 .\" Commit: 8512287a8165592466cb9cb347ba94892e9c56a5
199 The table below lists the symbols exported by the vDSO.
200 .if t \{\
201 .ft CW
202 \}
203 .TS
204 l l.
205 symbol version
206 _
207 __vdso_gettimeofday LINUX_2.6 (exported since Linux 4.1)
208 __vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1)
209 .TE
210 .if t \{\
211 .in
212 .ft P
213 \}
214 .P
215 .\" See linux/arch/arm/kernel/entry-armv.S
216 .\" See linux/Documentation/arm/kernel_user_helpers.rst
217 Additionally, the ARM port has a code page full of utility functions.
218 Since it's just a raw page of code, there is no ELF information for doing
219 symbol lookups or versioning.
220 It does provide support for different versions though.
221 .P
222 For information on this code page,
223 it's best to refer to the kernel documentation
224 as it's extremely detailed and covers everything you need to know:
225 .IR Documentation/arm/kernel_user_helpers.rst .
226 .SS aarch64 functions
227 .\" See linux/arch/arm64/kernel/vdso/vdso.lds.S
228 The table below lists the symbols exported by the vDSO.
229 .if t \{\
230 .ft CW
231 \}
232 .TS
233 l l.
234 symbol version
235 _
236 __kernel_rt_sigreturn LINUX_2.6.39
237 __kernel_gettimeofday LINUX_2.6.39
238 __kernel_clock_gettime LINUX_2.6.39
239 __kernel_clock_getres LINUX_2.6.39
240 .TE
241 .if t \{\
242 .in
243 .ft P
244 \}
245 .SS bfin (Blackfin) functions (port removed in Linux 4.17)
246 .\" See linux/arch/blackfin/kernel/fixed_code.S
247 .\" See http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:fixed-code
248 As this CPU lacks a memory management unit (MMU),
249 it doesn't set up a vDSO in the normal sense.
250 Instead, it maps at boot time a few raw functions into
251 a fixed location in memory.
252 User-space applications then call directly into that region.
253 There is no provision for backward compatibility
254 beyond sniffing raw opcodes,
255 but as this is an embedded CPU, it can get away with things\[em]some of the
256 object formats it runs aren't even ELF based (they're bFLT/FLAT).
257 .P
258 For information on this code page,
259 it's best to refer to the public documentation:
260 .br
261 http://docs.blackfin.uclinux.org/doku.php?id=linux\-kernel:fixed\-code
262 .SS mips functions
263 .\" See linux/arch/mips/vdso/vdso.ld.S
264 The table below lists the symbols exported by the vDSO.
265 .if t \{\
266 .ft CW
267 \}
268 .TS
269 l l.
270 symbol version
271 _
272 __kernel_gettimeofday LINUX_2.6 (exported since Linux 4.4)
273 __kernel_clock_gettime LINUX_2.6 (exported since Linux 4.4)
274 .TE
275 .if t \{\
276 .in
277 .ft P
278 \}
279 .SS ia64 (Itanium) functions
280 .\" See linux/arch/ia64/kernel/gate.lds.S
281 .\" Also linux/arch/ia64/kernel/fsys.S and linux/Documentation/ia64/fsys.rst
282 The table below lists the symbols exported by the vDSO.
283 .if t \{\
284 .ft CW
285 \}
286 .TS
287 l l.
288 symbol version
289 _
290 __kernel_sigtramp LINUX_2.5
291 __kernel_syscall_via_break LINUX_2.5
292 __kernel_syscall_via_epc LINUX_2.5
293 .TE
294 .if t \{\
295 .in
296 .ft P
297 \}
298 .P
299 The Itanium port is somewhat tricky.
300 In addition to the vDSO above, it also has "light-weight system calls"
301 (also known as "fast syscalls" or "fsys").
302 You can invoke these via the
303 .I __kernel_syscall_via_epc
304 vDSO helper.
305 The system calls listed here have the same semantics as if you called them
306 directly via
307 .BR syscall (2),
308 so refer to the relevant
309 documentation for each.
310 The table below lists the functions available via this mechanism.
311 .if t \{\
312 .ft CW
313 \}
314 .TS
315 l.
316 function
317 _
318 clock_gettime
319 getcpu
320 getpid
321 getppid
322 gettimeofday
323 set_tid_address
324 .TE
325 .if t \{\
326 .in
327 .ft P
328 \}
329 .SS parisc (hppa) functions
330 .\" See linux/arch/parisc/kernel/syscall.S
331 .\" See linux/Documentation/parisc/registers.rst
332 The parisc port has a code page with utility functions
333 called a gateway page.
334 Rather than use the normal ELF auxiliary vector approach,
335 it passes the address of
336 the page to the process via the SR2 register.
337 The permissions on the page are such that merely executing those addresses
338 automatically executes with kernel privileges and not in user space.
339 This is done to match the way HP-UX works.
340 .P
341 Since it's just a raw page of code, there is no ELF information for doing
342 symbol lookups or versioning.
343 Simply call into the appropriate offset via the branch instruction,
344 for example:
345 .P
346 .in +4n
347 .EX
348 ble <offset>(%sr2, %r0)
349 .EE
350 .in
351 .if t \{\
352 .ft CW
353 \}
354 .TS
355 l l.
356 offset function
357 _
358 00b0 lws_entry (CAS operations)
359 00e0 set_thread_pointer (used by glibc)
360 0100 linux_gateway_entry (syscall)
361 .TE
362 .if t \{\
363 .in
364 .ft P
365 \}
366 .SS ppc/32 functions
367 .\" See linux/arch/powerpc/kernel/vdso32/vdso32.lds.S
368 The table below lists the symbols exported by the vDSO.
369 The functions marked with a
370 .I *
371 are available only when the kernel is
372 a PowerPC64 (64-bit) kernel.
373 .if t \{\
374 .ft CW
375 \}
376 .TS
377 l l.
378 symbol version
379 _
380 __kernel_clock_getres LINUX_2.6.15
381 __kernel_clock_gettime LINUX_2.6.15
382 __kernel_clock_gettime64 LINUX_5.11
383 __kernel_datapage_offset LINUX_2.6.15
384 __kernel_get_syscall_map LINUX_2.6.15
385 __kernel_get_tbfreq LINUX_2.6.15
386 __kernel_getcpu \fI*\fR LINUX_2.6.15
387 __kernel_gettimeofday LINUX_2.6.15
388 __kernel_sigtramp_rt32 LINUX_2.6.15
389 __kernel_sigtramp32 LINUX_2.6.15
390 __kernel_sync_dicache LINUX_2.6.15
391 __kernel_sync_dicache_p5 LINUX_2.6.15
392 .TE
393 .if t \{\
394 .in
395 .ft P
396 \}
397 .P
398 Before Linux 5.6,
399 .\" commit 654abc69ef2e69712e6d4e8a6cb9292b97a4aa39
400 the
401 .B CLOCK_REALTIME_COARSE
402 and
403 .B CLOCK_MONOTONIC_COARSE
404 clocks are
405 .I not
406 supported by the
407 .I __kernel_clock_getres
408 and
409 .I __kernel_clock_gettime
410 interfaces;
411 the kernel falls back to the real system call.
412 .SS ppc/64 functions
413 .\" See linux/arch/powerpc/kernel/vdso64/vdso64.lds.S
414 The table below lists the symbols exported by the vDSO.
415 .if t \{\
416 .ft CW
417 \}
418 .TS
419 l l.
420 symbol version
421 _
422 __kernel_clock_getres LINUX_2.6.15
423 __kernel_clock_gettime LINUX_2.6.15
424 __kernel_datapage_offset LINUX_2.6.15
425 __kernel_get_syscall_map LINUX_2.6.15
426 __kernel_get_tbfreq LINUX_2.6.15
427 __kernel_getcpu LINUX_2.6.15
428 __kernel_gettimeofday LINUX_2.6.15
429 __kernel_sigtramp_rt64 LINUX_2.6.15
430 __kernel_sync_dicache LINUX_2.6.15
431 __kernel_sync_dicache_p5 LINUX_2.6.15
432 .TE
433 .if t \{\
434 .in
435 .ft P
436 \}
437 .P
438 Before Linux 4.16,
439 .\" commit 5c929885f1bb4b77f85b1769c49405a0e0f154a1
440 the
441 .B CLOCK_REALTIME_COARSE
442 and
443 .B CLOCK_MONOTONIC_COARSE
444 clocks are
445 .I not
446 supported by the
447 .I __kernel_clock_getres
448 and
449 .I __kernel_clock_gettime
450 interfaces;
451 the kernel falls back to the real system call.
452 .SS riscv functions
453 .\" See linux/arch/riscv/kernel/vdso/vdso.lds.S
454 The table below lists the symbols exported by the vDSO.
455 .if t \{\
456 .ft CW
457 \}
458 .TS
459 l l.
460 symbol version
461 _
462 __vdso_rt_sigreturn LINUX_4.15
463 __vdso_gettimeofday LINUX_4.15
464 __vdso_clock_gettime LINUX_4.15
465 __vdso_clock_getres LINUX_4.15
466 __vdso_getcpu LINUX_4.15
467 __vdso_flush_icache LINUX_4.15
468 .TE
469 .if t \{\
470 .in
471 .ft P
472 \}
473 .SS s390 functions
474 .\" See linux/arch/s390/kernel/vdso32/vdso32.lds.S
475 The table below lists the symbols exported by the vDSO.
476 .if t \{\
477 .ft CW
478 \}
479 .TS
480 l l.
481 symbol version
482 _
483 __kernel_clock_getres LINUX_2.6.29
484 __kernel_clock_gettime LINUX_2.6.29
485 __kernel_gettimeofday LINUX_2.6.29
486 .TE
487 .if t \{\
488 .in
489 .ft P
490 \}
491 .SS s390x functions
492 .\" See linux/arch/s390/kernel/vdso64/vdso64.lds.S
493 The table below lists the symbols exported by the vDSO.
494 .if t \{\
495 .ft CW
496 \}
497 .TS
498 l l.
499 symbol version
500 _
501 __kernel_clock_getres LINUX_2.6.29
502 __kernel_clock_gettime LINUX_2.6.29
503 __kernel_gettimeofday LINUX_2.6.29
504 .TE
505 .if t \{\
506 .in
507 .ft P
508 \}
509 .SS sh (SuperH) functions
510 .\" See linux/arch/sh/kernel/vsyscall/vsyscall.lds.S
511 The table below lists the symbols exported by the vDSO.
512 .if t \{\
513 .ft CW
514 \}
515 .TS
516 l l.
517 symbol version
518 _
519 __kernel_rt_sigreturn LINUX_2.6
520 __kernel_sigreturn LINUX_2.6
521 __kernel_vsyscall LINUX_2.6
522 .TE
523 .if t \{\
524 .in
525 .ft P
526 \}
527 .SS i386 functions
528 .\" See linux/arch/x86/vdso/vdso32/vdso32.lds.S
529 The table below lists the symbols exported by the vDSO.
530 .if t \{\
531 .ft CW
532 \}
533 .TS
534 l l.
535 symbol version
536 _
537 __kernel_sigreturn LINUX_2.5
538 __kernel_rt_sigreturn LINUX_2.5
539 __kernel_vsyscall LINUX_2.5
540 .\" Added in 7a59ed415f5b57469e22e41fc4188d5399e0b194 and updated
541 .\" in 37c975545ec63320789962bf307f000f08fabd48.
542 __vdso_clock_gettime LINUX_2.6 (exported since Linux 3.15)
543 __vdso_gettimeofday LINUX_2.6 (exported since Linux 3.15)
544 __vdso_time LINUX_2.6 (exported since Linux 3.15)
545 .TE
546 .if t \{\
547 .in
548 .ft P
549 \}
550 .SS x86-64 functions
551 .\" See linux/arch/x86/vdso/vdso.lds.S
552 The table below lists the symbols exported by the vDSO.
553 All of these symbols are also available without the "__vdso_" prefix, but
554 you should ignore those and stick to the names below.
555 .if t \{\
556 .ft CW
557 \}
558 .TS
559 l l.
560 symbol version
561 _
562 __vdso_clock_gettime LINUX_2.6
563 __vdso_getcpu LINUX_2.6
564 __vdso_gettimeofday LINUX_2.6
565 __vdso_time LINUX_2.6
566 .TE
567 .if t \{\
568 .in
569 .ft P
570 \}
571 .SS x86/x32 functions
572 .\" See linux/arch/x86/vdso/vdso32.lds.S
573 The table below lists the symbols exported by the vDSO.
574 .if t \{\
575 .ft CW
576 \}
577 .TS
578 l l.
579 symbol version
580 _
581 __vdso_clock_gettime LINUX_2.6
582 __vdso_getcpu LINUX_2.6
583 __vdso_gettimeofday LINUX_2.6
584 __vdso_time LINUX_2.6
585 .TE
586 .if t \{\
587 .in
588 .ft P
589 \}
590 .SS History
591 The vDSO was originally just a single function\[em]the vsyscall.
592 In older kernels, you might see that name
593 in a process's memory map rather than "vdso".
594 Over time, people realized that this mechanism
595 was a great way to pass more functionality
596 to user space, so it was reconceived as a vDSO in the current format.
597 .SH SEE ALSO
598 .BR syscalls (2),
599 .BR getauxval (3),
600 .BR proc (5)
601 .P
602 The documents, examples, and source code in the Linux source code tree:
603 .P
604 .in +4n
605 .EX
606 Documentation/ABI/stable/vdso
607 Documentation/ia64/fsys.rst
608 Documentation/vDSO/* (includes examples of using the vDSO)
609 .P
610 find arch/ \-iname \[aq]*vdso*\[aq] \-o \-iname \[aq]*gate*\[aq]
611 .EE
612 .in