ptrace(2) man page
A message that is not in the archive (sent off-list or not yet received): 20130417113933.GA11499@osiris
Hello Heiko,
Quoted 10 lines · Heiko Carstens
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.
Quoted 7 lines
In the kernel at least powerpc has
Documentation/powerpc/ptrace.txtwhich 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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): CAKgNAkgNWcgO=0hkn2pytk6MZ40vE=vN1T6JJ6rEvt53kW9-tw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org
Quoted 10 lines · Michael Kerrisk (man-pages)
Hello Heiko,
Quoted 5 lines · 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>?
Quoted 4 lines
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.
Quoted 3 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): 878v48htoh.fsf-MJW0/[email protected]
Quoted 6 lines · Andreas Arnez
Quoted 6 lines
On Wed, Apr 17, 2013 at 1:39 PM, Heiko Carstens
Quoted 4 lines
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>?
Quoted 8 lines
Quoted 4 lines
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.
Quoted 14 lines
And all the
architecture-specific ptrace requests could be explained.Quoted 3 lines
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?
Quoted 4 lines · Heiko Carstens
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?"
Quoted 2 lines
Quoted 2 lines
Especially the _exact_ semantics of each ptrace command including all data structures etc. are missing.
Can you be more specific?
Signature · 6 lines
vda -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html