From nobody Mon Oct 6 05:01:21 2025 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 82B652EBDE5; Fri, 25 Jul 2025 10:08:53 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=217.140.110.172 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753438135; cv=none; b=NY0psA7UZ7Kl49WYu6NxiCkHCnxqVYr6OETe2Qy0vf8ry+9WC+34Jq/uvSylqU7JkuNjs3ledQw/9ZJ5B8ngGg6DA1k1vSxTlf6sd6c/R0vcqckc/+xc7QspAICoBoBPJkvEfZYKoS/at8V0r4UQf74WB64sZp9PWJHyrI6es7A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753438135; c=relaxed/simple; bh=+3gjGeeKe7DyZ3/goDLLn+ZLf1jbvy7KWHPofuCLFbE=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=SvggCN3j4h/mCve4/VnwZ8UadKnibgfdhB4Q2rsWTLIzothetg3ysL/TJPRxw3LrjX2KAVAOVC/Ya2o8MU1y7GfvNxf4BHi48XXEKj2EudIFlrFboTh628+XJGaC+FCeZmqpy9E5cQplbUMADiOI9t8v62GiZMtzL4qoGfFr7ns= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com; spf=pass smtp.mailfrom=arm.com; arc=none smtp.client-ip=217.140.110.172 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=arm.com Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 187C8176C; Fri, 25 Jul 2025 03:08:46 -0700 (PDT) Received: from e132581.arm.com (e132581.arm.com [10.1.196.87]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id D64E03F5A1; Fri, 25 Jul 2025 03:08:48 -0700 (PDT) From: Leo Yan Date: Fri, 25 Jul 2025 11:08:16 +0100 Subject: [PATCH RESEND v3 6/6] perf docs: Document AUX pause and resume with BPF Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250725-perf_aux_pause_resume_bpf_rebase-v3-6-ae21deb49d1a@arm.com> References: <20250725-perf_aux_pause_resume_bpf_rebase-v3-0-ae21deb49d1a@arm.com> In-Reply-To: <20250725-perf_aux_pause_resume_bpf_rebase-v3-0-ae21deb49d1a@arm.com> To: Peter Zijlstra , Ingo Molnar , Arnaldo Carvalho de Melo , Namhyung Kim , Jiri Olsa , Ian Rogers , Adrian Hunter , KP Singh , Matt Bobrowski , Song Liu , Alexei Starovoitov , Daniel Borkmann , Andrii Nakryiko , Martin KaFai Lau , Eduard Zingerman , Yonghong Song , John Fastabend , Stanislav Fomichev , Hao Luo , Steven Rostedt , Masami Hiramatsu , Mathieu Desnoyers , James Clark , Suzuki K Poulose , Mike Leach Cc: linux-perf-users@vger.kernel.org, linux-kernel@vger.kernel.org, bpf@vger.kernel.org, linux-trace-kernel@vger.kernel.org, Leo Yan X-Mailer: b4 0.14.2 X-Developer-Signature: v=1; a=ed25519-sha256; t=1753438103; l=3165; i=leo.yan@arm.com; s=20250604; h=from:subject:message-id; bh=+3gjGeeKe7DyZ3/goDLLn+ZLf1jbvy7KWHPofuCLFbE=; b=ZHE4FA41woUg35swf1zGO1DfYw6G1BriPf/uj6IYI7C//DMngby8Kr9fu8gtJjKssd1UjRItX +n+fuanhJHoDixS9Q+H4a+W0T9jcO4FShVZwkr4pBdfoDFUyiFwzY+c X-Developer-Key: i=leo.yan@arm.com; a=ed25519; pk=k4BaDbvkCXzBFA7Nw184KHGP5thju8lKqJYIrOWxDhI= Documents the usage of the --bpf-aux-pause option and provides examples. Signed-off-by: Leo Yan --- tools/perf/Documentation/perf-record.txt | 51 ++++++++++++++++++++++++++++= ++++ 1 file changed, 51 insertions(+) diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Document= ation/perf-record.txt index 612612fa2d8041b94860035ed9cb01557a20b6b7..5aee20bfd03bda72bddabf42005= b9678309414ad 100644 --- a/tools/perf/Documentation/perf-record.txt +++ b/tools/perf/Documentation/perf-record.txt @@ -544,6 +544,57 @@ must be an AUX area event. Samples on other events wil= l be created containing data from the AUX area. Optionally sample size may be specified, otherwise= it defaults to 4KiB. =20 +--bpf-aux-pause=3D[=3DOPTIONS]:: +Specify trace events for triggering AUX pause with a BPF program. A trace = event +can be static ftrace tracepoint, or dynamic tracepoint by using kprobe, +kretprobe, uprobe or uretprobe. This option must be enabled in combination= with +the "aux-action=3Dstart-paused" configuration in an AUX event. + +For attaching a kprobe or kretprobe event, the format is: + + {kprobe|kretprobe}:{p|r}:function_name + +The format for attaching a uprobe or uretprobe event is: + + {uprobe|uretprobe}:{p|r}:executable:function_name + +The format for attaching a tracepoint is: + + {tp|tracepoint}:{p|r}:category:tracepint + +The first field is for the trace event type. It supports five types: kprob= e, +kretprobe, uprobe, uretprobe, and tracepoint ('tp' is also supported as an +abbreviation for "tracepoint"). The second field specifies whether the act= ion is +pause ("p") or resume ("r"). + +For probes, the "function_name" field is used to specify a function name. = In +particular, for a uprobe or uretprobe, an executable path must also be pro= vided. +In the case of a ftrace tracepoint, the "category" and "tracepoint" fields= are +used together to provide complete tracepoint information. + +The '--bpf-aux-pause' option does not support inherit mode. In the default +trace mode, it needs to be combined with the '-i' or '--no-inherit' option= to +disable inherit mode. + +The syntax supports multiple trace events, with each separated by a comma = (,). +For example, users can set up AUX pause on a kernel function with kretprob= e and +AUX resume on a tracepoint with the syntax below: + + For default trace mode (with inherit mode disabled): + perf record -e cs_etm/aux-action=3Dstart-paused/ \ + --bpf-aux-pause=3D"kretprobe:p:__arm64_sys_openat,tp:r:sched:sched_swi= tch" \ + -i ... + + For system wide trace mode: + perf record -e cs_etm/aux-action=3Dstart-paused/ \ + --bpf-aux-pause=3D"kretprobe:p:__arm64_sys_openat,tp:r:sched:sched_swi= tch" \ + -a ... + + For trace with uprobe and uretprobe: + perf record -e cs_etm/aux-action=3Dstart-paused/ \ + --bpf-aux-pause=3D"uretprobe:p:~/sort:bubble_sort,uprobe:r:~/sort:bubb= le_sort" \ + -i --per-thread -- ~/sort + --proc-map-timeout:: When processing pre-existing threads /proc/XXX/mmap, it may take a long ti= me, because the file may be huge. A time out is needed in such cases. --=20 2.34.1