/** 

* @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

*/