Skip to contentSkip to conversation

perf tools: Fix missing guest option documentation

PATCH Applied Adrian Hunter 2 participants 5 messages Aug 11, 2022

Subsystems (2)
lore
Share & tools
lore

Adrian Hunter

author reviewer
#0 lore raw

cover perf tools: Fix missing guest option documentation

Hi

Here are a couple of small documentation fixes and subsequent corresponding tidy-up.

Adrian Hunter (3):
perf script: Fix missing guest option documentation perf inject: Fix missing guestmount option documentation perf tools: Tidy guest option documentation

 tools/perf/Documentation/guest-files.txt | 16 ++++++++++++++++
 tools/perf/Documentation/guestmount.txt  | 11 +++++++++++
 tools/perf/Documentation/perf-inject.txt |  4 ++++
 tools/perf/Documentation/perf-kvm.txt    | 25 +++++--------------------
 tools/perf/Documentation/perf-script.txt |  6 +++---
 5 files changed, 39 insertions(+), 23 deletions(-)
 create mode 100644 tools/perf/Documentation/guest-files.txt
 create mode 100644 tools/perf/Documentation/guestmount.txt

Regards
Adrian

author reviewer
#1 lore raw

PATCH 1/3 perf script: Fix missing guest option documentation

perf script documentation is missing several options relating to guests. Add them.

Fixes 15a108af1a18 ("perf script: Allow specifying the files to process guest samples")
---
 tools/perf/Documentation/perf-script.txt | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
tools/perf/Documentation/perf-script.txt +23 -0
index 4c95e79e2c39..48ee42a891b6 100644
@@ -487,6 +487,29 @@ include::itrace.txt[]
 	For itrace only show specified functions and their callees for
 	itrace. Multiple functions can be separated by comma.
 
+--guestmount=<path>::
+	Guest OS root file system mount directory. Users mount guest OS
+	root directories under <path> by a specific filesystem access method,
+	typically, sshfs.
+	For example, start 2 guest OS, one's pid is 8888 and the other's is 9999:
+[verse]
+	$ mkdir \~/guestmount
+	$ cd \~/guestmount
+	$ sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/
+	$ sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/
+	$ perf script --guestmount=~/guestmount
+
+--guestkallsyms=<path>::
+	Guest OS /proc/kallsyms file copy. perf reads it to get guest
+	kernel symbols. Users copy it out from guest OS.
+
+--guestmodules=<path>::
+	Guest OS /proc/modules file copy. perf reads it to get guest
+	kernel module information. Users copy it out from guest OS.
+
+--guestvmlinux=<path>::
+	Guest OS kernel vmlinux.
+
 --switch-on EVENT_NAME::
 	Only consider events after this event is found.
 
Signature · 1 line
2.25.1
author reviewer
#2 lore raw

PATCH 2/3 perf inject: Fix missing guestmount option documentation

In reply to Adrian Hunter

perf inject documentation is missing the guestmount option. Add it.

Fixes 97406a7e4fa6 ("perf inject: Add support for injecting guest sideband events")
---
 tools/perf/Documentation/perf-inject.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)
tools/perf/Documentation/perf-inject.txt +12 -0
index 646aa31586ed..c741ca2107b1 100644
@@ -102,6 +102,18 @@ include::itrace.txt[]
 	should be used, and also --buildid-all and --switch-events may be
 	useful.
 
+--guestmount=<path>::
+	Guest OS root file system mount directory. Users mount guest OS
+	root directories under <path> by a specific filesystem access method,
+	typically, sshfs.
+	For example, start 2 guest OS, one's pid is 8888 and the other's is 9999:
+[verse]
+	$ mkdir \~/guestmount
+	$ cd \~/guestmount
+	$ sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/
+	$ sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/
+	$ perf inject --guestmount=~/guestmount
+
 SEE ALSO
 --------
 linkperf:perf-record[1], linkperf:perf-report[1], linkperf:perf-archive[1],
Signature · 1 line
2.25.1
author reviewer
#3 lore raw

PATCH 3/3 perf tools: Tidy guest option documentation

In reply to Adrian Hunter

Move common guest options into include files. Use attribute substitution to customize an example, using "[verse]" to define the block instead of a "literal" block which does not permit substitution.

---
 tools/perf/Documentation/guest-files.txt | 16 +++++++++++++
 tools/perf/Documentation/guestmount.txt  | 11 +++++++++
 tools/perf/Documentation/perf-inject.txt | 14 +++---------
 tools/perf/Documentation/perf-kvm.txt    | 25 ++++----------------
 tools/perf/Documentation/perf-script.txt | 29 +++---------------------
 5 files changed, 38 insertions(+), 57 deletions(-)
 create mode 100644 tools/perf/Documentation/guest-files.txt
 create mode 100644 tools/perf/Documentation/guestmount.txt
tools/perf/Documentation/guest-files.txt new file +16 -0
new file mode 100644
index 000000000000..8cc0b092f996
@@ -0,0 +1,16 @@
+include::guestmount.txt[]
+
+--guestkallsyms=<path>::
+	Guest OS /proc/kallsyms file copy. perf reads it to get guest
+	kernel symbols. Users copy it out from guest OS.
+
+--guestmodules=<path>::
+	Guest OS /proc/modules file copy. perf reads it to get guest
+	kernel module information. Users copy it out from guest OS.
+
+--guestvmlinux=<path>::
+	Guest OS kernel vmlinux.
+
+--guest-code::
+	Indicate that guest code can be found in the hypervisor process,
+	which is a common case for KVM test programs.
tools/perf/Documentation/guestmount.txt new file +11 -0
new file mode 100644
index 000000000000..6edf12363add
@@ -0,0 +1,11 @@
+--guestmount=<path>::
+	Guest OS root file system mount directory. Users mount guest OS
+	root directories under <path> by a specific filesystem access method,
+	typically, sshfs.
+	For example, start 2 guest OS, one's pid is 8888 and the other's is 9999:
+[verse]
+	$ mkdir \~/guestmount
+	$ cd \~/guestmount
+	$ sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/
+	$ sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/
+	$ perf {GMEXAMPLECMD} --guestmount=~/guestmount {GMEXAMPLESUBCMD}
tools/perf/Documentation/perf-inject.txt +3 -11
index c741ca2107b1..ffc293fdf61d 100644
@@ -102,17 +102,9 @@ include::itrace.txt[]
 	should be used, and also --buildid-all and --switch-events may be
 	useful.
 
