[Bug tapsets/2111] document syscalls tapset

[Bug tapsets/2111] document syscalls tapset

[mcermak at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

Martin Cermak <mcermak at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |mcermak at redhat dot com

--- Comment #10 from Martin Cermak <mcermak at redhat dot com> ---
(In reply to Frank Ch. Eigler from comment #5)
> Another important element of finishing this work is to document the syscalls
> tapset in the stapprobes.5 man page.  There is probably no need to
> elaborately
> enumerate all couple of hundred in the man page, but the general conventions
> should be there:
> - what general variables are available ("name", "argstr", ...)
> - what is done for user-space strings, decomposed struct fields

On  Tue  2015-07-21  14:40 , David Smith wrote:                                 
> We've about polished the [nd_]syscall tapsets to a fairly brilliant           
> shine as far as the code goes, but those tapsets aren't documented -             
> PR2111: <https://sourceware.org/bugzilla/show_bug.cgi?id=2111>. Although         
> this sounds a bit boring, there are actually some thinking that needs            
> doing there - like how to handle the nd_syscall probes vs. the syscall           
> probes. We might want to combine the documentation into one set instead          
> of two, but how do you do that cleanly?                                          
>                                                                                  

So this needs parser. Either stap's one, or some external one.                  
So firstly I'll think about how to resuse the former. What's                    
somewhat close to what we need is `stap -L 'syscall.*,nd_syscall.*'`.           
I see two drawbacks here:                                                       

1) This includes conditionals evaluation and thus output is                     
  architecture (and otherwise) specific. I think disabling
  conditionals evaluation might be doable.                                      

2) We don't have correct datatype information. For dwarf                        
   based probes, types do not match due to syscall wrappers, for                
   non-dwarf based syscalls we don't know types at all. Tapset                  
   source could be manually extended to contain type information                
   say, using comments, and then documentation could be                         
   autogenerated. But probably not using stap's internal parser.                
   At least not without significant tweaks.                                     

