The High Level API

Functions
int	PAPI_accum_counters (long long *values, int array_len)
int	PAPI_num_counters (void)
int	PAPI_num_components (void)
int	PAPI_read_counters (long long *values, int array_len)
int	PAPI_start_counters (int *events, int array_len)
int	PAPI_stop_counters (long long *values, int array_len)
int	PAPI_flips (float *rtime, float *ptime, long long *flpins, float *mflips)
int	PAPI_flops (float *rtime, float *ptime, long long *flpops, float *mflops)
int	PAPI_ipc (float *rtime, float *ptime, long long *ins, float *ipc)
int	PAPI_epc (int event, float *rtime, float *ptime, long long *ref, long long *core, long long *evt, float *epc)

Detailed Description

The simple interface implemented by the following eight routines allows the user to access and count specific hardware events from both C and Fortran. It should be noted that this API can be used in conjunction with the low level API.

Function Documentation

PAPI_accum_counters()

int PAPI_accum_counters	(	long long *	values,
		int	array_len
	)

add current counts to array and reset counters

Definition at line 760 of file papi_hl.c.

{
    if ( values == NULL || array_len <= 0 )
        return PAPI_EINVAL;

    return ( _internal_hl_read_cnts( values, array_len, HL_ACCUM ) );
}

PAPI_epc()

int PAPI_epc	(	int	event,
		float *	rtime,
		float *	ptime,
		long long *	ref,
		long long *	core,
		long long *	evt,
		float *	epc
	)

gets (named) events per cycle, real and processor time, reference and core cycles

Definition at line 387 of file papi_hl.c.

{
    long long values[3] = { 0, 0, 0 };
    int events[3] = {PAPI_TOT_INS, PAPI_TOT_CYC, PAPI_REF_CYC};
    int retval = 0;

    if ( rtime == NULL || ptime == NULL || ref == NULL ||core == NULL || evt == NULL || epc == NULL )
        return PAPI_EINVAL;

    // if an event is provided, use it; otherwise use TOT_INS
    if (event != 0 ) events[0] = event;
    
    if ( PAPI_query_event( ( int ) PAPI_REF_CYC ) != PAPI_OK )
        events[2] = 0;

    retval = _hl_rate_calls( rtime, ptime, events, values, evt, epc, HL_EPC );
    *core = values[1];
    *ref = values[2];
    return ( retval );
}

PAPI_flips()

int PAPI_flips	(	float *	rtime,
		float *	ptime,
		long long *	flpins,
		float *	mflips
	)

simplified call to get Mflips/s (floating point instruction rate), real and processor time

Definition at line 204 of file papi_hl.c.

{
    int retval;
    int events[1] = {PAPI_FP_INS};
    long long values = 0;

    if ( rtime == NULL || ptime == NULL ||
            flpins == NULL || mflips == NULL ) {
        return PAPI_EINVAL;
    }

    retval = _hl_rate_calls( rtime, ptime, events,
            &values, flpins, mflips, HL_FLIP );

    return ( retval );
}

PAPI_flops()

int PAPI_flops	(	float *	rtime,
		float *	ptime,
		long long *	flpops,
		float *	mflops
	)

simplified call to get Mflops/s (floating point operation rate), real and processor time

Definition at line 263 of file papi_hl.c.

{
    int retval;
   int events[1] = {PAPI_FP_OPS};
    long long values = 0;

    if ( rtime == NULL || ptime == NULL || flpops == NULL || mflops == NULL )
        return PAPI_EINVAL;

   retval = _hl_rate_calls( rtime, ptime, events, &values, flpops, mflops, HL_FLOP );
    return ( retval );
}

PAPI_ipc()

int PAPI_ipc	(	float *	rtime,
		float *	ptime,
		long long *	ins,
		float *	ipc
	)

gets instructions per cycle, real and processor time

Definition at line 320 of file papi_hl.c.

{
    long long values[2] = { 0, 0 };
    int events[2] = {PAPI_TOT_INS, PAPI_TOT_CYC};
    int retval = 0;

    if ( rtime == NULL || ptime == NULL || ins == NULL || ipc == NULL )
        return PAPI_EINVAL;

    retval = _hl_rate_calls( rtime, ptime, events, values, ins, ipc, HL_IPC );
    return ( retval );
}

PAPI_num_components()

int PAPI_num_components

(

void

)

get the number of components available on the system

Definition at line 4387 of file papi.c.

{
    APIDBG( "Entry:\n");
    return ( papi_num_components );
}

PAPI_num_counters()

int PAPI_num_counters

(

void

)

get the number of hardware counters available on the system

Definition at line 541 of file papi_hl.c.

{
    int retval;
    HighLevelInfo *tmp = NULL;

    /* Make sure the Library is initialized, etc... */
    if ( ( retval = _internal_check_state( &tmp ) ) != PAPI_OK )
        return ( retval );

    return ( PAPI_get_opt( PAPI_MAX_HWCTRS, NULL ) );
}

PAPI_read_counters()

int PAPI_read_counters	(	long long *	values,
		int	array_len
	)

copy current counts to array and reset counters

Definition at line 710 of file papi_hl.c.

{
    return ( _internal_hl_read_cnts( values, array_len, HL_READ ) );
}

PAPI_start_counters()

int PAPI_start_counters	(	int *	events,
		int	array_len
	)

start counting hardware events

Definition at line 597 of file papi_hl.c.

{
    int i, retval;
    HighLevelInfo *state = NULL;

    if ( events == NULL || array_len <= 0 )
        return PAPI_EINVAL;

    if ( ( retval = _internal_check_state( &state ) ) != PAPI_OK )
        return ( retval );

    if ( state->running != 0 )
        return ( PAPI_EINVAL );

    /* load events to the new EventSet */
    for ( i = 0; i < array_len; i++ ) {
        retval = PAPI_add_event( state->EventSet, events[i] );
        if ( retval == PAPI_EISRUN )
            return ( retval );

        if ( retval ) {
            /* remove any prior events that may have been added 
             * and cleanup the high level information
             */
            _internal_cleanup_hl_info( state );
            PAPI_cleanup_eventset( state->EventSet );
            return ( retval );
        }
    }
    /* start the EventSet */
    if ( ( retval = _internal_start_hl_counters( state ) ) == PAPI_OK ) {
        state->running = HL_START;
        state->num_evts = ( short ) array_len;
    }
    return ( retval );
}

PAPI_stop_counters()

int PAPI_stop_counters	(	long long *	values,
		int	array_len
	)

stop counters and return current counts

Definition at line 807 of file papi_hl.c.

{
    int retval;
    HighLevelInfo *state = NULL;

    if ( ( retval = _internal_check_state( &state ) ) != PAPI_OK )
        return ( retval );

    if ( state->running == 0 )
        return ( PAPI_ENOTRUN );

    if ( state->running == HL_START ) {
        if ( array_len < state->num_evts  || values == NULL) {
            return ( PAPI_EINVAL );
        } else {
            retval = PAPI_stop( state->EventSet, values );
        }
    }

    if ( state->running > HL_START ) {
        long long tmp_values[3];
        retval = PAPI_stop( state->EventSet, tmp_values );
    }
    
    if ( retval == PAPI_OK ) {
        _internal_cleanup_hl_info( state );
        PAPI_cleanup_eventset( state->EventSet );
    }
    APIDBG( "PAPI_stop_counters returns %d\n", retval );
    return retval;
}