Hi Dave,

On 9 December 2015 at 16:48, Dave Hansen [off-list ref] wrote:

Hi Michael,

Thanks for all the comments!  I'll fix most of it when I post a new
version of the manpage, but I have a few general questions.

On 12/09/2015 03:08 AM, Michael Kerrisk (man-pages) wrote:

quoted

quoted

+is the protection or storage key to assign to the memory.

Why "protection or storage key" here? This phrasing seems a
little ambiguous to me, given that we also have a 'prot'
argument.  I think it would be clearer just to say
"protection key". But maybe I'm missing something.

x86 calls it a "protection key" while powerpc calls it a "storage key".
 They're called "protection keys" consistently inside the kernel.

Should we just stick to one name in the manpages?

Yes. But perhaps you could note the alternate name in the pkey(7) page.

quoted

* A general overview of why this functionality is useful.

Any preference on a central spot to do the general overview?  Does it go
in one of the manpages I'm already modifying, or a new one?

How about we add one more page, pkey(7) that gives the overview and
also summarizes the APIs.

quoted

* A note on which architectures support/will support
  this functionality.

x86 only for now.  We might get powerpc support down the road somewhere.

Supported architectures can be listed in pkey(7).

quoted

* Explanation of what a protection domain is.

A protection domain is a unique view of memory and is represented by the
value in the PKRU register.

Out something about this in pkey(7), but explain what you mean by a
"unique view of memory".

quoted

* Explanation of how a process (thread?) changes its
  protection domain.

Changing protection domains is done by pkey_set() system call, or by
using the WRPKRU instruction.  The system call is preferred and less
error-prone since it enforces that a protection is allocated before its
access protection can be modified.

Details (perhaps not the WRPKRU bit) that should go in pkey(7).

quoted

* Explanation of the relationship between page permission
  bits (PROT_READ/PROT_WRITE/PROTE_EXEC) and
  PKEY_DISABLE_ACCESS and PKEY_DISABLE_WRITE.
  It's still not clear to me. Do the PKEY_* bits
  override the PROT_* bits. Or, something else?

Protection keys add access restrictions in addition to existing page
permissions.  They can only take away access; they never grant
additional access.

This belongs in pkey(7) :-).

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/