Xen project Mailing List

[Xen-changelog] [xen master] docs: Move xentrace.8 to docs/man/xentrace.pod.8

Date: Tue, 01 Sep 2015 10:57:07 +0000

Delivery-date: Tue, 01 Sep 2015 10:57:11 +0000

List-id: "Change log for Mercurial $receive only$" <xen-changelog.lists.xen.org>

commit 7b21214a3a8d8427bb1242f1cb5f138154ff5600 Author: Andrew Cooper <andrew.cooper3@xxxxxxxxxx> AuthorDate: Wed Aug 26 09:15:20 2015 +0000 Commit: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx> CommitDate: Thu Aug 27 19:14:35 2015 +0100 docs: Move xentrace.8 to docs/man/xentrace.pod.8 And transform to POD to match our other manpages. The content is identical, although the formatting was altered slightly to conform to more usual manpage layout. Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx> Acked-by: Wei Liu <wei.liu2@xxxxxxxxxx> --- docs/man/xentrace.pod.8 | 166 +++++++++++++++++++++++++++++++++++++++++++++ tools/xentrace/Makefile | 3 - tools/xentrace/xentrace.8 | 164 -------------------------------------------- 3 files changed, 166 insertions(+), 167 deletions(-) diff --git a/docs/man/xentrace.pod.8 b/docs/man/xentrace.pod.8 new file mode 100644 index 0000000..69aef05 --- /dev/null +++ b/docs/man/xentrace.pod.8 @@ -0,0 +1,166 @@ +=head1 NAME + +xentrace - capture Xen trace buffer data + +=head1 SYNOPSIS + +B<xentrace> [ I<OPTIONS> ] [ I<FILE> ] + +=head1 DESCRIPTION + +B<xentrace> is used to capture trace buffer data from Xen. The data is +output in the following binary format (host endian): + + CPU(uint) TSC(u64) EVENT(u32) D1 D2 D3 D4 D5 (all u32) + +Where CPU is the processor number, TSC is the record's timestamp +(the value of the CPU cycle counter), EVENT is the event ID and +D1...D5 are the trace data. + +Data is dumped onto the standard output (which must not be a TTY) or a +I<FILE> specified on the command line. + +The output should be parsed using the tool xentrace_format, which can +produce human-readable output in ASCII format. + + +=head1 OPTIONS + +=over 4 + +=item B<-t> I<l>, B<--log-thresh>=I<l> + +set the threshold number, I<l>, of new records required to trigger a write of +all new records to the output + +=item B<-s> I<p>, B<--poll-sleep>=I<p> + +set the time, I<p>, (in milliseconds) to sleep between polling the buffers +for new data. + +=item B<-c> [I<c>|I<CPU-LIST>|I<all>], B<--cpu-mask>=[I<c>|I<CPU-LIST>|I<all>] + +This can be: a hex value (of the form 0xNNNN...), or a set of cpu +ranges as described below, or the string I<all>. Hex values are limited +to 32 bits. If not specified, the cpu-mask as set during bootup will be +constructed. If using the I<CPU-LIST> it expects decimal numbers, which +may be specified as follows: + + "0-3" + Trace only on CPUs 0 through 3 + + "0,2,5-7" + Trace only on CPUs 0, 2, and 5 through 7 + + "-3" + Trace only on CPUs 0 through 3 + + "-3,7" + Trace only on CPUs 0 through 3 and 7 + + "3-" + Trace only on CPUs 3 up to maximum numbers of CPUs the host has + +If using I<all> it will use all of the CPUs the host has. + +=item B<-e> I<mask>, B<--evt-mask>=I<mask> + +set event capture mask. If not specified the TRC_ALL will be used. + +=item B<-?>, B<--help> + +Give this help list + +=item B<--usage> + +Give a short usage message + +=item B<-V>, B<--version> + +Print program version + +=back + +=head2 Event Classes (Masks) + +The following event classes (masks) can be used to filter the events being +gathered by xentrace: + + ID Description + + 0x0001f000 TRC_GEN + 0x0002f000 TRC_SCHED + 0x0004f000 TRC_DOM0OP + 0x0008f000 TRC_HVM + 0x0010f000 TRC_MEM + 0xfffff000 TRC_ALL + + +=head2 Event Subclasses (More Masks) + +The following event subclasses (masks) can also be used to filter the events being +gathered by xentrace: + + ID Description + + 0x00081000 TRC_HVM_ENTRYEXIT + 0x00082000 TRC_HVM_HANDLER + + +=head2 Events + +B<xentrace> collects the following events from the trace buffer: + + ID Description + + 0x0001f001 TRC_LOST_RECORDS + 0x0002f001 TRC_SCHED_DOM_ADD + 0x0002f002 TRC_SCHED_DOM_REM + 0x0002f003 TRC_SCHED_SLEEP + 0x0002f004 TRC_SCHED_WAKE + 0x0002f005 TRC_SCHED_YIELD + 0x0002f006 TRC_SCHED_BLOCK + 0x0002f007 TRC_SCHED_SHUTDOWN + 0x0002f008 TRC_SCHED_CTL + 0x0002f009 TRC_SCHED_ADJDOM + 0x0002f010 TRC_SCHED_SWITCH + 0x0002f011 TRC_SCHED_S_TIMER_FN + 0x0002f012 TRC_SCHED_T_TIMER_FN + 0x0002f013 TRC_SCHED_DOM_TIMER_FN + 0x0002f014 TRC_SCHED_SWITCH_INFPREV + 0x0002f015 TRC_SCHED_SWITCH_INFNEXT + + 0x00081001 TRC_HVM_VMENTRY + 0x00081002 TRC_HVM_VMEXIT + 0x00082001 TRC_HVM_PF_XEN + 0x00082002 TRC_HVM_PF_INJECT + 0x00082003 TRC_HVM_INJ_EXC + 0x00082004 TRC_HVM_INJ_VIRQ + 0x00082005 TRC_HVM_REINJ_VIRQ + 0x00082006 TRC_HVM_IO_READ + 0x00082007 TRC_HVM_IO_WRITE + 0x00082008 TRC_HVM_CR_READ + 0x00082009 TRC_HVM_CR_WRITE + 0x0008200A TRC_HVM_DR_READ + 0x0008200B TRC_HVM_DR_WRITE + 0x0008200C TRC_HVM_MSR_READ + 0x0008200D TRC_HVM_MSR_WRITE + 0x0008200E TRC_HVM_CPUID + 0x0008200F TRC_HVM_INTR + 0x00082010 TRC_HVM_NMI + 0x00082011 TRC_HVM_SMI + 0x00082012 TRC_HVM_VMMCALL + 0x00082013 TRC_HVM_HLT + 0x00082014 TRC_HVM_INVLPG + + 0x0010f001 TRC_MEM_PAGE_GRANT_MAP + 0x0010f002 TRC_MEM_PAGE_GRANT_UNMAP + 0x0010f003 TRC_MEM_PAGE_GRANT_TRANSFER + +=head1 AUTHOR + +Mark A. Williamson <mark.a.williamson@xxxxxxxxx> + +=head1 SEE ALSO + +xentrace_format(1) diff --git a/tools/xentrace/Makefile b/tools/xentrace/Makefile index 41caccb..6c13cd1 100644 --- a/tools/xentrace/Makefile +++ b/tools/xentrace/Makefile @@ -11,7 +11,6 @@ BIN = $(BIN-y) SBIN = xentrace xentrace_setsize LIBBIN = xenctx SCRIPTS = xentrace_format -MAN8 = $(wildcard *.8) .PHONY: all all: build @@ -24,14 +23,12 @@ install: build $(INSTALL_DIR) $(DESTDIR)$(bindir) $(INSTALL_DIR) $(DESTDIR)$(sbindir) [ -z "$(LIBBIN)" ] || $(INSTALL_DIR) $(DESTDIR)$(LIBEXEC_BIN) - $(INSTALL_DIR) $(DESTDIR)$(MAN8DIR) ifneq ($(BIN),) $(INSTALL_PROG) $(BIN) $(DESTDIR)$(bindir) endif $(INSTALL_PROG) $(SBIN) $(DESTDIR)$(sbindir) $(INSTALL_PYTHON_PROG) $(SCRIPTS) $(DESTDIR)$(bindir) [ -z "$(LIBBIN)" ] || $(INSTALL_PROG) $(LIBBIN) $(DESTDIR)$(LIBEXEC_BIN) - $(INSTALL_DATA) $(MAN8) $(DESTDIR)$(MAN8DIR) .PHONY: clean clean: diff --git a/tools/xentrace/xentrace.8 b/tools/xentrace/xentrace.8 deleted file mode 100644 index 7b3172b..0000000 --- a/tools/xentrace/xentrace.8 +++ /dev/null @@ -1,164 +0,0 @@ -.TH XENTRACE 8 "22 February 2007" "Xen domain 0 utils" -.SH NAME -xentrace \- capture Xen trace buffer data -.SH SYNOPSIS -.B xentrace -[ -.I OPTIONS -] [ -.I FILE -] -.SH DESCRIPTION -.B xentrace -is used to capture trace buffer data from Xen. The data is -output in the following binary format (host endian): -.PP - CPU(uint) TSC(u64) EVENT(u32) D1 D2 D3 D4 D5 (all u32) -.PP -Where CPU is the processor number, TSC is the record's timestamp -(the value of the CPU cycle counter), EVENT is the event ID and -D1...D5 are the trace data. - -Data is dumped onto the standard output (which must not be a TTY) or a -\fIFILE\fP specified on the command line. - -The output should be parsed using the tool xentrace_format, which can -produce human-readable output in ASCII format. - - -.SS Options -.TP -.B -t, --log-thresh=l -set the threshold number, l, of new records required to trigger a write of -all new records to the output -.TP -.B -s, --poll-sleep=p -set the time, p, (in milliseconds) to sleep between polling the buffers -for new data. -.TP -.B -c, --cpu-mask=[\fIc\fP|\fICPU-LIST\fP|\fIall\fP] -This can be: a hex value (of the form 0xNNNN...), or a set of cpu -ranges as described below, or the string \fIall\fP. Hex values are limited -to 32 bits. If not specified, the cpu-mask as set during bootup will be -constructed. If using the \fICPU-LIST\fP it expects decimal numbers, which -may be specified as follows: - -.RS 4 -.ie n .IP """0-3""" 4 -.el .IP "``0-3''" 4 -.IX Item "0-3" -Trace only on CPUs 0 through 3 -.ie n .IP """0,2,5-7""" 4 -.el .IP "``0,2,5-7''" 4 -.IX Item "0,2,5-7" -Trace only on CPUs 0, 2, and 5 through 7. -.ie n .IP """-3""" 4 -.el .IP "``-3''" 4 -.IX Item "-3" -Trace only on CPUs 0 through 3 -.ie n .IP """-3,7""" 4 -.el .IP "``-3,7''" 4 -.IX Item "-3,7" -Trace only on CPUs 0 through 3 and 7 -.ie n .IP """3-""" 4 -.el .IP "``3-''" 4 -.IX Item "-3-" -Trace only on CPUs 3 up to maximum numbers of CPUs the host has. -.RE -.Sp - -If using \fIall\fP it will use all of the CPUs the host has. -.TP -.B -e, --evt-mask=e -set event capture mask. If not specified the TRC_ALL will be used. -.TP -.B -?, --help -Give this help list -.TP -.B --usage -Give a short usage message -.TP -.B -V, --version -Print program version - -.SS Event Classes (Masks) -The following event classes (masks) can be used to filter the events being -gathered by xentrace: -.PP - \fIID\fP \fIDescription\fP -.PP - 0x0001f000 TRC_GEN - 0x0002f000 TRC_SCHED - 0x0004f000 TRC_DOM0OP - 0x0008f000 TRC_HVM - 0x0010f000 TRC_MEM - 0xfffff000 TRC_ALL - - -.SS Event Subclasses (More Masks) -The following event subclasses (masks) can also be used to filter the events being -gathered by xentrace: -.PP - \fIID\fP \fIDescription\fP -.PP - 0x00081000 TRC_HVM_ENTRYEXIT - 0x00082000 TRC_HVM_HANDLER - - -.SS Events -.B xentrace -collects the following events from the trace buffer: -.PP - \fIID\fP \fIDescription\fP -.PP - 0x0001f001 TRC_LOST_RECORDS - 0x0002f001 TRC_SCHED_DOM_ADD - 0x0002f002 TRC_SCHED_DOM_REM - 0x0002f003 TRC_SCHED_SLEEP - 0x0002f004 TRC_SCHED_WAKE - 0x0002f005 TRC_SCHED_YIELD - 0x0002f006 TRC_SCHED_BLOCK - 0x0002f007 TRC_SCHED_SHUTDOWN - 0x0002f008 TRC_SCHED_CTL - 0x0002f009 TRC_SCHED_ADJDOM - 0x0002f010 TRC_SCHED_SWITCH - 0x0002f011 TRC_SCHED_S_TIMER_FN - 0x0002f012 TRC_SCHED_T_TIMER_FN - 0x0002f013 TRC_SCHED_DOM_TIMER_FN - 0x0002f014 TRC_SCHED_SWITCH_INFPREV - 0x0002f015 TRC_SCHED_SWITCH_INFNEXT - - 0x00081001 TRC_HVM_VMENTRY - 0x00081002 TRC_HVM_VMEXIT - 0x00082001 TRC_HVM_PF_XEN - 0x00082002 TRC_HVM_PF_INJECT - 0x00082003 TRC_HVM_INJ_EXC - 0x00082004 TRC_HVM_INJ_VIRQ - 0x00082005 TRC_HVM_REINJ_VIRQ - 0x00082006 TRC_HVM_IO_READ - 0x00082007 TRC_HVM_IO_WRITE - 0x00082008 TRC_HVM_CR_READ - 0x00082009 TRC_HVM_CR_WRITE - 0x0008200A TRC_HVM_DR_READ - 0x0008200B TRC_HVM_DR_WRITE - 0x0008200C TRC_HVM_MSR_READ - 0x0008200D TRC_HVM_MSR_WRITE - 0x0008200E TRC_HVM_CPUID - 0x0008200F TRC_HVM_INTR - 0x00082010 TRC_HVM_NMI - 0x00082011 TRC_HVM_SMI - 0x00082012 TRC_HVM_VMMCALL - 0x00082013 TRC_HVM_HLT - 0x00082014 TRC_HVM_INVLPG - - 0x0010f001 TRC_MEM_PAGE_GRANT_MAP - 0x0010f002 TRC_MEM_PAGE_GRANT_UNMAP - 0x0010f003 TRC_MEM_PAGE_GRANT_TRANSFER - -.PP - -.SH AUTHOR -Mark A. Williamson <mark.a.williamson@xxxxxxxxx> - -.SH "SEE ALSO" -xentrace_format(1) -- generated by git-patchbot for /home/xen/git/xen.git#master _______________________________________________ Xen-changelog mailing list Xen-changelog@xxxxxxxxxxxxx http://lists.xensource.com/xen-changelog

©2013 Xen Project, A Linux Foundation Collaborative Project. All Rights Reserved.
Linux Foundation is a registered trademark of The Linux Foundation.
Xen Project is a trademark of The Linux Foundation.