From c7862451330bd6d792997fb1ef6cb711701d6b21 Mon Sep 17 00:00:00 2001 From: Julian Seward Date: Wed, 1 May 2002 01:24:52 +0000 Subject: [PATCH] Edit cache stuff, minorly. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@180 --- cachegrind/docs/manual.html | 245 ++++++++++++++++++++---------------- coregrind/docs/manual.html | 245 ++++++++++++++++++++---------------- docs/manual.html | 245 ++++++++++++++++++++---------------- memcheck/docs/manual.html | 245 ++++++++++++++++++++---------------- 4 files changed, 556 insertions(+), 424 deletions(-) diff --git a/cachegrind/docs/manual.html b/cachegrind/docs/manual.html index 4da22db114..daaa1535d1 100644 --- a/cachegrind/docs/manual.html +++ b/cachegrind/docs/manual.html @@ -518,10 +518,9 @@ follows:

  • --cachesim=no [default]
    - --cachesim=yes -

    When enabled, turns off memory checking, and turns on cache profiling. - Cache profiling is described in detail in Section 7. -

    • + --cachesim=yes

    When enabled, turns off memory + checking, and turns on cache profiling. Cache profiling is + described in detail in Section 7.

    There are also some options for debugging Valgrind itself. You @@ -1799,45 +1798,56 @@ program as it will be normally run. The three steps are:

      -
    1. Generate a cache simulator for your machine's cache configuration with - `vg_cachegen' and recompile Valgrind with make install. - Valgrind comes with a default simulator, but it is unlikely to be correct - for your system, so you should generate a simulator yourself.
      2. -
    2. Run your program with valgrind --cachesim=yes in front of - the normal command line invocation. When the program finishes, Valgrind - will print summary cache statistics. It also collects line-by-line - information in a file cachegrind.out.
      3. -
    3. Generate a function-by-function summary, and possibly annotate source - files with 'vg_annotate'. Source files to annotate can be specified - manually, or manually on the command line, or "interesting" source files - can be annotated automatically with the --auto=yes option. - You can annotate C/C++ files or assembly language files equally - easily.
      4. +
    4. Generate a cache simulator for your machine's cache + configuration with the supplied vg_cachegen + program, and recompile Valgrind with make install. +

      + The default settings are for an AMD Athlon, and you will get + useful information with the defaults, so you can skip this step + if you want. Nevertheless, for accurate cache profiles you will + need use vg_cachegen to customise + cachegrind for your system. +

      + This step only needs to be done once, unless you are interested + in simulating different cache configurations (eg. first + concentrating on instruction cache misses, then on data cache + misses). +

      5. +

      +

    5. Run your program with cachegrind in front of the + normal command line invocation. When the program finishes, + Valgrind will print summary cache statistics. It also collects + line-by-line information in a file cachegrind.out. +

      + This step should be done every time you want to collect + information about a new program, a changed program, or about the + same program with different input. +

      6. +

      +

    6. Generate a function-by-function summary, and possibly annotate + source files with 'vg_annotate'. Source files to annotate can be + specified manually, or manually on the command line, or + "interesting" source files can be annotated automatically with + the --auto=yes option. You can annotate C/C++ + files or assembly language files equally easily.
      7. +

      + This step can be performed as many times as you like for each + Step 2. You may want to do multiple annotations showing + different information each time.

    -Step 1 only needs to be done once, unless you are -interested in simulating different cache configurations (eg. first -concentrating on instruction cache misses, then on data cache misses).

    - -Step 2 should be done every time you want to collect -information about a new program, a changed program, or about the same program -with different input.

    - -Step 3 can be performed as many times as you like for -each Step 2; you may want to do multiple annotations showing different -information each time.

    - The steps are described in detail in the following sections.

    7.3  Generating a cache simulator

    -Although Valgrind comes with a pre-generated cache simulator, it most likely -won't match the cache configuration of your machine, so you should generate -a new simulator.

    -You need to generate three files, one for each of the I1, D1 and L2 caches. -For each cache, you need to know the: +Although Valgrind comes with a pre-generated cache simulator, it most +likely won't match the cache configuration of your machine, so you +should generate a new simulator.

    + +You need to generate three files, one for each of the I1, D1 and L2 +caches. For each cache, you need to know the:

    -You can specify one, two or all three caches per invocation of vg_cachegen. It -checks that the configuration is sensible before generating the simulators; to -see the allowed values, run vg_cachegen -h.

    +You can specify one, two or all three caches per invocation of +vg_cachegen. It checks that the configuration is sensible before +generating the simulators; to see the allowed values, run +vg_cachegen -h.

    An example invocation would be: @@ -1861,37 +1872,43 @@ An example invocation would be: vg_cachegen --I1=65536,64,2 --D1=65536,64,2 --L2=262144,64,8 -This simulates a machine with a 128KB split L1 2-way associative cache, and a -256KB unified 8-way associative L2 cache. Both caches have 64B lines.

    +This simulates a machine with a 128KB split L1 2-way associative +cache, and a 256KB unified 8-way associative L2 cache. Both caches +have 64B lines.

    -If you don't know your cache configuration, you'll have to find it out. -(Ideally vg_cachegen could auto-identify your cache configuration using the -CPUID instruction, which could be done automatically during installation, and -this whole step could be skipped...)

    +If you don't know your cache configuration, you'll have to find it +out. (Ideally vg_cachegen could auto-identify your cache +configuration using the CPUID instruction, which could be done +automatically during installation, and this whole step could be +skipped.)

    7.4  Cache simulation specifics

    -vg_cachegen only generates simulations for a machine with a split L1 cache and -a unified L2 cache. This configuration is used for all x86-based machines we -are aware of.

    + +vg_cachegen only generates simulations for a machine with +a split L1 cache and a unified L2 cache. This configuration is used +for all (modern) x86-based machines we are aware of. Old Cyrix CPUs +had a unified I and D L1 cache, but they are ancient history now.

    The more specific characteristics of the simulation are as follows.

    Other noteworthy behaviour: @@ -1924,14 +1941,18 @@ does.

    7.5  Profiling programs

    -Cache profiling is enabled by using the --cachesim=yes option to -Valgrind. This automatically turns off Valgrind's memory checking functions, -since the cache simulation is slow enough already, and you probably don't want -to do both at once.

    -To gather cache profiling information about the program ls -l--cachesim=yes +option to the valgrind shell script. Alternatively, it +is probably more convenient to use the cachegrind script. +This automatically turns off Valgrind's memory checking functions, +since the cache simulation is slow enough already, and you probably +don't want to do both at once. +

    +To gather cache profiling information about the program ls +-lvalgrind --cachesim=yes ls -l +

    cachegrind ls -l
    The program will execute (slowly). Upon completion, summary statistics that look like this will be printed: @@ -1967,30 +1988,36 @@ Combined instruction and data figures for the L2 cache follow that.

    7.6  Output file

    -As well as printing summary information, Valgrind also writes line-by-line -cache profiling information to a file named cachegrind.out . This -file is human-readable, but is best interpreted by the accompanying program -vg_annotate, described in the next section.

    +As well as printing summary information, Cachegrind also writes +line-by-line cache profiling information to a file named +cachegrind.out. This file is human-readable, but is best +interpreted by the accompanying program vg_annotate, +described in the next section. +

    Things to note about the cachegrind.out file:

    7.7  Annotating C/C++ programs

    -Before using vg_annotate, it is worth widening your window to be at least -120-characters wide if possible, as the output lines can be quite long.

    +Before using vg_annotate, it is worth widening your +window to be at least 120-characters wide if possible, as the output +lines can be quite long. +

    To get a function-by-function summary, run vg_annotate in -directory containing a cachegrind.out file. The output looks like -this: +directory containing a cachegrind.out file. The output +looks like this: 

     --------------------------------------------------------------------------------