---guestmount=<path>::
-	Guest OS root file system mount directory. Users mount guest OS
-	root directories under <path> by a specific filesystem access method,
-	typically, sshfs.
-	For example, start 2 guest OS, one's pid is 8888 and the other's is 9999:
-[verse]
-	$ mkdir \~/guestmount
-	$ cd \~/guestmount
-	$ sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/
-	$ sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/
-	$ perf inject --guestmount=~/guestmount
+:GMEXAMPLECMD: inject
+:GMEXAMPLESUBCMD:
+include::guestmount.txt[]
 
 SEE ALSO
 --------
tools/perf/Documentation/perf-kvm.txt +5 -20
index 83c742adf86e..2ad3f5d9f72b 100644
@@ -77,26 +77,11 @@ OPTIONS
         Collect host side performance profile.
 --guest::
         Collect guest side performance profile.
---guestmount=<path>::
-	Guest os root file system mount directory. Users mounts guest os
-        root directories under <path> by a specific filesystem access method,
-	typically, sshfs. For example, start 2 guest os. The one's pid is 8888
-	and the other's is 9999.
-        #mkdir ~/guestmount; cd ~/guestmount
-        #sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/
-        #sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/
-        #perf kvm --host --guest --guestmount=~/guestmount top
---guestkallsyms=<path>::
-        Guest os /proc/kallsyms file copy. 'perf' kvm' reads it to get guest
-	kernel symbols. Users copy it out from guest os.
---guestmodules=<path>::
-	Guest os /proc/modules file copy. 'perf' kvm' reads it to get guest
-	kernel module information. Users copy it out from guest os.
---guestvmlinux=<path>::
-	Guest os kernel vmlinux.
---guest-code::
-	Indicate that guest code can be found in the hypervisor process,
-	which is a common case for KVM test programs.
+
+:GMEXAMPLECMD: kvm --host --guest
+:GMEXAMPLESUBCMD: top
+include::guest-files.txt[]
+
 -v::
 --verbose::
 	Be more verbose (show counter open errors, etc).
tools/perf/Documentation/perf-script.txt +3 -26
index 48ee42a891b6..68e37de5fae4 100644
@@ -487,29 +487,6 @@ include::itrace.txt[]
 	For itrace only show specified functions and their callees for
 	itrace. Multiple functions can be separated by comma.
 
---guestmount=<path>::
-	Guest OS root file system mount directory. Users mount guest OS
-	root directories under <path> by a specific filesystem access method,
-	typically, sshfs.
-	For example, start 2 guest OS, one's pid is 8888 and the other's is 9999:
-[verse]
-	$ mkdir \~/guestmount
-	$ cd \~/guestmount
-	$ sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/
-	$ sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/
-	$ perf script --guestmount=~/guestmount
-
---guestkallsyms=<path>::
-	Guest OS /proc/kallsyms file copy. perf reads it to get guest
-	kernel symbols. Users copy it out from guest OS.
-
---guestmodules=<path>::
-	Guest OS /proc/modules file copy. perf reads it to get guest
-	kernel module information. Users copy it out from guest OS.
-
---guestvmlinux=<path>::
-	Guest OS kernel vmlinux.
-
 --switch-on EVENT_NAME::
 	Only consider events after this event is found.
 
@@ -530,9 +507,9 @@ include::itrace.txt[]
 	The known limitations include exception handing such as
 	setjmp/longjmp will have calls/returns not match.
 
---guest-code::
-	Indicate that guest code can be found in the hypervisor process,
-	which is a common case for KVM test programs.
+:GMEXAMPLECMD: script
+:GMEXAMPLESUBCMD:
+include::guest-files.txt[]
 
 SEE ALSO
 --------
Signature · 1 line
2.25.1
maintainer Applied
#4 lore raw
In reply to Adrian Hunter

Em Thu, Aug 11, 2022 at 08:04:08PM +0300, Adrian Hunter escreveu:

Quoted 4 lines

Hi

Here are a couple of small documentation fixes and subsequent corresponding tidy-up.

Thanks, applied.

- Arnaldo

Quoted 18 lines

Adrian Hunter (3):
perf script: Fix missing guest option documentation perf inject: Fix missing guestmount option documentation perf tools: Tidy guest option documentation

 tools/perf/Documentation/guest-files.txt | 16 ++++++++++++++++
 tools/perf/Documentation/guestmount.txt  | 11 +++++++++++
 tools/perf/Documentation/perf-inject.txt |  4 ++++
 tools/perf/Documentation/perf-kvm.txt    | 25 +++++--------------------
 tools/perf/Documentation/perf-script.txt |  6 +++---
 5 files changed, 39 insertions(+), 23 deletions(-)
 create mode 100644 tools/perf/Documentation/guest-files.txt
 create mode 100644 tools/perf/Documentation/guestmount.txt

Regards
Adrian

Signature · 1 line
- Arnaldo