Re: ptrace(2) man page

Re: ptrace(2) man page

[Michael Kerrisk (man-pages)]

Hello Heiko,

On Wed, Apr 17, 2013 at 1:39 PM, Heiko Carstens
<heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> Hi Michael,
>
> we are just wondering where we should document the s390 specific ptrace
> interface.
> The natural answer seems to be "in the man page", however when reading the
> ptrace(2) man page it hardly mentions any architecture dependent details.
>
> Especially the _exact_ semantics of each ptrace command including all data
> structures etc. are missing.
>
> In the kernel at least powerpc has Documentation/powerpc/ptrace.txt which
> seems to go into detail.
>
> So, what do you think? Should these architecture specific details go
> into the ptrace(2) man page?
> Or somewhere else? Like e.g. Documentation/<arch>/ptrace.txt in the kernel?
> Or maybe an arch specific "sub" man page like e.g. ptrace.<arch>?

I am not sure, mainly because I am not familiar with the extent of the
architecture-specific variation in ptrace(2). I do see that there is
just a very little arch-specific detail in the man page (x86, SPARC).
I am not (yet) sure of the way forward. I have CCed Denys Vlasenko,
since in recent times he has done a lot of work on this page, and I
assume has a lot of familiarity with the various arch-specific
details. Perhaps he has an opinion.

Cheers,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: ptrace(2) man page

[Andreas Arnez]

"Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> Hello Heiko,
>
> On Wed, Apr 17, 2013 at 1:39 PM, Heiko Carstens
> <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
>> ...
>> So, what do you think? Should these architecture specific details go
>> into the ptrace(2) man page?
>> Or somewhere else? Like e.g. Documentation/<arch>/ptrace.txt in the kernel?
>> Or maybe an arch specific "sub" man page like e.g. ptrace.<arch>?
>
> I am not sure, mainly because I am not familiar with the extent of the
> architecture-specific variation in ptrace(2). I do see that there is
> just a very little arch-specific detail in the man page (x86, SPARC).
> I am not (yet) sure of the way forward.

Per architecture there would potentially be a few hundred lines of
additional documentation.  For example, the various register sets could
be enumerated and their layout summarized.  And all the
architecture-specific ptrace requests could be explained.

> I have CCed Denys Vlasenko, since in recent times he has done a lot of
> work on this page, and I assume has a lot of familiarity with the
> various arch-specific details. Perhaps he has an opinion.

Denys, do you have an opinion?

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: ptrace(2) man page

[Denys Vlasenko]

On 04/24/2013 04:47 PM, Andreas Arnez wrote:
>> On Wed, Apr 17, 2013 at 1:39 PM, Heiko Carstens
>>> So, what do you think? Should these architecture specific details go
>>> into the ptrace(2) man page?
>>> Or somewhere else? Like e.g. Documentation/<arch>/ptrace.txt in the kernel?
>>> Or maybe an arch specific "sub" man page like e.g. ptrace.<arch>?
>>
>> I am not sure, mainly because I am not familiar with the extent of the
>> architecture-specific variation in ptrace(2). I do see that there is
>> just a very little arch-specific detail in the man page (x86, SPARC).
>> I am not (yet) sure of the way forward.
> 
> Per architecture there would potentially be a few hundred lines of
> additional documentation.  For example, the various register sets could
> be enumerated and their layout summarized.

I would add this information only after someone asks for it.
That is, if there is a demonstrated interest in having it documented.

> And all the
> architecture-specific ptrace requests could be explained.
> 
>> I have CCed Denys Vlasenko, since in recent times he has done a lot of
>> work on this page, and I assume has a lot of familiarity with the
>> various arch-specific details. Perhaps he has an opinion.
> 
> Denys, do you have an opinion?

> On Wed, Apr 17, 2013 at 1:39 PM, Heiko Carstens wrote:
>> we are just wondering where we should document the s390 specific ptrace
>> interface.
>> The natural answer seems to be "in the man page", however when reading the
>> ptrace(2) man page it hardly mentions any architecture dependent details.

I think that creating a S390 subsection in ptrace manpage and putting
information there is not a bad idea. This way all the info stays in one,
easily accessible place. (The downside is that modifying it is a PITA.)

I just think you should be reasonably terse while doing so.
Don't painstakingly describe those parts which are obvious.
For example, documenting PTRACE_POKEUSER / PTRACE_PEEKUSER's structure
can be done this way:

"""
struct user_offsets {
	uint64_t psw_mask;
	uint64_t psw_addr;
	uint64_t gpr0;	/* General purpose register #0 */
	uint64_t gpr1;	/* General purpose register #1 */
	uint64_t gpr2;	/* General purpose register #2 */
	uint64_t gpr3;	/* General purpose register #3 */
	uint64_t gpr4;	/* General purpose register #4 */
	uint64_t gpr5;	/* General purpose register #5 */
	uint64_t gpr6;	/* General purpose register #6 */
	uint64_t gpr7;	/* General purpose register #7 */
	uint64_t gpr8;	/* General purpose register #8 */
	uint64_t gpr9;	/* General purpose register #9 */
	uint64_t gpr10;	/* General purpose register #10 */
	uint64_t gpr11;	/* General purpose register #11 */
	uint64_t gpr12;	/* General purpose register #12 */
	uint64_t gpr13;	/* General purpose register #13 */
	uint64_t gpr14;	/* General purpose register #14 */
	uint64_t gpr15;	/* General purpose register #15 */
...
}
"""

but it's probably not a good idea. Use common sense. Compress
the explanation to a more manageable size.

Maybe even ask yourself "did anyone ask for PTRACE_PEEKUSER layout yet?
Do we really need to document it? Maybe people find this info
in headers / strace source / etc, and are fine as-is?"


>> Especially the _exact_ semantics of each ptrace command including all data
>> structures etc. are missing.

Can you be more specific?

-- 
vda

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html