@@ -2073,12 +2100,13 @@ First up is a summary of the annotation options:
       shown" line (and can be changed with the --sort option).
       
    
 
-  
  • Threshold: vg_annotate by default omits functions that cause very low
-      numbers of misses to avoid drowing you in information.  In this case,
-      vg_annotate shows summaries the functions that account for 99%   of the
-      Ir counts; Ir is chosen as the treshold event
-      since it is  the primary sort event.  The threshold can be adjusted with
-      the --threshold option.
    • 
+  
  • Threshold: vg_annotate by default omits functions
+      that cause very low numbers of misses to avoid drowning you in
+      information.  In this case, vg_annotate shows summaries the
+      functions that account for 99% of the Ir counts;
+      Ir is chosen as the threshold event since it is the
+      primary sort event.  The threshold can be adjusted with the
+      --threshold option.
    • 
 
   
  • Chosen for annotation: names of files specified manually for annotation; 
       in this case none.
    • 
@@ -2090,14 +2118,15 @@ First up is a summary of the annotation options:
 Then follows summary statistics for the whole program. These are similar
 to the summary provided when running valgrind --cachesim=yes.
    
   
-Then follows function-by-function statistics. Each function is identified by a
-file_name:function_name pair. If a column contains only a
-`.' it means  the function never performs that event (eg. the third row shows
-that strcmp() contains no instructions that write to memory). The
-name ??? is used if the the file name and/or function name could
-not be determined from debugging information. (If most of the entries have the
-form ???:??? the program probably wasn't compiled with
--g.)
     
+Then follows function-by-function statistics. Each function is
+identified by a file_name:function_name pair. If a column
+contains only a dot it means the function never performs
+that event (eg. the third row shows that strcmp()
+contains no instructions that write to memory). The name
+??? is used if the the file name and/or function name
+could not be determined from debugging information. If most of the
+entries have the form ???:??? the program probably wasn't
+compiled with -g.  
    
 
 It is worth noting that functions will come from three types of source files:
 
      
@@ -2111,12 +2140,13 @@ It is worth noting that functions will come from three types of source files:
   
 
    
 
-There are two ways to annotate source files -- by choosing them manually, or
-with the --auto=yes option. To do it manually, just
-specify the filenames as arguments to vg_annotate. For example, the output from
-running vg_annotate concord.c for our example produces the same
-output as above followed by an annotated version of concord.c, a
-section of which looks like:
+There are two ways to annotate source files -- by choosing them
+manually, or with the --auto=yes option. To do it
+manually, just specify the filenames as arguments to
+vg_annotate. For example, the output from running
+vg_annotate concord.c for our example produces the same
+output as above followed by an annotated version of
+concord.c, a section of which looks like:
 
 
     --------------------------------------------------------------------------------
@@ -2211,15 +2241,16 @@ auto-annotation can produce a lot of output if your program is large!
 
 
 
    7.8  Annotating assembler programs
    
-Valgrind can annotate assembler programs too, or annotate the assembler
-generated for your C program.  Sometimes this is useful for understanding what
-is really happening when an interesting line of C code is translated into
-multiple instructions.
    
+
+Valgrind can annotate assembler programs too, or annotate the
+assembler generated for your C program.  Sometimes this is useful for
+understanding what is really happening when an interesting line of C
+code is translated into multiple instructions.
    
 
 To do this, you just need to assemble your .s files with
-assembler-level debug information.  gcc doesn't do this, but you can use GNU as
-with the --gstabs option to generate object files with this
-information, eg:
+assembler-level debug information.  gcc doesn't do this, but you can
+use the GNU assembler with the --gstabs option to
+generate object files with this information, eg:
 
 
    as --gstabs foo.s
    
 
@@ -2227,7 +2258,7 @@ You can then profile and annotate source files in the same way as for C/C++
 programs.
 
 
-
    7.9  vg_annotate options
    
+
    7.9  vg_annotate options
    
 
      
   
    • -h, --help
      • 
   
    • -v, --version
      
@@ -2398,11 +2429,13 @@ hopefully they should be close enough to be useful.
      
 
        
   
      • Use CPUID instruction to auto-identify cache configuration during 
       installation.  This would save the user from having to know their cache
-      configuration and using vg_cachegen.
        • 
+      configuration and using vg_cachegen.
+  
        
   
      • Program start-up/shut-down calls a lot of functions that aren't
       interesting and just complicate the output.  Would be nice to exclude
-      these somehow.
        • 
-  
      • Handle files with >65535 lines
        • 
+      these somehow.
+  
        
+  
      • Handle files with more than 65535 lines.
        • 
 
       
 
      
 
diff --git a/coregrind/docs/manual.html b/coregrind/docs/manual.html
index 4da22db114..daaa1535d1 100644
--- a/coregrind/docs/manual.html
+++ b/coregrind/docs/manual.html
@@ -518,10 +518,9 @@ follows:
       

      • 
 
   
    • --cachesim=no [default]
      
-      --cachesim=yes
-      
      When enabled, turns off memory checking, and turns on cache profiling.
-      Cache profiling is described in detail in Section 7.
-      
      • 
+      --cachesim=yes 
      When enabled, turns off memory
+      checking, and turns on cache profiling.  Cache profiling is
+      described in detail in Section 7.  
      
 
    
 
 There are also some options for debugging Valgrind itself.  You
@@ -1799,45 +1798,56 @@ program as it will be normally run.
 
 The three steps are:
 
      
-  
    1. Generate a cache simulator for your machine's cache configuration with
-      `vg_cachegen' and recompile Valgrind with make install.
-      Valgrind comes with a default simulator, but it is unlikely to be correct
-      for your system, so you should generate a simulator yourself.
      2. 
-  
    2. Run your program with valgrind --cachesim=yes in front of 
-      the normal command line invocation.  When the program finishes, Valgrind
-      will print summary cache statistics. It also collects line-by-line
-      information in a file cachegrind.out.
      3. 
-  
    3. Generate a function-by-function summary, and possibly annotate source
-      files with 'vg_annotate'. Source files to annotate can be specified
-      manually, or manually on the command line, or "interesting" source files
-      can be annotated automatically with the --auto=yes option.
-      You can annotate C/C++ files or assembly language files equally
-      easily.
      4. 
+  
    4. Generate a cache simulator for your machine's cache
+      configuration with the supplied vg_cachegen
+      program, and recompile Valgrind with make install.
+      
      
