Overhaul the BBV manual chapter, mostly. Also tweak BBV's usage message to

match the docs better.



git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10724 a5019735-40e9-0310-863c-91ae7b9d1cf9

1 files changed, 70 insertions, 72 deletions

diff --git a/exp-bbv/docs/bbv-manual.xml b/exp-bbv/docs/bbv-manual.xml
index 54b334618..88603ed43 100644
--- a/exp-bbv/docs/bbv-manual.xml
+++ b/exp-bbv/docs/bbv-manual.xml
@@ -13,10 +13,10 @@ command line.</para>
 <title>Overview</title>
 
 <para>
-   A Basic Blocks Vector (BBV) is a list of all basic blocks entered
-   during program execution, and a count of how many times each
-   block was run (a basic block is a section of code
-   with only one entry point and one exit point).
+   A basic block is a linear section of code with one entry point and one exit
+   point.  A <emphasis>basic blocks vector</emphasis> (BBV) is a list of all
+   basic blocks entered during program execution, and a count of how many
+   times each basic block was run.
 </para>
 
 <para>
@@ -58,12 +58,14 @@ command line.</para>
 <para>
    To quickly create a basic block vector file, you will call Valgrind
    like this:
-   <computeroutput>valgrind --tool=exp-bbv /bin/ls</computeroutput>
-   In this case we are running on the "ls" program, but this
-   can be any executable.  By default a file called 
+
+   <programlisting>valgrind --tool=exp-bbv /bin/ls</programlisting>
+
+   In this case we are running on <filename>/bin/ls</filename>,
+   but this can be any program.  By default a file called
    <computeroutput>bb.out.PID</computeroutput> will be created,
    where PID is replaced by the process ID of the running process.
-   This file is the basic block vector.  For long-running programs
+   This file contains the basic block vector.  For long-running programs
    this file can be quite large, so it might be wise to compress
    it with gzip or some other compression program.
 </para>   
@@ -82,7 +84,7 @@ command line.</para>
     -saveSimpointWeights results.weights]]></programlisting>
 
    where bb.out.1234.gz is your compressed basic block vector file
-   generated by Valgrind exp-bbv.
+   generated by BBV.
 </para>
 
 <para>   
@@ -111,12 +113,47 @@ command line.</para>
 <sect1 id="bbv-manual.usage" xreflabel="BBV Usage">
 <title>BBV Command Line Options</title>
 
-<para>
-   BBV has various options that control the behavior of the plugin:
+<para> BBV-specific options are:</para>
+
 <!-- start of xi:include in the manpage -->
 <variablelist id="bbv.opts.list">
 
-  <varlistentry id="opt.interval-size" xreflabel="--interval-size">
+  <varlistentry id="opt.bb-out-file" xreflabel="--bb-out-file">
+     <term>
+        <option><![CDATA[--bb-out-file=<name> [default: bb.out.%p] ]]></option>
+     </term>
+     <listitem>
+        <para>
+           This option selects the name of the basic block vector file.  The
+           <option>%p</option> and <option>%q</option> format specifiers can be
+           used to embed the process ID and/or the contents of an environment
+           variable in the name, as is the case for the core option
+           <option><xref linkend="opt.log-file"/></option>.
+        </para>
+     </listitem>
+  </varlistentry>
+
+  <varlistentry id="opt.pc-out-file" xreflabel="--pc-out-file">
+     <term>
+        <option><![CDATA[--pc-out-file=<name> [default: pc.out.%p] ]]></option>
+     </term>
+     <listitem>
+        <para>
+           This option selects the name of the PC file.  
+           This file holds program counter addresses
+           and function name info for the various basic blocks.
+           This can be used in conjunction
+           with the basic block vector file to fast-forward via function names
+           instead of just instruction counts.  The 
+           <option>%p</option> and <option>%q</option> format specifiers can be
+           used to embed the process ID and/or the contents of an environment
+           variable in the name, as is the case for the core option
+           <option><xref linkend="opt.log-file"/></option>.
+        </para>
+     </listitem>
+   </varlistentry>
+
+   <varlistentry id="opt.interval-size" xreflabel="--interval-size">
       <term>
         <option><![CDATA[--interval-size=<number> [default: 100000000] ]]></option>
       </term>
@@ -143,57 +180,18 @@ command line.</para>
      </term>
      <listitem>
         <para>
-           This option tells the tool to only display instruction 
-           count totals, and to not generate the
-           actual BBV file.  This is useful for debugging, and for
-           gathering instruction count info without generating
-           the large BBV files.
+           This option tells the tool to only display instruction count
+           totals, and to not generate the actual basic block vector file.
+           This is useful for debugging, and for gathering instruction count
+           info without generating the large basic block vector files.
         </para>
      </listitem>
    </varlistentry>
   
