Update readme and build files. Also add a readme to Common dir that describes what to do if the Common dir is missing dependencies

chesik-amd · chesik-amd · commit b35dd8c8b549 · 2016-12-19T12:31:26.000-05:00
Change-Id: Ie523179c14cdd6ce345d9666fa2e37602a9d9bc3
diff --git a/BUILD.md b/BUILD.md
@@ -1,10 +1,24 @@
 # GPUPerfAPI Build Instructions
 ---
 ## Table of Contents
+* [Cloning/Updating Dependent Repositories](#DependentRepos)
 * [Windows Build Information](#Windows)
 * [Linux Build Information](#Linux)
 * [PublicCounterCompiler Tool](#PublicCounterCompiler)
 
+<A Name="DependentRepos">
+## Cloning/Updating Dependent Repositories
+GPUPerfAPI no longer uses git submodules to reference dependent repositories. Instead, you need to follow these instructions in
+order to clone/update any dependent repositories.
+#### Prerequisites
+  * This step requires that python be installed on the system. Python can be installed from https://www.python.org/
+#### Instructions
+ * Simply execute the [UpdateCommon.py](Utils/UpdateCommon.py) python script located in the [Utils](Utils) directory:
+   * __python Utils/UpdateCommon.py__
+This script will clone any dependent repositories that are not present on the system. If any of the dependent repositories are already
+present on the system, this script will instead do a "git pull" on those repositories to ensure that they are up to date. Please re-run
+this script everytime you pull new changes from GPA repository.
+
 <A Name="Windows">
 ## Windows Build Information
 
@@ -16,19 +30,18 @@
 ##### Build Instructions
  * Load Build\VS2015\GPUPerfAPI.sln into Visual Studio
  * Build the 64-bit and/or 32-bit configuration
- * After a successful build, the GPUPerfAPI binaries can be found in __Build\VS2015\\$(Configuration)-$(Platform)__ (for example Build\VS2015\Release-x64)
+ * After a successful build, the GPUPerfAPI binaries can be found in __GPA\Output\\$(Configuration)\bin__ (for example GPA\Output\Release\bin)
 
 #### Additional Information
  * The Visual Studio solution includes a Documentation project that allows you to generate the HTML-based source code documentation using Doxygen. In order
-   to build that project, you'll need to modify [Documentation.vcxproj](GPUPerfAPI/Build/VS2015/Documentation.vcxproj) and modify the paths to the doxygen executable.
+   to build that project, you'll need to modify [Documentation.vcxproj](Build/VS2015/Documentation.vcxproj) and modify the paths to the doxygen executable.
  * The Windows projects each include a .rc file that embeds the VERSIONINFO resource into the final binary. Internally within AMD, a Jenkins build system will dynamically update
-   the build number. The version and build numbers can be manually updated by modifying the [GPAVersion.h](GPUPerfAPI/GPUPerfAPI-Common/GPAVersion.h) file.
+   the build number. The version and build numbers can be manually updated by modifying the [GPAVersion.h](Src/GPUPerfAPI-Common/GPAVersion.h) file.
  * Information on building the Internal version:
     * To generate the internal version, two environment variables are required to be set prior to building in Visual Studio:
-      * GDT_BUILD=GDT_INTERNAL
-	  * GDT_BUILD_SUFFIX=-Internal
-    * The output location of the binaries will be __Build\VS2015\\$(Configuration)-$(Platform)-Internal__ (for example Build\VS2015\Release-x64-Internal)
-	* Each binary filename will also have a "-Internal" suffix (for example GPUPerfAPIDX11-x64-Internal.dll)
+      * AMDT_BUILD=AMDT_INTERNAL
+      * AMDT_BUILD_SUFFIX=-Internal
+    * Each binary filename will have a "-Internal" suffix (for example GPUPerfAPIDX11-x64-Internal.dll)
 
 <A Name="Linux">
 ## Linux Build Information
@@ -47,7 +60,7 @@
    * __quick__ or __incremental__: performs an incremental build (as opposed to a from-scratch build)
    * __buildinternal__: builds the internal versions of GPUPerfAPI
    * __hsadir__: overrides the location of the ROCm/HSA header files (by default they are expected to be in /opt/rocm/hsa)
- * After a successful build, the GPUPerfAPI binaries can be found in their respective source file directories. For instance, the binaries for the OpenGL version of GPUPerfAPI (libGPUPerfAPIGL.so) can be found in the GPUPerfAPIGL subdirectory.
+ * After a successful build, the GPUPerfAPI binaries can be found in their respective source file directories. For instance, the binaries for the OpenGL version of GPUPerfAPI (libGPUPerfAPIGL.so) can be found in the Src/GPUPerfAPIGL subdirectory.
  * Example build command line (builds the debug versions of the binaries, skipping the HSA library):
    * ./build.sh debug skiphsa
  * In addition to using the build.sh build script to build all of GPUPerfAPI, you can also build a single API library by executing __make__ in that library's directory. This is useful when making localized changes in a single version of GPUPerfAPI. When using __make__, the following default targets are supported:
@@ -76,8 +89,8 @@
 ## PublicCounterCompiler Tool
 
 The PublicCounterCompiler Tool is a utility, written in C#, that will generate C++ code to define the public (or derived) counters.
-It takes as input text files contained in the [PublicCounterCompilerInputFiles](GPUPerfAPI/PublicCounterCompilerInputFiles) directory and
-outputs files in the [GPUPerfAPICounterGenerator](GPUPerfAPI/GPUPerfAPICounterGenerator) and [GPUPerfAPIUnitTests](GPUPerfAPI/GPUPerfAPIUnitTests) directories.
+It takes as input text files contained in the [PublicCounterCompilerInputFiles](Src/PublicCounterCompilerInputFiles) directory and
+outputs files in the [GPUPerfAPICounterGenerator](Src/GPUPerfAPICounterGenerator) and [GPUPerfAPIUnitTests](Src/GPUPerfAPIUnitTests) directories.
 
 There are three ways to execute the tool:
 * With no parameters - it opens the user interface with no fields prepopulated
@@ -91,7 +104,7 @@ There are three ways to execute the tool:
   * Param 4: Test output Dir - the directory to generate the test output in (Ex: the path to the GPUPerfAPIUnitTests/counters directory)
   * Param 5: Active section label - the label to take the counter names from (ex: dx11gfx6)
 
-See the various PublicCounterDefinitions\*.txt files in the [PublicCounterCompilerInputFiles](GPUPerfAPI/PublicCounterCompilerInputFiles) directory. These contain all the counter definitions.
+See the various PublicCounterDefinitions\*.txt files in the [PublicCounterCompilerInputFiles](Src/PublicCounterCompilerInputFiles) directory. These contain all the counter definitions.
 Each counter is given a name, a description, a type, an optional usage type, a list of hardware counters required and a formula applied to the values of the hardware counters to calculate the value of the counter.
 
 Counter formulas are expressed in a Reverse Polish Notation and are made up the following elements:
@@ -101,5 +114,5 @@ Counter formulas are expressed in a Reverse Polish Notation and are made up the
 * functions: The supported functions are: min, max, sum, and ifnotzero. "max and "sum" have variants that work on multiple items at once (i.e. sum16, sum63, etc.)
 * hardware params: The supported hardware params are "num_shader_engines". "num_simds", "su_clock_prim", "num_prim_pipes", and "TS_FREQ"
 
-For more details, see the "EvaluateExpression" function in the [GPAPublicCounters.cpp](GPUPerfAPI/GPUPerfAPICounterGenerator/GPAPublicCounters.cpp) file.
+For more details, see the "EvaluateExpression" function in the [GPAPublicCounters.cpp](Src/GPUPerfAPICounterGenerator/GPAPublicCounters.cpp) file.
 
diff --git a/Common/README.md b/Common/README.md
@@ -0,0 +1,3 @@
+If the only subdirectory in this Common directory is Common/Lib/AMD/GPUPerfAPI, then you have probably forgotten to execute the
+[UpdateCommon.py](../Utils/UpdateCommon.py) script in the [Utils](../Utils) directory.
+Please see the instructions in [BUILD.md](../BUILD.md#DependentRepos) 
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ is used by both CodeXL and GPU PerfStudio.
 * [Source Code Directory Layout](#Source)
 * ["Public" vs "Internal" Versions](#PublicInternal)
 * [Building the Source Code](BUILD.md)
-* [GPUPerfAPI User Guide](GPUPerfAPI/doc/GPUPerfAPI-UserGuide.pdf)
+* [GPUPerfAPI User Guide](Doc/GPUPerfAPI-UserGuide.pdf)
 * [License](LICENSE)
 * [Historical Release Notes](#HistoricalNotes)
 
@@ -30,50 +30,47 @@ is used by both CodeXL and GPU PerfStudio.
 
 <A NAME="WhatsNew">
 ## What's New
-* Version 2.20 (5/12/16)
+* Version 2.21 (12/21/16)
   * Add support for additional GPUs and APUs.
-  * Initial Public release of ROCm/HSA support
-  * Alpha/Prototype for DirectX12 (no hardware-based performance counter support)
-  * Removed support for pre-GCN-based devices
-  * Improve accuracy of the various *VALUBusy and *SALUBusy counters (all APIs)
-  * OpenGL: Fixed possibly wrong GPUTime values for some applications
-  * OpenGL: Add support for open source OpenGL driver
-  * OpenGL: Fix value of TexUnitBusy counter for 3rd generation GCN hardware
-  * DirectX 11: Fix incorrect type returned for D3DGPUTime counter
-  * DirectX 11: Fix PSVALUBusy counter on 2nd and 3rd generation GCN hardware
-  * DirectX 11: A separate DLL (GPUPerfAPIDXGetAMDDeviceInfo\*.dll) is required in order to support certain multi-GPU configurations. This DLL will need to be deployed alongside GPUPerfAPIDX11\*.dll on multi-GPU systems. See the [User Guide](GPUPerfAPI/doc/GPUPerfAPI-UserGuide.pdf) for more information.
+  * ROCm/HSA: Support for ROCm 1.3 and ROCm 1.4
+  * OpenGL: Fixed an issue with GPU/APU detection with newer Radeon Crimson drivers
 
 <A NAME="System">
 ## System Requirements
 * An AMD Radeon GCN-based GPU or APU
-* Radeon Software Crimson Edition 16.2.1 or later (Driver Packaging Version 16.15 or later).
+* Radeon Software Crimson Edition 16.2.1 or later (Driver Packaging Version 16.40 or later).
 * Pre-GCN-based GPUs or APUs are no longer supported by GPUPerfAPI. Please use an older version ([2.17](http://developer.amd.com/tools-and-sdks/graphics-development/gpuperfapi/)) with older hardware.
 * Windows 7, 8.1, and 10
 * Ubuntu (14.04 and later) and RHEL (7 and later) distributions
 
 <A NAME="Cloning">
 ## Cloning the Repository
 To clone the GPA repository, execute the following git commands
- * git clone --recursive https://github.com/GPUOpen-Tools/GPA.git
+ * git clone https://github.com/GPUOpen-Tools/GPA.git
+After cloning the repository, please run the following python script to retrieve the required dependencies (see [BUILD.md](BUILD.md) for more information):
+ * python Utils/UpdateCommon.py
+UpdateCommon has replaced the use of git submodules in the GPA repository
  
 <A NAME="Source">
 ## Source Code Directory Layout
-* [Build](GPUPerfAPI/Build) -- contains both Linux and Windows build-related files
-* [DeviceInfo](GPUPerfAPI/DeviceInfo) -- builds a lib containing the Common/Src/DeviceInfo code (Linux only)
-* [doc](GPUPerfAPI/doc) -- contains User Guide and Doxygen configuration files
-* [GPUPerfAPICL](GPUPerfAPI/GPUPerfAPICL) - contains the source for the OpenCL™ version of GPUPerfAPI
-* [GPUPerfAPI-Common](GPUPerfAPI/GPUPerfAPI-Common) -- contains source code for a Common library shared by all versions of GPUPerfAPI
-* [GPUPerfAPICounterGenerator](GPUPerfAPI/GPUPerfAPICounterGenerator) - contains the source code for a Common library providing all counter data
-* [GPUPerfAPICounters](GPUPerfAPI/GPUPerfAPICounters) - contains the source code for a library that can be used to query counters without an active GPUPerfAPI context
-* [GPUPerfAPIDX](GPUPerfAPI/GPUPerfAPIDX) - contains source code shared by the DirectX versions of GPUPerfAPI
-* [GPUPerfAPIDX11](GPUPerfAPI/GPUPerfAPIDX11) - contains the source for the DirectX11 version of GPUPerfAPI
-* [GPUPerfAPIDX12](GPUPerfAPI/GPUPerfAPIDX12) - contains the source for the DirectX12 version of GPUPerfAPI (prototype/alpha)
-* [GPUPerfAPIGL](GPUPerfAPI/GPUPerfAPIGL) - contains the source for the OpenGL version of GPUPerfAPI
-* [GPUPerfAPIGLES](GPUPerfAPI/GPUPerfAPIGLES) - contains the source for the OpenGLES version of GPUPerfAPI
-* [GPUPerfAPIHSA](GPUPerfAPI/GPUPerfAPIHSA) - contains the source for the ROCm/HSA version of GPUPerfAPI
-* [GPUPerfAPIUnitTests](GPUPerfAPI/GPUPerfAPIUnitTests) - contains a small set of unit tests for GPUPerfAPI
-* [PublicCounterCompiler](GPUPerfAPI/PublicCounterCompiler) - source code for a tool to generate C++ code for public counters from text files defining the counters.
-* [PublicCounterCompilerInputFiles](GPUPerfAPI/PublicCounterCompilerInputFiles) - input files that can be fed as input to the PublicCounterCompiler tool
+* [Build]Build) -- contains both Linux and Windows build-related files
+* [Common](Common) -- Common libs, header and source code not found in other repositories
+* [Doc](Doc) -- contains User Guide and Doxygen configuration files
+* [DeviceInfo](Src/DeviceInfo) -- builds a lib containing the Common/Src/DeviceInfo code (Linux only)
+* [GPUPerfAPI-Common](Src/GPUPerfAPI-Common) -- contains source code for a Common library shared by all versions of GPUPerfAPI
+* [GPUPerfAPICL](Src/GPUPerfAPICL) - contains the source for the OpenCL™ version of GPUPerfAPI
+* [GPUPerfAPICounterGenerator](Src/GPUPerfAPICounterGenerator) - contains the source code for a Common library providing all counter data
+* [GPUPerfAPICounters](Src/GPUPerfAPICounters) - contains the source code for a library that can be used to query counters without an active GPUPerfAPI context
+* [GPUPerfAPIDX](Src/GPUPerfAPIDX) - contains source code shared by the DirectX versions of GPUPerfAPI
+* [GPUPerfAPIDX11](Src/GPUPerfAPIDX11) - contains the source for the DirectX11 version of GPUPerfAPI
+* [GPUPerfAPIDX12](Src/GPUPerfAPIDX12) - contains the source for the DirectX12 version of GPUPerfAPI (prototype/alpha)
+* [GPUPerfAPIGL](Src/GPUPerfAPIGL) - contains the source for the OpenGL version of GPUPerfAPI
+* [GPUPerfAPIGLES](Src/GPUPerfAPIGLES) - contains the source for the OpenGLES version of GPUPerfAPI
+* [GPUPerfAPIHSA](Src/GPUPerfAPIHSA) - contains the source for the ROCm/HSA version of GPUPerfAPI
+* [GPUPerfAPIUnitTests](Src/GPUPerfAPIUnitTests) - contains a small set of unit tests for GPUPerfAPI
+* [PublicCounterCompiler](Src/PublicCounterCompiler) - source code for a tool to generate C++ code for public counters from text files defining the counters.
+* [PublicCounterCompilerInputFiles](Src/PublicCounterCompilerInputFiles) - input files that can be fed as input to the PublicCounterCompiler tool
+* [Utils](Utils) -- scripts to use to clone/update dependent repositories
 
 <A NAME="PublicInternal">
 ## "Public" vs "Internal" Versions
@@ -90,5 +87,17 @@ no longer actually Internal-to-AMD can be a bit confusing, and we will aim to ch
 
 <A NAME="HistoricalNotes">
 ## Historical Release Notes
+* Version 2.20 (5/12/16)
+  * Add support for additional GPUs and APUs.
+  * Initial Public release of ROCm/HSA support
+  * Alpha/Prototype for DirectX12 (no hardware-based performance counter support)
+  * Removed support for pre-GCN-based devices
+  * Improve accuracy of the various *VALUBusy and *SALUBusy counters (all APIs)
+  * OpenGL: Fixed possibly wrong GPUTime values for some applications
+  * OpenGL: Add support for open source OpenGL driver
+  * OpenGL: Fix value of TexUnitBusy counter for 3rd generation GCN hardware
+  * DirectX 11: Fix incorrect type returned for D3DGPUTime counter
+  * DirectX 11: Fix PSVALUBusy counter on 2nd and 3rd generation GCN hardware
+  * DirectX 11: A separate DLL (GPUPerfAPIDXGetAMDDeviceInfo\*.dll) is required in order to support certain multi-GPU configurations. This DLL will need to be deployed alongside GPUPerfAPIDX11\*.dll on multi-GPU systems. See the [User Guide](Doc/GPUPerfAPI-UserGuide.pdf) for more information.
 * [Version 2.17](http://developer.amd.com/tools-and-sdks/graphics-development/gpuperfapi/)
 * [Earlier Releases](http://developer.amd.com/tools-and-sdks/graphics-development/gpuperfapi/gpuperfapi-historical-release-notes/)

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+If the only subdirectory in this Common directory is Common/Lib/AMD/GPUPerfAPI, then you have probably forgotten to execute the`
	`2`	`+[UpdateCommon.py](../Utils/UpdateCommon.py) script in the [Utils](../Utils) directory.`
	`3`	`+Please see the instructions in [BUILD.md](../BUILD.md#DependentRepos)`