Page Contents:

• What software must already be installed?
• Installing a New Version Over an Already Installed Version
• General Installation Tips for Linux*

What software must already be installed?
Before installing Intel® Thread Checker onto Microsoft Windows*, you must have the VTune™ Performance Analyzer v7.2 already installed, as Intel® Thread Checker is a plug-in to the VTune™ environment. Visit the Intel® Threading Tools Web site to obtain VTune Performance Analyzer and/or Intel Thread Checker.

On Microsoft Windows systems, you must also have the following already installed:

• Microsoft Visual* C++ v6.0, or higher
• Intel® Compilers are required for source instrumentation or OpenMP* analysis.
• Microsoft* Internet Explorer v6.0, or higher
• Adobe* Reader*

To use the Linux* Remote Data Collector (Remote Agent), you must also install Intel Thread Checker on a Microsoft Windows system.

Installing a New Version Over an Already Installed Version
To install a new version of Intel Thread Checker, you must first uninstall the currently installed version.

Note: Before removing the current version from Windows, you might want to save your projects using File » Pack and Go menu in the VTune environment.

To remove the currently installed version from Windows*, go to Start » Control Panel » Add or Remove Programs » Intel® Thread Checker.

To remove the currently installed version from Linux, run uninstall32.sh or uninstall64.sh, which is typically found in the /opt/intel/itt directory.

General Installation Tips for Linux*

• To use the Linux Remote Data Collector (Remote Agent), you must also install Intel Thread Checker on a Microsoft Windows system.
• The Remote Data Collector (RDC) .tar file for Linux is included with the Windows* installation package.
• If you use ftp* to transfer the RDC .tar file to a Linux system, be sure to use a binary transfer.
• If you are also using the Intel Compilers on your Linux system, you should install Intel Compilers before installing Intel Thread Checker.
• If you update your Intel Compilers after installing Thread Checker, re-run the Thread Checker install script after updating the Intel Compilers.

• Installation includes a script tcvars.sh (and tcvars.csh), typically in the /opt/intel/itt/tcheck/bin/32 or /opt/intel/itt/tcheck/bin/64 directory. Use the source tcvars.sh command to setup the shell environment for source instrumentation with the Intel® Compiler.
• After installation, see the file tcheckFAQ.htm, typically found in the /opt/intel/itt directory, for important overview and usage information.

Page Contents:

• I don't have source code. Can I use Intel® Thread Checker?
• Collecting Thread Checker Diagnostics Outside of the VTune™ Environment
• Analyze Multiple Processes or Executables
• Tips for Analyzing Long Diagnostic Lists
• Catastrophic error: tcheck10.ini not found

1. Compile your software using an Intel® Compiler and the /Qtcheck (on Microsoft Windows*) or -tcheck (on Linux*) switch. This option enables source instrumentation.
   
   
2. Start your software as usual from the Windows*, DOS* or Linux* environment. For example, use Windows Explorer* to browse to your executable file and double-click on that file name.
   
   
3. Run your software until it terminates normally. Don't forget to reduce your workload. Also because your software is instrumented, expect that it will run slower than usual.
   
   
4. Exit (quit) your software, and a Thread Checker results ("*.thr") file is written to the working folder. If you are running on a Linux* system, transfer the .thr results file back to a Microsoft Windows* system (with Thread Checker installed) for viewing.
   
   
5. To view the results file with Windows* Explorer, simply double-click the file. Alternatively you can start the VTune environment and open it with the File » Open File ... (NOT Open Project...) dialog. Important: Don't forget to set the file type to *.thr when using this dialog.

Intel® Thread Checker is a tool that locates software threading bugs, such as data races, stalls, and deadlocks. Thread Checker monitors your software's execution to detect hard-to-find and impossible-to-find intermittent errors whether or not they actually occurred during execution.

Thread Checker uses instrumentation, which occurs automatically at run-time within the VTune environment or Microsoft .NET* Developer Environment, or can be performed beforehand with the Intel® C++ or Fortran Compilers.

