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;
Message-ID: <b65f6a0f-772c-162c-6669-ff1d545f375c@oracle.com>
Date:   Thu, 20 Jul 2023 23:53:43 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.13.0
Subject: Re: [PATCH v2 9/9] Documentation: tracing: Update fprobe event
 example with BTF field
Content-Language: en-GB
To:     "Masami Hiramatsu (Google)" <mhiramat@kernel.org>,
        linux-trace-kernel@vger.kernel.org
Cc:     linux-kernel@vger.kernel.org, Steven Rostedt <rostedt@goodmis.org>,
        Martin KaFai Lau <martin.lau@linux.dev>, bpf@vger.kernel.org,
        Sven Schnelle <svens@linux.ibm.com>,
        Alexei Starovoitov <ast@kernel.org>
References: <168960739768.34107.15145201749042174448.stgit@devnote2>
 <168960748753.34107.1941635032108706544.stgit@devnote2>
From:   Alan Maguire <alan.maguire@oracle.com>
In-Reply-To: <168960748753.34107.1941635032108706544.stgit@devnote2>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?eGd0eFpPQTQyUHhidHhCdm9iQzdrdEM5Z0NGcVVVcEZXTG9vYWxKMVBUL1Vl?=
 =?utf-8?B?biszL1FwT0JUT3VRSkRTb2M4dmJNM1ZqeFY5ZUF6bnpYMnFMRXIxY2NyM2pk?=
 =?utf-8?B?WFNnMEFJTU9wb0hoWStEblNiYzgyVFlNQnZTZmZlc1hrZXBLOHo1U2V6a0ZG?=
 =?utf-8?B?REVwbllOSU9ZTUlUWXIvQkY1TEQrRmZhS0o5eUNxR3piTHNHeFdkT1FzSGxm?=
 =?utf-8?B?bC9IaHh6NnMrTWZDMUtESnNxTlBWWFprT0FjK01nNXk2MlE0ckcrTXdDMDNI?=
 =?utf-8?B?bFF4MTUrek9KdEJMOFJlamJhc29DR0xkemZ1ekFvYjdsYldjSkZMWE0yL0ZY?=
 =?utf-8?B?ck1xRENYRVVnK3YxS1VhSXdVMStpV0Z0V3pqWXhwaUJRQVcrQ1ZRUnpLWmgz?=
 =?utf-8?B?VU81b1JpS1o2SDRoVE5oOXViMEIzYWRMcEdvc09CMWpwWlU1ZkNpQThVL2RL?=
 =?utf-8?B?cDh1cG1NOVRqOWJ3NHhhWTB1Sld6T3BUbEJLRTV6eTJoZDgrRS8xUDdDZC85?=
 =?utf-8?B?QURxZDdGTVhESVRkNWdhQk45L1hITnhKSXZYY3VleDdoSEFyaFZBeW03NWt0?=
 =?utf-8?B?b1g5M0xLVmtyeVBHd2RFNlZEc1VHQXIwUkxKNnVNaWhNZDhGU2JsWkI4SVBj?=
 =?utf-8?B?dkpsTVpUNFRBN1lMYnRsY1FPTG1TemdUT3NWZU9nb09IWllSV0xoTUI5OG0y?=
 =?utf-8?B?Mmx4NDkvZXgvWVBkRUlGL1NVSFo1ZTFQMGF0cWJ1dXRabUZWYnc0NUNKTUZJ?=
 =?utf-8?B?RnNoZW0yazBuckdFK09kMHIzRmVta1VVc3NrRmlqSUE5K2dxNXQxMTB3ZVpq?=
 =?utf-8?B?NUdkMGNjcWxZSlNoQjBiWUN1Q0pSMXQzUTRhOWNUcmpBaDYyTlM3akZxRTJt?=
 =?utf-8?B?a2tjUnRQSkpiOG54a0o2VThkdXdXcjRBME5Da0xvVy9YcFRFMXNyNGhJOG5y?=
 =?utf-8?B?L1RyYXNuQTBWR1UxTTVxRFFHRG9QU2xJbmF6TVZnd0daellmZnZ5V2Q0cXVy?=
 =?utf-8?B?ZzFJUUsxUCtUbERpRnZLZTdtVEFGL2VJb0RiU0U1OFlLNHVTRGE4MVZHZGlt?=
 =?utf-8?B?YkVwbzNrYnFzejhtVVFrRjRuZTYvWXRmSDcvWVFPRlNtQzRzZllFSmg3NWR2?=
 =?utf-8?B?VnZFbGlRcnZIbmlKeVF1bHJaaDRnejV1bnhLOHZaZ09aUzJGOVhRY0F2NDYw?=
 =?utf-8?B?VTI1WUJpRlQ4YThjTVdyaWZYVmlLcDB6WnBWZ2tLQ1MzYzVLeVFvRTUwZlIy?=
 =?utf-8?B?TUErK0E3L1ljM0ZycHdrZWZsTFo3M05GRzdQQkJDaDZreDQ0Sy9KUWRmVk9u?=
 =?utf-8?B?STllaEZVemVrWWRkQ0djOFVmZ0VEY0lQK3l0NjVyZFJkTTR5NlllTVNlRlRG?=
 =?utf-8?B?bXlmaUhtTEZ0T3I4aW5Tazd6NFJmUGt0UEtPMExUaWJKNkg0LzRGYWN1TW1O?=
 =?utf-8?B?ZFIyY0VQV1d5enlVcVl1RnhpTkIwbXFLRXhZZFpQS1pKdDN4TmlhSUhneXVH?=
 =?utf-8?B?cTVuUEFOZDVFVDVWOUlTNGFmelhQMktiUTRJY0NnMnlwVjMrR1JXSmtTSlpl?=
 =?utf-8?B?VTlJbTBidU9pNGZDampxb2ZXZzBvdkNxNVBWYkFUSTBpKzZBMmNOQTVCU09z?=
 =?utf-8?B?MUtsdEdUa2RXZnFqeEVKQ1dZS1ZPczRYYTlPek9lQS9PSWo2WXJZQnRPSEla?=
 =?utf-8?B?cm5GY0szU1U5NFRTTE8vWUlwL3JyenFYNlA2bDUwUGtaNC9sQi9vRExaUFVw?=
 =?utf-8?B?S3pRanpHYVpxZzB2VzVBME16N3c0eWFrckNpWGV5VXZDRllBbnl6eTVlZXkr?=
 =?utf-8?B?SnNXL0tDcXhOZEFlSWhtRVhWRjZTa0NsbXdVdmVjc3RSQi9IOTN0MkpiOTEx?=
 =?utf-8?B?OTExaEtpRTNISHZwdUgyczgxeTlidFhCT0ZFTGEzY1Rpc1ZRTDdmS3FwMDND?=
 =?utf-8?B?YVV6VWpkRW1wdWdmSFdoVnJEcVBQblhrSGIxS0wrdUJWWTcvRDV4YmdFSE9W?=
 =?utf-8?B?ellGekFMbEtiTXB4NENZdU5GdHhUOWxiMmk2bmF6QzFiblk1Y01NbVhDTXgr?=
 =?utf-8?B?UFovZUtpQkM4MFVFSWs3MGxhRDB0VS9LUms0aUJuLzgyaFhWbWFDcGR5VU9r?=
 =?utf-8?B?T3BXV2F1a2FSUG1TSXlrQzVFZGpzcElueldYQ0dFVm5NRVdBV1QybTQ3cWtT?=
 =?utf-8?Q?gBgtQs2yw+6ED7h+86oq95Q=3D?=
