Diff of /faq/index.php [9d1011] .. [4014b2] Maximize Restore

  Switch to side-by-side view

--- a/faq/index.php
+++ b/faq/index.php
@@ -4,15 +4,21 @@
 <p>
 For 2.4 kernels, you must have the kernel source available for the kernel
 you want to run OProfile under. Do <tt>./configure --with-linux=/path/to/kernel/source</tt>
-then <tt>make install</tt>. For 2.6 kernels, configure OProfile into the
-kernel (or as a module), then do <tt>./configure --with-kernel-support</tt>
-instead.
+then <tt>make install</tt>. This option is no longer supported with OProfile 0.9.8
+and higher.
+</p>
+<p>
+For 2.6 or higher kernels, ensure that the kernel has been configured to include OProfile, either
+built into the kernel or as a module.  Next, do <tt>./configure --with-kernel-support</tt>.
+As of OProfile 0.9.8, kernel support is assumed, and the <tt>--with-kernel-support</tt>
+option is no longer needed nor available.
 </p>
 
 <h3>Where can I get the required libraries ?</h3>
 <p>
-They should already be installed on your system. You may not have
-the binutils development package installed, which provides libiberty 
+Most required runtime libraries should already be installed on your system. 
+For building OProfile, you may need to install additional devel packages --
+for example, the binutils development package, which provides libiberty 
 and others. On Debian, this package is not installed by default, and
 is named "binutils-dev".
 </p>
@@ -24,25 +30,44 @@
 
 <h3>How do I reset the profiling data ?</h3>
 <p>
-Using <tt>opcontrol --reset</tt>, or you can save the session under a name
-with <tt>opcontrol --save sessionname</tt>.
+For legacy OProfile (i.e., <tt>opcontrol</tt>-based profiling), use <tt>opcontrol --reset</tt>,
+or you can save the session under a name with <tt>opcontrol --save &lt;sessionname&gt;</tt>.
+When using <tt>operf</tt> for profiling, a new profiling session will cause the current
+profile data (stored in <tt>&lt;cur-dir&gt;/oprofile_data/samples/current</tt>) to be
+renamed from <tt>current</tt> to <tt>previous</tt>, so there is usually no need to manually
+delete old profile data.  However, a manual deletion can be accomplished by simply
+doing <tt>rm -rf &lt;cur-dir&gt;/oprofile_data/samples/current</tt>.
 </p>
 
 <h3>I get "error: no sample files found: profile specification too strict ?"</h3>
 <p>
-Read <?php rlink("doc/results.html#no-results", "What to do when you don't get any results") ?>.
+If using <tt>operf</tt>, make sure you run OProfile post-processing tools (e.g., <tt>opreport, opannotate</tt>)
+from the directory where you collected the profile.  Alternatively, you can specify the
+location of sample data using the <tt>--session-dir</tt> option.
+</p>
+<p>Incorrect specification of the image name (i.e., app name) when invoking post-processing tools
+is a common cause for this error message. If you used <tt>operf</tt> to profile a single application,
+there is no need to append the image name at the end of your invocation since samples are collected
+only for the given application.
+</p>
+<p>
+For other possible causes for this error message, read <?php rlink("doc/results.html#no-results", "What to do when you don't get any results") ?>.
 </p>
 
 <h3>Can OProfile profile the kernel too ?</h3>
 <p>
-Yes, it profiles the kernel and all kernel modules by default. Pass
-the kernel vmlinux image to the post-profiling tools to get kernel
-profiles (or the module .o files). For example, <tt>opreport -l /boot/2.6.0/vmlinux</tt>.
+Yes, if you pass the <tt>--vmlinux</tt> option when profiling, OProfile will profile the kernel and
+all kernel modules, and the post-processing tools will show kernel symbols for which samples
+were taken.  In order for post-processing tools to show symbol info for kernel modules, you
+must pass the <tt>--image-path</tt> option; for example, <tt>opreport --symbols /lib/modules/`uname -r`</tt>.
 </p>
 
 <h3>I don't have a vmlinux file, but I want to profile the kernel anyway !</h3>
 <p>
