From patchwork Wed Jul 26 13:01:21 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Masami Hiramatsu (Google)" X-Patchwork-Id: 126351 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:a985:0:b0:3e4:2afc:c1 with SMTP id t5csp396033vqo; Wed, 26 Jul 2023 06:16:56 -0700 (PDT) X-Google-Smtp-Source: APBJJlEOBf2FfW59WykqRK2d8iXD3KF7ZCtV+4Qm0dF6zowk4j2OVmQ6qeYoPm1zR4DvSzB9tk90 X-Received: by 2002:a05:6512:3c8d:b0:4fd:d016:c2e8 with SMTP id h13-20020a0565123c8d00b004fdd016c2e8mr1923153lfv.43.1690377414145; Wed, 26 Jul 2023 06:16:54 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1690377414; cv=none; d=google.com; s=arc-20160816; b=RKSztZlueO7hcqO9sQwxGhRJB4YdBRo7KgEtuyZBWuzDs7x387qJovgZCaEJ3hrALU vQIjclwAFy8Jo3LWkNvsInOgylN4oxLeEfRzJrMVu4EK9uSYomynjh3dn4DP48qjfu2B 2VbzIQqxXQxnRcodU+UWEQS1Z8SY9SO/nzTpD6t15jn7FK4I/lV/GouBO7aO8yAQFR5v LdMlZu4r/U9FlfxIrbMzJB49beC4RY+Ywr1xbIaYs6o0vYP2ju7i1S2RDQjFfFPDaBUR fM+3EPCvEhYd3TPXUWrSBl4TDjbKJ1cRLw4DB2EimlL63KQmGtTfLA51GW28DRXq1VWE 3XIQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :user-agent:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=Nhv0fMyByyMrlK8yFYQh43STKZphpezVS0+jtbTBXXw=; fh=raxTTJvC+dSJYbgfX5JG5gvrVjxTZXczN0HF8iDayLY=; b=klHxqjqvyS/SA+BP6c8jbcr6htYQ/NWPlncCxqM2d8D6Gf+Hrw3GWZe+nSLAFejFgJ qZB95WmaURERVh48/khuDZvja72KxhTg83OODoiU0SgETFLTkmH9XfIqx9le9DPrPhip ft4D/IErOfOrHCNfYQxclA7J8vodlp6otRGT4q4St4mJeYBmx1l5p/Y1bKrFwZIl/zEZ 4jJ8FnMcHR7bhb8XR8F8WbFrqMcH91FULMkcizonUrVWjvfvdgP+bk5Nmrrbg4qe4Yx3 PIc1QMB86XaZCULS1WE5aSL8dPsypDV2FTF+oCH3IiIAPKGOnzOrr6i6kZS+F3djz1vk 7UoA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@kernel.org header.s=k20201202 header.b=Pbc+uSu8; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id v25-20020a056402185900b0051d9246f95csi9606597edy.174.2023.07.26.06.16.27; Wed, 26 Jul 2023 06:16:54 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@kernel.org header.s=k20201202 header.b=Pbc+uSu8; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233833AbjGZNBt (ORCPT + 99 others); Wed, 26 Jul 2023 09:01:49 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:60084 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233798AbjGZNBf (ORCPT ); Wed, 26 Jul 2023 09:01:35 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [IPv6:2604:1380:4641:c500::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EE9FD26BD; Wed, 26 Jul 2023 06:01:26 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 699A26173F; Wed, 26 Jul 2023 13:01:26 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id D76D0C433C8; Wed, 26 Jul 2023 13:01:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1690376485; bh=CcGORqTI9ZQHAZplK151N2vLhAMfOhssOSPkNJphVGw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Pbc+uSu8VD3m5STq3XL048/uvTncN+tUJZ6Zhe/8MbtHzpfZS3Vjt1mel+Qq44uv9 T43JoBLDSZaziybKP954o38v0ix4aSQMH9cLXnuRFwgxWvUZQjh1WfrLbUkXodqz4c Hn3Wdwgkpuc6M66PWQ4m4uaHqR/aBNyzNUVwWgk7modCyi8saqnb1/fwcvvBlKgPNA ysBplL4MGi69v6KwrlSDsmdB7AxG4sG9Vm/8UjpdHBCPtA8CipAdxsyD4AqAb82XQe EKcVaZfeKW1i+addyIzssh0iIbScYejmc0mCiZrekGg9MglzIL5QKBzThgxHg+hvoc kCFzUOSAWyXYQ== From: "Masami Hiramatsu (Google)" To: linux-trace-kernel@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Steven Rostedt , mhiramat@kernel.org, Martin KaFai Lau , bpf@vger.kernel.org, Sven Schnelle , Alexei Starovoitov Subject: [PATCH v3 9/9] Documentation: tracing: Update fprobe event example with BTF field Date: Wed, 26 Jul 2023 22:01:21 +0900 Message-Id: <169037648115.607919.18187565150152698053.stgit@devnote2> X-Mailer: git-send-email 2.34.1 In-Reply-To: <169037639315.607919.2613476171148037242.stgit@devnote2> References: <169037639315.607919.2613476171148037242.stgit@devnote2> User-Agent: StGit/0.19 MIME-Version: 1.0 X-Spam-Status: No, score=-4.4 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_MED, SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1772489186931629814 X-GMAIL-MSGID: 1772489186931629814 From: Masami Hiramatsu (Google) Update fprobe event example with BTF data structure field specification. Signed-off-by: Masami Hiramatsu (Google) Reviewed-by: Alan Maguire --- Changes in v2: - Remove 'retval' and use '$retval'. Changes in v3: - Add description about mixture of '.' and '->' usage. --- Documentation/trace/fprobetrace.rst | 64 +++++++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 18 deletions(-) diff --git a/Documentation/trace/fprobetrace.rst b/Documentation/trace/fprobetrace.rst index 7297f9478459..8e9bebcf0a2e 100644 --- a/Documentation/trace/fprobetrace.rst +++ b/Documentation/trace/fprobetrace.rst @@ -79,9 +79,9 @@ automatically set by the given name. :: f:fprobes/myprobe vfs_read count=count pos=pos It also chooses the fetch type from BTF information. For example, in the above -example, the ``count`` is unsigned long, and the ``pos`` is a pointer. Thus, both -are converted to 64bit unsigned long, but only ``pos`` has "%Lx" print-format as -below :: +example, the ``count`` is unsigned long, and the ``pos`` is a pointer. Thus, +both are converted to 64bit unsigned long, but only ``pos`` has "%Lx" +print-format as below :: # cat events/fprobes/myprobe/format name: myprobe @@ -105,9 +105,47 @@ is expanded to all function arguments of the function or the tracepoint. :: # cat dynamic_events f:fprobes/myprobe vfs_read file=file buf=buf count=count pos=pos -BTF also affects the ``$retval``. If user doesn't set any type, the retval type is -automatically picked from the BTF. If the function returns ``void``, ``$retval`` -is rejected. +BTF also affects the ``$retval``. If user doesn't set any type, the retval +type is automatically picked from the BTF. If the function returns ``void``, +``$retval`` is rejected. + +You can access the data fields of a data structure using allow operator ``->`` +(for pointer type) and dot operator ``.`` (for data structure type.):: + +# echo 't sched_switch preempt prev_pid=prev->pid next_pid=next->pid' >> dynamic_events + +The field access operators, ``->`` and ``.`` can be combined for accessing deeper +members and other structure members pointed by the member. e.g. ``foo->bar.baz->qux`` +If there is non-name union member, you can directly access it as the C code does. +For example:: + + struct { + union { + int a; + int b; + }; + } *foo; + +To access ``a`` and ``b``, use ``foo->a`` and ``foo->b`` in this case. + +This data field access is available for the return value via ``$retval``, +e.g. ``$retval->name``. + +For these BTF arguments and fields, ``:string`` and ``:ustring`` change the +behavior. If these are used for BTF argument or field, it checks whether +the BTF type of the argument or the data field is ``char *`` or ``char []``, +or not. If not, it rejects applying the string types. Also, with the BTF +support, you don't need a memory dereference operator (``+0(PTR)``) for +accessing the string pointed by a ``PTR``. It automatically adds the memory +dereference operator according to the BTF type. e.g. :: + +# echo 't sched_switch prev->comm:string' >> dynamic_events +# echo 'f getname_flags%return $retval->name:string' >> dynamic_events + +The ``prev->comm`` is an embedded char array in the data structure, and +``$retval->name`` is a char pointer in the data structure. But in both +cases, you can use ``:string`` type to get the string. + Usage examples -------------- @@ -161,10 +199,10 @@ parameters. This means you can access any field values in the task structure pointed by the ``prev`` and ``next`` arguments. For example, usually ``task_struct::start_time`` is not traced, but with this -traceprobe event, you can trace it as below. +traceprobe event, you can trace that field as below. :: - # echo 't sched_switch comm=+1896(next):string start_time=+1728(next):u64' > dynamic_events + # echo 't sched_switch comm=next->comm:string next->start_time' > dynamic_events # head -n 20 trace | tail # TASK-PID CPU# ||||| TIMESTAMP FUNCTION # | | | ||||| | | @@ -176,13 +214,3 @@ traceprobe event, you can trace it as below. -0 [000] d..3. 5606.690317: sched_switch: (__probestub_sched_switch+0x4/0x10) comm="kworker/0:1" usage=1 start_time=137000000 kworker/0:1-14 [000] d..3. 5606.690339: sched_switch: (__probestub_sched_switch+0x4/0x10) comm="swapper/0" usage=2 start_time=0 -0 [000] d..3. 5606.692368: sched_switch: (__probestub_sched_switch+0x4/0x10) comm="kworker/0:1" usage=1 start_time=137000000 - -Currently, to find the offset of a specific field in the data structure, -you need to build kernel with debuginfo and run `perf probe` command with -`-D` option. e.g. -:: - - # perf probe -D "__probestub_sched_switch next->comm:string next->start_time" - p:probe/__probestub_sched_switch __probestub_sched_switch+0 comm=+1896(%cx):string start_time=+1728(%cx):u64 - -And replace the ``%cx`` with the ``next``.