X-MS-Exchange-AntiSpam-ExternalHop-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-ExternalHop-MessageData-0: 7469QSKNYXW4l42dfsRKfPWIniS2/kzOxTqiuEaL0WG1ABq9oUEPxrC4L9Ss6P3u5BYzYhUoQrZCmtP4SXyGQyfQEMzH6YN2CNWH6hoXSG+ZfKd1h843t3JEEB/7MfoDJVSdnJ1oLUOgfZhF1GHmwTHzTzSNXUA3F7czECWuUCLq2BIVekAuX8xO2kHtkTtFzX7x2eK6D+5mo4zsTOoaqEyMr2w+FFQ8RwjAzApN1ll3gl0d/1ALt64SKLKguhbqeis6ddgYGbwz1g8+EPKjxKGCEr/U2+jxmWGQhKdHFtH13cNpbxaiLe2QdWLCO2RXZYR+GRkzHhqiu9+3FGNPCQtU+vnM6fNwY1WNB2lgkDw/4BF5aKff9PJANzoI673i8Jom1JEjn+rpS++lmFooiQvOYwIbRJDb82oXxgC0sBh4W/E6/bpkgovIEX5Gb3W+iGR7NaFqfEdRArOx5gYkDWoFbxWyhp6AKM5aeA7De9aYwQrTlIRzZw4v1EcoadhtoxLn1ShawykoivYn6D22fPgTyeclpDRnZ4lss+TNnM3bpemv0Q+X2cyDIIPQA4XF37wYQKXfnjjI45YzS2nGW+o7BE4EzcTtKabPfztgyvB4Jyu3qYYz+U3tu17akyA08Al/hPn7QPgvTne2ogS1ZciDdLdVaTd87U9PXsihi+r9KVrltro/Lt5hIlHFoADuu0clADneLR6lrpechI4j7ExP6yCxP4umMUmPTRgxM3+pZKWxqXtO4EWbayZ9phKKR7n+9+OA4pi2Oo+MQ9Y1YdmMzZ9JUM9vFMWCj0hcS3fCIYple5/vkMqZVG8QvMxDMCav4kykZ5ZqLorPMlhw9TMKwWMComAv0E6gPcLOJUZXsB5Peqg3j9wULeL/e3CN46yXVf78tN2DOqZi5QY0Eg==
X-OriginatorOrg: oracle.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 73ed3ec1-5179-4ef3-fcd6-08db89742e5a
X-MS-Exchange-CrossTenant-AuthSource: BLAPR10MB5267.namprd10.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 20 Jul 2023 22:53:49.2201
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 9/pGg6HZ5zaAXFwZSPWjXgJeRIAYIMn0WV3tu1vYpUNQbGD+lrd/f3SIDsVVgN1LoZYYeBN+CZcyKKvKFK3Q8A==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SA2PR10MB4539
X-Proofpoint-Virus-Version: vendor=baseguard
 engine=ICAP:2.0.254,Aquarius:18.0.957,Hydra:6.0.591,FMLib:17.11.176.26
 definitions=2023-07-20_10,2023-07-20_01,2023-05-22_02
