[patch 5/5] x86, ptrace, man: man pages for ptrace BTS extensions
Document changes for this patch set.
Signed-off-by: Markus Metzger <[EMAIL PROTECTED]>
---
Index: man/man2/ptrace.2
===
--- man.orig/man2/ptrace.2 2007-12-14 17:45:33.%N +0100
+++ man/man2/ptrace.2 2007-12-20 13:20:07.%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 <[EMAIL PROTECTED]>
+.\" Added PTRACE_BTS_* commands
+.\"
.TH PTRACE 2 2007-11-15 "Linux" "Linux Programmer's Manual"
.SH NAME
ptrace \- process trace
@@ -378,6 +381,131 @@
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. For every (conditional) control flow change, the source and
+destination address are stored. On some architectures, control flow
+changes inside the kernel are recorded, as well. On later
+architectures, these are automatically filtered out.
+.LP
+The buffer (called Branch Trace Store) can be configured to be either
+circular, or to send a signal to the traced task when it is about to
+overflow. Not all methods may be available on all architectures.
+.LP
+The buffer can be accessed in two ways matching the above
+configurations: either as an array of BTS records from newest
+record to older records, one record at a time; or all records at once,
+from oldest to newest.
+.LP
+The former is mostly used for circular buffers to capture a tail of
+the execution trace (e.g. for debugging); the latter is mostly used to
+collect a continuous trace (e.g. for profiling) where the user drains
+the hardware buffer into a larger private buffer or into a file.
+.LP
+In addition to branches, timestamps (in jiffies) 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
+A BTS record is defined as:
+.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 {
+ u64 qualifier;
+ union {
+ /* PTRACE_BTS_BRANCH */
+ struct {
+ u64 from_ip;
+ u64 to_ip;
+ } lbr;
+ /* PTRACE_BTS_TASK_ARRIVES or
+ PTRACE_BTS_TASK_DEPARTS */
+ u64 timestamp;
+ } variant;
+};
+.fi
+.LP
+For configuring last branch recording and for querying its status, the
+following struct is used:
+.LP
+.nf
+struct ptrace_bts_config {
+ unsigned int size;
+ unsigned int flags;
+ unsigned int signal;
+};
+.fi
+.LP
+\fISize\fP is either the requested or the actual size of the kernel
+BTS buffer in bytes.
+\fIFlags\fP is a bitmask of options, which are specified by the
+following flags:
+.RS
+.TP
+.BR PTRACE_BTS_O_TRACE
+Collect branch trace records
+.TP
+.BR PTRACE_BTS_O_SCHED
+Collect scheduling timing information
+.TP
+.BR PTRACE_BTS_O_SIGNAL
+Send \fIsignal\fP to the traced task in case of a buffer overflow
+.TP
+.BR PTRACE_BTS_O_CUT_SIZE
+Reduce the requested buffer size if it is bigger than the available
+buffer size.
+.RE
+\fISignal\fP is the signal to send to the traced task in case of a
+buffer overflow.
+.TP
+.BR PTRACE_BTS_CONFIG
+Configure last branch recording. \fIaddr\fP points to a
+\fIptrace_bts_config\fP structure (see above); \fIdata\fP specifies
+the size of that structure.
+Returns the number of bytes read.
+.TP
+.BR PTRACE_BTS_STATUS
+Writes the actual configuration into a \fIptrace_bts_config\fP
+structure pointed to by \fIaddr\fP. The caller is responsible for
+allocating memory at \fIaddr\fP to hold a \fIptrace_bts_config\fP
+structure. \fIData\fP specifies the size of that structure.
+Returns the number of bytes written.
+.TP
+.BR PTRACE_BTS_SIZE
+Returns the number of BTS records available for draining. For a
+circular buffer, this number is meaningless.
+(\fIaddr\fP and \fIdata\fP are ignored.)
+.TP
+.BR PTRACE_BTS_GET
+Reads a single BTS record at index \fIdata\fP into \fIaddr\fP. The
+caller is responsible for allocating memory at \fIaddr\fP to hold one
+\fIptrace_bts_record\fP structure.
+The bigger the index, the older the record; the latest record can
+always be found at index 0.
+Returns the number of bytes written.
+.TP
+.BR PTRACE_BTS_CLEAR
+Clears the BTS buffer. This command can be used after a manual
+draining using PTRACE_BTS_GET commands.
+(\fIaddr\fP and \fIdata\fP are ignored.)
+.TP
+.BR PTRACE_BTS_DRAIN
+Reads all available BTS records into the buffer pointed to by
+\fIaddr\fP and clears
[patch 5/5] x86, ptrace, man: man pages for ptrace BTS extensions
Document changes for this patch set.
Signed-off-by: Markus Metzger [EMAIL PROTECTED]
---
Index: man/man2/ptrace.2
===
--- man.orig/man2/ptrace.2 2007-12-14 17:45:33.%N +0100
+++ man/man2/ptrace.2 2007-12-20 13:20:07.%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 [EMAIL PROTECTED]
+.\ Added PTRACE_BTS_* commands
+.\
.TH PTRACE 2 2007-11-15 Linux Linux Programmer's Manual
.SH NAME
ptrace \- process trace
@@ -378,6 +381,131 @@
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. For every (conditional) control flow change, the source and
+destination address are stored. On some architectures, control flow
+changes inside the kernel are recorded, as well. On later
+architectures, these are automatically filtered out.
+.LP
+The buffer (called Branch Trace Store) can be configured to be either
+circular, or to send a signal to the traced task when it is about to
+overflow. Not all methods may be available on all architectures.
+.LP
+The buffer can be accessed in two ways matching the above
+configurations: either as an array of BTS records from newest
+record to older records, one record at a time; or all records at once,
+from oldest to newest.
+.LP
+The former is mostly used for circular buffers to capture a tail of
+the execution trace (e.g. for debugging); the latter is mostly used to
+collect a continuous trace (e.g. for profiling) where the user drains
+the hardware buffer into a larger private buffer or into a file.
+.LP
+In addition to branches, timestamps (in jiffies) 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
+A BTS record is defined as:
+.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 {
+ u64 qualifier;
+ union {
+ /* PTRACE_BTS_BRANCH */
+ struct {
+ u64 from_ip;
+ u64 to_ip;
+ } lbr;
+ /* PTRACE_BTS_TASK_ARRIVES or
+ PTRACE_BTS_TASK_DEPARTS */
+ u64 timestamp;
+ } variant;
+};
+.fi
+.LP
+For configuring last branch recording and for querying its status, the
+following struct is used:
+.LP
+.nf
+struct ptrace_bts_config {
+ unsigned int size;
+ unsigned int flags;
+ unsigned int signal;
+};
+.fi
+.LP
+\fISize\fP is either the requested or the actual size of the kernel
+BTS buffer in bytes.
+\fIFlags\fP is a bitmask of options, which are specified by the
+following flags:
+.RS
+.TP
+.BR PTRACE_BTS_O_TRACE
+Collect branch trace records
+.TP
+.BR PTRACE_BTS_O_SCHED
+Collect scheduling timing information
+.TP
+.BR PTRACE_BTS_O_SIGNAL
+Send \fIsignal\fP to the traced task in case of a buffer overflow
+.TP
+.BR PTRACE_BTS_O_CUT_SIZE
+Reduce the requested buffer size if it is bigger than the available
+buffer size.
+.RE
+\fISignal\fP is the signal to send to the traced task in case of a
+buffer overflow.
+.TP
+.BR PTRACE_BTS_CONFIG
+Configure last branch recording. \fIaddr\fP points to a
+\fIptrace_bts_config\fP structure (see above); \fIdata\fP specifies
+the size of that structure.
+Returns the number of bytes read.
+.TP
+.BR PTRACE_BTS_STATUS
+Writes the actual configuration into a \fIptrace_bts_config\fP
+structure pointed to by \fIaddr\fP. The caller is responsible for
+allocating memory at \fIaddr\fP to hold a \fIptrace_bts_config\fP
+structure. \fIData\fP specifies the size of that structure.
+Returns the number of bytes written.
+.TP
+.BR PTRACE_BTS_SIZE
+Returns the number of BTS records available for draining. For a
+circular buffer, this number is meaningless.
+(\fIaddr\fP and \fIdata\fP are ignored.)
+.TP
+.BR PTRACE_BTS_GET
+Reads a single BTS record at index \fIdata\fP into \fIaddr\fP. The
+caller is responsible for allocating memory at \fIaddr\fP to hold one
+\fIptrace_bts_record\fP structure.
+The bigger the index, the older the record; the latest record can
+always be found at index 0.
+Returns the number of bytes written.
+.TP
+.BR PTRACE_BTS_CLEAR
+Clears the BTS buffer. This command can be used after a manual
+draining using PTRACE_BTS_GET commands.
+(\fIaddr\fP and \fIdata\fP are ignored.)
+.TP
+.BR PTRACE_BTS_DRAIN
+Reads all available BTS records into the buffer pointed to by
+\fIaddr\fP and clears the buffer.
