10 files changed, 156 insertions, 67 deletions

diff --git a/tools/perf/Documentation/Makefile b/tools/perf/Documentation/Makefile
index 5a37a7c84e69..3ba1c0b09908 100644
--- a/tools/perf/Documentation/Makefile
+++ b/tools/perf/Documentation/Makefile
@@ -145,16 +145,17 @@ endif
 
 ifneq ($(findstring $(MAKEFLAGS),s),s)
 ifneq ($(V),1)
-        QUIET_ASCIIDOC  = @echo '   ' ASCIIDOC $@;
-        QUIET_XMLTO     = @echo '   ' XMLTO $@;
-        QUIET_DB2TEXI   = @echo '   ' DB2TEXI $@;
-        QUIET_MAKEINFO  = @echo '   ' MAKEINFO $@;
-        QUIET_DBLATEX   = @echo '   ' DBLATEX $@;
-        QUIET_XSLTPROC  = @echo '   ' XSLTPROC $@;
-        QUIET_GEN       = @echo '   ' GEN $@;
+        QUIET_ASCIIDOC  = @echo '  ASCIIDOC '$@;
+        QUIET_XMLTO     = @echo '  XMLTO    '$@;
+        QUIET_DB2TEXI   = @echo '  DB2TEXI  '$@;
+        QUIET_MAKEINFO  = @echo '  MAKEINFO '$@;
+        QUIET_DBLATEX   = @echo '  DBLATEX  '$@;
+        QUIET_XSLTPROC  = @echo '  XSLTPROC '$@;
+        QUIET_GEN       = @echo '  GEN      '$@;
         QUIET_STDERR    = 2> /dev/null
         QUIET_SUBDIR0   = +@subdir=
-        QUIET_SUBDIR1   = ;$(NO_SUBDIR) echo '   ' SUBDIR $$subdir; \
+        QUIET_SUBDIR1   = ;$(NO_SUBDIR) \
+                           echo '  SUBDIR   ' $$subdir; \
                           $(MAKE) $(PRINT_DIR) -C $$subdir
         export V
 endif
@@ -183,47 +184,43 @@ ifdef missing_tools
 endif
 
 do-install-man: man
-        $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
-#       $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
-#       $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
-        $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(man1dir)
-#       $(INSTALL) -m 644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
-#       $(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
+        $(call QUIET_INSTALL, Documentation-man) \
+                $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir); \
+#               $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir); \
+#               $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir); \
+                $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(man1dir); \
+#               $(INSTALL) -m 644 $(DOC_MAN5) $(DESTDIR)$(man5dir); \
+#               $(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
 
 install-man: check-man-tools man
 
-try-install-man:
 ifdef missing_tools
-        $(warning Please install $(missing_tools) to have the man pages installed)
+  DO_INSTALL_MAN = $(warning Please install $(missing_tools) to have the man pages installed)
 else
-        $(MAKE) do-install-man
+  DO_INSTALL_MAN = do-install-man
 endif
 
+try-install-man: $(DO_INSTALL_MAN)
+
 install-info: info
-        $(INSTALL) -d -m 755 $(DESTDIR)$(infodir)
-        $(INSTALL) -m 644 $(OUTPUT)perf.info $(OUTPUT)perfman.info $(DESTDIR)$(infodir)
+        $(call QUIET_INSTALL, Documentation-info) \
+                $(INSTALL) -d -m 755 $(DESTDIR)$(infodir); \
+                $(INSTALL) -m 644 $(OUTPUT)perf.info $(OUTPUT)perfman.info $(DESTDIR)$(infodir); \
         if test -r $(DESTDIR)$(infodir)/dir; then \
-          $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) perf.info ;\
-          $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) perfman.info ;\
+                $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) perf.info ;\
+                $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) perfman.info ;\
         else \
           echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \
         fi
 
 install-pdf: pdf
-        $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
-        $(INSTALL) -m 644 $(OUTPUT)user-manual.pdf $(DESTDIR)$(pdfdir)
+        $(call QUIET_INSTALL, Documentation-pdf) \
+                $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir); \
+                $(INSTALL) -m 644 $(OUTPUT)user-manual.pdf $(DESTDIR)$(pdfdir)
 
 #install-html: html
 #       '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
 
-ifneq ($(MAKECMDGOALS),clean)
-ifneq ($(MAKECMDGOALS),tags)
-$(OUTPUT)PERF-VERSION-FILE: .FORCE-PERF-VERSION-FILE
-        $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) $(OUTPUT)PERF-VERSION-FILE
-
--include $(OUTPUT)PERF-VERSION-FILE
-endif
-endif
 
 #
 # Determine "include::" file references in asciidoc files.
