Re: [PATCH v3] vdso(7): new man page

[Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>]

[-- Attachment #1.1: Type: Text/Plain, Size: 3221 bytes --]

On Wednesday 01 January 2014 05:38:20 Michael Kerrisk (man-pages) wrote:
> On 12/31/13 20:41, Mike Frysinger wrote:
> > +The "vDSO" is a small shared library that the kernel automatically maps
> > into the +address space of all user-space applications.
> > +Applications themselves usually need not concern themselves with these
> > details +as the vDSO is most commonly called by the C library.
> > +This way you can write using standard functions and the C library will
> > take care
> 
> After "write" I added "programs". Okay?

you can write libraries too, but i think either wording is fine.  or maybe 
change "write" to "code" ?

> > +of using any available functionality.
> 
> I made this piece:
> 
>     of using any functionality that is available via the vDSO.
> 
> Okay?

np

> > +Why does the vDSO exist at all?
> > +There are some facilities the kernel provides that user space ends up
> > using
> 
> I changed "facilities" to "system calls". Okay?

that wasn't exactly what i was going for, but the nuances are probably lost, 
so it doesn't matter (the vDSO isn't purely a replacement for syscalls).

> > +Note that the terminology can be confusing.
> > +On x86 systems, the vDSO function is named "__kernel_vsyscall", but on
> > x86_64,
> 
> After "function" I added
> 
>     used to determine the preferred method of making a system call is
> 
> Okay?

maybe put in paren ?  either works.

> > Note that the vDSO that is used is based on the ABI of your user-space
> > code and not the ABI of the kernel.
> > i.e. If you run an i386 32-bit ELF under an i386 32-bit kernel or under
> > an x86_64 64-bit kernel, you'll get the same vDSO.
> > So when referring to sections below, use the user-space ABI.
> 
> I still can't make any sense of that last sentence. What are "sections"
> in this context?

"sections" refers to the .SS stuff following this paragraph.  e.g.
	.SS i386 functions
	.SS x86_64 functions
	.SS x86/x32 functions

so if your userspace program is compiled as a 32bit i386 ELF, you should refer 
to the "i386 functions" section even if your kernel is a 64bit x86_64 build.  
but if your userspace program is a 64bit x86_64 program, then refer to the 
x86_64 section.   a single kernel can support many ABIs and execute them 
simultaneously.  but the vDSO that is available is determined by the format of 
your program, not the kernel.

> What does it mean to "*use* the user-space ABI"?

use the userspace ABI as the index into the following sections.

> > +.SS aarch64 functions
> > +.\" See linux/arch/arm64/kernel/vdso/vdso.lds.S
> > +.if t \{\
> > +.ft CW
> > +\}
> > +.TS
> > +l l.
> > +symbol	version
> 
> You don't explicitly say what tables such as the below are about.
> Could you provide me with a sentence to describe them?

i only documented the deviations as they don't follow the vDSO standards (ELF 
object that has dynamic symbol information available).  all the standard ones 
may follow Documentation/ABI/stable/vdso/ and Documentation/vDSO/*.  but i 
guess a one line sentence could be added to each of these telling people to 
look at the kernel's vDSO/ dir for more details.
-mike

[-- Attachment #1.2: 0xB902B5271325F892AC251AD441633B9FE837F581.asc --]
[-- Type: application/pgp-keys, Size: 46825 bytes --]

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]