+      The default settings are for an AMD Athlon, and you will get
+      useful information with the defaults, so you can skip this step
+      if you want.  Nevertheless, for accurate cache profiles you will
+      need use vg_cachegen to customise
+      cachegrind for your system.
+      
      
+      This step only needs to be done once, unless you are interested
+      in simulating different cache configurations (eg. first
+      concentrating on instruction cache misses, then on data cache
+      misses).      
+  
      5. 
+  
      
+  
    5. Run your program with cachegrind in front of the
+      normal command line invocation.  When the program finishes,
+      Valgrind will print summary cache statistics. It also collects
+      line-by-line information in a file cachegrind.out.
+      
      
+      This step should be done every time you want to collect
+      information about a new program, a changed program, or about the
+      same program with different input.
+  
      6. 
+  
      
+  
    6. Generate a function-by-function summary, and possibly annotate
+      source files with 'vg_annotate'. Source files to annotate can be
+      specified manually, or manually on the command line, or
+      "interesting" source files can be annotated automatically with
+      the --auto=yes option.  You can annotate C/C++
+      files or assembly language files equally easily.
      7. 
+      
      
+      This step can be performed as many times as you like for each
+      Step 2.  You may want to do multiple annotations showing
+      different information each time.
      
 
    
 
-Step 1 only needs to be done once, unless you are
-interested in simulating different cache configurations (eg. first
-concentrating on instruction cache misses, then on data cache misses).
    
-
-Step 2 should be done every time you want to collect
-information about a new program, a changed program, or about the same program
-with different input.
    
-
-Step 3 can be performed as many times as you like for
-each Step 2; you may want to do multiple annotations showing different
-information each time.
    
-
 The steps are described in detail in the following sections.
    
 
 
 
 
    7.3  Generating a cache simulator
    
-Although Valgrind comes with a pre-generated cache simulator, it most likely
-won't match the cache configuration of your machine, so you should generate
-a new simulator.
    
 
-You need to generate three files, one for each of the I1, D1 and L2 caches.
-For each cache, you need to know the:
+Although Valgrind comes with a pre-generated cache simulator, it most
+likely won't match the cache configuration of your machine, so you
+should generate a new simulator.
    
+
+You need to generate three files, one for each of the I1, D1 and L2
+caches.  For each cache, you need to know the:
 
      
   
    • Cache size (bytes);
   
    • Line size (bytes);
@@ -1851,9 +1861,10 @@ vg_cachegen takes three options:
   
    • --L2=size,line_size,associativity
 
    
 
-You can specify one, two or all three caches per invocation of vg_cachegen.  It
-checks that the configuration is sensible before generating the simulators;  to
-see the allowed values, run vg_cachegen -h.
    
+You can specify one, two or all three caches per invocation of
+vg_cachegen.  It checks that the configuration is sensible before
+generating the simulators; to see the allowed values, run
+vg_cachegen -h.
    
 
 An example invocation would be:
 
@@ -1861,37 +1872,43 @@ An example invocation would be:
   vg_cachegen --I1=65536,64,2 --D1=65536,64,2 --L2=262144,64,8
 
 
-This simulates a machine with a 128KB split L1 2-way associative cache, and a
-256KB unified 8-way associative L2 cache.  Both caches have 64B lines.
    
+This simulates a machine with a 128KB split L1 2-way associative
+cache, and a 256KB unified 8-way associative L2 cache.  Both caches
+have 64B lines.
    
 
-If you don't know your cache configuration, you'll have to find it out.
-(Ideally vg_cachegen could auto-identify your cache configuration using the
-CPUID instruction, which could be done automatically during installation, and
-this whole step could be skipped...)
    
+If you don't know your cache configuration, you'll have to find it
+out.  (Ideally vg_cachegen could auto-identify your cache
+configuration using the CPUID instruction, which could be done
+automatically during installation, and this whole step could be
+skipped.)
    
 
 
 
    7.4  Cache simulation specifics
    
-vg_cachegen only generates simulations for a machine with a split L1 cache and
-a unified L2 cache.  This configuration is used for all x86-based machines we
-are aware of.
    
+
+vg_cachegen only generates simulations for a machine with
+a split L1 cache and a unified L2 cache.  This configuration is used
+for all (modern) x86-based machines we are aware of.  Old Cyrix CPUs
+had a unified I and D L1 cache, but they are ancient history now.
    
 
 The more specific characteristics of the simulation are as follows.
 
 
      
-  
    • Write-allocate: when a write miss occurs, the block written to is brought
-      into the D1 cache.  Most modern caches have this property.
      • 
+  
    • Write-allocate: when a write miss occurs, the block written to
+      is brought into the D1 cache.  Most modern caches have this
+      property.
      • 
 
-  
    • Bit-selection hash function:  the line(s) in the cache to which a memory
-      block maps is chosen by the middle bits M--(M+N-1) of the byte address,
-      where:
+  
    • Bit-selection hash function: the line(s) in the cache to which a
+      memory block maps is chosen by the middle bits M--(M+N-1) of the
+      byte address, where:
       
        
         
      •  line size = 2^M bytes 
        • 
         
      • (cache size / line size) = 2^N bytes
        • 
       
       
      • 
 
-  
    • Inclusive L2 cache:  the L2 cache replicates all the entries of the L1
-      cache.  This is standard on Pentium chips, but AMD Athlons use an
-      exclusive L2 cache that only holds blocks evicted from L1.
      • 
+  
    • Inclusive L2 cache: the L2 cache replicates all the entries of
+      the L1 cache.  This is standard on Pentium chips, but AMD
+      Athlons use an exclusive L2 cache that only holds blocks evicted
+      from L1.  Ditto AMD Durons and most modern VIAs.
      • 
 
    
 
 Other noteworthy behaviour:
@@ -1924,14 +1941,18 @@ does.
 
 
 
    7.5  Profiling programs
    
-Cache profiling is enabled by using the --cachesim=yes option to
-Valgrind.  This automatically turns off Valgrind's memory checking functions,
-since the cache simulation is slow enough already, and you probably don't want
-to do both at once.
    
 
-To gather cache profiling information about the program ls -l--cachesim=yes
+option to the valgrind shell script.  Alternatively, it
+is probably more convenient to use the cachegrind script.
+This automatically turns off Valgrind's memory checking functions,
+since the cache simulation is slow enough already, and you probably
+don't want to do both at once.
+
    
+To gather cache profiling information about the program ls
+-lvalgrind --cachesim=yes ls -l
+
    cachegrind ls -l
    
 
 The program will execute (slowly).  Upon completion, summary statistics
 that look like this will be printed:
@@ -1967,30 +1988,36 @@ Combined instruction and data figures for the L2 cache follow that.
    
 
 
 
    7.6  Output file
    
-As well as printing summary information, Valgrind also writes line-by-line
-cache profiling information to a file named cachegrind.out .  This
-file is human-readable, but is best interpreted by the accompanying program
-vg_annotate, described in the next section.
    
 
+As well as printing summary information, Cachegrind also writes
+line-by-line cache profiling information to a file named
+cachegrind.out.  This file is human-readable, but is best
+interpreted by the accompanying program vg_annotate,
+described in the next section.
+
    
 Things to note about the cachegrind.out file:
 
      