-  <varlistentry id="opt.bb-out-file" xreflabel="--bb-out-file">
-     <term>
-        <option><![CDATA[--bb-out-file=<name> [default: bb.out.%p] ]]></option>
-     </term>
-     <listitem>
-        <para>
-           This option selects the name of the basic block file.  Default is 
-           bb.out.%p.   The
-           <option>%p</option> and <option>%q</option> format specifiers can be
-           used to embed the process ID and/or the contents of an environment
-           variable in the name, as is the case for the core option
-           <option>--log-file</option>.
-        </para>
-     </listitem>
-  </varlistentry>
-
-  <varlistentry id="opt.pc-out-file" xreflabel="--pc-out-file">
-     <term>
-        <option><![CDATA[--pc-out-file=<name> [default: pc.out.%p] ]]></option>
-     </term>
-     <listitem>
-        <para>
-           This option selects the name of the PC file.  
-           This file holds program counter addresses
-           and function name info for the various basic blocks.
-           This can be used in conjunction
-           with the bbv file to fast-forward via function names
-           instead of just instruction counts.
-	   The default filename is pc.out.%p.
-           <option>%p</option> and <option>%q</option> format specifiers can be
-           used to embed the process ID and/or the contents of an environment
-           variable in the name, as is the case for the core option
-           <option>--log-file</option>.
 
-        </para>
-     </listitem>
-   </varlistentry>
 </variablelist>
 <!-- end of xi:include in the manpage -->
 
-</para>
-
 </sect1>
 
 <sect1 id="bbv-manual.fileformat" xreflabel="BBV File Format">
@@ -225,8 +223,8 @@ T:18:45 :12:135353 :56:78 314:4324263]]></programlisting>
 <para>
   The entry count is multiplied by the number of instructions that are 
   in the basic block, in order to weigh the count so that instructions in 
-  small Basic Blocks aren't counted as more important than instructions 
-  in large Basic Blocks.
+  small basic blocks aren't counted as more important than instructions 
+  in large basic blocks.
 </para>
 
 </sect1>
@@ -238,32 +236,32 @@ T:18:45 :12:135353 :56:78 314:4324263]]></programlisting>
    Valgrind provides all of the information necessary to create
    BBV files.  In the current implementation, all instructions
    are instrumented.  This is slower (by approximately a factor
-   of two) than a method that instruments at the basic-block level, 
+   of two) than a method that instruments at the basic block level, 
    but there are some complications (especially with rep prefix
    detection) that make that method more difficult.
 </para>
   
 <para>
-   Valgrind actually provides instrumentation at a super-block level.
-   A super-block has one entry point but unlike basic-blocks can
+   Valgrind actually provides instrumentation at a superblock level.
+   A superblock has one entry point but unlike basic blocks can
    have multiple exit points.  Once a branch occurs into the middle
-   of a block, it is split into a new basic-block.  Because
+   of a block, it is split into a new basic block.  Because
    Valgrind cannot produce "true" basic blocks, the generated
    BBV vectors will be different than those generated by other tools.
    In practice this does not seem to affect the accuracy of the
    SimPoint results.  We do internally force the
    <option>--vex-guest-chase-thresh=0</option>
-   option to Valgrind which forces a more basic-block like
+   option to Valgrind which forces a more basic-block-like
    behavior.
 </para>
 
 <para>
-   When a super block is run for the first time, it is instrumented
+   When a superblock is run for the first time, it is instrumented
    with our BBV routine.  This adds a call to our instruction
    counting function for each original instruction.
-   The current superblock is looked up in an Ordered Set to find 
+   The current superblock is looked up in an ordered set to find 
    a structure that holds block-specific statistics (the entry point 
-   address is the index into the hash table).  We increment the 
+   address is the index into the ordered set).  We increment the 
    instruction count for this superblock and
    also update the master instruction count.
    If the master count overflows the interval size 
@@ -283,7 +281,7 @@ T:18:45 :12:135353 :56:78 314:4324263]]></programlisting>
 </para>   
    
 <para>
-   The exp-bbv tool also counts the fldcw instruction.  This
+   BBV also counts the fldcw instruction.  This
    instruction is used on x86 machines when converting numbers
    from floating point to integer (among other uses).
    On Pentium 4 systems the retired instruction performance
@@ -300,8 +298,8 @@ T:18:45 :12:135353 :56:78 314:4324263]]></programlisting>
 
 <para>
    BBV supports threaded programs.  When a program has multiple threads,
-   an additional BBV file is created for each thread (each additional
-   file is the specified filename with the thread number
+   an additional basic block vector file is created for each thread (each
+   additional file is the specified filename with the thread number
    appended at the end).
 </para>
 
@@ -310,8 +308,8 @@ T:18:45 :12:135353 :56:78 314:4324263]]></programlisting>
    threaded workloads.  The most common method is to run
    SimPoint on each thread's results independently, and use 
    some method of deterministic execution to try to match the
-   original workload.  This should be possible with current
-   exp-bbv.
+   original workload.  This should be possible with the current
+   BBV.
 </para>
 
 </sect1>
@@ -320,8 +318,8 @@ T:18:45 :12:135353 :56:78 314:4324263]]></programlisting>
 <title>Validation</title>
 
 <para>
-   This plugin has been tested on x86, amd64, and ppc32 platforms.
-   An earlier version of the plugin was tested in detail using
+   BBV has been tested on x86, amd64, and ppc32 platforms.
+   An earlier version of BBV was tested in detail using
    hardware performance counters, this work is described in a paper 
    from the HiPEAC'08 conference, "Using Dynamic Binary Instrumentation 
    to Generate Multi-Platform SimPoints: Methodology and Accuracy" by