[PATCH v2] perf docs: Refine the description for the buffer size

[PATCH v2] perf docs: Refine the description for the buffer size

[Leo Yan]

Current description for the AUX trace buffer size is misleading. When a
user specifies the option '-m,512M', it represents a size value in bytes
(512MiB) but not 512M pages (512M x 4KiB regard to a page of 4KiB).

Make the document clear that the normal buffer and the AUX tracing
buffer share the same semantics. Syncs the documents for consistent
text.

Signed-off-by: Leo Yan <leo.yan@arm.com>
Reviewed-by: James Clark <james.clark@linaro.org>
---

Changes from v1:
 Synced for all documents for consistent description (James)

 tools/perf/Documentation/perf-kvm.txt    | 6 +++---
 tools/perf/Documentation/perf-record.txt | 9 +++++----
 tools/perf/Documentation/perf-top.txt    | 4 ++--
 tools/perf/Documentation/perf-trace.txt  | 4 ++--
 4 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/tools/perf/Documentation/perf-kvm.txt b/tools/perf/Documentation/perf-kvm.txt
index b66be66fe836..c26524d38f47 100644
--- a/tools/perf/Documentation/perf-kvm.txt
+++ b/tools/perf/Documentation/perf-kvm.txt
@@ -115,9 +115,9 @@ STAT LIVE OPTIONS
 
 -m::
 --mmap-pages=::
-    Number of mmap data pages (must be a power of two) or size
-    specification with appended unit character - B/K/M/G. The
-    size is rounded up to have nearest pages power of two value.
+        Number of mmap data pages (must be a power of two) or size
+        specification in bytes with appended unit character - B/K/M/G.
+        The size is rounded up to the nearest power-of-two page value.
 
 -a::
 --all-cpus::
diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
index 41e36b4dc765..242223240a08 100644
--- a/tools/perf/Documentation/perf-record.txt
+++ b/tools/perf/Documentation/perf-record.txt
@@ -273,10 +273,11 @@ OPTIONS
 -m::
 --mmap-pages=::
 	Number of mmap data pages (must be a power of two) or size
-	specification with appended unit character - B/K/M/G. The
-	size is rounded up to have nearest pages power of two value.
-	Also, by adding a comma, the number of mmap pages for AUX
-	area tracing can be specified.
+	specification in bytes with appended unit character - B/K/M/G.
+	The size is rounded up to the nearest power-of-two page value.
+	By adding a comma, an additional parameter with the same
+	semantics used for the normal mmap areas can be specified for
+	AUX tracing area.
 
 -g::
 	Enables call-graph (stack chain/backtrace) recording for both
diff --git a/tools/perf/Documentation/perf-top.txt b/tools/perf/Documentation/perf-top.txt
index 667e5102075e..af3e4230c72f 100644
--- a/tools/perf/Documentation/perf-top.txt
+++ b/tools/perf/Documentation/perf-top.txt
@@ -83,8 +83,8 @@ Default is to monitor all CPUS.
 -m <pages>::
 --mmap-pages=<pages>::
 	Number of mmap data pages (must be a power of two) or size
-	specification with appended unit character - B/K/M/G. The
-	size is rounded up to have nearest pages power of two value.
+	specification in bytes with appended unit character - B/K/M/G.
+	The size is rounded up to the nearest power-of-two page value.
 
 -p <pid>::
 --pid=<pid>::
diff --git a/tools/perf/Documentation/perf-trace.txt b/tools/perf/Documentation/perf-trace.txt
index f0da8cf63e9a..6e0cc50bbc13 100644
--- a/tools/perf/Documentation/perf-trace.txt
+++ b/tools/perf/Documentation/perf-trace.txt
@@ -106,8 +106,8 @@ filter out the startup phase of the program, which is often very different.
 -m::
 --mmap-pages=::
 	Number of mmap data pages (must be a power of two) or size
-	specification with appended unit character - B/K/M/G. The
-	size is rounded up to have nearest pages power of two value.
+	specification in bytes with appended unit character - B/K/M/G.
+	The size is rounded up to the nearest power-of-two page value.
 
 -C::
 --cpu::
-- 
2.34.1

Re: [PATCH v2] perf docs: Refine the description for the buffer size

[Arnaldo Carvalho de Melo]

