perf tools: Tidy guest option documentation

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.

Signed-off-by: Adrian Hunter <adrian.hunter@intel.com>
Cc: Ian Rogers <irogers@google.com>
Cc: Jiri Olsa <jolsa@kernel.org>
Cc: Namhyung Kim <namhyung@kernel.org>
Link: https://lore.kernel.org/r/20220811170411.84154-4-adrian.hunter@intel.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>

diff --git a/tools/perf/Documentation/guest-files.txt b/tools/perf/Documentation/guest-files.txt
new file mode 100644 (file)
index 0000000..8cc0b09
--- /dev/null
+++ b/tools/perf/Documentation/guest-files.txt
@@ -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.

diff --git a/tools/perf/Documentation/guestmount.txt b/tools/perf/Documentation/guestmount.txt
new file mode 100644 (file)
index 0000000..6edf123
--- /dev/null
+++ b/tools/perf/Documentation/guestmount.txt
@@ -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}

diff --git a/tools/perf/Documentation/perf-inject.txt b/tools/perf/Documentation/perf-inject.txt
index c741ca2..ffc293f 100644 (file)
--- a/tools/perf/Documentation/perf-inject.txt
+++ b/tools/perf/Documentation/perf-inject.txt
@@ -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
 --------

diff --git a/tools/perf/Documentation/perf-kvm.txt b/tools/perf/Documentation/perf-kvm.txt
index 83c742a..2ad3f5d 100644 (file)
--- a/tools/perf/Documentation/perf-kvm.txt
+++ b/tools/perf/Documentation/perf-kvm.txt
@@ -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).

diff --git a/tools/perf/Documentation/perf-script.txt b/tools/perf/Documentation/perf-script.txt
index 48ee42a..68e37de 100644 (file)
--- a/tools/perf/Documentation/perf-script.txt
+++ b/tools/perf/Documentation/perf-script.txt
@@ -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
 --------