1=head1 NAME
2
3xentrace - capture Xen trace buffer data
4
5=head1 SYNOPSIS
6
7B<xentrace> [ I<OPTIONS> ] [ I<FILE> ]
8
9=head1 DESCRIPTION
10
11B<xentrace> is used to capture trace buffer data from Xen.  The data is
12output in the following binary format (host endian):
13
14    CPU(uint) TSC(u64) EVENT(u32) D1 D2 D3 D4 D5 (all u32)
15
16Where CPU is the processor number, TSC is the record's timestamp
17(the value of the CPU cycle counter), EVENT is the event ID and
18D1...D5 are the trace data.
19
20Data is dumped onto the standard output (which must not be a TTY) or a
21I<FILE> specified on the command line.
22
23The output should be parsed using the tool xentrace_format, which can
24produce human-readable output in ASCII format.
25
26
27=head1 OPTIONS
28
29=over 4
30
31=item B<-t> I<l>, B<--log-thresh>=I<l>
32
33set the threshold number, I<l>, of new records required to trigger a write of
34all new records to the output
35
36=item B<-s> I<p>, B<--poll-sleep>=I<p>
37
38set the time, I<p>, (in milliseconds) to sleep between polling the buffers
39for new data.
40
41=item B<-c> [I<c>|I<CPU-LIST>|I<all>], B<--cpu-mask>=[I<c>|I<CPU-LIST>|I<all>]
42
43This can be: a hex value (of the form 0xNNNN...), or a set of cpu
44ranges as described below, or the string I<all>. Hex values are limited
45to 32 bits. If not specified, the cpu-mask as set during bootup will be
46constructed. If using the I<CPU-LIST> it expects decimal numbers, which
47may be specified as follows:
48
49  "0-3"
50      Trace only on CPUs 0 through 3
51
52  "0,2,5-7"
53      Trace only on CPUs 0, 2, and 5 through 7
54
55  "-3"
56      Trace only on CPUs 0 through 3
57
58  "-3,7"
59      Trace only on CPUs 0 through 3 and 7
60
61  "3-"
62      Trace only on CPUs 3 up to maximum numbers of CPUs the host has
63
64If using I<all> it will use all of the CPUs the host has.
65
66=item B<-e> I<mask>, B<--evt-mask>=I<mask>
67
68set event capture mask. If not specified the TRC_ALL will be used.
69
70=item B<-?>, B<--help>
71
72Give this help list
73
74=item B<--usage>
75
76Give a short usage message
77
78=item B<-V>, B<--version>
79
80Print program version
81
82=back
83
84=head2 Event Classes (Masks)
85
86The following event classes (masks) can be used to filter the events being
87gathered by xentrace:
88
89        ID                  Description
90
91        0x0001f000          TRC_GEN
92        0x0002f000          TRC_SCHED
93        0x0004f000          TRC_DOM0OP
94        0x0008f000          TRC_HVM
95        0x0010f000          TRC_MEM
96        0xfffff000          TRC_ALL
97
98
99=head2 Event Subclasses (More Masks)
100
101The following event subclasses (masks) can also be used to filter the events being
102gathered by xentrace:
103
104        ID                  Description
105
106        0x00081000          TRC_HVM_ENTRYEXIT
107        0x00082000          TRC_HVM_HANDLER
108
109
110=head2 Events
111
112B<xentrace> collects the following events from the trace buffer:
113
114        ID                 Description
115
116        0x0001f001         TRC_LOST_RECORDS
117        0x0002f001         TRC_SCHED_DOM_ADD
118        0x0002f002         TRC_SCHED_DOM_REM
119        0x0002f003         TRC_SCHED_SLEEP
120        0x0002f004         TRC_SCHED_WAKE
121        0x0002f005         TRC_SCHED_YIELD
122        0x0002f006         TRC_SCHED_BLOCK
123        0x0002f007         TRC_SCHED_SHUTDOWN
124        0x0002f008         TRC_SCHED_CTL
125        0x0002f009         TRC_SCHED_ADJDOM
126        0x0002f010         TRC_SCHED_SWITCH
127        0x0002f011         TRC_SCHED_S_TIMER_FN
128        0x0002f012         TRC_SCHED_T_TIMER_FN
129        0x0002f013         TRC_SCHED_DOM_TIMER_FN
130        0x0002f014         TRC_SCHED_SWITCH_INFPREV
131        0x0002f015         TRC_SCHED_SWITCH_INFNEXT
132
133        0x00081001         TRC_HVM_VMENTRY
134        0x00081002         TRC_HVM_VMEXIT
135        0x00082001         TRC_HVM_PF_XEN
136        0x00082002         TRC_HVM_PF_INJECT
137        0x00082003         TRC_HVM_INJ_EXC
138        0x00082004         TRC_HVM_INJ_VIRQ
139        0x00082005         TRC_HVM_REINJ_VIRQ
140        0x00082006         TRC_HVM_IO_READ
141        0x00082007         TRC_HVM_IO_WRITE
142        0x00082008         TRC_HVM_CR_READ
143        0x00082009         TRC_HVM_CR_WRITE
144        0x0008200A         TRC_HVM_DR_READ
145        0x0008200B         TRC_HVM_DR_WRITE
146        0x0008200C         TRC_HVM_MSR_READ
147        0x0008200D         TRC_HVM_MSR_WRITE
148        0x0008200E         TRC_HVM_CPUID
149        0x0008200F         TRC_HVM_INTR
150        0x00082010         TRC_HVM_NMI
151        0x00082011         TRC_HVM_SMI
152        0x00082012         TRC_HVM_VMMCALL
153        0x00082013         TRC_HVM_HLT
154        0x00082014         TRC_HVM_INVLPG
155
156        0x0010f001         TRC_MEM_PAGE_GRANT_MAP
157        0x0010f002         TRC_MEM_PAGE_GRANT_UNMAP
158        0x0010f003         TRC_MEM_PAGE_GRANT_TRANSFER
159
160=head1 AUTHOR
161
162Mark A. Williamson <mark.a.williamson@intel.com>
163
164=head1 SEE ALSO
165
166xentrace_format(1)
167