On Mon, Aug 12, 2024 at 10:34:59AM +0100, Leo Yan wrote:
> Current description for the AUX trace buffer size is misleading. When a
> user specifies the option '-m,512M', it represents a size value in bytes
> (512MiB) but not 512M pages (512M x 4KiB regard to a page of 4KiB).
> 
> Make the document clear that the normal buffer and the AUX tracing
> buffer share the same semantics. Syncs the documents for consistent
> text.
> 
> Signed-off-by: Leo Yan <leo.yan@arm.com>
> Reviewed-by: James Clark <james.clark@linaro.org>
> ---
> 
> Changes from v1:
>  Synced for all documents for consistent description (James)

Thanks, applied to tmp.perf-tools-next,

- Arnaldo
 
>  tools/perf/Documentation/perf-kvm.txt    | 6 +++---
>  tools/perf/Documentation/perf-record.txt | 9 +++++----
>  tools/perf/Documentation/perf-top.txt    | 4 ++--
>  tools/perf/Documentation/perf-trace.txt  | 4 ++--
>  4 files changed, 12 insertions(+), 11 deletions(-)
> 
> diff --git a/tools/perf/Documentation/perf-kvm.txt b/tools/perf/Documentation/perf-kvm.txt
> index b66be66fe836..c26524d38f47 100644
> --- a/tools/perf/Documentation/perf-kvm.txt
> +++ b/tools/perf/Documentation/perf-kvm.txt
> @@ -115,9 +115,9 @@ STAT LIVE OPTIONS
>  
>  -m::
>  --mmap-pages=::
> -    Number of mmap data pages (must be a power of two) or size
> -    specification with appended unit character - B/K/M/G. The
> -    size is rounded up to have nearest pages power of two value.
> +        Number of mmap data pages (must be a power of two) or size
> +        specification in bytes with appended unit character - B/K/M/G.
> +        The size is rounded up to the nearest power-of-two page value.
>  
>  -a::
>  --all-cpus::
> diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
> index 41e36b4dc765..242223240a08 100644
> --- a/tools/perf/Documentation/perf-record.txt
> +++ b/tools/perf/Documentation/perf-record.txt
> @@ -273,10 +273,11 @@ OPTIONS
>  -m::
>  --mmap-pages=::
>  	Number of mmap data pages (must be a power of two) or size
> -	specification with appended unit character - B/K/M/G. The
> -	size is rounded up to have nearest pages power of two value.
> -	Also, by adding a comma, the number of mmap pages for AUX
> -	area tracing can be specified.
> +	specification in bytes with appended unit character - B/K/M/G.
> +	The size is rounded up to the nearest power-of-two page value.
> +	By adding a comma, an additional parameter with the same
> +	semantics used for the normal mmap areas can be specified for
> +	AUX tracing area.
>  
>  -g::
>  	Enables call-graph (stack chain/backtrace) recording for both
> diff --git a/tools/perf/Documentation/perf-top.txt b/tools/perf/Documentation/perf-top.txt
> index 667e5102075e..af3e4230c72f 100644
> --- a/tools/perf/Documentation/perf-top.txt
> +++ b/tools/perf/Documentation/perf-top.txt
> @@ -83,8 +83,8 @@ Default is to monitor all CPUS.
>  -m <pages>::
>  --mmap-pages=<pages>::
>  	Number of mmap data pages (must be a power of two) or size
> -	specification with appended unit character - B/K/M/G. The
> -	size is rounded up to have nearest pages power of two value.
> +	specification in bytes with appended unit character - B/K/M/G.
> +	The size is rounded up to the nearest power-of-two page value.
>  
>  -p <pid>::
>  --pid=<pid>::
> diff --git a/tools/perf/Documentation/perf-trace.txt b/tools/perf/Documentation/perf-trace.txt
> index f0da8cf63e9a..6e0cc50bbc13 100644
> --- a/tools/perf/Documentation/perf-trace.txt
> +++ b/tools/perf/Documentation/perf-trace.txt
> @@ -106,8 +106,8 @@ filter out the startup phase of the program, which is often very different.
>  -m::
>  --mmap-pages=::
>  	Number of mmap data pages (must be a power of two) or size
> -	specification with appended unit character - B/K/M/G. The
> -	size is rounded up to have nearest pages power of two value.
> +	specification in bytes with appended unit character - B/K/M/G.
> +	The size is rounded up to the nearest power-of-two page value.
>  
>  -C::
>  --cpu::
> -- 
> 2.34.1