-  
    • It is written every time valgrind --cachesim=yes is run; it
-      will automatically overwrite any existing cachegrind.out in
-      the current directory.
      • 
-  
    • It can be quite large: ls -l generates a file of about
-      350KB; browsing a few files and web pages with Konqueror generates a file
-      of around 10MB.
      • 
+  
    • It is written every time valgrind --cachesim=yes or
+      cachegrind is run, and will overwrite any existing
+      cachegrind.out in the current directory.
      • 
+  
      
+  
    • It can be huge: ls -l generates a file of about
+      350KB.  Browsing a few files and web pages with a Konqueror
+      built with full debugging information generates a file
+      of around 15 MB.
      • 
 
    
 
 
 
 
    7.7  Annotating C/C++ programs
    
-Before using vg_annotate, it is worth widening your window to be at least
-120-characters wide if possible, as the output lines can be quite long.
    
 
+Before using vg_annotate, it is worth widening your
+window to be at least 120-characters wide if possible, as the output
+lines can be quite long.
+
    
 To get a function-by-function summary, run vg_annotate in
-directory containing a cachegrind.out file.  The output looks like
-this:
+directory containing a cachegrind.out file.  The output
+looks like this:
 
 
     --------------------------------------------------------------------------------
@@ -2073,12 +2100,13 @@ First up is a summary of the annotation options:
       shown" line (and can be changed with the --sort option).
       
    
 
-  
  • Threshold: vg_annotate by default omits functions that cause very low
-      numbers of misses to avoid drowing you in information.  In this case,
-      vg_annotate shows summaries the functions that account for 99%   of the
-      Ir counts; Ir is chosen as the treshold event
-      since it is  the primary sort event.  The threshold can be adjusted with
-      the --threshold option.
    • 
+  
  • Threshold: vg_annotate by default omits functions
+      that cause very low numbers of misses to avoid drowning you in
+      information.  In this case, vg_annotate shows summaries the
+      functions that account for 99% of the Ir counts;
+      Ir is chosen as the threshold event since it is the
+      primary sort event.  The threshold can be adjusted with the
+      --threshold option.
    • 
 
   
  • Chosen for annotation: names of files specified manually for annotation; 
       in this case none.
    • 
@@ -2090,14 +2118,15 @@ First up is a summary of the annotation options:
 Then follows summary statistics for the whole program. These are similar
 to the summary provided when running valgrind --cachesim=yes.
    
   
-Then follows function-by-function statistics. Each function is identified by a
-file_name:function_name pair. If a column contains only a
-`.' it means  the function never performs that event (eg. the third row shows
-that strcmp() contains no instructions that write to memory). The
-name ??? is used if the the file name and/or function name could
-not be determined from debugging information. (If most of the entries have the
-form ???:??? the program probably wasn't compiled with
--g.)
     
+Then follows function-by-function statistics. Each function is
+identified by a file_name:function_name pair. If a column
+contains only a dot it means the function never performs
+that event (eg. the third row shows that strcmp()
+contains no instructions that write to memory). The name
+??? is used if the the file name and/or function name
+could not be determined from debugging information. If most of the
+entries have the form ???:??? the program probably wasn't
+compiled with -g.  
    
 
 It is worth noting that functions will come from three types of source files:
 
      
@@ -2111,12 +2140,13 @@ It is worth noting that functions will come from three types of source files:
   
 
    
 
-There are two ways to annotate source files -- by choosing them manually, or
-with the --auto=yes option. To do it manually, just
-specify the filenames as arguments to vg_annotate. For example, the output from
-running vg_annotate concord.c for our example produces the same
-output as above followed by an annotated version of concord.c, a
-section of which looks like:
+There are two ways to annotate source files -- by choosing them
+manually, or with the --auto=yes option. To do it
+manually, just specify the filenames as arguments to
+vg_annotate. For example, the output from running
+vg_annotate concord.c for our example produces the same
+output as above followed by an annotated version of
+concord.c, a section of which looks like:
 
 
     --------------------------------------------------------------------------------
@@ -2211,15 +2241,16 @@ auto-annotation can produce a lot of output if your program is large!
 
 
 
    7.8  Annotating assembler programs
    
-Valgrind can annotate assembler programs too, or annotate the assembler
-generated for your C program.  Sometimes this is useful for understanding what
-is really happening when an interesting line of C code is translated into
-multiple instructions.
    
+
+Valgrind can annotate assembler programs too, or annotate the
+assembler generated for your C program.  Sometimes this is useful for
+understanding what is really happening when an interesting line of C
+code is translated into multiple instructions.
    
 
 To do this, you just need to assemble your .s files with
-assembler-level debug information.  gcc doesn't do this, but you can use GNU as
-with the --gstabs option to generate object files with this
-information, eg:
+assembler-level debug information.  gcc doesn't do this, but you can
+use the GNU assembler with the --gstabs option to
+generate object files with this information, eg:
 
 
    as --gstabs foo.s
    
 
@@ -2227,7 +2258,7 @@ You can then profile and annotate source files in the same way as for C/C++
 programs.
 
 
-
    7.9  vg_annotate options
    
+
    7.9  vg_annotate options
    
 
      
   
    • -h, --help
      • 
   
    • -v, --version
      
@@ -2398,11 +2429,13 @@ hopefully they should be close enough to be useful.
      
 
        
   
      • Use CPUID instruction to auto-identify cache configuration during 
       installation.  This would save the user from having to know their cache
-      configuration and using vg_cachegen.
        • 
+      configuration and using vg_cachegen.
+  
        
   
      • Program start-up/shut-down calls a lot of functions that aren't
       interesting and just complicate the output.  Would be nice to exclude
-      these somehow.
        • 
-  
      • Handle files with >65535 lines
        • 
+      these somehow.
+  
        
+  
      • Handle files with more than 65535 lines.
        • 
 
       
 
      
 
diff --git a/docs/manual.html b/docs/manual.html
index 4da22db114..daaa1535d1 100644
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -518,10 +518,9 @@ follows:
       

      • 
 
   
    • --cachesim=no [default]
      
-      --cachesim=yes
-      
      When enabled, turns off memory checking, and turns on cache profiling.
-      Cache profiling is described in detail in Section 7.
-      
      • 
+      --cachesim=yes 
      When enabled, turns off memory
+      checking, and turns on cache profiling.  Cache profiling is
+      described in detail in Section 7.  
      
 
    
 
 There are also some options for debugging Valgrind itself.  You
@@ -1799,45 +1798,56 @@ program as it will be normally run.
 
 The three steps are:
 
      
-  
    1. Generate a cache simulator for your machine's cache configuration with
-      `vg_cachegen' and recompile Valgrind with make install.
-      Valgrind comes with a default simulator, but it is unlikely to be correct
-      for your system, so you should generate a simulator yourself.
      2. 
-  
    2. Run your program with valgrind --cachesim=yes in front of 
-      the normal command line invocation.  When the program finishes, Valgrind
-      will print summary cache statistics. It also collects line-by-line
-      information in a file cachegrind.out.
      3. 
