Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1759158AbXK2IOe (ORCPT ); Thu, 29 Nov 2007 03:14:34 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1752745AbXK2IOZ (ORCPT ); Thu, 29 Nov 2007 03:14:25 -0500 Received: from mga02.intel.com ([134.134.136.20]:18086 "EHLO mga02.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751324AbXK2IOY convert rfc822-to-8bit (ORCPT ); Thu, 29 Nov 2007 03:14:24 -0500 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="4.23,228,1194249600"; d="scan'208";a="236327123" X-MimeOLE: Produced By Microsoft Exchange V6.5 Content-class: urn:content-classes:message MIME-Version: 1.0 Subject: [patch 2/2] man: man pages for ptrace BTS extensions Date: Thu, 29 Nov 2007 08:14:16 -0000 Message-ID: <029E5BE7F699594398CA44E3DDF5544401024077@swsmsx413.ger.corp.intel.com> X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: [patch 2/2] man: man pages for ptrace BTS extensions thread-index: AcgyX9V0U29K9EgXTGmcsKVfZEy4QQ== From: "Metzger, Markus T" To: , , , , Cc: "Siddha, Suresh B" , "Metzger, Markus T" , X-OriginalArrivalTime: 29 Nov 2007 08:14:12.0915 (UTC) FILETIME=[D358C030:01C8325F] Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 8BIT Sender: linux-kernel-owner@vger.kernel.org X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 5463 Lines: 157 Describe extensions to ptrace interface for branch trace store Signed-off-by: Markus Metzger Signed-off-by: Suresh Siddha --- Index: man/man2/ptrace.2 =================================================================== --- man.orig/man2/ptrace.2 2007-11-22 20:25:21.%N +0100 +++ man/man2/ptrace.2 2007-11-22 20:25:33.%N +0100 @@ -40,7 +40,10 @@ .\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP .\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.) .\" -.TH PTRACE 2 2006-03-24 "Linux 2.6.16" "Linux Programmer's Manual" +.\" Modified Nov 2007, Markus Metzger +.\" Added PTRACE_BTS_* commands +.\" +.TH PTRACE 2 2007-11 "Linux 2.6.16" "Linux Programmer's Manual" .SH NAME ptrace \- process trace .SH SYNOPSIS @@ -312,6 +315,96 @@ 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 +This is not a ptrace command but a macro that defines the maximal size +of the BTS buffer in number of BTS records. +.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. +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 NOTES Although arguments to .BR ptrace () @@ -409,6 +502,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 "SEE ALSO" --------------------------------------------------------------------- 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/