@@ -253,15 +250,17 @@ $(OUTPUT)cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
         $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \
         date >$@
 
+CLEAN_FILES =                                                                   \
+        $(MAN_XML) $(addsuffix +,$(MAN_XML))                                    \
+        $(MAN_HTML) $(addsuffix +,$(MAN_HTML))                                  \
+        $(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7)                         \
+        $(OUTPUT)*.texi $(OUTPUT)*.texi+ $(OUTPUT)*.texi++                      \
+        $(OUTPUT)perf.info $(OUTPUT)perfman.info                                \
+        $(OUTPUT)howto-index.txt $(OUTPUT)howto/*.html $(OUTPUT)doc.dep         \
+        $(OUTPUT)technical/api-*.html $(OUTPUT)technical/api-index.txt          \
+        $(cmds_txt) $(OUTPUT)*.made
 clean:
-        $(RM) $(MAN_XML) $(addsuffix +,$(MAN_XML))
-        $(RM) $(MAN_HTML) $(addsuffix +,$(MAN_HTML))
-        $(RM) $(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7)
-        $(RM) $(OUTPUT)*.texi $(OUTPUT)*.texi+ $(OUTPUT)*.texi++
-        $(RM) $(OUTPUT)perf.info $(OUTPUT)perfman.info
-        $(RM) $(OUTPUT)howto-index.txt $(OUTPUT)howto/*.html $(OUTPUT)doc.dep
-        $(RM) $(OUTPUT)technical/api-*.html $(OUTPUT)technical/api-index.txt
-        $(RM) $(cmds_txt) $(OUTPUT)*.made
+        $(call QUIET_CLEAN, Documentation) $(RM) $(CLEAN_FILES)
 
 $(MAN_HTML): $(OUTPUT)%.html : %.txt
         $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
@@ -342,5 +341,3 @@ $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
 
 #quick-install-html:
 #       '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir)
-
-.PHONY: .FORCE-PERF-VERSION-FILE
diff --git a/tools/perf/Documentation/perf-buildid-cache.txt b/tools/perf/Documentation/perf-buildid-cache.txt
index e9a8349a7172..fd77d81ea748 100644
--- a/tools/perf/Documentation/perf-buildid-cache.txt
+++ b/tools/perf/Documentation/perf-buildid-cache.txt
@@ -21,6 +21,19 @@ OPTIONS
 -a::
 --add=::
         Add specified file to the cache.
+-k::
+--kcore::
+        Add specified kcore file to the cache. For the current host that is
+        /proc/kcore which requires root permissions to read. Be aware that
+        running 'perf buildid-cache' as root may update root's build-id cache
+        not the user's. Use the -v option to see where the file is created.
+        Note that the copied file contains only code sections not the whole core
+        image. Note also that files "kallsyms" and "modules" must also be in the
+        same directory and are also copied.  All 3 files are created with read
+        permissions for root only. kcore will not be added if there is already a
+        kcore in the cache (with the same build-id) that has the same modules at
+        the same addresses. Use the -v option to see if a copy of kcore is
+        actually made.
 -r::
 --remove=::
         Remove specified file from the cache.
diff --git a/tools/perf/Documentation/perf-kvm.txt b/tools/perf/Documentation/perf-kvm.txt
index ac84db2d2334..6a06cefe9642 100644
--- a/tools/perf/Documentation/perf-kvm.txt
+++ b/tools/perf/Documentation/perf-kvm.txt
@@ -109,7 +109,9 @@ STAT LIVE OPTIONS
 
 -m::
 --mmap-pages=::
-    Number of mmap data pages. Must be a power of two.
+    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.
 
 -a::
 --all-cpus::
diff --git a/tools/perf/Documentation/perf-lock.txt b/tools/perf/Documentation/perf-lock.txt
index c7f5f55634ac..ab25be28c9dc 100644
--- a/tools/perf/Documentation/perf-lock.txt
+++ b/tools/perf/Documentation/perf-lock.txt
@@ -48,7 +48,7 @@ REPORT OPTIONS
 -k::
 --key=<value>::
         Sorting key. Possible values: acquired (default), contended,
-        wait_total, wait_max, wait_min.
+        avg_wait, wait_total, wait_max, wait_min.
 
 INFO OPTIONS
 ------------
diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
index e297b74471b8..052f7c4dc00c 100644
--- a/tools/perf/Documentation/perf-record.txt
+++ b/tools/perf/Documentation/perf-record.txt
@@ -87,11 +87,25 @@ OPTIONS
 
 -m::
 --mmap-pages=::
-        Number of mmap data pages. Must be a power of two.
+        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.
 
 -g::
+        Enables call-graph (stack chain/backtrace) recording.
+
 --call-graph::
-        Do call-graph (stack chain/backtrace) recording.
+        Setup and enable call-graph (stack chain/backtrace) recording,
+        implies -g.
+
+        Allows specifying "fp" (frame pointer) or "dwarf"
+        (DWARF's CFI - Call Frame Information) as the method to collect
+        the information used to show the call graphs.
+
+        In some systems, where binaries are build with gcc
+        --fomit-frame-pointer, using the "fp" method will produce bogus
+        call graphs, using "dwarf", if available (perf tools linked to
+        the libunwind library) should be used instead.
 
 -q::
 --quiet::
@@ -166,6 +180,9 @@ following filters are defined:
         - u:  only when the branch target is at the user level
         - k: only when the branch target is in the kernel
         - hv: only when the target is at the hypervisor level
+        - in_tx: only when the target is in a hardware transaction
+        - no_tx: only when the target is not in a hardware transaction
+        - abort_tx: only when the target is a hardware transaction abort
 
 +
 The option requires at least one branch type among any, any_call, any_ret, ind_call.
@@ -176,12 +193,14 @@ is enabled for all the sampling events. The sampled branch type is the same for
 The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
 Note that this feature may not be available on all processors.
 
--W::
 --weight::
 Enable weightened sampling. An additional weight is recorded per sample and can be
 displayed with the weight and local_weight sort keys.  This currently works for TSX
 abort events and some memory events in precise mode on modern Intel CPUs.
 
+--transaction::
+Record transaction flags for transaction related events.
+
 SEE ALSO
 --------
 linkperf:perf-stat[1], linkperf:perf-list[1]
diff --git a/tools/perf/Documentation/perf-report.txt b/tools/perf/Documentation/perf-report.txt
index 2b8097ee39d8..10a279871251 100644
--- a/tools/perf/Documentation/perf-report.txt
+++ b/tools/perf/Documentation/perf-report.txt
@@ -71,7 +71,11 @@ OPTIONS
         entries are displayed as "[other]".
         - cpu: cpu number the task ran at the time of sample
         - srcline: filename and line number executed at the time of sample.  The
-        DWARF debuggin info must be provided.
+        DWARF debugging info must be provided.
+        - weight: Event specific weight, e.g. memory latency or transaction
+        abort cost. This is the global weight.
+        - local_weight: Local weight version of the weight above.
+        - transaction: Transaction abort flags.
 
         By default, comm, dso and symbol keys are used.
         (i.e. --sort comm,dso,symbol)
@@ -85,6 +89,8 @@ OPTIONS
         - symbol_from: name of function branched from
         - symbol_to: name of function branched to
         - mispredict: "N" for predicted branch, "Y" for mispredicted branch
+        - in_tx: branch in TSX transaction
+        - abort: TSX transaction abort.
 
         And default sort keys are changed to comm, dso_from, symbol_from, dso_to
         and symbol_to, see '--branch-stack'.
@@ -135,6 +141,14 @@ OPTIONS
 
         Default: fractal,0.5,callee,function.
 
+--max-stack::
+        Set the stack depth limit when parsing the callchain, anything
+        beyond the specified depth will be ignored. This is a trade-off
+        between information loss and faster processing especially for
+        workloads that can have a very long callchain stack.
+
+        Default: 127
+
 -G::
 --inverted::
         alias for inverted caller based call graph.
diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt
index 73c9759005a3..80c7da6732f2 100644
--- a/tools/perf/Documentation/perf-stat.txt
+++ b/tools/perf/Documentation/perf-stat.txt
@@ -137,6 +137,11 @@ core number and the number of online logical processors on that physical process
 After starting the program, wait msecs before measuring. This is useful to
 filter out the startup phase of the program, which is often very different.
 
+-T::
+--transaction::
+
+Print statistics of transactional execution if supported.
+
 EXAMPLES
 --------
 
diff --git a/tools/perf/Documentation/perf-timechart.txt b/tools/perf/Documentation/perf-timechart.txt
index 1632b0efc757..3ff8bd4f0b4d 100644
--- a/tools/perf/Documentation/perf-timechart.txt
+++ b/tools/perf/Documentation/perf-timechart.txt
@@ -8,7 +8,8 @@ perf-timechart - Tool to visualize total system behavior during a workload
 SYNOPSIS
 --------
 [verse]
-'perf timechart' {record}
+'perf timechart' record <command>
+'perf timechart' [<options>]
 
 DESCRIPTION
 -----------
@@ -41,6 +42,18 @@ OPTIONS
 --symfs=<directory>::
         Look for files with symbols relative to this directory.
 
+EXAMPLES
+--------
+
+$ perf timechart record git pull
+
+  [ perf record: Woken up 13 times to write data ]
+  [ perf record: Captured and wrote 4.253 MB perf.data (~185801 samples) ]
+
+$ perf timechart
+
+  Written 10.2 seconds of trace to output.svg.
+
 SEE ALSO
 --------
 linkperf:perf-record[1]
diff --git a/tools/perf/Documentation/perf-top.txt b/tools/perf/Documentation/perf-top.txt
index 58d6598a9686..7de01dd79688 100644
--- a/tools/perf/Documentation/perf-top.txt
+++ b/tools/perf/Documentation/perf-top.txt
@@ -68,7 +68,9 @@ Default is to monitor all CPUS.
 
 -m <pages>::
 --mmap-pages=<pages>::
-        Number of mmapped data 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.
 
 -p <pid>::
 --pid=<pid>::
@@ -112,7 +114,8 @@ Default is to monitor all CPUS.
 
 -s::
 --sort::
-        Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight, local_weight.
+        Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight,
+        local_weight, abort, in_tx, transaction
 
 -n::
 --show-nr-samples::
@@ -140,20 +143,20 @@ Default is to monitor all CPUS.
 --asm-raw::
         Show raw instruction encoding of assembly instructions.
 
--G [type,min,order]::
+-G::
+        Enables call-graph (stack chain/backtrace) recording.
+
 --call-graph::
-        Display call chains using type, min percent threshold and order.
-        type can be either:
-        - flat: single column, linear exposure of call chains.
-        - graph: use a graph tree, displaying absolute overhead rates.
-        - fractal: like graph, but displays relative rates. Each branch of
-                 the tree is considered as a new profiled object.
-
-        order can be either:
-        - callee: callee based call graph.
-        - caller: inverted caller based call graph.
-
-        Default: fractal,0.5,callee.
+        Setup and enable call-graph (stack chain/backtrace) recording,
+        implies -G.
+
+--max-stack::
+        Set the stack depth limit when parsing the callchain, anything
+        beyond the specified depth will be ignored. This is a trade-off
+        between information loss and faster processing especially for
+        workloads that can have a very long callchain stack.
+
+        Default: 127
 
 --ignore-callees=<regex>::
         Ignore callees of the function(s) matching the given regex.
diff --git a/tools/perf/Documentation/perf-trace.txt b/tools/perf/Documentation/perf-trace.txt
index daccd2c0a48f..7b0497f95a75 100644
--- a/tools/perf/Documentation/perf-trace.txt
+++ b/tools/perf/Documentation/perf-trace.txt
@@ -9,6 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'perf trace'
+'perf trace record'
 
 DESCRIPTION
 -----------
@@ -16,9 +17,14 @@ This command will show the events associated with the target, initially
 syscalls, but other system events like pagefaults, task lifetime events,
 scheduling events, etc.
 
-Initially this is a live mode only tool, but eventually will work with
-perf.data files like the other tools, allowing a detached 'record' from
-analysis phases.
+This is a live mode tool in addition to working with perf.data files like
+the other perf tools. Files can be generated using the 'perf record' command
+but the session needs to include the raw_syscalls events (-e 'raw_syscalls:*').
+Alernatively, the 'perf trace record' can be used as a shortcut to
+automatically include the raw_syscalls events when writing events to a file.
+
+The following options apply to perf trace; options to perf trace record are
+found in the perf record man page.
 
 OPTIONS
 -------
@@ -59,7 +65,9 @@ OPTIONS
 
 -m::
 --mmap-pages=::
-        Number of mmap data pages. Must be a power of two.
+        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.
 
 -C::
 --cpu::
@@ -78,6 +86,21 @@ the thread executes on the designated CPUs. Default is to monitor all CPUs.
 --input
         Process events from a given perf data file.
 
+-T
+--time
+        Print full timestamp rather time relative to first sample.
+
+--comm::
+        Show process COMM right beside its ID, on by default, disable with --no-comm.
+
+--summary::
+        Show a summary of syscalls by thread with min, max, and average times (in
+    msec) and relative stddev.
+
+--tool_stats::
+        Show tool stats such as number of times fd->pathname was discovered thru
+        hooking the open syscall return + vfs_getname or via reading /proc/pid/fd, etc.
+
 SEE ALSO
 --------
 linkperf:perf-record[1], linkperf:perf-script[1]