-  
    3. Generate a function-by-function summary, and possibly annotate source
-      files with 'vg_annotate'. Source files to annotate can be specified
-      manually, or manually on the command line, or "interesting" source files
-      can be annotated automatically with the --auto=yes option.
-      You can annotate C/C++ files or assembly language files equally
-      easily.
      4. 
+  
    4. Generate a cache simulator for your machine's cache
+      configuration with the supplied vg_cachegen
+      program, and recompile Valgrind with make install.
+      
      
+      The default settings are for an AMD Athlon, and you will get
+      useful information with the defaults, so you can skip this step
+      if you want.  Nevertheless, for accurate cache profiles you will
+      need use vg_cachegen to customise
+      cachegrind for your system.
+      
      
+      This step only needs to be done once, unless you are interested
+      in simulating different cache configurations (eg. first
+      concentrating on instruction cache misses, then on data cache
+      misses).      
+  
      5. 
+  
      
+  
    5. Run your program with cachegrind in front of the
+      normal command line invocation.  When the program finishes,
+      Valgrind will print summary cache statistics. It also collects
+      line-by-line information in a file cachegrind.out.
+      
      
+      This step should be done every time you want to collect
+      information about a new program, a changed program, or about the
+      same program with different input.
+  
      6. 
+  
      
+  
    6. Generate a function-by-function summary, and possibly annotate
+      source files with 'vg_annotate'. Source files to annotate can be
+      specified manually, or manually on the command line, or
+      "interesting" source files can be annotated automatically with
+      the --auto=yes option.  You can annotate C/C++
+      files or assembly language files equally easily.
      7. 
+      
      
+      This step can be performed as many times as you like for each
+      Step 2.  You may want to do multiple annotations showing
+      different information each time.
      
 
    
 
-Step 1 only needs to be done once, unless you are
-interested in simulating different cache configurations (eg. first
-concentrating on instruction cache misses, then on data cache misses).
    
-
-Step 2 should be done every time you want to collect
-information about a new program, a changed program, or about the same program
-with different input.
    
-
-Step 3 can be performed as many times as you like for
-each Step 2; you may want to do multiple annotations showing different
-information each time.
    
-
 The steps are described in detail in the following sections.
    
 
 
 
 
    7.3  Generating a cache simulator
    
-Although Valgrind comes with a pre-generated cache simulator, it most likely
-won't match the cache configuration of your machine, so you should generate
-a new simulator.
    
 
-You need to generate three files, one for each of the I1, D1 and L2 caches.
-For each cache, you need to know the:
+Although Valgrind comes with a pre-generated cache simulator, it most
+likely won't match the cache configuration of your machine, so you
+should generate a new simulator.
    
+
+You need to generate three files, one for each of the I1, D1 and L2
+caches.  For each cache, you need to know the:
 
      
   
    • Cache size (bytes);
   
    • Line size (bytes);
@@ -1851,9 +1861,10 @@ vg_cachegen takes three options:
   
    • --L2=size,line_size,associativity
 
    
 
-You can specify one, two or all three caches per invocation of vg_cachegen.  It
-checks that the configuration is sensible before generating the simulators;  to
-see the allowed values, run vg_cachegen -h.
    
+You can specify one, two or all three caches per invocation of
+vg_cachegen.  It checks that the configuration is sensible before
+generating the simulators; to see the allowed values, run
+vg_cachegen -h.
    
 
 An example invocation would be:
 
@@ -1861,37 +1872,43 @@ An example invocation would be:
   vg_cachegen --I1=65536,64,2 --D1=65536,64,2 --L2=262144,64,8
 
 
-This simulates a machine with a 128KB split L1 2-way associative cache, and a
-256KB unified 8-way associative L2 cache.  Both caches have 64B lines.
    
+This simulates a machine with a 128KB split L1 2-way associative
+cache, and a 256KB unified 8-way associative L2 cache.  Both caches
+have 64B lines.
    
 
-If you don't know your cache configuration, you'll have to find it out.
-(Ideally vg_cachegen could auto-identify your cache configuration using the
-CPUID instruction, which could be done automatically during installation, and
-this whole step could be skipped...)
    
+If you don't know your cache configuration, you'll have to find it
+out.  (Ideally vg_cachegen could auto-identify your cache
+configuration using the CPUID instruction, which could be done
+automatically during installation, and this whole step could be
+skipped.)
    
 
 
 
    7.4  Cache simulation specifics
    
-vg_cachegen only generates simulations for a machine with a split L1 cache and
-a unified L2 cache.  This configuration is used for all x86-based machines we
-are aware of.
    
+
+vg_cachegen only generates simulations for a machine with
+a split L1 cache and a unified L2 cache.  This configuration is used
+for all (modern) x86-based machines we are aware of.  Old Cyrix CPUs
+had a unified I and D L1 cache, but they are ancient history now.
    
 
 The more specific characteristics of the simulation are as follows.
 
 
      
-  
    • Write-allocate: when a write miss occurs, the block written to is brought
-      into the D1 cache.  Most modern caches have this property.
      • 
+  
    • Write-allocate: when a write miss occurs, the block written to
+      is brought into the D1 cache.  Most modern caches have this
+      property.
      • 
 
-  
    • Bit-selection hash function:  the line(s) in the cache to which a memory
-      block maps is chosen by the middle bits M--(M+N-1) of the byte address,
-      where:
+  
    • Bit-selection hash function: the line(s) in the cache to which a
+      memory block maps is chosen by the middle bits M--(M+N-1) of the
+      byte address, where:
       
        
         
      •  line size = 2^M bytes 
        • 
         
      • (cache size / line size) = 2^N bytes
        • 
       
       
      • 
 
-  
    • Inclusive L2 cache:  the L2 cache replicates all the entries of the L1
-      cache.  This is standard on Pentium chips, but AMD Athlons use an
-      exclusive L2 cache that only holds blocks evicted from L1.
      • 
+  
    • Inclusive L2 cache: the L2 cache replicates all the entries of
+      the L1 cache.  This is standard on Pentium chips, but AMD
+      Athlons use an exclusive L2 cache that only holds blocks evicted
+      from L1.  Ditto AMD Durons and most modern VIAs.
      • 
 
    
 
 Other noteworthy behaviour:
@@ -1924,14 +1941,18 @@ does.
 
 
 
    7.5  Profiling programs
    
-Cache profiling is enabled by using the --cachesim=yes option to
-Valgrind.  This automatically turns off Valgrind's memory checking functions,
-since the cache simulation is slow enough already, and you probably don't want
-to do both at once.
    
 
-To gather cache profiling information about the program ls -l--cachesim=yes
+option to the valgrind shell script.  Alternatively, it
+is probably more convenient to use the cachegrind script.
+This automatically turns off Valgrind's memory checking functions,
+since the cache simulation is slow enough already, and you probably
+don't want to do both at once.
+
    
+To gather cache profiling information about the program ls
+-lvalgrind --cachesim=yes ls -l
+
    cachegrind ls -l
    
 
 The program will execute (slowly).  Upon completion, summary statistics
 that look like this will be printed:
