Document x86 machine-specific ptrace(2) requests.

[kib]

Summary

Document x86 requests. List ppc requests for completeness.

[gjb]

Only minor suggestions, but looks good.

lib/libc/sys/ptrace.2

543

'allowed by the OS [...]'

593

'^The buffer [...]'

634

'allows setting the base [...]'

[emaste]

lib/libc/sys/ptrace.2

534

As with

543

also "to use by" is odd.
Maybe allowed by the OS for use by userspace programs although it's still a bit awkward.

582

The kernel

583

The buffer layout

590

The buffer size is

[brueffer]

lib/libc/sys/ptrace.2

566

singular, field

605

segmented?

[kib]

Handled all reviews notes.

[wblock]

These are suggestions, and some are not meant to be literal. Thanks!

lib/libc/sys/ptrace.2

509

Might be better with just
s/Copies out/Copy/

512

No instances of "32bit" in /usr/share/man/man2/*. The standard form appears to be "32-bit". Same for 64: s/64bit/64-bit/.

516

s/32bit/32-bit/

518

s/64bit/64-bit/

527

Might be better as
s/Loads/Load/

530

s/32bit/32-bit/

542

Might be better with:
s/Returns the/Return/

I don't know if "enablement" is a valid word. "enabled state" might be adequate, or it might need to be expanded a bit.

543

"for use by userspace programs" is a bit redundant. This sentence is long and it gets a little vague in the second part.
Are all the extensions reported allows by the OS, or is it two different categories? Maybe:

Report which XSAVE FPU extensions are supported by the CPU
and allowed in userspace programs.

547

s/the variable/a variable/

551

This should either be "The struct ptrace_xstate_info structure is defined..." or remove the "The".

I prefer the second form, just "struct ptrace_xstate_info is defined...", it is less wordy and redundant.

561

s/the bitmask/a bitmask/ (although it could be argued)

562

s/by/in/

576

s/Returns/Return/

579

argument points to the buffer where the content is copied, and the

593

This needs to be specific about what the buffer size is being compared to:

The buffer size must be at least as large as the blahblah struct to hold the x87 FPU and XMM state,

594

s/large/larger/

600

This is a long and potentially confusing sentence. Probably best to break it in at least two, and maybe three sentences.

The buffer must be at least (this big) to hold the x87 FPU and XMM state.
It must not be larger than the value of
.Dv xsave_len
in the
.Vt struct ptrace_xstate_info
returned by the
.Dv PT_GETXSTATE_INFO
​request.

605

s/The request returns/Return/

609

s/the/an/

611

"gets" is a little vague. Maybe

variable where the base value is stored.

617

s/Same/The same/

or even

s/Same as/Like/

621

s/Sets/Set/
s/pointed/pointed to/

624

Might need to split the sentence after "argument", it seems to say a double "pointed to" and is hard to tell what it means.

632

As above, either "The same as" or just "Like".

634

Does it allow it, or is just "sets the base" more accurate?

639

s/Returns/Return/

641

This is layered a little deep:
for the thread

into the buffer
  pointed to
    by the argument

Maybe:

Return the thread's machine state in the buffer pointed to by
.Fa addr .

653

As above:

Set the thread's machine state from the buffer pointed to by
.Fa addr .

660

As a reader, I would immediately ask "Like what?" Another sentence that explains the first would help. We can also eliminate the pause of an "aside" by rewording the sentence:

Other machine-specific requests can also exist.
For example, on certain x86 processors, GOFASTER and WHATISTAKINGSOLONG requests are common.

722

Needs a space between "data" and the paren.

729

Also needs a space, so the paren is not taken as part of the argument.

732

Probably should spell out that "plus".

739

This is another one of those long sentences with a lot of clauses. It could benefit from being split up, but here is an attempt to clarify:

The size (
.Fa data )
provided to the x86-specific
.Dv PT_SETXSTATE
request was either less than the size of the x87 plus XMM save area,
or larger than the size returned in
.Dv xsave_len
in the
.Vt struct ptrace_xstate_info
from the
​.Dv PT_GETXSTATE_INFO
​request.

[kib]

I created another review for the changes requested by wblock, since previous patch was committed and replacing the diff would cause phabricator displaying garbage.

lib/libc/sys/ptrace.2

542

I removed the 'enablement'/'enabled' at all. It seems to be still reasonable, although indeed loose some grain of thought I tried to put.

543

Ok, just took that formulation.

561

I changed this. My understanding was that this is the bitmask which is currently running on the CPU, but I am not native speaker. Russians cannot get articles right even under torment, anyway.

660

The intent there is to say that for _other architectures_, other requests may exist. I.e. there could be another <arch-blah-blah> MACHINE-SPECIFIC REQUESTS sections which are unwritten.

In fact, right now they do not exist, but due to practice of adding ptrace requests without updating the man page, I preferred to keep the original placeholder.