Re: [PATCH manpages 1/2] modify_ldt.2: Overhaul the documentation

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Andy,
On 01/30/2015 03:42 PM, Andy Lutomirski wrote:
> On Jan 30, 2015 8:18 AM, "Michael Kerrisk (man-pages)"
> <mtk.manpages@gmail.com> wrote:
>>
>> Hi Andy,
>>
>> On 01/29/2015 10:47 PM, Andy Lutomirski wrote:
>>> This clarifies the behavior and documents all four functions.
>>
>> Thanks! I've merged this in a branch, pending one or two questions below.
>>
>>> Signed-off-by: Andy Lutomirski <luto@amacapital.net>
>>> ---
>>>  man2/modify_ldt.2 | 101 +++++++++++++++++++++++++++++++++++++++++-------------
>>>  1 file changed, 78 insertions(+), 23 deletions(-)
>>>
>>> diff --git a/man2/modify_ldt.2 b/man2/modify_ldt.2
>>> index d128664716c6..f3cc94d397b3 100644
>>> --- a/man2/modify_ldt.2
>>> +++ b/man2/modify_ldt.2

[...]

>>> +.PP
>>> +The
>>> +.I contents
>>> +field is the segment type (data, expand-down data, non-conforming code, or
>>> +conforming code).  The other fields match their descriptions in the
>>> +CPU manual, although
>>> +.BR modify_ldt ()
>>> +cannot set the accessed bit.
>>
>> The "accessed bit" is mentioned here for the first time. Is this something
>> described in the CPU Manual? If so, we better say that. As it is, I started
>> hunting the rest of this man page for an explanation of this bit, without
>> success.
> 
> Yes, it's in the CPU manual.  Could we say "cannot set the
> hardware-defined accessed bit"?

I made it "the hardware-defined "accessed" bit described in the CPU manual".

[...]

>>> +.PP
>>> +A conforming code segment will be rejected if
>>> +.I
>>> +func
>>> +is 1 or if
>>> +.I seg_not_present
>>> +is 0.
>>
>> It's not clear what a "conforming code segment is". Should some words
>> be added here?
> 
> How about "conforming code segment (i.e. contents == 3)"?

Done.


[...]

>>> +.SH BUGS
>>> +On 64-bit kernels before Linux 3.19, one of the padding bits in
>>
>> Was that commit e30ab185c490e9a9381385529e0fd32f0a399495 ?
> 
> Yes.

Thanks. I dropped that into the page source.

> It could be worth adding a note somewhere that 64-bit kernels define a
> user_desc bit called "lm", but that its only effect is to interfere
> with detection of "empty" descriptors on older kernels.  

So, I changed the text here to:

[[
On 64-bit kernels before Linux 3.19,
.\" commit e30ab185c490e9a9381385529e0fd32f0a399495
setting the "lm" padding bit in
.IR user_desc
prevents the descriptor from being considered empty.
]]

> It may be
> further worth noting somewhere that it is not possible to use
> modify_ldt(2) to install a long mode segment.

Do you want to send a patch? (It would at least need to explain where 
one finds out about "long mode".)

Your revisions are now sitting in the branch at:
http://git.kernel.org/cgit/docs/man-pages/man-pages.git/log/?h=draft_luto

Thanks,

Michael


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