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

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

[-- Attachment #1: Type: Text/Plain, Size: 3449 bytes --]

On Wednesday 01 January 2014 14:56:15 Michael Kerrisk (man-pages) wrote:
> .SH DESCRIPTION
> The "vDSO" is a small shared library that
> the kernel automatically maps into the
> address space of all user-space applications.
> Applications usually do not need to concern themselves with these details
> as the vDSO is most commonly called by the C library.
> This way you can code in the normal way using standard functions
> and the C library will take care
> of using any functionality that is available via the vDSO.

seems like sentences in this new version are excessively wrapped.  for 
example, this first one will easily fit into two lines.  is this just due to the 
editing process ?  content changed but things weren't re-wrapped ?  or do you 
not wrap to 80 cols ?  (this is beyond the rule of "wrap to commas and 
periods").

> There are some system calls the kernel provides that
> user space code ends up using frequently,

shouldn't this be "user-space" now ?

> .SH ARCHITECTURE_SPECIFIC NOTES

change the _ to a space ?

> The subsections below provide architecture-specific notes
> on the vDSO.

another example of a sentence easily fitting on one line (there are many)

> Note that the vDSO that is used is based on the ABI of your user-space code
> and not the ABI of the kernel.
> Thus, for example,
> when you run an i386 32-bit ELF binary,
> you'll get the same vDSO regardless of whether you run it under
> an i386 32-bit kernel or under an x86_64 64-bit kernel.
> Thus, the name of the user-space ABI should be used to determine
> which of the sections below is relevant.

having two sentences in a row start with "Thus" is a little funny sounding.  
could change one to "So" and largely be the same.

> The system calls listed here have the same semantics as if you called them
> directly via
> .BR syscall (2),
> so refer to the relevant
> documentation for each.
> The table below lists the functions available via this mechanism.
> .if t \{\
> .ft CW
> \}
> .TS
> l.
> function
> _
> clock_gettime
> getcpu
> getpid
> getppid
> gettimeofday
> set_tid_address
> .TE
> .if t \{\
> .in
> .ft P
> \}

my troff foo is not strong.  this section renders funny for me -- there's three 
blank lines above the table.  do you see the same thing ?

	The  Itanium port is somewhat tricky.  In addition to the vDSO above, it
	also has "light-weight system calls" (also known as "fast syscalls" or
	"fsys").  You can invoke these via the __kernel_syscall_via_epc vDSO
	helper.  The system calls listed here have the same semantics as if you
	called them directly via syscall(2), so refer to the relevant
	documentation for each.  The table below lists the functions available
	via this mechanism.



       function
       ────────────────
       clock_gettime
       getcpu

> .SS parisc (hppa) functions
> .\" See linux/arch/parisc/kernel/syscall.S
> .\" See linux/Documentation/parisc/registers
> The parisc port has a code page full of utility functions
> called a gateway page.
> Rather than use the normal ELF auxiliary vector approach,
> it passes the address of
> the page to the process via the SR2 register.
> The permissions on the page are such that merely executing those addresses
> automatically executes with kernel privileges and not in user-space.

should be "user space" i think.
-mike

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