aboutsummaryrefslogtreecommitdiffstats
path: root/tools/perf/Documentation
diff options
context:
space:
mode:
authorIngo Molnar <mingo@elte.hu>2009-06-06 14:33:43 -0400
committerIngo Molnar <mingo@elte.hu>2009-06-06 14:33:43 -0400
commit864709302a80f26fa9da3be5b47304f0b8bae192 (patch)
tree8c2bab78f141fe43a38914bd3e3aae0a88f958e5 /tools/perf/Documentation
parent75b5032212641f6d38ac041416945e70da833b68 (diff)
perf_counter tools: Move from Documentation/perf_counter/ to tools/perf/
Several people have suggested that 'perf' has become a full-fledged tool that should be moved out of Documentation/. Move it to the (new) tools/ directory. Cc: Peter Zijlstra <a.p.zijlstra@chello.nl> Cc: Mike Galbraith <efault@gmx.de> Cc: Paul Mackerras <paulus@samba.org> Cc: Arnaldo Carvalho de Melo <acme@redhat.com> LKML-Reference: <new-submission> Signed-off-by: Ingo Molnar <mingo@elte.hu>
Diffstat (limited to 'tools/perf/Documentation')
-rw-r--r--tools/perf/Documentation/Makefile300
-rw-r--r--tools/perf/Documentation/asciidoc.conf91
-rw-r--r--tools/perf/Documentation/manpage-1.72.xsl14
-rw-r--r--tools/perf/Documentation/manpage-base.xsl35
-rw-r--r--tools/perf/Documentation/manpage-bold-literal.xsl17
-rw-r--r--tools/perf/Documentation/manpage-normal.xsl13
-rw-r--r--tools/perf/Documentation/manpage-suppress-sp.xsl21
-rw-r--r--tools/perf/Documentation/perf-annotate.txt29
-rw-r--r--tools/perf/Documentation/perf-help.txt38
-rw-r--r--tools/perf/Documentation/perf-list.txt25
-rw-r--r--tools/perf/Documentation/perf-record.txt42
-rw-r--r--tools/perf/Documentation/perf-report.txt26
-rw-r--r--tools/perf/Documentation/perf-stat.txt66
-rw-r--r--tools/perf/Documentation/perf-top.txt39
-rw-r--r--tools/perf/Documentation/perf.txt24
15 files changed, 780 insertions, 0 deletions
diff --git a/tools/perf/Documentation/Makefile b/tools/perf/Documentation/Makefile
new file mode 100644
index 000000000000..5457192e1b41
--- /dev/null
+++ b/tools/perf/Documentation/Makefile
@@ -0,0 +1,300 @@
1MAN1_TXT= \
2 $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
3 $(wildcard perf-*.txt)) \
4 perf.txt
5MAN5_TXT=
6MAN7_TXT=
7
8MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
9MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
10MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
11
12DOC_HTML=$(MAN_HTML)
13
14ARTICLES =
15# with their own formatting rules.
16SP_ARTICLES =
17API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
18SP_ARTICLES += $(API_DOCS)
19SP_ARTICLES += technical/api-index
20
21DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
22
23DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))
24DOC_MAN5=$(patsubst %.txt,%.5,$(MAN5_TXT))
25DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT))
26
27prefix?=$(HOME)
28bindir?=$(prefix)/bin
29htmldir?=$(prefix)/share/doc/perf-doc
30pdfdir?=$(prefix)/share/doc/perf-doc
31mandir?=$(prefix)/share/man
32man1dir=$(mandir)/man1
33man5dir=$(mandir)/man5
34man7dir=$(mandir)/man7
35# DESTDIR=
36
37ASCIIDOC=asciidoc
38ASCIIDOC_EXTRA =
39MANPAGE_XSL = manpage-normal.xsl
40XMLTO_EXTRA =
41INSTALL?=install
42RM ?= rm -f
43DOC_REF = origin/man
44HTML_REF = origin/html
45
46infodir?=$(prefix)/share/info
47MAKEINFO=makeinfo
48INSTALL_INFO=install-info
49DOCBOOK2X_TEXI=docbook2x-texi
50DBLATEX=dblatex
51ifndef PERL_PATH
52 PERL_PATH = /usr/bin/perl
53endif
54
55-include ../config.mak.autogen
56-include ../config.mak
57
58#
59# For asciidoc ...
60# -7.1.2, no extra settings are needed.
61# 8.0-, set ASCIIDOC8.
62#
63
64#
65# For docbook-xsl ...
66# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0)
67# 1.69.0, no extra settings are needed?
68# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP?
69# 1.71.1, no extra settings are needed?
70# 1.72.0, set DOCBOOK_XSL_172.
71# 1.73.0-, set ASCIIDOC_NO_ROFF
72#
73
74#
75# If you had been using DOCBOOK_XSL_172 in an attempt to get rid
76# of 'the ".ft C" problem' in your generated manpages, and you
77# instead ended up with weird characters around callouts, try
78# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8).
79#
80
81ifdef ASCIIDOC8
82ASCIIDOC_EXTRA += -a asciidoc7compatible
83endif
84ifdef DOCBOOK_XSL_172
85ASCIIDOC_EXTRA += -a perf-asciidoc-no-roff
86MANPAGE_XSL = manpage-1.72.xsl
87else
88 ifdef ASCIIDOC_NO_ROFF
89 # docbook-xsl after 1.72 needs the regular XSL, but will not
90 # pass-thru raw roff codes from asciidoc.conf, so turn them off.
91 ASCIIDOC_EXTRA += -a perf-asciidoc-no-roff
92 endif
93endif
94ifdef MAN_BOLD_LITERAL
95XMLTO_EXTRA += -m manpage-bold-literal.xsl
96endif
97ifdef DOCBOOK_SUPPRESS_SP
98XMLTO_EXTRA += -m manpage-suppress-sp.xsl
99endif
100
101SHELL_PATH ?= $(SHELL)
102# Shell quote;
103SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
104
105#
106# Please note that there is a minor bug in asciidoc.
107# The version after 6.0.3 _will_ include the patch found here:
108# http://marc.theaimsgroup.com/?l=perf&m=111558757202243&w=2
109#
110# Until that version is released you may have to apply the patch
111# yourself - yes, all 6 characters of it!
112#
113
114QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir
115QUIET_SUBDIR1 =
116
117ifneq ($(findstring $(MAKEFLAGS),w),w)
118PRINT_DIR = --no-print-directory
119else # "make -w"
120NO_SUBDIR = :
121endif
122
123ifneq ($(findstring $(MAKEFLAGS),s),s)
124ifndef V
125 QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@;
126 QUIET_XMLTO = @echo ' ' XMLTO $@;
127 QUIET_DB2TEXI = @echo ' ' DB2TEXI $@;
128 QUIET_MAKEINFO = @echo ' ' MAKEINFO $@;
129 QUIET_DBLATEX = @echo ' ' DBLATEX $@;
130 QUIET_XSLTPROC = @echo ' ' XSLTPROC $@;
131 QUIET_GEN = @echo ' ' GEN $@;
132 QUIET_STDERR = 2> /dev/null
133 QUIET_SUBDIR0 = +@subdir=
134 QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \
135 $(MAKE) $(PRINT_DIR) -C $$subdir
136 export V
137endif
138endif
139
140all: html man
141
142html: $(DOC_HTML)
143
144$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7): asciidoc.conf
145
146man: man1 man5 man7
147man1: $(DOC_MAN1)
148man5: $(DOC_MAN5)
149man7: $(DOC_MAN7)
150
151info: perf.info perfman.info
152
153pdf: user-manual.pdf
154
155install: install-man
156
157install-man: man
158 $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
159# $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
160# $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
161 $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(man1dir)
162# $(INSTALL) -m 644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
163# $(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
164
165install-info: info
166 $(INSTALL) -d -m 755 $(DESTDIR)$(infodir)
167 $(INSTALL) -m 644 perf.info perfman.info $(DESTDIR)$(infodir)
168 if test -r $(DESTDIR)$(infodir)/dir; then \
169 $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) perf.info ;\
170 $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) perfman.info ;\
171 else \
172 echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \
173 fi
174
175install-pdf: pdf
176 $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
177 $(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)
178
179install-html: html
180 '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
181
182../PERF-VERSION-FILE: .FORCE-PERF-VERSION-FILE
183 $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) PERF-VERSION-FILE
184
185-include ../PERF-VERSION-FILE
186
187#
188# Determine "include::" file references in asciidoc files.
189#
190doc.dep : $(wildcard *.txt) build-docdep.perl
191 $(QUIET_GEN)$(RM) $@+ $@ && \
192 $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \
193 mv $@+ $@
194
195-include doc.dep
196
197cmds_txt = cmds-ancillaryinterrogators.txt \
198 cmds-ancillarymanipulators.txt \
199 cmds-mainporcelain.txt \
200 cmds-plumbinginterrogators.txt \
201 cmds-plumbingmanipulators.txt \
202 cmds-synchingrepositories.txt \
203 cmds-synchelpers.txt \
204 cmds-purehelpers.txt \
205 cmds-foreignscminterface.txt
206
207$(cmds_txt): cmd-list.made
208
209cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
210 $(QUIET_GEN)$(RM) $@ && \
211 $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \
212 date >$@
213
214clean:
215 $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
216 $(RM) *.texi *.texi+ *.texi++ perf.info perfman.info
217 $(RM) howto-index.txt howto/*.html doc.dep
218 $(RM) technical/api-*.html technical/api-index.txt
219 $(RM) $(cmds_txt) *.made
220
221$(MAN_HTML): %.html : %.txt
222 $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
223 $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
224 $(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) -o $@+ $< && \
225 mv $@+ $@
226
227%.1 %.5 %.7 : %.xml
228 $(QUIET_XMLTO)$(RM) $@ && \
229 xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
230
231%.xml : %.txt
232 $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
233 $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
234 $(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) -o $@+ $< && \
235 mv $@+ $@
236
237XSLT = docbook.xsl
238XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
239
240user-manual.html: user-manual.xml
241 $(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<
242
243perf.info: user-manual.texi
244 $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi
245
246user-manual.texi: user-manual.xml
247 $(QUIET_DB2TEXI)$(RM) $@+ $@ && \
248 $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \
249 $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \
250 rm $@++ && \
251 mv $@+ $@
252
253user-manual.pdf: user-manual.xml
254 $(QUIET_DBLATEX)$(RM) $@+ $@ && \
255 $(DBLATEX) -o $@+ -p /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -s /etc/asciidoc/dblatex/asciidoc-dblatex.sty $< && \
256 mv $@+ $@
257
258perfman.texi: $(MAN_XML) cat-texi.perl
259 $(QUIET_DB2TEXI)$(RM) $@+ $@ && \
260 ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
261 --to-stdout $(xml) &&) true) > $@++ && \
262 $(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
263 rm $@++ && \
264 mv $@+ $@
265
266perfman.info: perfman.texi
267 $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi
268
269$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
270 $(QUIET_DB2TEXI)$(RM) $@+ $@ && \
271 $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \
272 mv $@+ $@
273
274howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
275 $(QUIET_GEN)$(RM) $@+ $@ && \
276 '$(SHELL_PATH_SQ)' ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \
277 mv $@+ $@
278
279$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
280 $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 $*.txt
281
282WEBDOC_DEST = /pub/software/tools/perf/docs
283
284$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
285 $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
286 sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+ && \
287 mv $@+ $@
288
289install-webdoc : html
290 '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST)
291
292quick-install: quick-install-man
293
294quick-install-man:
295 '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(DOC_REF) $(DESTDIR)$(mandir)
296
297quick-install-html:
298 '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir)
299
300.PHONY: .FORCE-PERF-VERSION-FILE
diff --git a/tools/perf/Documentation/asciidoc.conf b/tools/perf/Documentation/asciidoc.conf
new file mode 100644
index 000000000000..356b23a40339
--- /dev/null
+++ b/tools/perf/Documentation/asciidoc.conf
@@ -0,0 +1,91 @@
1## linkperf: macro
2#
3# Usage: linkperf:command[manpage-section]
4#
5# Note, {0} is the manpage section, while {target} is the command.
6#
7# Show PERF link as: <command>(<section>); if section is defined, else just show
8# the command.
9
10[macros]
11(?su)[\\]?(?P<name>linkperf):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
12
13[attributes]
14asterisk=&#42;
15plus=&#43;
16caret=&#94;
17startsb=&#91;
18endsb=&#93;
19tilde=&#126;
20
21ifdef::backend-docbook[]
22[linkperf-inlinemacro]
23{0%{target}}
24{0#<citerefentry>}
25{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
26{0#</citerefentry>}
27endif::backend-docbook[]
28
29ifdef::backend-docbook[]
30ifndef::perf-asciidoc-no-roff[]
31# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
32# v1.72 breaks with this because it replaces dots not in roff requests.
33[listingblock]
34<example><title>{title}</title>
35<literallayout>
36ifdef::doctype-manpage[]
37&#10;.ft C&#10;
38endif::doctype-manpage[]
39|
40ifdef::doctype-manpage[]
41&#10;.ft&#10;
42endif::doctype-manpage[]
43</literallayout>
44{title#}</example>
45endif::perf-asciidoc-no-roff[]
46
47ifdef::perf-asciidoc-no-roff[]
48ifdef::doctype-manpage[]
49# The following two small workarounds insert a simple paragraph after screen
50[listingblock]
51<example><title>{title}</title>
52<literallayout>
53|
54</literallayout><simpara></simpara>
55{title#}</example>
56
57[verseblock]
58<formalpara{id? id="{id}"}><title>{title}</title><para>
59{title%}<literallayout{id? id="{id}"}>
60{title#}<literallayout>
61|
62</literallayout>
63{title#}</para></formalpara>
64{title%}<simpara></simpara>
65endif::doctype-manpage[]
66endif::perf-asciidoc-no-roff[]
67endif::backend-docbook[]
68
69ifdef::doctype-manpage[]
70ifdef::backend-docbook[]
71[header]
72template::[header-declarations]
73<refentry>
74<refmeta>
75<refentrytitle>{mantitle}</refentrytitle>
76<manvolnum>{manvolnum}</manvolnum>
77<refmiscinfo class="source">perf</refmiscinfo>
78<refmiscinfo class="version">{perf_version}</refmiscinfo>
79<refmiscinfo class="manual">perf Manual</refmiscinfo>
80</refmeta>
81<refnamediv>
82 <refname>{manname}</refname>
83 <refpurpose>{manpurpose}</refpurpose>
84</refnamediv>
85endif::backend-docbook[]
86endif::doctype-manpage[]
87
88ifdef::backend-xhtml11[]
89[linkperf-inlinemacro]
90<a href="{target}.html">{target}{0?({0})}</a>
91endif::backend-xhtml11[]
diff --git a/tools/perf/Documentation/manpage-1.72.xsl b/tools/perf/Documentation/manpage-1.72.xsl
new file mode 100644
index 000000000000..b4d315cb8c47
--- /dev/null
+++ b/tools/perf/Documentation/manpage-1.72.xsl
@@ -0,0 +1,14 @@
1<!-- manpage-1.72.xsl:
2 special settings for manpages rendered from asciidoc+docbook
3 handles peculiarities in docbook-xsl 1.72.0 -->
4<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
5 version="1.0">
6
7<xsl:import href="manpage-base.xsl"/>
8
9<!-- these are the special values for the roff control characters
10 needed for docbook-xsl 1.72.0 -->
11<xsl:param name="git.docbook.backslash">&#x2593;</xsl:param>
12<xsl:param name="git.docbook.dot" >&#x2302;</xsl:param>
13
14</xsl:stylesheet>
diff --git a/tools/perf/Documentation/manpage-base.xsl b/tools/perf/Documentation/manpage-base.xsl
new file mode 100644
index 000000000000..a264fa616093
--- /dev/null
+++ b/tools/perf/Documentation/manpage-base.xsl
@@ -0,0 +1,35 @@
1<!-- manpage-base.xsl:
2 special formatting for manpages rendered from asciidoc+docbook -->
3<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
4 version="1.0">
5
6<!-- these params silence some output from xmlto -->
7<xsl:param name="man.output.quietly" select="1"/>
8<xsl:param name="refentry.meta.get.quietly" select="1"/>
9
10<!-- convert asciidoc callouts to man page format;
11 git.docbook.backslash and git.docbook.dot params
12 must be supplied by another XSL file or other means -->
13<xsl:template match="co">
14 <xsl:value-of select="concat(
15 $git.docbook.backslash,'fB(',
16 substring-after(@id,'-'),')',
17 $git.docbook.backslash,'fR')"/>
18</xsl:template>
19<xsl:template match="calloutlist">
20 <xsl:value-of select="$git.docbook.dot"/>
21 <xsl:text>sp&#10;</xsl:text>
22 <xsl:apply-templates/>
23 <xsl:text>&#10;</xsl:text>
24</xsl:template>
25<xsl:template match="callout">
26 <xsl:value-of select="concat(
27 $git.docbook.backslash,'fB',
28 substring-after(@arearefs,'-'),
29 '. ',$git.docbook.backslash,'fR')"/>
30 <xsl:apply-templates/>
31 <xsl:value-of select="$git.docbook.dot"/>
32 <xsl:text>br&#10;</xsl:text>
33</xsl:template>
34
35</xsl:stylesheet>
diff --git a/tools/perf/Documentation/manpage-bold-literal.xsl b/tools/perf/Documentation/manpage-bold-literal.xsl
new file mode 100644
index 000000000000..608eb5df6281
--- /dev/null
+++ b/tools/perf/Documentation/manpage-bold-literal.xsl
@@ -0,0 +1,17 @@
1<!-- manpage-bold-literal.xsl:
2 special formatting for manpages rendered from asciidoc+docbook -->
3<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
4 version="1.0">
5
6<!-- render literal text as bold (instead of plain or monospace);
7 this makes literal text easier to distinguish in manpages
8 viewed on a tty -->
9<xsl:template match="literal">
10 <xsl:value-of select="$git.docbook.backslash"/>
11 <xsl:text>fB</xsl:text>
12 <xsl:apply-templates/>
13 <xsl:value-of select="$git.docbook.backslash"/>
14 <xsl:text>fR</xsl:text>
15</xsl:template>
16
17</xsl:stylesheet>
diff --git a/tools/perf/Documentation/manpage-normal.xsl b/tools/perf/Documentation/manpage-normal.xsl
new file mode 100644
index 000000000000..a48f5b11f3dc
--- /dev/null
+++ b/tools/perf/Documentation/manpage-normal.xsl
@@ -0,0 +1,13 @@
1<!-- manpage-normal.xsl:
2 special settings for manpages rendered from asciidoc+docbook
3 handles anything we want to keep away from docbook-xsl 1.72.0 -->
4<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
5 version="1.0">
6
7<xsl:import href="manpage-base.xsl"/>
8
9<!-- these are the normal values for the roff control characters -->
10<xsl:param name="git.docbook.backslash">\</xsl:param>
11<xsl:param name="git.docbook.dot" >.</xsl:param>
12
13</xsl:stylesheet>
diff --git a/tools/perf/Documentation/manpage-suppress-sp.xsl b/tools/perf/Documentation/manpage-suppress-sp.xsl
new file mode 100644
index 000000000000..a63c7632a87d
--- /dev/null
+++ b/tools/perf/Documentation/manpage-suppress-sp.xsl
@@ -0,0 +1,21 @@
1<!-- manpage-suppress-sp.xsl:
2 special settings for manpages rendered from asciidoc+docbook
3 handles erroneous, inline .sp in manpage output of some
4 versions of docbook-xsl -->
5<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
6 version="1.0">
7
8<!-- attempt to work around spurious .sp at the tail of the line
9 that some versions of docbook stylesheets seem to add -->
10<xsl:template match="simpara">
11 <xsl:variable name="content">
12 <xsl:apply-templates/>
13 </xsl:variable>
14 <xsl:value-of select="normalize-space($content)"/>
15 <xsl:if test="not(ancestor::authorblurb) and
16 not(ancestor::personblurb)">
17 <xsl:text>&#10;&#10;</xsl:text>
18 </xsl:if>
19</xsl:template>
20
21</xsl:stylesheet>
diff --git a/tools/perf/Documentation/perf-annotate.txt b/tools/perf/Documentation/perf-annotate.txt
new file mode 100644
index 000000000000..c9dcade06831
--- /dev/null
+++ b/tools/perf/Documentation/perf-annotate.txt
@@ -0,0 +1,29 @@
1perf-annotate(1)
2==============
3
4NAME
5----
6perf-annotate - Read perf.data (created by perf record) and display annotated code
7
8SYNOPSIS
9--------
10[verse]
11'perf annotate' [-i <file> | --input=file] symbol_name
12
13DESCRIPTION
14-----------
15This command reads the input file and displays an annotated version of the
16code. If the object file has debug symbols then the source code will be
17displayed alongside assembly code.
18
19If there is no debug info in the object, then annotated assembly is displayed.
20
21OPTIONS
22-------
23-i::
24--input=::
25 Input file name. (default: perf.data)
26
27SEE ALSO
28--------
29linkperf:perf-record[1]
diff --git a/tools/perf/Documentation/perf-help.txt b/tools/perf/Documentation/perf-help.txt
new file mode 100644
index 000000000000..514391818d1f
--- /dev/null
+++ b/tools/perf/Documentation/perf-help.txt
@@ -0,0 +1,38 @@
1perf-help(1)
2============
3
4NAME
5----
6perf-help - display help information about perf
7
8SYNOPSIS
9--------
10'perf help' [-a|--all] [COMMAND]
11
12DESCRIPTION
13-----------
14
15With no options and no COMMAND given, the synopsis of the 'perf'
16command and a list of the most commonly used perf commands are printed
17on the standard output.
18
19If the option '--all' or '-a' is given, then all available commands are
20printed on the standard output.
21
22If a perf command is named, a manual page for that command is brought
23up. The 'man' program is used by default for this purpose, but this
24can be overridden by other options or configuration variables.
25
26Note that `perf --help ...` is identical to `perf help ...` because the
27former is internally converted into the latter.
28
29OPTIONS
30-------
31-a::
32--all::
33 Prints all the available commands on the standard output. This
34 option supersedes any other option.
35
36PERF
37----
38Part of the linkperf:perf[1] suite
diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt
new file mode 100644
index 000000000000..8290b9422668
--- /dev/null
+++ b/tools/perf/Documentation/perf-list.txt
@@ -0,0 +1,25 @@
1perf-list(1)
2============
3
4NAME
5----
6perf-list - List all symbolic event types
7
8SYNOPSIS
9--------
10[verse]
11'perf list'
12
13DESCRIPTION
14-----------
15This command displays the symbolic event types which can be selected in the
16various perf commands with the -e option.
17
18OPTIONS
19-------
20None
21
22SEE ALSO
23--------
24linkperf:perf-stat[1], linkperf:perf-top[1],
25linkperf:perf-record[1]
diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
new file mode 100644
index 000000000000..1dbc1eeb4c01
--- /dev/null
+++ b/tools/perf/Documentation/perf-record.txt
@@ -0,0 +1,42 @@
1perf-record(1)
2==============
3
4NAME
5----
6perf-record - Run a command and record its profile into perf.data
7
8SYNOPSIS
9--------
10[verse]
11'perf record' [-e <EVENT> | --event=EVENT] [-l] [-a] <command>
12'perf record' [-e <EVENT> | --event=EVENT] [-l] [-a] -- <command> [<options>]
13
14DESCRIPTION
15-----------
16This command runs a command and gathers a performance counter profile
17from it, into perf.data - without displaying anything.
18
19This file can then be inspected later on, using 'perf report'.
20
21
22OPTIONS
23-------
24<command>...::
25 Any command you can specify in a shell.
26
27-e::
28--event=::
29 Select the PMU event. Selection can be a symbolic event name
30 (use 'perf list' to list all events) or a raw PMU
31 event (eventsel+umask) in the form of rNNN where NNN is a
32 hexadecimal event descriptor.
33
34-a::
35 system-wide collection
36
37-l::
38 scale counter values
39
40SEE ALSO
41--------
42linkperf:perf-stat[1], linkperf:perf-list[1]
diff --git a/tools/perf/Documentation/perf-report.txt b/tools/perf/Documentation/perf-report.txt
new file mode 100644
index 000000000000..52d3fc6846a9
--- /dev/null
+++ b/tools/perf/Documentation/perf-report.txt
@@ -0,0 +1,26 @@
1perf-report(1)
2==============
3
4NAME
5----
6perf-report - Read perf.data (created by perf record) and display the profile
7
8SYNOPSIS
9--------
10[verse]
11'perf report' [-i <file> | --input=file]
12
13DESCRIPTION
14-----------
15This command displays the performance counter profile information recorded
16via perf report.
17
18OPTIONS
19-------
20-i::
21--input=::
22 Input file name. (default: perf.data)
23
24SEE ALSO
25--------
26linkperf:perf-stat[1]
diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt
new file mode 100644
index 000000000000..c368a72721d7
--- /dev/null
+++ b/tools/perf/Documentation/perf-stat.txt
@@ -0,0 +1,66 @@
1perf-stat(1)
2============
3
4NAME
5----
6perf-stat - Run a command and gather performance counter statistics
7
8SYNOPSIS
9--------
10[verse]
11'perf stat' [-e <EVENT> | --event=EVENT] [-l] [-a] <command>
12'perf stat' [-e <EVENT> | --event=EVENT] [-l] [-a] -- <command> [<options>]
13
14DESCRIPTION
15-----------
16This command runs a command and gathers performance counter statistics
17from it.
18
19
20OPTIONS
21-------
22<command>...::
23 Any command you can specify in a shell.
24
25
26-e::
27--event=::
28 Select the PMU event. Selection can be a symbolic event name
29 (use 'perf list' to list all events) or a raw PMU
30 event (eventsel+umask) in the form of rNNN where NNN is a
31 hexadecimal event descriptor.
32
33-i::
34--inherit::
35 child tasks inherit counters
36-p::
37--pid=<pid>::
38 stat events on existing pid
39
40-a::
41 system-wide collection
42
43-l::
44 scale counter values
45
46EXAMPLES
47--------
48
49$ perf stat -- make -j
50
51 Performance counter stats for 'make -j':
52
53 8117.370256 task clock ticks # 11.281 CPU utilization factor
54 678 context switches # 0.000 M/sec
55 133 CPU migrations # 0.000 M/sec
56 235724 pagefaults # 0.029 M/sec
57 24821162526 CPU cycles # 3057.784 M/sec
58 18687303457 instructions # 2302.138 M/sec
59 172158895 cache references # 21.209 M/sec
60 27075259 cache misses # 3.335 M/sec
61
62 Wall-clock time elapsed: 719.554352 msecs
63
64SEE ALSO
65--------
66linkperf:perf-top[1], linkperf:perf-list[1]
diff --git a/tools/perf/Documentation/perf-top.txt b/tools/perf/Documentation/perf-top.txt
new file mode 100644
index 000000000000..539d01289725
--- /dev/null
+++ b/tools/perf/Documentation/perf-top.txt
@@ -0,0 +1,39 @@
1perf-top(1)
2===========
3
4NAME
5----
6perf-top - Run a command and profile it
7
8SYNOPSIS
9--------
10[verse]
11'perf top' [-e <EVENT> | --event=EVENT] [-l] [-a] <command>
12
13DESCRIPTION
14-----------
15This command runs a command and gathers a performance counter profile
16from it.
17
18
19OPTIONS
20-------
21<command>...::
22 Any command you can specify in a shell.
23
24-e::
25--event=::
26 Select the PMU event. Selection can be a symbolic event name
27 (use 'perf list' to list all events) or a raw PMU
28 event (eventsel+umask) in the form of rNNN where NNN is a
29 hexadecimal event descriptor.
30
31-a::
32 system-wide collection
33
34-l::
35 scale counter values
36
37SEE ALSO
38--------
39linkperf:perf-stat[1], linkperf:perf-list[1]
diff --git a/tools/perf/Documentation/perf.txt b/tools/perf/Documentation/perf.txt
new file mode 100644
index 000000000000..69c832557199
--- /dev/null
+++ b/tools/perf/Documentation/perf.txt
@@ -0,0 +1,24 @@
1perf(1)
2=======
3
4NAME
5----
6perf - Performance analysis tools for Linux
7
8SYNOPSIS
9--------
10[verse]
11'perf' [--version] [--help] COMMAND [ARGS]
12
13DESCRIPTION
14-----------
15Performance counters for Linux are are a new kernel-based subsystem
16that provide a framework for all things performance analysis. It
17covers hardware level (CPU/PMU, Performance Monitoring Unit) features
18and software features (software counters, tracepoints) as well.
19
20SEE ALSO
21--------
22linkperf:perf-stat[1], linkperf:perf-top[1],
23linkperf:perf-record[1], linkperf:perf-report[1],
24linkperf:perf-list[1]