X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 mlxlogscore=999
 suspectscore=0 phishscore=0 bulkscore=0 mlxscore=0 malwarescore=0
 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1
 engine=8.12.0-2306200000 definitions=main-2307200195
X-Proofpoint-GUID: _aLCLRuLQMWkBmgQ5Nle-bSNMIWMXlBS
X-Proofpoint-ORIG-GUID: _aLCLRuLQMWkBmgQ5Nle-bSNMIWMXlBS
X-Spam-Status: No, score=-2.2 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,NICE_REPLY_A,
        RCVD_IN_DNSWL_BLOCKED,RCVD_IN_MSPIKE_H5,RCVD_IN_MSPIKE_WL,
        SPF_HELO_NONE,SPF_NONE,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: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On 17/07/2023 16:24, Masami Hiramatsu (Google) wrote:
> From: Masami Hiramatsu (Google) <mhiramat@kernel.org>
> 
> Update fprobe event example with BTF data structure field specification.
> 
> Signed-off-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>

One suggestion below, but

Reviewed-by: Alan Maguire <alan.maguire@oracle.com>

> ---
>  Changes in v2:
>   - Remove 'retval' and use '$retval'.
> ---
>  Documentation/trace/fprobetrace.rst |   50 ++++++++++++++++++++++-------------
>  1 file changed, 32 insertions(+), 18 deletions(-)
> 
> diff --git a/Documentation/trace/fprobetrace.rst b/Documentation/trace/fprobetrace.rst
> index 7297f9478459..e9e764fadf14 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,33 @@ 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
> +

Could you describe what field access combinations are supported here;
i.e. foo->bar[.baz]?

> +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 +185,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 +200,3 @@ traceprobe event, you can trace it as below.
>             <idle>-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
>             <idle>-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``.
> 
>