[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.