1 files changed, 482 insertions, 0 deletions
diff --git a/doc/howto_pttc.md b/doc/howto_pttc.md
new file mode 100755
index 0000000000000..02cb597bc2102
--- /dev/null
+++ b/doc/howto_pttc.md
@@ -0,0 +1,482 @@
+Testing the Intel(R) Processor Trace (Intel PT) Decoder Library and Samples {#pttc}
+===========================================================================
+
+<!---
+ ! Copyright (c) 2013-2018, Intel Corporation
+ !
+ ! Redistribution and use in source and binary forms, with or without
+ ! modification, are permitted provided that the following conditions are met:
+ !
+ !  * Redistributions of source code must retain the above copyright notice,
+ !    this list of conditions and the following disclaimer.
+ !  * Redistributions in binary form must reproduce the above copyright notice,
+ !    this list of conditions and the following disclaimer in the documentation
+ !    and/or other materials provided with the distribution.
+ !  * Neither the name of Intel Corporation nor the names of its contributors
+ !    may be used to endorse or promote products derived from this software
+ !    without specific prior written permission.
+ !
+ ! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ ! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ ! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ ! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ ! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ ! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ ! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ ! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ ! POSSIBILITY OF SUCH DAMAGE.
+ !-->
+
+This chapter documents how to use the pttc tool to generate and run tests.
+Pttc takes a yasm assembly file and creates a Processor Trace stream from
+special directives in its input.
+
+
+Usage
+-----
+
+	$ pttc path/to/file.ptt
+
+If no error occurs, the following files will be generated in the current working
+directory:
+
+	file.lst
+	file.bin
+	file.pt
+	file-<tool>.exp
+	file-<src>.sb
+
+The `.lst` and `.bin` files are generated by a call to yasm. The `.pt` file
+contains the Processor Trace and the `.exp` files contain the content of the
+comments after the `.exp` directive for tool `<tool>` (see below).  The `.sb`
+files contain sideband infomrmation from source `<src>` (see below).
+
+Pttc prints the filenames of the generated `.exp` and `.sb` files to stdout.
+
+
+Syntax
+------
+
+Pttc allows annotations in the comments of yasm assembler source files.  The
+parser recognizes all comments that contain the `@pt` directive marker.
+
+Every pt directive can be preceded by a label name followed by a colon (`:`).
+Refer to the description of the `.exp()` and `.sb()` directives below on how to
+use these labels.
+
+The general syntax for pt directives is as follows:
+
+	@pt [label:]directive([arguments])
+
+
+### Intel PT directives
+
+This section lists the directives that are understood by pttc.
+
+
+#### psb, psbend, pad, ovf, stop
+
+	@pt psb()
+	@pt psbend()
+	@pt pad()
+	@pt ovf()
+	@pt stop()
+
+These packets do not have any arguments and correspond to the packets from the
+specification.
+
+
+#### tnt, tnt64
+
+	@pt tnt(args)
+	@pt tnt64(args)
+
+The arguments of the tnt and tnt64 packets is a list of Takens `t` and
+Not-Takens `n`. For better readability an arbitrary number of blanks and dots
+can be intervened.
+
+It is an error if no characters, only blanks or dots, or other characters are in
+the payload. Additionally for the TNT packet and the TNT64 packet it is an error
+to have more than 6 and more than 47 t's or n's in the payload, respectively.
+
+
+#### tip, tip.pge, tip.pgd, fup
+
+	@pt tip(ipc: addr)
+	@pt tip.pge(ipc: addr)
+	@pt tip.pgd(ipc: addr)
+	@pt fup(ipc: addr)
+
+These packets accept arbitrary addresses. `Addr` must be a parsable integer or a
+valid label name. `Ipc` specifies the IP compression bits as integer number.
+
+If `addr` is given as a label, the address is truncated according to the IP
+bytes value given in `ipc`.  Otherwise the address needs to be a zero-extended
+integer no bigger than specified in `ipc`.
+
+
+#### mode.exec, mode.tsx
+
+	@pt mode.exec(mode)
+	@pt mode.tsx(state)
+
+`Mode` must be either `16bit` or `32bit` or `64bit`; `state` must be `begin` or
+`abort` or `commit`.
+
+
+#### pip
+
+	@pt pip(addr[, nr])
+
+Addr is the value that was written to CR3.
+
+If nr is specified after addr, the non-root bit is set.
+
+
+#### tsc
+
+	@pt tsc(value)
+
+Value is the timestamp.
+
+
+#### cbr
+
+	@pt cbr(value)
+
+Value is the core/bus ratio.
+
+
+#### tma
+
+    @pt tma(ctc, fc)
+
+Ctc is the 16bit crystal clock component.
+Fc is the 9bit fast counter component.
+
+
+#### mtc
+
+    @pt mtc(value)
+
+Value is the 8bit crystal clock component.
+
+
+#### cyc
+
+    @pt cyc(value)
+
+Value is the cycle count.
+
+
+#### vmcs
+
+    @pt vmcs(value)
+
+Value is the VMCS base address.  Beware that only bits 12 to 51 will be used.
+The rest will be silently ignored.
+
+
+#### mnt
+
+    @pt mnt(value)
+
+Value is the 8-byte packet payload represented as 64-bit little-endian number.
+
+
+#### exstop
+
+    @pt exstop([ip])
+
+If ip is specified, the IP bit in the packet opcode is set, it is clear
+otherwise.
+
+
+#### mwait
+
+    @pt mwait(hints, ext)
+
+Hints is the 4-byte mwait hints argument in eax.  Ext is the 4-byte extensions
+argument in ecx.
+
+
+#### pwre
+
+    @pt pwre(c-state[, hw])
+
+C-state is a thread C-state with optional sub C-state in the format
+`c<state>[.<sub>]` where both `<state>` and `<sub>` are decimal integer values
+between 0 and 15.  If the sub C-state is not specified, it defaults to c0.
+
+If hw is specified, the C-state entry was initiated by hardware.
+
+
+#### pwrx
+
+    @pt pwrx(wr: last, deepest)
+
+Wr is the wake reason.  It must be `int`, `st`, or `hw`.
+
+Last and deepest are the last and deepest achieved core C-state in the format
+`c<state>` where `<state>` is a decimal integer value between 0 and 15.
+
+
+#### ptw
+
+    @pt ptw(size: payload[, ip])
+
+Size is the payload size; it must be 0 or 1.  Payload is the unsigned integer
+payload.  If ip is specified, the IP bit in the packet opcode is set, it is
+clear otherwise.
+
+
+#### .exp
+
+	@pt .exp([tool])
+
+Every occurrence of this directive prints all the lines, following this
+directive, to a `file[-tool].exp`.
+
+The first occurrence of this directive stops processing of other directives.
+
+In order to have a valid yasm file, it is necessary to put the expected output
+into yasm comments (with the semi-colon character (`;`)). Any character up to
+(and including) the semi-colon is not printed to the `.exp` file. Trailing white
+space is removed from each line.
+
+Comments are made with the `#` character and go to the end of line.  Comments
+and whitespace before comments are not printed in the `.exp` file.
+
+Each line that contains no yasm comment at all is not printed to the exp file.
+Empty lines can be used to structure the expected output text.
+
+In `.exp` files and in sideband directives, the address of a yasm label can be
+substituted using:
+
+	%[?0]label[.<number>].
+
+
+Labels are prefixed with `%`, for example, `%%label`.  A label name can consist
+of alphanumeric characters and underscores.  Labels must be unique.  The address
+of label will be substituted with a hex number including leading `0x`.
+
+Prefixing the label with `0`, for example `%0label`, prints the address with
+leading zeroes using 16 hex digits plus the leading `0x`.
+
+The least significant `n` bytes of an address can be masked by appending `.n` to
+the label.  For example, `%%label.2` with `label` = `0xffffff004c` is printed as
+`0x4c`.
+
+Prefixing the label with `?` in combination with masking replaces the masked out
+parts with `?` using 16 digits for the address plus the leading `0x`.  The
+remaining number is zero extended.  For example, `%?label.2` with `label` =
+`0xc0001` is printed as `0x????????????0001`.
+
+The packet number of pt directives can also be substituted in the output. These
+numbers are printed in decimal. The syntax is as follows:
+
+	%label
+
+
+### Special Labels
+
+There is a special label for the byte offset after the last packet: `%%eos`.
+
+
+Labels in sections are relative to the section's vstart address.  PTTC also adds
+the following special section labels:
+
+ * *section_<name>_start*   gives the section's offset in the binary file
+ * *section_<name>_vstart*  gives the virtual base address of the mapped section
+ * *section_<name>_length*  gives the size of the section in bytes
+
+Beware that PTTC does not support switching back and forth between sections.
+
+
+### Sideband Directives
+
+This section lists the sideband directives that are understood by pttc.
+
+
+#### primary/secondary [requires SIDEBAND]
+
+	@sb primary(format [,src])
+	@sb secondary(format [,src])
+
+Every occurrence of this directive switches the current sideband file to
+`file[-src]-format-primary.sb` or `file[-src]-format-secondary.sb` respectively.
+Every subsequent sideband directive will write to the current sideband file.
+
+A primary sideband file is directly related to the trace.  For example, it may
+contain the sideband information for the traced cpu.  A secondary sideband file
+is indirectly related to the trace.  For example, it may contain the sideband
+information for other cpus on the system.
+
+Sideband directive and Intel PT directives can be mixed.
+
+
+#### raw [requires SIDEBAND]
+
+    @sb raw-8(value)
+    @sb raw-16(value)
+    @sb raw-32(value)
+    @sb raw-64(value)
+
+Writes a raw unsigned 8, 16, 32, or 64 bit value into the current sideband
+stream.
+
+
+#### pevent-sample_type [requires SIDEBAND, PEVENT]
+
+    @sb pevent-sample_type(t1[, t2[, t3[...]]])
+
+Sets the perf_event sample_type for subsequent pevent sideband directives for
+the current sideband file to the bit-wise or '|' of all arguments.  Each
+argument can be:
+
+ * *tid*          representing PERF_SAMPLE_TID
+ * *time*         representing PERF_SAMPLE_TIME
+ * *id*           representing PERF_SAMPLE_ID
+ * *cpu*          representing PERF_SAMPLE_CPU
+ * *stream*       representing PERF_SAMPLE_STREAM_ID
+ * *identifier*   representing PERF_SAMPLE_IDENTIFIER
+ * a 64bit unsigned integer representing a bit-mask of
+   enum perf_event_sample_format values
+
+
+Subsequent perf event record generating directives must provide the specified
+number of sample arguments in the above order order.  The `tid` sample type
+takes two arguments: a pid followed by a tid.
+
+This directive may only be used before the first perf event record generating
+directive.
+
+
+#### pevent-mmap [requires SIDEBAND, PEVENT]
+
+    @sb pevent-mmap(pid, tid, addr, len, pgoff, filename[, samples])
+
+Writes a PERF_RECORD_MMAP event into the current sideband stream describing the
+mapping of filename.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-mmap-section [requires SIDEBAND, PEVENT]
+
+    @sb pevent-mmap-section(name, pid, tid[, samples])
+
+Writes a PERF_RECORD_MMAP event into the current sideband stream describing the
+mapping of section `name` to its vstart address from its start address in the
+test binary.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-lost [requires SIDEBAND, PEVENT]
+
+    @sb pevent-lost(id, lost[, samples])
+
+Writes a PERF_RECORD_LOST event into the current sideband stream describing the
+loss of perf_event records.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-comm [requires SIDEBAND, PEVENT]
+
+    @sb pevent-comm(pid, tid, comm[, samples])
+    @sb pevent-comm.exec(pid, tid, comm[, samples])
+
+Writes a PERF_RECORD_COMM event into the current sideband stream describing the
+command that is being traced.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-exit [requires SIDEBAND, PEVENT]
+
+    @sb pevent-exit(pid, ppid, tid, ptid, time[, samples])
+
+Writes a PERF_RECORD_EXIT event into the current sideband stream describing the
+exiting of the current thread.  The thread is still running in kernel space but
+won't return to user space.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-fork [requires SIDEBAND, PEVENT]
+
+    @sb pevent-fork(pid, ppid, tid, ptid, time[, samples])
+
+Writes a PERF_RECORD_FORK event into the current sideband stream describing the
+creation of a new thread or process.  The event occurs in the context of the
+parent thread.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-aux [requires SIDEBAND, PEVENT]
+
+    @sb pevent-aux(offset, size, flags[, samples])
+
+Writes a PERF_RECORD_AUX event into the current sideband stream describing that
+new data landed in the aux buffer.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-itrace-start [requires SIDEBAND, PEVENT]
+
+    @sb pevent-itrace-start(pid, tid[, samples])
+
+Writes a PERF_RECORD_ITRACE_START event into the current sideband stream
+describing that instruction tracing has started.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-lost-samples [requires SIDEBAND, PEVENT]
+
+    @sb pevent-lost-samples(lost[, samples])
+
+Writes a PERF_RECORD_LOST_SAMPLES event into the current sideband stream
+describing a loss of sample records.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-switch [requires SIDEBAND, PEVENT]
+
+    @sb pevent-switch.in([samples])
+    @sb pevent-switch.out([samples])
+
+Writes a PERF_RECORD_SWITCH event into the current sideband stream describing a
+switch into or out of context.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.
+
+
+#### pevent-switch-cpu-wide [requires SIDEBAND, PEVENT]
+
+    @sb pevent-switch-cpu-wide.in(pid, tid[, samples])
+    @sb pevent-switch-cpu-wide.out(pid, tid[, samples])
+
+Writes a PERF_RECORD_SWITCH_CPU_WIDE event into the current sideband stream
+describing a switch into or out of context.  The `pid` and `tid` arguments give
+the process and thread id of the previous task.
+
+The `samples` argument is a comma-separated list of samples corresponding to the
+pevent-sample_type configuration.