When your software has finished executing, a diagnostic list of potential threading errors will be displayed. You can drill down to the line of source code where each diagnostics occurred, look at the call stack, and review variable definitions and context.

For more information on this product, including how to purchase or get a free evaluation copy, please visit the Intel® Threading Tools web site.

Page Contents:

• Tips on Preparing Microsoft Windows* Code
• Intel® Thread Checker Run-Time Warnings for Microsoft Windows* Applications
• I don't have source code. Can I use Intel® Thread Checker?

Tips on Preparing Microsoft Windows* Code for Intel® Thread Checker
The following are general tips for preparing Windows* source code for Intel® Thread Checker. Build (make) your source with the following switches:

• Be sure to build thread-safe by compiling with the /MD, /MDd, /MT or /MTd switch. This will use the thread-safe run-time libraries.
  
  Note: The default for Microsoft* and Intel® Compilers is the /ML or /MLd switch and this does not use thread-safe libraries.
  
  
• Generate symbols by compiling with the /Zi, /ZI or /Z7 switches and link with the /DEBUG switch. This will enable Thread Checker to specify source code information (file name and line number) with its diagnostics.
  
  
• Compile without optimization using the /Od switch. Just like when using a debugger, this will enable Thread Checker source code information (especially line numbers) to be accurate. Moreover, turning on compiler optimizations is usually not beneficial for code run under Intel Thread Checker.
  
  
• Executable software must be built so that it contains a relocation section that allows for relocation in memory. Relocation is required for instrumentation. Most dynamic-link library (.dll) files can be relocated by default; however by default, most executable (.exe) files cannot be relocated. So always link with the /FIXED:NO switch to allow for relocation.
  
  Tip: Instead of changing your project's settings, set the (system) environment variable LINK to the value /FIXED:NO and re-link your code to add a relocation section.
  
  
• To reduce executable (.dll or .exe) code size, link with the /INCREMENTAL:NO switch.

Intel® Thread Checker Run-Time Warnings for Microsoft Windows* Applications
If you get the warning "modules were created without base relocations" when you run Intel® Thread Checker activity in the VTune™ environment or Microsoft .NET* Development Environment, your code probably doesn't contain a relocation section. Link with the /FIXED:NO switch to add a relocation section.

I don't have source code. Can I use Intel® Thread Checker?
Yes -- But on Microsoft Windows*, do not expect to get any threading diagnostics for the application (.exe) file itself b ecause typically on Windows the executable does not have a relocation section.

An example of using Thread Checker without source code might be if you are using an application file from another vendor, so you don't have source code for the for the application. But you are interested in diagnostics about a dynamic or shared library file that is loaded by the vendor's .application. You may not even have source code for the library that gets loaded. You can still use Thread Checker to see if any threading diagnostics are detected. Of course, if you really want to correct threading issues, you'll need source code.

Page Contents:

• Why does my software run so slow and/or use so much memory when run with Intel® Thread Checker?
• About Workload Reduction: What does workload reduction mean?
• About Workload Reduction: What kind of workload reduction should I use?
• Reducing Memory Usage

Why does my software run so slow and/or use so much memory when run with Intel® Thread Checker?
Intel® Thread Checker uses dynamic analysis as your threading software executes. As your software runs, Thread Checker uses instrumentation to monitor each thread, including the threading APIs used and memory accesses. Therefore Thread Checker uses more memory due to the instrumentation and significantly slows down the execution of any software.

For this reason, it is critical to reduce the workload of your software before running it under Thread Checker. Reducing the workload may speed up analysis of the software and may reduce the memory used.

About Workload Reduction: What does workload reduction mean?
This is a reduction in the amount of work your program performs. It might include reducing the amount of data your program processes and/or reducing the amount of processing your program performs on each piece of data.

Some examples of work-load reduction include:

