1What:		vDSO
2Date:		July 2011
3KernelVersion:	3.0
4Contact:	Andy Lutomirski <luto@kernel.org>
5Description:
6
7On some architectures, when the kernel loads any userspace program it
8maps an ELF DSO into that program's address space.  This DSO is called
9the vDSO and it often contains useful and highly-optimized alternatives
10to real syscalls.
11
12These functions are called according to your platform's ABI. On many
13platforms they are called just like ordinary C function. On other platforms
14(ex: powerpc) they are called with the same convention as system calls which
15is different from ordinary C functions. Call them from a sensible context.
16(For example, if you set CS on x86 to something strange, the vDSO functions are
17within their rights to crash.)  In addition, if you pass a bad
18pointer to a vDSO function, you might get SIGSEGV instead of -EFAULT.
19
20To find the DSO, parse the auxiliary vector passed to the program's
21entry point.  The AT_SYSINFO_EHDR entry will point to the vDSO.
22
23The vDSO uses symbol versioning; whenever you request a symbol from the
24vDSO, specify the version you are expecting.
25
26Programs that dynamically link to glibc will use the vDSO automatically.
27Otherwise, you can use the reference parser in
28tools/testing/selftests/vDSO/parse_vdso.c.
29
30Unless otherwise noted, the set of symbols with any given version and the
31ABI of those symbols is considered stable.  It may vary across architectures,
32though.
33
34Note:
35 As of this writing, this ABI documentation as been confirmed for x86_64.
36 The maintainers of the other vDSO-using architectures should confirm
37 that it is correct for their architecture.
38