@@ -1967,30 +1988,36 @@ Combined instruction and data figures for the L2 cache follow that.
    
 
 
 
    7.6  Output file
    
-As well as printing summary information, Valgrind also writes line-by-line
-cache profiling information to a file named cachegrind.out .  This
-file is human-readable, but is best interpreted by the accompanying program
-vg_annotate, described in the next section.
    
 
+As well as printing summary information, Cachegrind also writes
+line-by-line cache profiling information to a file named
+cachegrind.out.  This file is human-readable, but is best
+interpreted by the accompanying program vg_annotate,
+described in the next section.
+
    
 Things to note about the cachegrind.out file:
 
      
-  
    • It is written every time valgrind --cachesim=yes is run; it
-      will automatically overwrite any existing cachegrind.out in
-      the current directory.
      • 
-  
    • It can be quite large: ls -l generates a file of about
-      350KB; browsing a few files and web pages with Konqueror generates a file
-      of around 10MB.
      • 
+  
    • It is written every time valgrind --cachesim=yes or
+      cachegrind is run, and will overwrite any existing
+      cachegrind.out in the current directory.
      • 
+  
      
+  
    • It can be huge: ls -l generates a file of about
+      350KB.  Browsing a few files and web pages with a Konqueror
+      built with full debugging information generates a file
+      of around 15 MB.
      • 
 
    
 
 
 
 
    7.7  Annotating C/C++ programs
    
-Before using vg_annotate, it is worth widening your window to be at least
-120-characters wide if possible, as the output lines can be quite long.
    
 
+Before using vg_annotate, it is worth widening your
+window to be at least 120-characters wide if possible, as the output
+lines can be quite long.
+
    
 To get a function-by-function summary, run vg_annotate in
-directory containing a cachegrind.out file.  The output looks like
-this:
+directory containing a cachegrind.out file.  The output
+looks like this:
 
 
     --------------------------------------------------------------------------------
@@ -2073,12 +2100,13 @@ First up is a summary of the annotation options:
       shown" line (and can be changed with the --sort option).
       
    
 
-  
  • Threshold: vg_annotate by default omits functions that cause very low
-      numbers of misses to avoid drowing you in information.  In this case,
-      vg_annotate shows summaries the functions that account for 99%   of the
-      Ir counts; Ir is chosen as the treshold event
-      since it is  the primary sort event.  The threshold can be adjusted with
-      the --threshold option.
    • 
+  
  • Threshold: vg_annotate by default omits functions
+      that cause very low numbers of misses to avoid drowning you in
+      information.  In this case, vg_annotate shows summaries the
+      functions that account for 99% of the Ir counts;
+      Ir is chosen as the threshold event since it is the
+      primary sort event.  The threshold can be adjusted with the
+      --threshold option.
    • 
 
   
  • Chosen for annotation: names of files specified manually for annotation; 
       in this case none.
    • 
@@ -2090,14 +2118,15 @@ First up is a summary of the annotation options:
 Then follows summary statistics for the whole program. These are similar
 to the summary provided when running valgrind --cachesim=yes.
    
   
-Then follows function-by-function statistics. Each function is identified by a
-file_name:function_name pair. If a column contains only a
-`.' it means  the function never performs that event (eg. the third row shows
-that strcmp() contains no instructions that write to memory). The
-name ??? is used if the the file name and/or function name could
-not be determined from debugging information. (If most of the entries have the
-form ???:??? the program probably wasn't compiled with
--g.)
     
+Then follows function-by-function statistics. Each function is
+identified by a file_name:function_name pair. If a column
+contains only a dot it means the function never performs
+that event (eg. the third row shows that strcmp()
+contains no instructions that write to memory). The name
+??? is used if the the file name and/or function name
+could not be determined from debugging information. If most of the
+entries have the form ???:??? the program probably wasn't
+compiled with -g.  
    
 
 It is worth noting that functions will come from three types of source files:
 
      
@@ -2111,12 +2140,13 @@ It is worth noting that functions will come from three types of source files:
   
 
    
 
-There are two ways to annotate source files -- by choosing them manually, or
-with the --auto=yes option. To do it manually, just
-specify the filenames as arguments to vg_annotate. For example, the output from
-running vg_annotate concord.c for our example produces the same
-output as above followed by an annotated version of concord.c, a
-section of which looks like:
+There are two ways to annotate source files -- by choosing them
+manually, or with the --auto=yes option. To do it
+manually, just specify the filenames as arguments to
+vg_annotate. For example, the output from running
+vg_annotate concord.c for our example produces the same
+output as above followed by an annotated version of
+concord.c, a section of which looks like:
 
 
     --------------------------------------------------------------------------------
@@ -2211,15 +2241,16 @@ auto-annotation can produce a lot of output if your program is large!
 
 
 
    7.8  Annotating assembler programs
    
-Valgrind can annotate assembler programs too, or annotate the assembler
-generated for your C program.  Sometimes this is useful for understanding what
-is really happening when an interesting line of C code is translated into
-multiple instructions.
    
+
+Valgrind can annotate assembler programs too, or annotate the
+assembler generated for your C program.  Sometimes this is useful for
+understanding what is really happening when an interesting line of C
+code is translated into multiple instructions.
    
 
 To do this, you just need to assemble your .s files with
-assembler-level debug information.  gcc doesn't do this, but you can use GNU as
-with the --gstabs option to generate object files with this
-information, eg:
+assembler-level debug information.  gcc doesn't do this, but you can
+use the GNU assembler with the --gstabs option to
+generate object files with this information, eg:
 
 
    as --gstabs foo.s
    
 
@@ -2227,7 +2258,7 @@ You can then profile and annotate source files in the same way as for C/C++
 programs.
 
 
-
    7.9  vg_annotate options
    
+
    7.9  vg_annotate options
    
 
      
   
    • -h, --help
      • 
   
    • -v, --version
      
@@ -2398,11 +2429,13 @@ hopefully they should be close enough to be useful.
      
 
        
   
      • Use CPUID instruction to auto-identify cache configuration during 
       installation.  This would save the user from having to know their cache
-      configuration and using vg_cachegen.
        • 
+      configuration and using vg_cachegen.
+  
        
   
      • Program start-up/shut-down calls a lot of functions that aren't
       interesting and just complicate the output.  Would be nice to exclude
-      these somehow.
        • 
-  
      • Handle files with >65535 lines
        • 
+      these somehow.
+  
        
+  
      • Handle files with more than 65535 lines.
        • 
 
       
 
      
 
diff --git a/memcheck/docs/manual.html b/memcheck/docs/manual.html
index 4da22db114..daaa1535d1 100644
--- a/memcheck/docs/manual.html
+++ b/memcheck/docs/manual.html
@@ -518,10 +518,9 @@ follows:
       

      • 
 
   
    • --cachesim=no [default]
      
-      --cachesim=yes
-      
      When enabled, turns off memory checking, and turns on cache profiling.
-      Cache profiling is described in detail in Section 7.
-      
      • 
+      --cachesim=yes 
      When enabled, turns off memory
+      checking, and turns on cache profiling.  Cache profiling is
+      described in detail in Section 7.  
      
 
    
 
 There are also some options for debugging Valgrind itself.  You
@@ -1799,45 +1798,56 @@ program as it will be normally run.
 
 The three steps are:
 
      
-  
    1. Generate a cache simulator for your machine's cache configuration with
-      `vg_cachegen' and recompile Valgrind with make install.
-      Valgrind comes with a default simulator, but it is unlikely to be correct
-      for your system, so you should generate a simulator yourself.
      2. 
