[patch 2/2] man: man pages for ptrace BTS extension

[Markus Metzger <markus.t.metzger@intel.com>]

Resend using different email client


Changes to the last version:
- ported to v 2.68

Signed-off-by: Markus Metzger <markus.t.metzger@intel.com>
Signed-off-by: Suresh Siddha <suresh.b.siddha@intel.com>
---

Index: man-pages-2.68/man2/ptrace.2
===================================================================
--- man-pages-2.68.orig/man2/ptrace.2	2007-11-30 17:22:59.%N +0100
+++ man-pages-2.68/man2/ptrace.2	2007-11-30 17:26:48.%N +0100
@@ -40,6 +40,9 @@
 .\"        PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP
 .\"    (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.)
 .\"
+.\" Modified Nov 2007, Markus Metzger <markus.t.metzger@intel.com>
+.\"     Added PTRACE_BTS_* commands
+.\"
 .TH PTRACE 2 2007-11-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
 ptrace \- process trace
@@ -378,6 +381,95 @@
 detached in this way regardless of which method was used to initiate
 tracing.
 (\fIaddr\fP is ignored.)
+.LP
+The following ptrace commands provide access to the hardware's last
+branch recording. They may not be available on all architectures.
+.LP
+Last branch recording stores an execution trace of the traced process
+in a circular buffer (called Branch Trace Store). For every
+(conditional) control flow change, the source and destination address
+are stored. On some architectures, control flow changes inside the
+kernel may be recorded, as well. On later architectures, these are
+automatically filtered out.
+.LP
+In addition to branches, timestamps may optionally be recorded when
+the traced process arrives and departs, respectively. This information
+can be used to obtain a qualitative execution order, if more than one
+process is traced.
+.LP
+.nf
+enum ptrace_bts_qualifier {
+	PTRACE_BTS_INVALID = 0,
+	PTRACE_BTS_BRANCH,
+	PTRACE_BTS_TASK_ARRIVES,
+	PTRACE_BTS_TASK_DEPARTS
+};
+.sp
+struct ptrace_bts_record {
+	enum ptrace_bts_qualifier qualifier;
+	union {
+		/* PTRACE_BTS_BRANCH */
+		struct {
+			void *from_ip;
+			void *to_ip;
+		} lbr;
+		/* PTRACE_BTS_TASK_ARRIVES or
+		   PTRACE_BTS_TASK_DEPARTS */
+		unsigned long long timestamp;
+	} variant;
+};
+.fi
+.LP
+.TP
+PTRACE_BTS_MAX_BUFFER_SIZE
+Returns the maximal BTS buffer size.
+.TP
+PTRACE_BTS_ALLOCATE_BUFFER
+Allocate a new BTS buffer big enough to hold \fIdata\fP \fBstruct
+ptrace_bts_record\fP entries.
+\fIData\fP must be in the range of 0..PTRACE_BTS_MAX_BUFFER_SIZE.
+If a buffer is already allocated, that buffer is freed after the new
+buffer was successfully allocated. The new buffer initially contains
+invalid entries.
+Typically, a buffer is allocated once when tracing starts. It is
+automatically deallocated when the parent detaches from the child.
+(\fIaddr\fP is ignored.)
+.TP
+PTRACE_BTS_GET_BUFFER_SIZE
+Returns the actual BTS buffer size in number of BTS records. The
+command fails, if no buffer has been allocated.
+(\fIaddr\fP and \fIdata\fP are ignored.)
+.TP
+PTRACE_BTS_GET_INDEX
+Returns the index of the next entry to be (over)written by the tracing
+hardware. This can be used to determine the end of the current
+execution trace.
+(\fIaddr\fP and \fIdata\fP are ignored.)
+.TP
+PTRACE_BTS_READ_RECORD
+Reads the BTS record at index \fIdata\fP into \fIaddr\fP. The caller
+is responsible for allocating memory at \fIaddr\fP of at least
+\fB sizeof(struct ptrace_bts_record)\fP bytes. The index \fIdata\fP
+must be in the range 0..PTRACE_BTS_GET_BUFFER_SIZE - 1.
+.TP
+PTRACE_BTS_CONFIG
+Configures last branch recording from \fIdata\fP in the parent.
+(\fIaddr\fP is ignored.)
+\fIdata\fP is interpreted
+as a bitmask of options, which are specified by the following flags:
+.RS
+.TP
+PTRACE_BTS_O_TRACE_TASK
+Record last branch records for control flow changes.
+.TP
+PTRACE_BTS_O_TIMESTAMPS
+Record timestamps when child arrives and departs, respectively.
+.RE
+.TP
+PTRACE_BTS_STATUS
+Returns the current BTS configuration as a bitmask of the above
+options.
+(\fIaddr\fP and \fIdata\fP are ignored.)
 .SH "RETURN VALUE"
 On success,
 .B PTRACE_PEEK*
@@ -432,6 +524,16 @@
 .B ESRCH
 The specified process does not exist, or is not currently being traced
 by the caller, or is not stopped (for requests that require that).
+.TP
+.B EOPNOTSUPP
+The operation is not supported on this architecture.
+.TP
+.B ENOMEM
+Not enough memory to allocate the BTS buffer.
+.TP
+.B ENXIO
+An attempt to access BTS information has been made without allocating
+a BTS buffer first.
 .SH "CONFORMING TO"
 SVr4, 4.3BSD
 .SH NOTES
---------------------------------------------------------------------
Intel GmbH
Dornacher Strasse 1
85622 Feldkirchen/Muenchen Germany
Sitz der Gesellschaft: Feldkirchen bei Muenchen
Geschaeftsfuehrer: Douglas Lusk, Peter Gleissner, Hannes Schwaderer
Registergericht: Muenchen HRB 47456 Ust.-IdNr.
VAT Registration No.: DE129385895
Citibank Frankfurt (BLZ 502 109 00) 600119052

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.