/** 
* @file:   README
* CVS:     $Id$
* @author: Asim YarKhan yarkhan@icl.utk.edu
* @author: Heike McCraw mccraw@icl.utk.edu
* @defgroup papi_components Components
* @brief Component Specific Readme file: CUDA
*/

/** @page component_readme Component Readme 

@section Component Specific Information

cuda/ 

CUDA component update: Support for CUPTI metrics (early release)


Known problems and limitations in early release of metric support
-----------------------------------------------------------------

* Only sets of metrics and events that can be gathered in a single
  pass are supported.  Transparent multi-pass support is expected
* All metrics are returned as long long integers, which means that
  CUPTI double precision values will be truncated, possibly severely.
* The NVLink metrics have been disabled for this alpha release.


General information
-------------------

The PAPI CUDA component is a hardware performance counter
measurement technology for the NVIDIA CUDA platform which provides
access to the hardware counters inside the GPU. PAPI CUDA is based on
CUPTI support in the NVIDIA driver library. In any environment where
the CUPTI-enabled driver is installed, the PAPI CUDA component should
be able to provide detailed performance counter information regarding
events on the GPU kernels.  

NOTE: When adding CUDA related events or metrics to the CUDA
component, each event can be added within a users specified CUDA
context.  If the event is outside its context or in no context, a
default CUDA context will be created for the event.

NOTE: In order to disable and destroy the CUDA eventGroup properly,
the user has to call PAPI_cleanup_eventset( EventSet ) before calling
PAPI_shutdown() in the application. This is important since it also
frees the performance monitoring hardware on the GPU.


How to install PAPI with the CUDA component?
-------------------------------------------- 

This PAPI CUDA componen has been developed and tested using CUDA
version 8.0 and the associated CUPTI library. CUPTI is released with
the CUDA Tools SDK.

This component uses the CUDA location from the environment (or looks
for /opt/cuda by default).  Please set CUDA_DIR and CUPTI_DIR during
builds so that the component can find the required header files.

Configure PAPI with CUDA enabled.  
    % cd src
    % ./configure --prefix=some_location --with-components="cuda"

Build with CUDA_DIR and CUPTI_DIR specified
    % export CUDA_DIR=/opt/cuda
    % export CUPTI_DIR=/opt/cuda/extras/CUPTI
    % make 

Testing the component requires that libraries for PAPI, CUDA, CUPTI
can be found or are statically linked in to the executable.  You may
need to add the library directories as shown here.  

 % export LD_LIBRARY_PATH=${CUDA_DIR}/lib64:${CUPTI_DIR}/lib64:${LD_LIBRARY_PATH}

Test by running from the src directory
   % ./components/cuda/tests/simpleMultiGPU

For general information on how to create and run components, the user
is referred to the INSTALL.txt section "CREATING AND RUNNING
COMPONENTS".

To find a list of CUDA supported events.
    % utils/papi_native_avail | grep CUDA

*/