-  
    2. Run your program with valgrind --cachesim=yes in front of 
-      the normal command line invocation.  When the program finishes, Valgrind
-      will print summary cache statistics. It also collects line-by-line
-      information in a file cachegrind.out.
      3. 
-  
    3. Generate a function-by-function summary, and possibly annotate source
-      files with 'vg_annotate'. Source files to annotate can be specified
-      manually, or manually on the command line, or "interesting" source files
-      can be annotated automatically with the --auto=yes option.
-      You can annotate C/C++ files or assembly language files equally
-      easily.
      4. 
+  
    4. Generate a cache simulator for your machine's cache
+      configuration with the supplied vg_cachegen
+      program, and recompile Valgrind with make install.
+      
      
+      The default settings are for an AMD Athlon, and you will get
+      useful information with the defaults, so you can skip this step
+      if you want.  Nevertheless, for accurate cache profiles you will
+      need use vg_cachegen to customise
+      cachegrind for your system.
+      
      
+      This step only needs to be done once, unless you are interested
+      in simulating different cache configurations (eg. first
+      concentrating on instruction cache misses, then on data cache
+      misses).      
+  
      5. 
+  
      
+  
    5. Run your program with cachegrind in front of the
+      normal command line invocation.  When the program finishes,
+      Valgrind will print summary cache statistics. It also collects
+      line-by-line information in a file cachegrind.out.
+      
      
+      This step should be done every time you want to collect
+      information about a new program, a changed program, or about the
+      same program with different input.
+  
      6. 
+  
      
+  
    6. Generate a function-by-function summary, and possibly annotate
+      source files with 'vg_annotate'. Source files to annotate can be
+      specified manually, or manually on the command line, or
+      "interesting" source files can be annotated automatically with
+      the --auto=yes option.  You can annotate C/C++
+      files or assembly language files equally easily.
      7. 
+      
      
+      This step can be performed as many times as you like for each
+      Step 2.  You may want to do multiple annotations showing
+      different information each time.
      
 
    
 
-Step 1 only needs to be done once, unless you are
-interested in simulating different cache configurations (eg. first
-concentrating on instruction cache misses, then on data cache misses).
    
-
-Step 2 should be done every time you want to collect
-information about a new program, a changed program, or about the same program
-with different input.
    
-
-Step 3 can be performed as many times as you like for
-each Step 2; you may want to do multiple annotations showing different
-information each time.
    
-
 The steps are described in detail in the following sections.
    
 
 
 
 
    7.3  Generating a cache simulator
    
-Although Valgrind comes with a pre-generated cache simulator, it most likely
-won't match the cache configuration of your machine, so you should generate
-a new simulator.
    
 
-You need to generate three files, one for each of the I1, D1 and L2 caches.
-For each cache, you need to know the:
+Although Valgrind comes with a pre-generated cache simulator, it most
+likely won't match the cache configuration of your machine, so you
+should generate a new simulator.
    
+
+You need to generate three files, one for each of the I1, D1 and L2
+caches.  For each cache, you need to know the:
 
      
   
    • Cache size (bytes);
   
    • Line size (bytes);
@@ -1851,9 +1861,10 @@ vg_cachegen takes three options:
   
    • --L2=size,line_size,associativity
 
    
 
-You can specify one, two or all three caches per invocation of vg_cachegen.  It
-checks that the configuration is sensible before generating the simulators;  to
-see the allowed values, run vg_cachegen -h.
    
+You can specify one, two or all three caches per invocation of
+vg_cachegen.  It checks that the configuration is sensible before
+generating the simulators; to see the allowed values, run
+vg_cachegen -h.
    
 
 An example invocation would be:
 
@@ -1861,37 +1872,43 @@ An example invocation would be:
   vg_cachegen --I1=65536,64,2 --D1=65536,64,2 --L2=262144,64,8
 
 
-This simulates a machine with a 128KB split L1 2-way associative cache, and a
-256KB unified 8-way associative L2 cache.  Both caches have 64B lines.
    
+This simulates a machine with a 128KB split L1 2-way associative
+cache, and a 256KB unified 8-way associative L2 cache.  Both caches
+have 64B lines.
    
 
-If you don't know your cache configuration, you'll have to find it out.
-(Ideally vg_cachegen could auto-identify your cache configuration using the
-CPUID instruction, which could be done automatically during installation, and
-this whole step could be skipped...)
    
+If you don't know your cache configuration, you'll have to find it
+out.  (Ideally vg_cachegen could auto-identify your cache
+configuration using the CPUID instruction, which could be done
+automatically during installation, and this whole step could be
+skipped.)
    
 
 
 
    7.4  Cache simulation specifics
    
-vg_cachegen only generates simulations for a machine with a split L1 cache and
-a unified L2 cache.  This configuration is used for all x86-based machines we
-are aware of.
    
+
+vg_cachegen only generates simulations for a machine with
+a split L1 cache and a unified L2 cache.  This configuration is used
+for all (modern) x86-based machines we are aware of.  Old Cyrix CPUs
+had a unified I and D L1 cache, but they are ancient history now.
    
 
 The more specific characteristics of the simulation are as follows.
 
 
      
-  
    • Write-allocate: when a write miss occurs, the block written to is brought
-      into the D1 cache.  Most modern caches have this property.
      • 
+  
    • Write-allocate: when a write miss occurs, the block written to
+      is brought into the D1 cache.  Most modern caches have this
+      property.
      • 
 
-  
    • Bit-selection hash function:  the line(s) in the cache to which a memory
-      block maps is chosen by the middle bits M--(M+N-1) of the byte address,
-      where:
+  
    • Bit-selection hash function: the line(s) in the cache to which a
+      memory block maps is chosen by the middle bits M--(M+N-1) of the
+      byte address, where:
       
        
         
      •  line size = 2^M bytes 
        • 
         
      • (cache size / line size) = 2^N bytes
        • 
       
       
      • 
 
-  
    • Inclusive L2 cache:  the L2 cache replicates all the entries of the L1
-      cache.  This is standard on Pentium chips, but AMD Athlons use an
-      exclusive L2 cache that only holds blocks evicted from L1.
      • 
+  
    • Inclusive L2 cache: the L2 cache replicates all the entries of
+      the L1 cache.  This is standard on Pentium chips, but AMD
+      Athlons use an exclusive L2 cache that only holds blocks evicted
+      from L1.  Ditto AMD Durons and most modern VIAs.
      • 
 
    
 
 Other noteworthy behaviour:
@@ -1924,14 +1941,18 @@ does.
 
 
 
    7.5  Profiling programs
    
