Netdev Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Alan Maguire <alan.maguire@oracle.com>
To: ast@kernel.org, daniel@iogearbox.net, andrii@kernel.org
Cc: kafai@fb.com, songliubraving@fb.com, yhs@fb.com,
john.fastabend@gmail.com, kpsingh@kernel.org,
quentin@isovalent.com, toke@redhat.com, bpf@vger.kernel.org,
netdev@vger.kernel.org, Alan Maguire <alan.maguire@oracle.com>
Subject: [PATCH bpf-next 2/3] tools: ksnoop: document ksnoop tracing of entry/return with value display
Date: Tue, 3 Aug 2021 22:23:15 +0100 [thread overview]
Message-ID: <1628025796-29533-3-git-send-email-alan.maguire@oracle.com> (raw)
In-Reply-To: <1628025796-29533-1-git-send-email-alan.maguire@oracle.com>
Add ksnoop.8 describing options for tracing function entry/return
with full argument/return value display. Include example use
cases with output to demonstrate functionality.
Signed-off-by: Alan Maguire <alan.maguire@oracle.com>
---
tools/bpf/ksnoop/Documentation/Makefile | 58 ++++++++++
tools/bpf/ksnoop/Documentation/ksnoop.rst | 173 ++++++++++++++++++++++++++++++
tools/bpf/ksnoop/Makefile | 17 ++-
3 files changed, 244 insertions(+), 4 deletions(-)
create mode 100644 tools/bpf/ksnoop/Documentation/Makefile
create mode 100644 tools/bpf/ksnoop/Documentation/ksnoop.rst
diff --git a/tools/bpf/ksnoop/Documentation/Makefile b/tools/bpf/ksnoop/Documentation/Makefile
new file mode 100644
index 0000000..7c2331b9
--- /dev/null
+++ b/tools/bpf/ksnoop/Documentation/Makefile
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: GPL-2.0-only
+include ../../../scripts/Makefile.include
+include ../../../scripts/utilities.mak
+
+INSTALL ?= install
+RM ?= rm -f
+RMDIR ?= rmdir --ignore-fail-on-non-empty
+
+ifeq ($(V),1)
+ Q =
+else
+ Q = @
+endif
+
+prefix ?= /usr/local
+mandir ?= $(prefix)/man
+man8dir = $(mandir)/man8
+
+MAN8_RST = ksnoop.rst
+
+_DOC_MAN8 = $(patsubst %.rst,%.8,$(MAN8_RST))
+DOC_MAN8 = $(addprefix $(OUTPUT),$(_DOC_MAN8))
+
+man: man8
+man8: $(DOC_MAN8)
+
+RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null)
+RST2MAN_OPTS += --verbose
+
+list_pages = $(sort $(basename $(filter-out $(1),$(MAN8_RST))))
+see_also = $(subst " ",, \
+ "\n" \
+ "SEE ALSO\n" \
+ "========\n" \
+ "\t**bpf**\ (2),\n")
+
+$(OUTPUT)%.8: %.rst
+ifndef RST2MAN_DEP
+ $(error "rst2man not found, but required to generate man pages")
+endif
+ $(QUIET_GEN)( cat $< ; printf "%b" $(call see_also,$<) ) | rst2man $(RST2MAN_OPTS) > $@
+
+clean:
+ $(call QUIET_CLEAN, Documentation)
+ $(Q)$(RM) $(DOC_MAN8)
+
+install: man
+ $(call QUIET_INSTALL, Documentation-man)
+ $(Q)$(INSTALL) -d -m 755 $(DESTDIR)$(man8dir)
+ $(Q)$(INSTALL) -m 644 $(DOC_MAN8) $(DESTDIR)$(man8dir)
+
+uninstall:
+ $(call QUIET_UNINST, Documentation-man)
+ $(Q)$(RM) $(addprefix $(DESTDIR)$(man8dir)/,$(_DOC_MAN8))
+ $(Q)$(RMDIR) $(DESTDIR)$(man8dir)
+
+.PHONY: man man8 clean install uninstall
+.DEFAULT_GOAL := man
diff --git a/tools/bpf/ksnoop/Documentation/ksnoop.rst b/tools/bpf/ksnoop/Documentation/ksnoop.rst
new file mode 100644
index 0000000..31161c4
--- /dev/null
+++ b/tools/bpf/ksnoop/Documentation/ksnoop.rst
@@ -0,0 +1,173 @@
+================
+KSNOOP
+================
+-------------------------------------------------------------------------------
+tool for tracing kernel function entry/return showing arguments/return values
+-------------------------------------------------------------------------------
+
+:Manual section: 8
+
+SYNOPSIS
+========
+
+ **ksnoop** [*OPTIONS*] { *COMMAND* *FUNC* | **help** }
+
+ *OPTIONS* := { { **-V** | **--version** } | { **-h** | **--help** }
+ | { [**-P** | **--pages**] nr_pages} | { [**-p** | **--pid**] pid} |
+ [{ **-s** | **--stack** }] | [{ **-d** | **--debug** }] }
+
+ *COMMAND* := { **trace** | **info** }
+
+ *FUNC* := { **name** | **name**\(**arg**\[,**arg\]) }
+
+DESCRIPTION
+===========
+ *ksnoop* allows for inspection of arguments and return values
+ associated with function entry/return.
+
+ **ksnoop info** *FUNC*
+ Show function description, arguments and return value types.
+ **ksnoop trace** *FUNC* [*FUNC*]
+ Trace function entry and return, showing arguments and
+ return values. A function name can simply be specified,
+ or a function name along with named arguments, return values.
+ **return** is used to specify the return value.
+
+ *ksnoop* requires the kernel to provide BTF for itself, and if
+ tracing of module data is required, module BTF must be present also.
+ Check /sys/kernel/btf to see if BTF is present.
+
+ **ksnoop** requires *CAP_BPF* and *CAP_TRACING* capabilities.
+
+OPTIONS
+=======
+ -h, --help
+ Show help information
+ -V, --version
+ Show version.
+ -d, --debug
+ Show debug output.
+ -p, --pid
+ Filter events by pid.
+ -P, --pages
+ Specify number of pages used per-CPU for perf event
+ collection. Default is 8.
+ -s, --stack
+ Specified set of functions are traced if and only
+ if they are encountered in the order specified.
+
+EXAMPLES
+========
+**# ksnoop info ip_send_skb** ::
+
+ int ip_send_skb(struct net * net, struct sk_buff * skb);
+
+Show function description.
+
+**# ksnoop trace ip_send_skb** ::
+
+ TIME CPU PID FUNCTION/ARGS
+ 78101668506811 1 2813 ip_send_skb(
+ net = *(0xffffffffb5959840)
+ (struct net){
+ .passive = (refcount_t){
+ .refs = (atomic_t){
+ .counter = (int)0x2,
+ },
+ },
+ .dev_base_seq = (unsigned int)0x18,
+ .ifindex = (int)0xf,
+ .list = (struct list_head){
+ .next = (struct list_head *)0xffff9895440dc120,
+ .prev = (struct list_head *)0xffffffffb595a8d0,
+ },
+ ...
+
+ 79561322965250 1 2813 ip_send_skb(
+ return =
+ (int)0x0
+ );
+
+Show entry/return for ip_send_skb() with arguments, return values.
+
+**# ksnoop trace "ip_send_skb(skb)"** ::
+
+
+ TIME CPU PID FUNCTION/ARGS
+ 78142420834537 1 2813 ip_send_skb(
+ skb = *(0xffff989750797c00)
+ (struct sk_buff){
+ (union){
+ .sk = (struct sock *)0xffff98966ce19200,
+ .ip_defrag_offset = (int)0x6ce19200,
+ },
+ (union){
+ (struct){
+ ._skb_refdst = (long unsigned int)0xffff98981dde2d80,
+ .destructor = (void (*)(struct sk_buff *))0xffffffffb3e1beb0,
+ },
+ ...
+
+Show entry argument **skb**.
+
+**# ksnoop trace "ip_send_skb(return)"** ::
+
+ TIME CPU PID FUNCTION/ARGS
+ 78178228354796 1 2813 ip_send_skb(
+ return =
+ (int)0x0
+ );
+
+Show return value from ip_send_skb().
+
+**# ksnoop trace "ip_send_skb(skb->sk)"** ::
+
+ TIME CPU PID FUNCTION/ARGS
+ 78207649138829 2 2813 ip_send_skb(
+ skb->sk = *(0xffff98966ce19200)
+ (struct sock){
+ .__sk_common = (struct sock_common){
+ (union){
+ .skc_addrpair = (__addrpair)0x1701a8c017d38f8d,
+ (struct){
+ .skc_daddr = (__be32)0x17d38f8d,
+ .skc_rcv_saddr = (__be32)0x1701a8c0,
+ },
+ },
+ ...
+
+Trace meber information associated with argument. Only one level of
+membership is supported.
+
+**# ksnoop -p 2813 "ip_rcv(dev)"** ::
+
+ TIME CPU PID FUNCTION/ARGS
+ 78254803164920 1 2813 ip_rcv(
+ dev = *(0xffff9895414cb000)
+ (struct net_device){
+ .name = (char[16])[
+ 'l',
+ 'o',
+ ],
+ .name_node = (struct netdev_name_node *)0xffff989541515ec0,
+ .state = (long unsigned int)0x3,
+ ...
+
+Trace **dev** argument of **ip_rcv()**. Specify process id 2813 for events
+for that process only.
+
+**# ksnoop -s tcp_sendmsg __tcp_transmit_skb ip_output** ::
+
+ TIME CPU PID FUNCTION/ARGS
+ 71827770952903 1 4777 __tcp_transmit_skb(
+ sk = *(0xffff9852460a2300)
+ (struct sock){
+ .__sk_common = (struct sock_common){
+ (union){
+ .skc_addrpair = (__addrpair)0x61b2af0a35cbfe0a,
+
+Trace entry/return of tcp_sendmsg, __tcp_transmit_skb and ip_output when
+tcp_sendmsg leads to a call to __tcp_transmit_skb and that in turn
+leads to a call to ip_output; i.e. with a call graph matching the order
+specified. The order does not have to be direct calls, i.e. function A
+can call another function that calls function B.
diff --git a/tools/bpf/ksnoop/Makefile b/tools/bpf/ksnoop/Makefile
index 0a1420e..149e4be 100644
--- a/tools/bpf/ksnoop/Makefile
+++ b/tools/bpf/ksnoop/Makefile
@@ -42,12 +42,12 @@ endif
.DELETE_ON_ERROR:
-.PHONY: all clean ksnoop
+.PHONY: all clean ksnoop doc doc-clean doc-install
all: ksnoop
-ksnoop: $(OUTPUT)/ksnoop
+ksnoop: $(OUTPUT)/ksnoop doc
-clean:
+clean: doc-clean
$(call QUIET_CLEAN, ksnoop)
$(Q)$(RM) -r $(BPFOBJ_OUTPUT) $(BPFTOOL_OUTPUT)
$(Q)$(RM) $(OUTPUT)*.o $(OUTPUT)*.d
@@ -55,11 +55,20 @@ clean:
$(Q)$(RM) $(OUTPUT)ksnoop
$(Q)$(RM) -r .output
-install: ksnoop
+install: ksnoop doc-install
$(call QUIET_INSTALL, ksnoop)
$(Q)$(INSTALL) -m 0755 -d $(DESTDIR)$(prefix)/sbin
$(Q)$(INSTALL) $(OUTPUT)/ksnoop $(DESTDIR)$(prefix)/sbin/ksnoop
+doc:
+ $(call descend,Documentation)
+
+doc-clean:
+ $(call descend,Documentation,clean)
+
+doc-install:
+ $(call descend,Documentation,install)
+
$(OUTPUT)/ksnoop: $(OUTPUT)/ksnoop.o $(BPFOBJ)
$(QUIET_LINK)$(CC) $(CFLAGS) $^ -lelf -lz -o $@
--
1.8.3.1
next prev parent reply other threads:[~2021-08-03 21:23 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-08-03 21:23 [PATCH bpf-next 0/3] tools: ksnoop: tracing kernel function entry/return with argument/return " Alan Maguire
2021-08-03 21:23 ` [PATCH bpf-next 1/3] tools: ksnoop: kernel argument/return value tracing/display using BTF Alan Maguire
2021-08-03 21:23 ` Alan Maguire [this message]
2021-08-03 21:23 ` [PATCH bpf-next 3/3] tools: ksnoop: add .gitignore Alan Maguire
2021-08-04 21:05 ` [PATCH bpf-next 0/3] tools: ksnoop: tracing kernel function entry/return with argument/return value display Daniel Borkmann
2021-08-05 11:14 ` Alan Maguire
2021-08-06 14:56 ` Daniel Borkmann
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1628025796-29533-3-git-send-email-alan.maguire@oracle.com \
--to=alan.maguire@oracle.com \
--cc=andrii@kernel.org \
--cc=ast@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=daniel@iogearbox.net \
--cc=john.fastabend@gmail.com \
--cc=kafai@fb.com \
--cc=kpsingh@kernel.org \
--cc=netdev@vger.kernel.org \
--cc=quentin@isovalent.com \
--cc=songliubraving@fb.com \
--cc=toke@redhat.com \
--cc=yhs@fb.com \
--subject='Re: [PATCH bpf-next 2/3] tools: ksnoop: document ksnoop tracing of entry/return with value display' \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).