-Use <tt>opcontrol --no-vmlinux</tt> when profiling.  Then
+If using <tt>operf</tt>, all kernel samples are automatically attributed to a
+"no-vmlinux" pseudo-symbol, unless the <tt>--vmlinux</tt> option is used.
+If profiling with legacy <tt>opcontrol</tt>, use <tt>opcontrol --no-vmlinux</tt> if no
+vmlinux file is available.  Then
 <a href="http://marc.info/?l=oprofile-list&m=121514749918466&q=p3">use
 this script to list the samples</a>.
 </p>
@@ -50,49 +75,39 @@
 <h3>Why do the profile tools fail to open the vmlinux kernel image ?</h3>
 <p>
 Probably because you have accidentally specified the vmlinu<em>z</em> not
-vmlinu<em>x</em> file. If you don't have a vmlinux file you need to recompile your kernel from source.
-If you're not doing kernel profiling, you can use <tt>opcontrol --no-vmlinux</tt>.
+vmlinu<em>x</em> file. If you don't have a vmlinux file, most Linux distributions provide
+a kernel debuginfo package that includes it.  Otherwise, you need to recompile your kernel from source.
+If you're not interested in kernel samples, then don't use the <tt>--vmlinux</tt> option
+(and for legacy profiling, use <tt>opcontrol --no-vmlinux</tt>).
 </p>
  
 <h3>Why is OProfile ignoring me when I try to change the events to profile ?</h3>
 <p>
-For OProfile to start profiling using the new events, the daemon must be
-restarted. In particular, you must use <tt>--shutdown</tt> not
+When using legacy <tt>opcontrol</tt>, the <tt>oprofiled</tt> daemon must be
+restarted in order to use newly-specified events and other new profiling parameters.
+To restart the daemon, you must use <tt>--shutdown</tt>, not
 <tt>--stop</tt>, as the latter does <em>not</em> restart the daemon.
-Note that the old profiling data is still kept: use <tt>--reset</tt> or
-<tt>--save</tt> if you want to clear out old data.
-</p>
-
-<h3>But Red Hat don't ship a <tt>vmlinux</tt></h3>
-<p>
-Actually they do, but it's not installed by default, because it's
-stupidly included the huge <tt>kernel-debuginfo</tt> package. I'm afraid
-you have no choice other than downloading this CD-sized package, or
-compiling your own.
-</p>
-
-<h3>OProfile doesn't work on Red Hat !</h3>
-<p>
-Red Hat made changes to their kernel, so you cannot use OProfile on Red Hat
-kernels unless you use their version (which is not available for 7.3). Any problems
-with Red Hat's version of OProfile should be reported to them not us. If you
-compile your own kernel from Linus's tarball, OProfile should work. Alternatively,
-you can re-compile Red Hat's kernel with <tt>sys_call_table</tt> added.
-Alternatively, the latest "bigmem" kernels for 7.3 include the Red Hat OProfile backport. 
-If you use this version you must use the OProfile userspace RPM
-from Red Hat 8.0, not any version from this site.
-</p>
+Note that old profiling data is still kept; only <tt>--reset</tt> or
+<tt>--save</tt> will clear the default sample data directory.
+</p>
+
+<h3>But Red Hat doesn't ship a <tt>vmlinux</tt></h3>
+<p>
+Actually they do, but it's not installed by default; it's
+included the <tt>kernel-debuginfo</tt> package.
+</p>
+
 
 <h3>Why is OProfile in timer mode on x86? I have performance counters...</h3>
 <p>
-Recent 2.6 kernels disable the local APIC by default. You can try
+Some 2.6+ kernels disable the local APIC by default. You can try
 enabling the local APIC (if you do indeed have one) by booting with the
 <tt>lapic</tt> boot option.
 </p>
 
 <h3>Why does OProfile fail with "can't get RTC I/O ports" ?</h3>
 <p>
-On some systems, only RTC mode profiling is available, as described
+On some systems running with pre-2.6 kernels, only RTC mode profiling is available, as described
 in the documentation. If RTC mode is used, you must <i>not</i> use a kernel
 with the RTC driver built-in (that is, <tt>CONFIG_RTC</tt> must not be set to
 <tt>y</tt>). Otherwise, OProfile cannot acquire the RTC hardware for its own
@@ -102,7 +117,7 @@
 
 <h3>Can I get a summary of the whole system ?</h3>
 <p>
-Try
+Assuming you collected a system-wide profile with either <tt>opcontrol</tt> or <tt>operf --system-wide</tt>, try
 </p>
 
 <div class="computeroutput">opreport
