*************************************************
*   C o d e A n a l y s t  2.8 U1  R E A D M E  *
*************************************************
Revision	: 2.8 U1 
Last Update	: 6/3/2009


*********************
* Table Of Contents *
*********************

  * Introduction

  * Supported Platforms
  
  * Installation

  * Trouble Shooting

  * FAQ (Frequently Asked Questions)

  * Support and Bug Report


-----------------------------------------------------------------------------------------

****************
* Introduction *
****************

CodeAnalyst is a program used to help developers optimize program execution on 
AMD platforms. It uses information generated by the AMD CPU hardware.

This README addresses mostly install issues. For full documentation on using the 
the CodeAnalyst program see the extensive HTML documentation either on the AMD 
website or in the help directory usually in "/opt/CodeAnalyst/share/codeanalyst/doc/".

The man pages for commandline options are in "/opt/CodeAnalyst/man" or 
"/opt/CodeAnalyst/share/man" directory.  Please include this path in the "MANPATH" 
environment variable.


-----------------------------------------------------------------------------------------

***********************
* Supported Platforms *
***********************

CodeAnalyst(CA) is supported on the following Linux distributions on both x86 and 
AMD64 architectures.  

	----------------------------------------------------------------------------------------
	|           LINUX Distributions         | Source  | RPMS  |            Supported       |
	|                                       | Install |       |            Platforms       |
	----------------------------------------------------------------------------------------
	| - SUSE Linux Enterprise Server 11     |   Yes   |  Yes  | K8 / family10h / family11h |
	| - SUSE Linux Enterprise Server 10     |   Yes   |  Yes  | K8 / family10h / family11h |
	| - SUSE Linux Enterprise Server 9      |   Yes   |  Yes  | K8                         |
	| - OpenSUSE 11, 11.1                   |   Yes   |  No   | K8 / family10h / family11h |
	| - SuSE Linux 10.1                     |   Yes   |  No   | K8 / family10h / family11h |
        |                                       |         |       |                            |	
	| - Red Hat Enterprise Linux 5          |   Yes   |  Yes  | K8 / family10h / family11h |
	| - Red Hat Enterprise Linux 4 *        |   Yes   |  Yes  | K8 / family10h / family11h |
	| - Fedora Core 8, 9, 10, 11            |   Yes   |  No   | K8 / family10h / family11h |
        |                                       |         |       |                            |	
	| - Ubuntu-8.10, 9.04                   |   Yes   |  No   | K8 / family10h / family11h |
	----------------------------------------------------------------------------------------

	*    Red Hat Enterprise Linux 4 requires CodeAnalyst Kernel Module to be installed
	     to run java profiling.

	***  CodeAnalyst Kernel Module is required to run on family 0x10 or 0x11  platform.

	**** Event-multiplexing feature required CodeAnalyst Kernel Module to be installed.

CA may work on other revisions and platforms if the proper required packages are 
available and installed. However it will require rebuilding from sources. Other 
platforms are not officially supported but we will make notes in the troubleshooting 
section of this README as available.


-----------------------------------------------------------------------------------------

****************
* Installation *
****************

Please see the INSTALLATION file for installation related information.


-----------------------------------------------------------------------------------------

********************
* Trouble Shooting *
********************

1. If you get a runtime error that names 
	- libCA.so 
	- libopdata072.so
	- libopdata091.so 
   	- lib_flat_output.so, 
	- libopdata081.so, or 
	- lib_tbp_output.so 

   This is caused by the CA libraries not being part of the path for 
   ld searches for dynamically loading shared objects.   
   Please add the installed CA lib directory, by default
   
	/opt/CodeAnalyst/lib/ 
   or 
	/opt/CodeAnalyst/lib64, 

   to ld.so.conf or LD_LIBRARY_PATH.  This may require running 
   ldconf after updating the path.


2. If you have installed CodeAnalyst to a different directory, 
   the environment variable : 

	OPROFILE_EVENTS_DIR 

   needs to be set to <prefix path>/share/oprofile/.


3. It is possible for the daemon to generate malformed sample file during 
   profiling. If CodeAnalyst reports "Oprofile collects no samples" and the
   dialog contains "input/output error", The work around is to delete the
   malformed file and import the profiling result into CodeAnalyst. 


4. If non-root user cannot run CodeAnalyst, please see section 
   "Adding Non-root Users" in the INSTALLATION file.


5. In case Java application do not run when start profile, please make sure
   that "libCAJVMTIA.so" or "libCAJVMPIA.so" exist in the "/usr/local/bin" and
   "/usr/local/lib" directory. Otherwise, please see section "For Java Profiling"
   in INSTALLATION document.  For more information, please see the "Help" 
   document in CodeAnalyst GUI for how to set-up Java profiling.


6. If opcontrol utility gives the following error message when running on 
   Barcelona system:

	cpu_type 'unset' is not valid
	you should upgrade oprofile or force the use of timer mode

   It ususally means the current Oprofile driver does not support
   the processor. In this case, please install the stand-alone kernel driver.
   Please see INSTALLATION instruction for more information.

7. CodeAnalyst Linux requires an APIC-enabled system.
	
8. Some newer Linux distributions come with QT4 as default QT package which
   is not compatible with CodeAnalyst.  Please install QT3 package instead.


-----------------------------------------------------------------------------------------

************************************
* FAQ (frequently asked questions) *
************************************

 Q: How do I start CodeAnalyst?
 A: Code Analyst is installed in /opt/CodeAnalyst/bin/CodeAnalyst by default. It may also 
    be installed to a different directory if built with the --prefix option.
    To start CodeAnalyst be sure you have root privilege unless you have setup 
    non-root users to access the daemon (see next question).

 Q: How can I setup CA so I don't have to be root to use the tool?
 A: Please see topic 4 of section "Trouble Shooting". However, the non-root users
    cannot run the opcontrol.

 Q: How do I use the command-line version of CodeAnalyst?
 A: Please see "Help" document in CodeAnalyst for how to use command-line utility
    (opcontrol).
 
 Q: When I try to run CA, I get "XXX.so" not found error messages, what is wrong?
 A: Please see topic 1 of section "Trouble Shooting" 


-----------------------------------------------------------------------------------------

****************************
* Support and Bugs Reports *
****************************

- Please send feedback and questions to codeanalyst.support@amd.com.

- Upon sending email, please run "careport.sh" script found in the CodeAnalyst 
source directory or installation directory (/usr/local/bin), and attach the 
output file "careport.txt".