-Cache profiling is enabled by using the --cachesim=yes option to
-Valgrind.  This automatically turns off Valgrind's memory checking functions,
-since the cache simulation is slow enough already, and you probably don't want
-to do both at once.
    
 
-To gather cache profiling information about the program ls -l--cachesim=yes
+option to the valgrind shell script.  Alternatively, it
+is probably more convenient to use the cachegrind script.
+This automatically turns off Valgrind's memory checking functions,
+since the cache simulation is slow enough already, and you probably
+don't want to do both at once.
+
    
+To gather cache profiling information about the program ls
+-lvalgrind --cachesim=yes ls -l
+
    cachegrind ls -l
    
 
 The program will execute (slowly).  Upon completion, summary statistics
 that look like this will be printed:
@@ -1967,30 +1988,36 @@ Combined instruction and data figures for the L2 cache follow that.
    
 
 
 
    7.6  Output file
    
-As well as printing summary information, Valgrind also writes line-by-line
-cache profiling information to a file named cachegrind.out .  This
-file is human-readable, but is best interpreted by the accompanying program
-vg_annotate, described in the next section.
    
 
+As well as printing summary information, Cachegrind also writes
+line-by-line cache profiling information to a file named
+cachegrind.out.  This file is human-readable, but is best
+interpreted by the accompanying program vg_annotate,
+described in the next section.
+
    
 Things to note about the cachegrind.out file:
 
      
-  
    • It is written every time valgrind --cachesim=yes is run; it
-      will automatically overwrite any existing cachegrind.out in
-      the current directory.
      • 
-  
    • It can be quite large: ls -l generates a file of about
-      350KB; browsing a few files and web pages with Konqueror generates a file
-      of around 10MB.
      • 
+  
    • It is written every time valgrind --cachesim=yes or
+      cachegrind is run, and will overwrite any existing
+      cachegrind.out in the current directory.
      • 
+  
      
+  
    • It can be huge: ls -l generates a file of about
+      350KB.  Browsing a few files and web pages with a Konqueror
+      built with full debugging information generates a file
+      of around 15 MB.
      • 
 
    
 
 
 
 
    7.7  Annotating C/C++ programs
    
-Before using vg_annotate, it is worth widening your window to be at least
-120-characters wide if possible, as the output lines can be quite long.
    
 
+Before using vg_annotate, it is worth widening your
+window to be at least 120-characters wide if possible, as the output
+lines can be quite long.
+
    
 To get a function-by-function summary, run vg_annotate in
-directory containing a cachegrind.out file.  The output looks like
-this:
+directory containing a cachegrind.out file.  The output
+looks like this:
 
 
     --------------------------------------------------------------------------------
@@ -2073,12 +2100,13 @@ First up is a summary of the annotation options:
       shown" line (and can be changed with the --sort option).
       
    
 
-  
  • Threshold: vg_annotate by default omits functions that cause very low
-      numbers of misses to avoid drowing you in information.  In this case,
-      vg_annotate shows summaries the functions that account for 99%   of the
-      Ir counts; Ir is chosen as the treshold event
-      since it is  the primary sort event.  The threshold can be adjusted with
-      the --threshold option.
    • 
+  
  • Threshold: vg_annotate by default omits functions
+      that cause very low numbers of misses to avoid drowning you in
+      information.  In this case, vg_annotate shows summaries the
+      functions that account for 99% of the Ir counts;
+      Ir is chosen as the threshold event since it is the
+      primary sort event.  The threshold can be adjusted with the
+      --threshold option.
    • 
 
   
  • Chosen for annotation: names of files specified manually for annotation; 
       in this case none.
    • 
@@ -2090,14 +2118,15 @@ First up is a summary of the annotation options:
 Then follows summary statistics for the whole program. These are similar
 to the summary provided when running valgrind --cachesim=yes.
    
   
-Then follows function-by-function statistics. Each function is identified by a
-file_name:function_name pair. If a column contains only a
-`.' it means  the function never performs that event (eg. the third row shows
-that strcmp() contains no instructions that write to memory). The
-name ??? is used if the the file name and/or function name could
-not be determined from debugging information. (If most of the entries have the
-form ???:??? the program probably wasn't compiled with
--g.)
     
+Then follows function-by-function statistics. Each function is
+identified by a file_name:function_name pair. If a column
+contains only a dot it means the function never performs
+that event (eg. the third row shows that strcmp()
+contains no instructions that write to memory). The name
+??? is used if the the file name and/or function name
+could not be determined from debugging information. If most of the
+entries have the form ???:??? the program probably wasn't
+compiled with -g.  
    
 
 It is worth noting that functions will come from three types of source files:
 
      
@@ -2111,12 +2140,13 @@ It is worth noting that functions will come from three types of source files:
   
 
    
 
-There are two ways to annotate source files -- by choosing them manually, or
-with the --auto=yes option. To do it manually, just
-specify the filenames as arguments to vg_annotate. For example, the output from
-running vg_annotate concord.c for our example produces the same
-output as above followed by an annotated version of concord.c, a
-section of which looks like:
+There are two ways to annotate source files -- by choosing them
+manually, or with the --auto=yes option. To do it
+manually, just specify the filenames as arguments to
+vg_annotate. For example, the output from running
+vg_annotate concord.c for our example produces the same
+output as above followed by an annotated version of
+concord.c, a section of which looks like:
 
 
     --------------------------------------------------------------------------------
@@ -2211,15 +2241,16 @@ auto-annotation can produce a lot of output if your program is large!
 
 
 
    7.8  Annotating assembler programs
    
-Valgrind can annotate assembler programs too, or annotate the assembler
-generated for your C program.  Sometimes this is useful for understanding what
-is really happening when an interesting line of C code is translated into
-multiple instructions.
    
+
+Valgrind can annotate assembler programs too, or annotate the
+assembler generated for your C program.  Sometimes this is useful for
+understanding what is really happening when an interesting line of C
+code is translated into multiple instructions.
    
 
 To do this, you just need to assemble your .s files with
-assembler-level debug information.  gcc doesn't do this, but you can use GNU as
-with the --gstabs option to generate object files with this
-information, eg:
+assembler-level debug information.  gcc doesn't do this, but you can
+use the GNU assembler with the --gstabs option to
+generate object files with this information, eg:
 
 
    as --gstabs foo.s
    
 
@@ -2227,7 +2258,7 @@ You can then profile and annotate source files in the same way as for C/C++
 programs.
 
 
-
    7.9  vg_annotate options
    
+
    7.9  vg_annotate options
    
 
      
   
    • -h, --help
      • 
   
    • -v, --version
      
@@ -2398,11 +2429,13 @@ hopefully they should be close enough to be useful.
      
 
        
   
      • Use CPUID instruction to auto-identify cache configuration during 
       installation.  This would save the user from having to know their cache
-      configuration and using vg_cachegen.
        • 
+      configuration and using vg_cachegen.
+  
        
   
      • Program start-up/shut-down calls a lot of functions that aren't
       interesting and just complicate the output.  Would be nice to exclude
-      these somehow.
        • 
-  
      • Handle files with >65535 lines
        • 
+      these somehow.
+  
        
+  
      • Handle files with more than 65535 lines.
        • 
 
       
 
      
 
-- 
2.47.2