• Processing a 32x24 pixel image instead of a 1920x1440 pixel image. If there is a threading error within the loops that process the image, it does not provide you with any more information to find the same error thousands or millions of times. Finding a threading error a few (tens or hundreds) times is sufficient and makes you more productive.
  
  
• Minimize the number of times you process each piece of data by reducing the loop iterations. Your software does not need a lot of accuracy when run under Intel® Thread Checker. After all, the goal is to find threading errors and not to get accurate results.
  
  
• Minimize the update rates and/or length. Try using only one second of video, or reduce the update rate of the display to once per second instead of thirty or more updates a second.

About Workload Reduction: What kind of workload reduction should I use?
You should use as much workload reduction as possible while still being sure that you're executing the code that you want checked. Intel® Thread Checker uses dynamic analysis when executing your software. If section of your code is not executed, Thread Checker cannot give you diagnostics about the not-executed code. Where possible, you should try using multip le short runs over different code paths.

Reducing Memory Usage
Some general tips for reducing memory usage:

• Reduce the size of the data-set that your software reads or writes, so that Intel® Thread Checker doesn't need to track as many memory accesses.
  
  
• Disable Allocated memory guard padding by setting it to 0 (zero). In the VTune™ environment, this can be set via the Configure » Modify Intel® Thread Checker Collector menu item and the Analysis tab.
  
  
• Make sure you are using the instrumentation level of All Functions instead of Full Image. In the VTune environment, this can be set via the Configure » Modify Intel® Thread Checker Collector menu item and the Module Instrumentation tab.
  
  
• On Microsoft Windows*, link your software with the /INCREMENTAL:NO switch.

• Features
• Product Brief
• Compatibility

Features

• Detects hidden potential errors, mapping them to the source-code line, call stack, and memory reference
• Displays warnings for effective diagnosis, highlighting the most potentially severe errors
• Tracks the error down to the specific variable in your source code using source instrumentation
• Mitigates the risk of adding threads and enables hands-on learning about threading principles

Patented advanced error detection engine:

• Detects hidden potential errors, mapping them to the source-code line, call stack, and memory reference
• Displays warnings for effective diagnosis, highlighting the most potentially severe errors
• Tracks the error down to the specific variable in your source code using source instrumentation
• Mitigates the risk of adding threads and enables hands-on learning about threading principles

Works on standard debug builds:

• Does not require your application to be recompiled

Calibration run:

• Recommends which modules to instrument based on usage, decreasing instrumentation time

Patented OpenMP* analysis:

• Enables rapid prototyping by determining the impact that threading will have atspecific points in your application

Real-time verbose output and status query:

• Start viewing detailed diagnostic information as soon as a potential error is uncovered, while Intel® Thread Checker continues to check the rest of the application.

Improved existing features in the 3.1 release include the following:

• 32-bit and 64-bit support for Windows Vista*
• Support for Intel® VTune™ Performance Analyzer 9.0 for Windows*
• Support for the latest Intel® multi-core processors, including
• Intel® Core™ 2 Duo, and
• Intel® Core™ 2 Quad processors

• Performance optimizations by descriptor-based static binary instrumentation which, reduces the instrumented image size and decreases runtime overhead.

Product Brief

Intel® Thread Checker 3.1 for Windows* is instrumental at every phase of the application development cycle.

• In the design phase, it helps you decide where and how to add threading in your application.
• As you implement threading into your application, it can detect hard-to-find threading bugs like data races and deadlocks.
• You can also ensure code quality by integrating it into your automated Quality Assurance/ test process.

Compatibility

Intel Thread Checker 3.1 for Windows is compatible with today's in dustry-standard development tools:

• Microsoft Visual Studio* .NET
• Microsoft Visual C++* .NET development environment Compiler 2005, 2003, 2002 Editions or Visual C++ 6.0
• Intel® Fortran and C++ Compilers
• Windows threads and POSIX* threads
• Support for OpenMP*