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@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
