Menu
▾
▴
Re: [Patch] Documentation for Extended Feature Interface and IBS
|
From: Maynard J. <may...@us...> - 2009-05-06 16:25:22
|
Suravee Suthikulpanit wrote:
> This patch contains documentation for Extended Feature Interface and IBS.
Thanks for this! Nice work. Refresh my memory . . . are some of the extended feature callback handlers mandatory to implement, while others are optional? If so, we should identify them as such.
See other comments below. Mostly minor grammatical or spelling comments.
-Maynard
>
> ChangeLog | 5 +
> doc/internals.xml | 208 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> doc/oprofile.xml | 129 ++++++++++++++++++++++++++++-----
> 3 files changed, 323 insertions(+), 19 deletions(-)
>
> Signed-off-by: Suravee Suthikulpanit <sur...@am...>
>
> ---
>
> --- oprofile/ChangeLog 2009-05-01 15:34:23.000000000 -0500
> +++ oprofile-ibs-doc/ChangeLog 2009-05-05 12:32:47.000000000 -0500
> @@ -1,3 +1,8 @@
> +2009-05-04 Suravee Suthikulpanit <sur...@am...>
> +
> + * doc/oprofile.xml:
> + * doc/internals.xml: Add Extended-Interface and IBS documentation,
> +
> 2009-04-30 Andi Kleen <ak...@li...>
>
> * events/i386/arch_perfmon/events: Update event names to conform to manual.
> --- oprofile/doc/internals.xml 2006-11-15 10:33:26.000000000 -0600
> +++ oprofile-ibs-doc/doc/internals.xml 2009-05-05 11:58:42.000000000 -0500
> @@ -900,6 +900,214 @@ field formatters, with the <varname>symb
>
> </chapter>
>
> +<chapter id="ext">
> +<title>Extended Feature Interface</title>
> +
> +<sect1 id="ext-intro">
> +<title>Introduction</title>
> +
> +<para>
> +The Extended Feature Interface is a standard callback interface
> +designed to allow extension to the OProfile daemon's sample processing.
> +Each feature defines a set of callback handlers which can be enabled or
> +disabled through OProfile daemon command-line option.
> +This interface can be used to implement supports for architecture-specific
Change "supports" to "support"
> +features, or features not commonly used by general OProfile users.
No comma ^
> +</para>
> +
> +</sect1>
> +
> +<sect1 id="ext-name-and-handlers">
> +<title>Feature Name and Handlers</title>
> +
> +<para>
> +Each extended feature has an entry in the <varname>ext_feature_table</varname>
> +in <filename>opd_extended.cpp</filename>. Each entry contains a feature name,
> +and a corresponded set of handlers. Feature name is a unique string, which is
"corresponded" -> "corresponding"
> +used to identify a feature in the table. Each feature provides a set
> +of handlers, which will be executed by OProfile daemon from pre-determined
Be consistent in reference to "the" OProfile daemon. Add "the" here and elsewhere that it's needed.
> +locations to perform certain tasks. At runtime, OProfile daemon calls a feature
> +handler wrapper from one of the pre-determined locations to check whether
> +an extended feature is enabled, and whether a particular handler exists.
> +Only the handlers of the enabled feature will be executed.
> +</para>
> +
> +</sect1>
> +
> +<sect1 id="ext-enable">
> +<title>Enabling Features</title>
> +
> +<para>
> +Each feature is enabled using the OProfile daemon (oprofiled) command-line
> +option "--ext-feature=<extended-feature-name>:[args]". The
> +"extended-feature-name" is used to determine the feature to be enabled.
> +The optional "args" is passed into the feature-specific initialization handler
> +(<function>ext_init</function>). Currently, only one extended feature can be
> +enabled at a time.
> +</para>
> +
> +</sect1>
> +
> +<sect1 id="ext-types-of-handlers">
> +<title>Type of Handlers</title>
> +
> +<para>
> +Each feature is responsible for providing its own set of handlers.
> +Types of handler are:
> +</para>
> +
> +<sect2 id="ext_init">
> +<title>ext_init Handler</title>
> +
> +<para>
> +"ext_init" handles initialization of an extended feature. It takes
> +"args" parameter which is passed in through the "oprofiled --ext-feature=<
> +extended-feature-name>:[args]". This handler is executed in the function
> +<function>opd_options()</function> in the file <filename>daemon/oprofiled.c
> +</filename>.
> +</para>
> +
> +</sect2>
> +
> +<sect2 id="ext_print_stats">
> +<title>ext_print_stats Handler</title>
> +
> +<para>
> +"ext_print_stats" handles the extended feature statistics report. It addes
> +a new section in the OProfile daemon statistics report, which is normally
> +outputed to the file
> +<filename>/var/lib/oprofile/samples/oprofiled.log</filename>.
> +This handler is executed in the function <function>opd_print_stats()</function>
> +in the file <filename>daemon/opd_stats.c</filename>.
> +</para>
> +
> +</sect2>
> +
> +<sect2 id="ext_sfile_handlers">
> +<title>ext_sfile Handler</title>
> +
> +<para>
> +"ext_sfile" contains a set of handlers related to operations on the extended
> +sample files (sample files for events related to extended feature).
> +These operations include <function>create_sfile()</function>,
> +<function>sfile_dup()</function>, <function>close_sfile()</function>,
> +<function>sync_sfile()</function>, and <function>get_file()</function>
> +as defined in <filename>daemon/opd_sfile.c</filename>.
> +An additional field ,<varname>odb_t * ext_file</varname>, is added to the
Remove space before ^ comma, and add a space after it.
> +<varname>struct sfile</varname> for storing extended sample files
> +information.
> +
> +</para>
> +
> +</sect2>
> +
> +</sect1>
> +
> +<sect1 id="ext-features-list">
> +<title>List of Extended Features</title>
I don't think we need a list of extended features -- i.e., every developer who adds a new extended feature need not update this section of the manual. Let's change this title to "Extended Feature Reference Implementation: AMD64 Instruction-based Sampling". This means that section header 5.1 can go away and the rest of your section levels can move up.
> +
> +<sect2 id="ext-ibs">
> +<title>AMD64 (x86_64) Instruction-Based Sampling (IBS)</title>
> +
> +<sect3 id="ibs-init">
> +<title>IBS Initialization</title>
> +
> +<para>
> +Instruction-Based Sampling (IBS) is a new performance measurement technique
> +available on AMD Family 10h processors. Enabling IBS profiling is done simply
> +by specifying IBS performance events through the "--event=" options.
> +</para>
> +
> +<screen>
> +opcontrol --event=IBS_FETCH_XXX:<count>:<um>:<kernel>:<user>
> +opcontrol --event=IBS_OP_XXX:<count>:<um>:<kernel>:<user>
> +
> +Note: * All IBS fetch event must have the same event count and unitmask. So does IBS op.
change "event" to "events" . . . ^^^ Not a complete sentence.
> +</screen>
> +
> +<para>
> +IBS performance events are listed in <function>opcontrol --list-events</function>.
> +When users specify these events, opcontrol verifies them using ophelp, which
> +checks for the <varname>ext:ibs_fetch</varname> or <varname>ext:ibs_op</varname>
> +tag in <filename>events/x86-64/family10/events</filename> file.
> +Then, it configures the driver interface (/dev/oprofile/ibs_fetch/... and
> +/dev/oprofile/ibs_op/...) and starts OProfile daemon as following.
change "following." to "follows:"
> +</para>
> +
> +<screen>
> +oprofiled \
> + --ext-feature=ibs:\
> + fetch:<IBS_FETCH_EVENT1>,<IBS_FETCH_EVENT2>,...,:<IBS fetch count>:<IBS Fetch um>|\
> + op:<IBS_OP_EVENT1>,<IBS_OP_EVENT2>,...,:<IBS op count>:<IBS op um>
> +</screen>
> +
> +<para>
> +Here, oprofiled parse the <varname>--ext-feature</varname> option, and
Change "oprofiled parse" to "the OProfile daemon parses". Remove ^ comma.
> +check the feature name ("ibs") before calling the
Change "check" to "checks".
> +the initialization function to handle the string
> +containing IBS events, counts, and unitmasks.
> +Then, it stores each event in the IBS virtual-counter table
> +(<varname>struct opd_event ibs_vc[OP_MAX_IBS_COUNTERS]</varname>), and
Remove ^ comma.
> +stores the event index in the IBS Virtual Counter Index (VCI) map
> +(<varname>ibs_vci_map[OP_MAX_IBS_COUNTERS]</varname>) with IBS event value
> +as the map key.
> +</para>
> +</sect3>
> +
> +<sect3 id="ibs-data-processing">
> +<title>IBS Data Processing</title>
> +
> +<para>
> +During a profile session, OProfile daemon identifies IBS samples in the
> +event buffer using the <varname>"IBS_FETCH_CODE"</varname> or
> +<varname>"IBS_OP_CODE"</varname>. These code trigger the handlers
Change "code" to "codes".
> +<function>code_ibs_fetch_sample()</function> or
> +<function>code_ibs_op_sample()</function> listed in the
> +<varname>handler_t handlers[]</varname> vector in
> +<filename>daemon/opd_trans.c </filename>. These handlers are responsible for
> +processing IBS samples and translate them into IBS performance events.
> +</para>
> +
> +<para>
> +Unlike traditional performance events, each IBS sample can be derived into
> +multiple IBS performance events. For each event that users specified,
Change "users specified" to "the user specifies".
> +a combination of bits from Model-Specific Registers (MSR) are checked
> +against the bitmask defining the event. If the condition is met, the event
> +will then be recorded. The derivation logic is in the file
Change "file" to "files".
> +<filename>daemon/opd_ibs_macro.h</filename>, and
Remove ^ comma.
> +<filename>daemon/opd_ibs_trans.[h,c]</filename>.
> +</para>
> +
> +</sect3>
> +
> +<sect3 id="ibs-sample-file">
> +<title>IBS Sample File</title>
> +
> +<para>
> +Traditionally, sample file information <varname>(odb_t)</varname> is stored
> +in the <varname>struct sfile::odb_t file[OP_MAX_COUNTER]</varname>.
> +Currently, <varname>OP_MAX_COUNTER</varname> is 8 on non-alpha, and 20 on
> +alpha-based system. Event index (i.e. the counter number which the event
Change "which" to "on which"
> +is configured) is used to access the corresponded entry in the array.
Change "correpsonded" to "corresponding".
> +Unlike the traditional performance event, IBS does not use the actual
> +counter registers (i.e. <filename>/dev/oprofile/0,1,2,3</filename>).
> +Also, the number of performance event generated by IBS could be larger than
Change "event" to "events".
> +<varname>OP_MAX_COUNTER</varname>. (currently upto 13 IBS-fetch, and 46 IBS-op
Remove ^ period. Add ^ space.
> +events). Therefore, IBS requires a special data structure, and sfile
Remove ^ comma.
> +handlers (<varname>struct opd_ext_sfile_handlers</varname>) for managing
> +IBS sample files. IBS-sample-file information is stored in a memory
> +allocated by handler <function>ibs_sfile_create()</function>, which can
> +be accessed through <varname>struct sfile::odb_t * ext_files</varname>.
> +</para>
> +
> +</sect3>
> +
> +</sect2>
> +
> +</sect1>
> +
> +</chapter>
> +
> <glossary id="glossary">
> <title>Glossary of OProfile source concepts and types</title>
>
> --- oprofile/doc/oprofile.xml 2009-02-03 14:22:11.000000000 -0600
> +++ oprofile-ibs-doc/doc/oprofile.xml 2009-05-05 12:27:31.000000000 -0500
> @@ -99,7 +99,8 @@ For information on how to use OProfile's
> <variablelist>
> <varlistentry>
> <term>Linux kernel 2.2/2.4/2.6</term>
> - <listitem><para>
> + <listitem>
> + <para>
> OProfile uses a kernel module that can be compiled for
> 2.2.11 or later and 2.4. 2.4.10 or above is required if you use the
> boot-time kernel option <option>nosmp</option>. 2.6 kernels are supported with the in-kernel
> @@ -115,21 +116,27 @@ For information on how to use OProfile's
> PPC64 processors (Power4/Power5/PPC970, etc.) require a recent (> 2.6.5) kernel with the line
> <constant>#define PV_970</constant> present in <filename>include/asm-ppc64/processor.h</filename>.
> <!-- FIXME: do we require always gte 2.4.10 for nosmp ? -->
> - </para>
> - <para>
> - Profiling the Cell Broadband Engine PowerPC Processing Element (PPE) requires a kernel version
> - of 2.6.18 or more recent.
> - Profiling the Cell Broadband Engine Synergistic Processing Element (SPE) requires a kernel version
> - of 2.6.22 or more recent. Additionally, full support of SPE profiling requires a BFD library
> - from binutils code dated January 2007 or later. To ensure the proper BFD support exists, run
> - the <code>configure</code> utility with <code>--with-target=cell-be</code>.
> + </para>
> + <para>
> + Profiling the Cell Broadband Engine PowerPC Processing Element (PPE) requires a kernel version
> + of 2.6.18 or more recent.
> + Profiling the Cell Broadband Engine Synergistic Processing Element (SPE) requires a kernel version
> + of 2.6.22 or more recent. Additionally, full support of SPE profiling requires a BFD library
> + from binutils code dated January 2007 or later. To ensure the proper BFD support exists, run
> + the <code>configure</code> utility with <code>--with-target=cell-be</code>.
>
> - Profiling the Cell Broadband Engine using SPU events requires a kernel version of 2.6.29-rc1
> - or more recent.
> + Profiling the Cell Broadband Engine using SPU events requires a kernel version of 2.6.29-rc1
> + or more recent.
>
> - <note>Attempting to profile SPEs with kernel versions older than 2.6.22 may cause the
> - system to crash.</note>
> - </para></listitem>
> + <note>Attempting to profile SPEs with kernel versions older than 2.6.22 may cause the
> + system to crash.</note>
> + </para>
Did you actually change anything above other than changing spacing moving the <para>'s? I would prefer you avoid making such changes if possible.
> +
> + <para>
> + Instruction-Based Sampling (IBS) profille on AMD family10h processors requires
> + kernel version 2.6.28-rc2 or later.
> + </para>
> + </listitem>
> </varlistentry>
> <varlistentry>
> <term>modutils 2.4.6 or above</term>
> @@ -145,7 +152,7 @@ For information on how to use OProfile's
> required. In marketing terms this translates to anything
> between an Intel Pentium Pro (not Pentium Classics) and
> a Pentium 4 / Xeon, including all Celerons. The AMD
> - Athlon, and Duron CPUs are also supported. Other IA32
> + Athlon, Opteron, Phenom, and Turion CPUs are also supported. Other IA32
> CPU types only support the RTC mode of OProfile; please
> see later in this manual for details. Hyper-threaded Pentium IVs
> are not supported in 2.4. For 2.4 kernels, the Intel
> @@ -910,6 +917,8 @@ The table below lists the events selecte
> <row><entry>Pentium 4 (non-HT)</entry><entry>i386/p4</entry><entry>GLOBAL_POWER_EVENTS:100000:1:1:1</entry></row>
> <row><entry>Pentium 4 (HT)</entry><entry>i386/p4-ht</entry><entry>GLOBAL_POWER_EVENTS:100000:1:1:1</entry></row>
> <row><entry>Hammer</entry><entry>x86-64/hammer</entry><entry>CPU_CLK_UNHALTED:100000:0:1:1</entry></row>
> +<row><entry>Family10h</entry><entry>x86-64/family10</entry><entry>CPU_CLK_UNHALTED:100000:0:1:1</entry></row>
> +<row><entry>Family11h</entry><entry>x86-64/family11h</entry><entry>CPU_CLK_UNHALTED:100000:0:1:1</entry></row>
> <row><entry>Itanium</entry><entry>ia64/itanium</entry><entry>CPU_CYCLES:100000:0:1:1</entry></row>
> <row><entry>Itanium 2</entry><entry>ia64/itanium2</entry><entry>CPU_CYCLES:100000:0:1:1</entry></row>
> <row><entry>TIMER_INT</entry><entry>timer</entry><entry>None selectable</entry></row>
> @@ -1011,8 +1020,8 @@ events other than the default event chos
> </note>
> <para>
> The Intel hardware performance counters are detailed in the Intel IA-32 Architecture Manual, Volume 3, available
> -from <ulink url="http://developer.intel.com/">http://developer.intel.com/</ulink>. The AMD Athlon/Duron
> -implementation is detailed in <ulink
> +from <ulink url="http://developer.intel.com/">http://developer.intel.com/</ulink>.
> +The AMD Athlon/Opteron/Phenom/Turion implementation is detailed in <ulink
> url="http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/22007.pdf">
> http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/22007.pdf</ulink>.
> For PowerPC64 processors in IBM iSeries, pSeries, and blade server systems, processor documentation
> @@ -1119,7 +1128,7 @@ particular set of events which are to be
> operation. Unfortunately the relationship between these registers is quite complex; they cannot all be used with one
> another at any time. There is, however, a subset of 8 counters, 8 ESCRs, and 8 CCCRs which can be used independently of
> one another, so OProfile only accesses those registers, treating them as a bank of 8 "normal" counters, similar
> -to those in the P6 or Athlon families of CPU.
> +to those in the P6 or Athlon/Opteron/Phenom/Turion families of CPU.
> </para>
> <para>
> There is currently no support for Precision Event-Based Sampling (PEBS), nor any advanced uses of the Debug Store
> @@ -1230,6 +1239,88 @@ with -g to facilitate finding the right
>
> </sect2>
>
> +<sect2 id="amd-ibs-support">
> +<title>AMD64 (x86_64) Instruction-Based Sampling (IBS) support</title>
> +
> +<para>
> +Instruction-Based Sampling (IBS) is a new performance measurement technique
> +available on AMD Family 10h processors. Traditional performance counter
> +sampling is not precise enough to isolate performance issues to individual
> +instructions. IBS, however, precisely identyfies instructions which are not
Change "identyfies" to "identifies".
> +making the best use of the processor pipeline and memeory hierarchy.
Change "memeory" to "memory".
> +For more information, please refer to the "Instruction-Based Sampling:
> +A New Performance Analysis Technique for AMD Family 10h Processors" (
> +<ulink url="http://developer.amd.com/assets/AMD_IBS_paper_EN.pdf">
> +http://developer.amd.com/assets/AMD_IBS_paper_EN.pdf</ulink>).
> +There are two types of IBS profile:
How about changing "IBS profile:" to "IBS profile types, described in the following sections." ?
> +</para>
> +
> +<sect3 id="ibs-fetch">
> +<title>IBS Fetch</title>
> +
> +<para>
> +IBS fetch sampling is a statistical sampling method which counts completed
> +fetch operations. When the number of completed fetch operations reaches the
> +maximum fetch count (the sampling period), IBS tags the fetch operation and
> +monitors that operation until it either completes or aborts. When a tagged
> +fetch completes or aborts, a sampling interrupt is generated and an IBS fetch
> +sample is taken. An IBS fetch sample contains a timestamp, the identifier of
> +the interrupted process, the virtual fetch address, and several event flags
> +and values that described what happened during the fetch operation.
> +</para>
> +
> +</sect3>
> +
> +<sect3 id="ibs-op">
> +<title>IBS Op</title>
> +
> +<para>
> +IBS op sampling selects, tags, and monitors macro-ops as issued from AMD64
> +instructions. Two options are available for selecting ops for sampling.
Change ^ period to colon.
> +</para>
> +
> +<itemizedlist>
> +<listitem>
> +Cycles-based selection counts CPU clock cycles. The op is tagged and monitored
> +when the count reaches a threshold (the sampling period) and a valid op is
> +available.
> +</listitem>
> +
> +<listitem>
> +Dispatched op-based selection counts dispatched macro-ops.
> +When the count reaches a threshold, the next valid op is tagged and monitored.
> +</listitem>
> +</itemizedlist>
> +
> +<para>
> +In both cases, an IBS sample is generated only if the tagged op retires.
> +Thus, IBS op event information does not measure speculative execution activity.
> +The execution stages of the pipeline monitor the tagged macro-op. When the
> +tagged macro-op retires, a sampling interrupt is generated and an IBS op
> +sample is taken. An IBS op sample contains a timestamp, the identifier of
> +the interrupted process, the virtual address of the AMD64 instruction from
> +which the op was issued, and several event flags and values that describe
> +what happened when the macro-op executed.
> +</para>
> +
> +</sect3>
> +
> +<para>
> +Enabling IBS profiling is done simply by specifying IBS performance events
> +through the "--event=" options. These events are listed in the
> +<function>opcontrol --list-events</function>.
> +</para>
> +
> +<screen>
> +opcontrol --event=IBS_FETCH_XXX:<count>:<um>:<kernel>:<user>
> +opcontrol --event=IBS_OP_XXX:<count>:<um>:<kernel>:<user>
> +
> +Note: * All IBS fetch event must have the same event count and unitmask. So does IBS op.
> +</screen>
> +
> +</sect2>
> +
> +
> <sect2 id="misuse">
> <title>Dangerous counter settings</title>
> <para>
> @@ -2477,7 +2568,7 @@ problem and OProfile can do nothing abou
> <title>Interrupt masking</title>
> <para>
> OProfile uses non-maskable interrupts (NMI) on the P6 generation, Pentium 4,
> -Athlon and Duron processors. These interrupts can occur even in section of the
> +Athlon, Opteron, Phenom, and Turion processors. These interrupts can occur even in section of the
> Linux where interrupts are disabled, allowing collection of samples in virtually
> all executable code. The RTC, timer interrupt mode, and Itanium 2 collection mechanisms
> use maskable interrupts. Thus, the RTC and Itanium 2 data collection mechanism have "sample
>
>
>
>
> ------------------------------------------------------------------------------
> The NEW KODAK i700 Series Scanners deliver under ANY circumstances! Your
> production scanning environment may not be a perfect world - but thanks to
> Kodak, there's a perfect scanner to get the job done! With the NEW KODAK i700
> Series Scanner you'll get full speed at 300 dpi even with all image
> processing features enabled. http://p.sf.net/sfu/kodak-com
> _______________________________________________
> oprofile-list mailing list
> opr...@li...
> https://lists.sourceforge.net/lists/listinfo/oprofile-list
|