So using stap parser with conditionals evaluation disabled, collecting
syscalls list, matching syscalls against nd_syscalls and collecting 
convenience variables list per syscall probe (without type information)
might be doable. Thoughts?

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[mcermak at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

--- Comment #11 from Martin Cermak <mcermak at redhat dot com> ---
When 'kernel.function' gets replaced by 'kprobe.function' in whole the tapset,
I seem to be able to get syscalls list per architecture using cross-compilation
(without having respective kernel-debuginfo):

=======
fc20 x86_64 # cat syscalls_per_arch 
MYARCH=$1

ORIG=/usr/share/systemtap/tapset
TEMP=`mktemp -d`

cp -r ${ORIG}/* ${TEMP}/
find $TEMP -type f -exec sed -i 's/kernel\.function/kprobe\.function/g' {} \;

export SYSTEMTAP_TAPSET=$TEMP
stap -a $MYARCH -L 'syscall.*' 2> /dev/null | perl -anle 'print shift @F, "
@{[sort @F]}"' | sort

rm -rf $TEMP



fc20 x86_64 # ./syscalls_per_arch s390 | tail
syscall.utimensat argstr:unknown dfd:unknown dfd_str:unknown filename:unknown
filename_uaddr:unknown flags:unknown flags_str:unknown name:unknown
tsp_uaddr:unknown
syscall.utimes argstr:unknown filename:unknown filename_uaddr:unknown
name:unknown tvp_uaddr:unknown
syscall.vfork argstr:unknown name:unknown
syscall.vhangup argstr:unknown name:unknown
syscall.vmsplice argstr:unknown name:unknown
syscall.wait4 argstr:unknown name:unknown options:unknown options_str:unknown
pid:unknown rusage_uaddr:unknown status_uaddr:unknown
syscall.waitid argstr:unknown infop_uaddr:unknown name:unknown options:unknown
options_str:unknown pid:unknown rusage_uaddr:unknown which:unknown
which_str:unknown
syscall.waitpid argstr:unknown name:unknown options:unknown options_str:unknown
pid:unknown status_uaddr:unknown
syscall.write argstr:unknown buf_uaddr:unknown count:unknown fd:unknown
name:unknown
syscall.writev argstr:unknown count:unknown fd:unknown name:unknown
vector_uaddr:unknown
fc20 x86_64 # 
=======

With nd_syscalls this is even more straightforward. I wonder if this is worth
of some elaboration.

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[mcermak at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

Martin Cermak <mcermak at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |dsmith at redhat dot com

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[mcermak at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

--- Comment #12 from Martin Cermak <mcermak at redhat dot com> ---
Created attachment 8508
  --> https://sourceware.org/bugzilla/attachment.cgi?id=8508&action=edit
proposed patch

Attached patch generates a table of [nd_]syscalls and list of their convenience
variables for me.

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[mcermak at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

--- Comment #13 from Martin Cermak <mcermak at redhat dot com> ---
Created attachment 8509
  --> https://sourceware.org/bugzilla/attachment.cgi?id=8509&action=edit
A pdf output acquired using aforementioned patch on f22/x86_64.

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[jistone at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

Josh Stone <jistone at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jistone at redhat dot com

--- Comment #14 from Josh Stone <jistone at redhat dot com> ---
1. The table would be a lot more useful if it were sorted by syscall name.

2. The "argstr" and "name" should be common to all syscall probes.  Let's
mention those in the intro section and filter them from the rest of the table. 
Might also mention "retstr" for syscall return probes.

3. Underscored names are most likely "private" locals, like the "__nr" that
frequently appears.  Let's filter them.

4. I think any differences between syscall and nd_syscall locals should be
considered bugs, not documented features.  But AFAICS the only differences
right now are underscored names -- see point 3.  So maybe we can report any
additional differences with a build-time warning, or even an error, but I don't
think they need any mention in the document.

5. (off-topic) That 15-page Table of Contents is kind of ridiculous IMO.  I'm
glad your syscall addition didn't get fully enumerated there too!  I think we
should probably reduce the TOC to just major section headings, and maybe add a
fuller index at the end of the document.

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[mcermak at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

--- Comment #15 from Martin Cermak <mcermak at redhat dot com> ---
Created attachment 8520
  --> https://sourceware.org/bugzilla/attachment.cgi?id=8520&action=edit
updated patch

Attached patch tries to address aforementioned comments plus it adds a 3stap
syscall man page. Using 'make rpm' I seem to get expected outputs.

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[mcermak at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

--- Comment #16 from Martin Cermak <mcermak at redhat dot com> ---
Created attachment 8521
  --> https://sourceware.org/bugzilla/attachment.cgi?id=8521&action=edit
Outputs acquired using patch from comment 15

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[mcermak at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

--- Comment #17 from Martin Cermak <mcermak at redhat dot com> ---
(In reply to Josh Stone from comment #14)
> 4. I think any differences between syscall and nd_syscall locals should be
> considered bugs, not documented features.  But AFAICS the only differences
> right now are underscored names -- see point 3.  So maybe we can report any
> additional differences with a build-time warning, or even an error, but I
> don't think they need any mention in the document.

Will try to fix this within PR18827.

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[mcermak at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=2111

Martin Cermak <mcermak at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|ASSIGNED                    |RESOLVED
         Resolution|---                         |FIXED

--- Comment #18 from Martin Cermak <mcermak at redhat dot com> ---
Fixed in commit 86204b9b663525f5a9d42aabf9989b59c50ef0c1

-- 
You are receiving this mail because:
You are the assignee for the bug.

[Bug tapsets/2111] document syscalls tapset

[fche at redhat dot com]

------- Additional Comments From fche at redhat dot com  2010-04-08 19:12 -------
It may be sufficient for now to excise the section for the syscall
tapset from stapprobes.3stap and put them into a separate tapset::syscall
manpage.

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=2111

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

[Bug tapsets/2111] document syscalls tapset

[fche at redhat dot com]

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
         AssignedTo|hunt at redhat dot com      |systemtap at sources dot
                   |                            |redhat dot com


http://sourceware.org/bugzilla/show_bug.cgi?id=2111

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.