@@ -139,7 +154,7 @@
 
 <li>
 Many laptops do not have performance counter hardware; in this case OProfile
-falls back to RTC mode (read the <? rlink("docs/", "documentation"); ?> for
+falls back to RTC/timer mode (read the <? rlink("docs/", "documentation"); ?> for
 more details).
 </li>
 
@@ -147,7 +162,7 @@
 Users report that power management is not compatible with OProfile
 on some laptops. Enabling power management is likely
 to hang your box if you are using the performance counters. This
-does not apply if you're using a 2.6 kernel.
+does not apply if you're using a 2.6 or higher kernel.
 </li>
 
 </ol>
@@ -158,16 +173,18 @@
 lost in the noise (1-3%). <? rlink("performance/", "This graph gives typical examples."); ?>
 </p>
 
-<h3>Does OProfile work on any other architectures yet ?</h3>
+<h3>What architectures are supported by OProfile ?</h3>
 <p>
 OProfile ports for IA-64, AMD64, ARM, Alpha, PA-RISC, sparc64, s390, and ppc64
-are all in various stages of support, mostly only on 2.6 kernels.
+are all in various stages of support, mostly only on 2.6 or higher kernels.  Older processor
+models or defunct architectures may only be supported with the legacy (i.e., <tt>opcontrol</tt>)
+profiler, while newer processors/architectures may only be supported with <tt>operf</tt>.
 </p>
 
 <h3>Can OProfile collect call graphs like <tt>gprof</tt>?</h3>
 <p>
-Yes, starting with OProfile 0.8. You need to be on x86 or ARM, and run a recent 2.6
-kernel.  Call graph is also supported on PowerPC, beginning with the 2.6.17 kernel.
+Yes, starting with OProfile 0.8 and kernel version 2.6, callgraph support
+is available on many (but not all) architectures, such as x86, ARM, and ppc/ppc64.
 </p>
 
 <h3>What about the "security hole" <a
@@ -193,31 +210,31 @@
 
 <h3>Using the 2.4 kernel module, I get "Failed to open hash map device: Operation not permitted"?</h3>
 <p>
-This is an intermittent problem we have not yet tracked down. The device
+This is an intermittent problem that was never completely resolved. The device
 file <tt>/var/lib/oprofile/hashmapdev/</tt> is failing the <tt>capable(CAP_SYS_PTRACE)</tt>
 test. The simplest workaround is to remove <em>both</em> of these tests in the source
 (<tt>oprofile.c</tt>), recompile and reinstall OProfile, then run <tt>opcontrol --deinit</tt>
 and start again.
 </p>
 
-<h3>Suse kernel, I get: "May  8 11:05:14 mynode kernel: Unable to handle kernel paging request at virtual address ffffe030"</h3>
-<p>
-This occur with recent Suse UP kernel when you compile your
-kernel with CONFIG_X86_LOCAL_APIC. By default these kernel does
+<h3>SUSE kernel, I get: "May  8 11:05:14 mynode kernel: Unable to handle kernel paging request at virtual address ffffe030"</h3>
+<p>
+This occurs with older SUSE UP kernel when you compile your
+kernel with CONFIG_X86_LOCAL_APIC. By default, these kernels do
 not up the local apic. You must force local apic initialization
-by booting with the kernel command line parameter apic.
+by booting with the kernel command line parameter <tt>apic</tt>.
 </p>
 
 <h3>VMware</h3>
 <p>
 OProfile can't work with VMware when using performance counter interface.
-A workaround is to use RTC mode (2.4 kernel) or timer interrupt mode (2.6
+A workaround is to use RTC mode (2.4 kernel) or timer interrupt mode (2.6+
 kernel)
 </p>
 
 <h3>What is the meaning of "cpu_type 'unset' is not valid"</h3>
 <p>
-Generally this means your kernel supports your hardware, but user space tools are not up to date.  You should try to upgrade. You can check if your hardware is supported by looking at <tt>/dev/oprofile/cpu_type</tt>.
+This error can occur when using legacy <tt>opcontrol</tt> for profiling.  Generally this means your kernel supports your hardware, but user space tools are not up to date.  You should try to upgrade. You can check if your hardware is supported by looking at <tt>/dev/oprofile/cpu_type</tt>.
 </p>
 
 <h3>What are the [vdso] messages I sometimes see from opreport?</h3>