Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Linux Tools Project/OProfile/User Guide"
(→Install Script Errors) |
|||
Line 186: | Line 186: | ||
=== Error: script must be run as the root user === | === Error: script must be run as the root user === | ||
You must be the root user to run the install script, since it requires touching files in root-owned directories. | You must be the root user to run the install script, since it requires touching files in root-owned directories. | ||
− | Solution:Run the command <code>su -</code> to become the root user, or run the script as the root user with <code>su -c './install.sh'</code>. | + | |
+ | Solution: Run the command <code>su -</code> to become the root user, or run the script as the root user with <code>su -c './install.sh'</code>. | ||
=== Error: script must be run with pwd in script dir === | === Error: script must be run with pwd in script dir === | ||
Your current working directory must be the <code>scripts</code> directory; running the script relative from another location will not work. | Your current working directory must be the <code>scripts</code> directory; running the script relative from another location will not work. | ||
+ | |||
Solution: Simply follow the steps of [[#Step 1 - Locate Plug-in Installation Directory]] to <code>cd</code> into the <code>scripts</code> dir. | Solution: Simply follow the steps of [[#Step 1 - Locate Plug-in Installation Directory]] to <code>cd</code> into the <code>scripts</code> dir. | ||
=== Error: required binaries do not exist, OProfile not installed? === | === Error: required binaries do not exist, OProfile not installed? === | ||
The <code>oprofiled</code> and <code>opcontrol</code> binaries are not in their usual directory (<code>/usr/bin</code>). Either they are in a non-standard directory or do not exist. | The <code>oprofiled</code> and <code>opcontrol</code> binaries are not in their usual directory (<code>/usr/bin</code>). Either they are in a non-standard directory or do not exist. | ||
+ | |||
Solution: If the binaries are on your system (and in your <code>PATH</code>) but not in those directories, you either remove these checks from the install script or create symlinks in the <code>/usr/bin</code> directory. Or if they are not on your system at all, install OProfile :) | Solution: If the binaries are on your system (and in your <code>PATH</code>) but not in those directories, you either remove these checks from the install script or create symlinks in the <code>/usr/bin</code> directory. Or if they are not on your system at all, install OProfile :) | ||
=== Error: /usr/bin/consolehelper does not exist, run install-noconsolehelper.sh instead === | === Error: /usr/bin/consolehelper does not exist, run install-noconsolehelper.sh instead === | ||
As described in [[#Step 2 - Choose Which Installation Script To Run]], if your system does not have the <code>consolehelper</code> program you must use the other mode of root authentication which makes use of the sudo mechanism. | As described in [[#Step 2 - Choose Which Installation Script To Run]], if your system does not have the <code>consolehelper</code> program you must use the other mode of root authentication which makes use of the sudo mechanism. | ||
+ | |||
Solution: Run the <code>install-noconsolehelper.sh</code> script instead. | Solution: Run the <code>install-noconsolehelper.sh</code> script instead. | ||
=== Error: cannot create opcontrol wrapper in <directory> === | === Error: cannot create opcontrol wrapper in <directory> === | ||
If the <code>ln</code> command returns that the symlink could not be created then this error will occur. This can occur if <code>scripts</code> is a sub-directory of an NFS mount -- the NFS server will not allow the local root user to create files in the directory. | If the <code>ln</code> command returns that the symlink could not be created then this error will occur. This can occur if <code>scripts</code> is a sub-directory of an NFS mount -- the NFS server will not allow the local root user to create files in the directory. | ||
+ | |||
Solution: Create the symlink yourself as a regular user by running <code>ln -s /usr/bin/consolehelper opcontrol</code> and edit the <code>install.sh</code> script to remove the section for the symlink (this is fixed in SVN, but not in the 0.2.0 release). | Solution: Create the symlink yourself as a regular user by running <code>ln -s /usr/bin/consolehelper opcontrol</code> and edit the <code>install.sh</code> script to remove the section for the symlink (this is fixed in SVN, but not in the 0.2.0 release). | ||
=== Error: cannot find opxml binary, required plugin missing === | === Error: cannot find opxml binary, required plugin missing === | ||
This can occur if the native binary <code>opxml</code> is not found. It is required for proper operation of the plug-in. | This can occur if the native binary <code>opxml</code> is not found. It is required for proper operation of the plug-in. | ||
+ | |||
Solution: If the <code>org.eclipse.linuxtools.oprofile.core.linux.{x86,x86_64,ppc}</code> directories exist then see the [[#Rebuilding opxml]] section to re-build the binary and put it in the proper directory. Otherwise, re-install the plug-in. | Solution: If the <code>org.eclipse.linuxtools.oprofile.core.linux.{x86,x86_64,ppc}</code> directories exist then see the [[#Rebuilding opxml]] section to re-build the binary and put it in the proper directory. Otherwise, re-install the plug-in. | ||
Revision as of 16:29, 27 April 2009
{{#eclipseproject:technology.linux-distros}}
Contents
- 1 Getting Started
- 2 Launching A Profile
- 3 OProfile View
- 4 Profiling Configuration
- 5 Example Project
- 6 Troubleshooting
- 6.1 Install Script Errors
- 6.1.1 Error: script must be run as the root user
- 6.1.2 Error: script must be run with pwd in script dir
- 6.1.3 Error: required binaries do not exist, OProfile not installed?
- 6.1.4 Error: /usr/bin/consolehelper does not exist, run install-noconsolehelper.sh instead
- 6.1.5 Error: cannot create opcontrol wrapper in <directory>
- 6.1.6 Error: cannot find opxml binary, required plugin missing
- 6.2 No Samples From A Profile
- 6.3 Log Reader Hangs
- 6.4 Other Errors
- 6.5 Rebuilding opxml
- 6.1 Install Script Errors
Getting Started
The OProfile plug-in requires a little extra set up compared to other Eclipse plug-ins. However, it only takes a few simple steps and only needs to be done once. After the plug-in is first installed, running most profile-related commands will bring up a dialog similar to the following:
As the dialog suggests, you must run the supplied install script to allow the plug-in to perform OProfile tasks as root (since OProfile can not be run as an unprivileged user). The steps below are the same as the dialog but described in more detail.
Step 1 - Locate Plug-in Installation Directory
Open up a terminal and locate the scripts
directory. The install script is located in the org.eclipse.linuxtools.oprofile.core
plug-in directory, but this directory can be in a few places:
- If you are using a distro-supplied version of Eclipse and installed the plug-in via the update site, it will most likely be under the
~/.eclipse
directory, hence use the command:
find ~/.eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'
- Alternatively, if you are using an extracted tarball of Eclipse (ie: you downloaded a .tar.gz from here) then the plug-in will most likely be in the plugins sub-directory of where you extracted it. Let's say you extracted the tarball to
/home/ksebasti
, so your Eclipse installation would be in/home/ksebasti/eclipse
, then use the command:
find /home/ksebasti/eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'
Note that the quotes (') and asterisk (*) are necessary. Example output will look something like this:
$ find /home/ksebasti/eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'
/home/ksebasti/eclipse/plugins/org.eclipse.linuxtools.oprofile.core_0.2.0.200904131051
Then, change the sub-directory natives/linux/scripts
of this plug-in directory:
cd /home/ksebasti/eclipse/plugins/org.eclipse.linuxtools.oprofile.core_0.2.0.200904131051/natives/linux/scripts
Note that if you are not the root user while performing these commands, you may have to become the root user and re-execute them in Step 3.
Step 2 - Choose Which Installation Script To Run
In the scripts
directory there are two scripts, install.sh
and install-noconsolehelper.sh
. Both scripts will do some sanity checks to ensure OProfile is installed and that opxml, a C++ program required to interface with OProfile, exists and can be run. The difference is in how root authentication with the plug-in is set up.
-
install.sh
uses the pluggable authentication modules (PAM) mechanism. This is the default and recommended method for root authentication. When an OProfile task is required, you will be presented with this dialog to enter the root password:
-
install-noconsolehelper.sh
can be used when consolehelper is not present on the system, or if required PAM modules are not on the system. It uses the sudo mechanism and a small wrapper script. The install script will describe the text which should be written in thesudoers
file, then run the commandvisudo
to edit it. Note that thesudoers
file is a sensitive system file and altering it in other ways may lead to system instability. Only users with enough knowledge of running a Linux system should use this method. For these reasons, this method of root authentication is discouraged. However, it may be the only option available to some users and it has been tested to work by developers and users of the plug-in.
Step 3 - Running The Install Script
Now simply run the install script (assuming you are in the scripts
directory as in #Step 1 - Locate Plug-in Installation Directory):
./install.sh
Successful output will look like this:
# ./install.sh
Eclipse-OProfile plugin install successful.
Note that the install script must be run as the root user, since both install scripts have some actions which require root -- install.sh
places files in /etc
sub-directories and install-noconsolehelper.sh
runs the command visudo
. If you are not already the root user, this command will run only the install script as the root user, then return control to the regular user:
su -c './install.sh'
Successful output will be the same as above. If instead you receive error messages, refer to the Troubleshooting section at the bottom of this page.
Step 4 - Restart Eclipse
That's it! Simply restart Eclipse by clicking File -> Restart and you should be good to go.
Note that if you need to uninstall the plug-in, run the uninstall.sh
or uninstall-noconsolehelper.sh
script in the scripts
directory before uninstalling it from within Eclipse.
Launching A Profile
The purpose of the OProfile plug-in is to provide useful profile information in a user-friendly manner. The first step is to gather this information. The plug-in hooks into the Eclipse and the CDT's launching facilities, hence profiling is no harder than a normal run of your program. The plug-in will start, stop and perform other OProfile tasks in the background as needed, while the binary itself runs as normal. Currently, it is only possible to start profiling when a user binary is run, and stop profiling after the binary has returned. However, there are plans to include a feature to start/stop profiling at arbitrary times in the near future.
One-Click Launch
For the majority of users, the most interesting profile is to see where time is spent during execution of the program. A one-click launch feature exists in the plug-in, which will set appropriate defaults for a profile configuration and launch it with no extra user intervention required. Simply right-click on the project, the binary or in an open editor for a source file belonging to that project, navigate to Profile As and click Profile With OProfile to start the launch.
Configurable Profile
OProfile has many options to configure its operation; many of these are exposed via the launch configuration in a user-friendly manner and allows for a more complex profile of your binary. See #Profiling Configuration for details. After configuring these details, simply click the Profile button to launch the profile.
OProfile View
The OProfile view is the central point of interaction of the plug-in with the results of profiling.
Tree Structure
The tree structure shown above describes one or more profiles of one or more events in the following manner:
- Events -- the name of the profiling event used by OProfile
Note that if source code is not available, then there may be symbols shown (including source file name) but no samples. This is usually the case with shared libraries. As well, depending on the #Global Settings, there may be no dependent images shown.
Features
This section describes the features of the plug-in exposed through the view.
View Tree
- Double-clicking on a sample will open the source file in an editor and place the cursor at that line.
- Note this requires that the source code is available and is in the correct directory (as described in the binary's debug info).
View Menu
- Open OProfile Daemon Log
- This will launch a dialog showing the contents of the oprofile daemon log (by default in /var/lib/oprofile/samples/oprofiled.log):
- Refresh View
- This will re-read the OProfile data on the system, re-create the internal data model and re-display the profile tree. Also useful to display data already on the system without launching a profile.
- Save Default Session
- The default session, named
current
, is overwritten on each launch of a profile if it is not saved. If you wish to keep the profile for later viewing, this menu action will allow you to save the session to a different name. Note that since the samples are in a system directory, this operation requires the use of OProfile and hence you will be prompted for the root password. The save session dialog is shown below:
- The default session, named
Profiling Configuration
OProfile has many configuration options, which can easily be overwhelming. The profile configuration aims to make the relevant OProfile configuration options easily accessible for all users of the plug-in, experienced with OProfile or not. Currently, there are two configuration tabs added to the standard CDT launch configuration tabs: #Global Settings and #Event Configuration.
Global Settings
The settings exposed in this tab affect the way the OProfile daemon gathers the profiling information. Each option is described below.
- Kernel Image File
- If you wish to get more detailed information about the operation of your program in the Linux kernel, then point this location to the location of your currently running kernel's
vmlinux
file. This file contains debugging information required by OProfile. Note that the compressed vmlinux file, often namedvmlinuz
, can not be used for this purpose. Note that if Include dependent kernel modules is not checked then this field will have no effect.
- If you wish to get more detailed information about the operation of your program in the Linux kernel, then point this location to the location of your currently running kernel's
- Include dependent shared libraries
- This option will make OProfile keep samples from shared libraries that are used by the binary being profiled and aggregate them in the profile results.
- Include dependent kernel modules
- This option will make OProfile keep samples related to running in the kernel. If the
vmlinux
file is specified, the profile will include details of the specific kernel modules in use. Otherwise, kernel samples are grouped under the nameno-vmlinux
.
- This option will make OProfile keep samples related to running in the kernel. If the
The differences between options is highlighted in the screenshot of multiple sessions below:
-
incl_library
was run with only the Include dependent shared libraries checked -
incl_vmlinux
was run with the vmlinux image specified and both Include dependent shared libraries and Include dependent kernel modules checked -
no_vmlinux
was run with the vmlinux image left empty and both Include dependent shared libraries and Include dependent kernel modules checked -
novmlinux_noseparate
was run with none of the options checked
Event Configuration
The event configuration tab condenses the (often) large number of options available for configuring the hardware profiling registers of your system's processor.
- Use default event
- The first option use default event is enabled by default when creating a new profile configuration or when a profile configuration is created from a #One-Click Launch. This is a shortcut to use an event based on processor execution time with a reasonable value for Count. Default events are listed for various processors here, at the end of the page. Note that using this option does not allow you to configure the counters further.
- Counter Tabs
- A processor may have 1 to 8 hardware profiling registers (also called counters). Each one may be programmed separately to profile many events simultaneously. The tabs labelled Ctr each represent one counter and expose the same options.
- Enabled
- Enable or disable the counter.
- Event Description
- A short description of the function of the selected profiling event; the text is given by OProfile.
- Event List
- A list of the events available for profiling on a given counter.
- Profile Kernel / Profile user binaries
- Instructs OProfile to profile binaries in the selected spaces. Keeping both checked is recommended (even if other #Global Settings are not specified).
- Count
- Specifies a reset count for the hardware counter. In the majority of cases, the default value (based on the CPU's clock frequency) is sufficient. Each event has a minimum value, but it is recommended to use a value many orders of magnitude larger. WARNING: if you specify too low of a value, your program may take much longer to return or your system may hang.
- Unit Mask
- Many events have a unit mask which allows further narrowing of the scope of the event. If in doubt, use the default value (which is provided by OProfile). There are three types of unit masks:
- Mandatory -- no selection necessary; a single required value
- Exclusive -- several possible values; a single required value
- Bitmask -- several possible values; a combination of several values
- Many events have a unit mask which allows further narrowing of the scope of the event. If in doubt, use the default value (which is provided by OProfile). There are three types of unit masks:
Timer Interrupt Mode
If your processor (or kernel) does not support the hardware profiling registers OProfile uses, OProfile will run in timer-interrupt mode. No extra configuration of events is possible. The event configuration tab will then look like the screenshot below:
Example Project
If you wish to try out any of the above steps with a test project, download the example project used to create the screenshots here.
Troubleshooting
Various problems and their solutions are described here. If you encounter a problem not described here, please file a bug.
Install Script Errors
Each of the errors that could occur from the install scripts (install.sh
or install-noconsolehelper.sh
) are described below and the solutions to fix them.
Error: script must be run as the root user
You must be the root user to run the install script, since it requires touching files in root-owned directories.
Solution: Run the command su -
to become the root user, or run the script as the root user with su -c './install.sh'
.
Error: script must be run with pwd in script dir
Your current working directory must be the scripts
directory; running the script relative from another location will not work.
Solution: Simply follow the steps of #Step 1 - Locate Plug-in Installation Directory to cd
into the scripts
dir.
Error: required binaries do not exist, OProfile not installed?
The oprofiled
and opcontrol
binaries are not in their usual directory (/usr/bin
). Either they are in a non-standard directory or do not exist.
Solution: If the binaries are on your system (and in your PATH
) but not in those directories, you either remove these checks from the install script or create symlinks in the /usr/bin
directory. Or if they are not on your system at all, install OProfile :)
Error: /usr/bin/consolehelper does not exist, run install-noconsolehelper.sh instead
As described in #Step 2 - Choose Which Installation Script To Run, if your system does not have the consolehelper
program you must use the other mode of root authentication which makes use of the sudo mechanism.
Solution: Run the install-noconsolehelper.sh
script instead.
Error: cannot create opcontrol wrapper in <directory>
If the ln
command returns that the symlink could not be created then this error will occur. This can occur if scripts
is a sub-directory of an NFS mount -- the NFS server will not allow the local root user to create files in the directory.
Solution: Create the symlink yourself as a regular user by running ln -s /usr/bin/consolehelper opcontrol
and edit the install.sh
script to remove the section for the symlink (this is fixed in SVN, but not in the 0.2.0 release).
Error: cannot find opxml binary, required plugin missing
This can occur if the native binary opxml
is not found. It is required for proper operation of the plug-in.
Solution: If the org.eclipse.linuxtools.oprofile.core.linux.{x86,x86_64,ppc}
directories exist then see the #Rebuilding opxml section to re-build the binary and put it in the proper directory. Otherwise, re-install the plug-in.
No Samples From A Profile
- no samples
Log Reader Hangs
- log reader hanging
Other Errors
Errors may be caused by problems with the native program that bridges OProfile and the plugin, opxml
. Running this program manually may reveal the issue. It is in the plugins
directory similar to #Step 1 - Locate Plug-in Installation Directory. However, depending on your platform, the location of opxml
will be different. Open a terminal and run the command:
uname -m
Depending on the output, locate the following directory in the same manner as #Step 1 - Locate Plug-in Installation Directory, and change into that directory:
Output from uname -m
|
Directory to use in find command
|
Sub-directory to change to |
---|---|---|
i386, i468, i568, i686, x86 | org.eclipse.linuxtools.oprofile.core.linux.x86 | os/linux/x86 |
x86_64 | org.eclipse.linuxtools.oprofile.core.linux.x86_64 | os/linux/x86_64 |
ppc, ppc64 | org.eclipse.linuxtools.oprofile.core.linux.ppc | os/linux/ppc |
For example, if you were on a 64bit machine, the process would be similar to:
$ find /home/ksebasti/eclipse -name 'org.eclipse.linuxtools.oprofile.core.linux.x86_64_*'
/home/ksebasti/eclipse/plugins/org.eclipse.linuxtools.oprofile.core.linux.x86_64_0.2.0.200904201514
$ cd /home/ksebasti/eclipse/plugins/org.eclipse.linuxtools.oprofile.core.linux.x86_64_0.2.0.200904201514/os/linux/x86_64
Then run the command:
./opxml info
Check that the paths in the defaults
section are correct. If the output is similar the output of the command ophelp
, but formatted as XML, then this might not be the problem. However, if running opxml produces an error, it may be the root cause. A common error on some systems is an older version of the C runtime libraries, glibc. See #Rebuilding opxml for a solution to this error.
In any case, if there is an error please look for an existing bug or if one does not exist, file a new bug.
Rebuilding opxml
If the need arises to rebuild the opxml
binary follow the steps below. Note: this is rarely necessary and may break an otherwise working installation. Only rebuild opxml
if explicitly recommended.
- Follow the exact same steps as #Step 1 - Locate Plug-in Installation Directory, except instead of changing to the
natives/linux/scripts
sub-directory, change to thenatives/linux/opxml
sub-directory of the core plugin. In here will be the source files for theopxml
binary. -
opxml
requiresmake
,g++
, the OProfile development libraries and thelibbfd
libraries to build; ensure that these are on your system. For Fedora systems these are themake
,gcc-c++
,oprofile-devel
andbinutils-devel
packages. - run the command
make
to build the binary - run the command
make install
to install the binary into the correct plug-in directory - run the command
make clean
to remove the extra files created during the build process