Module Papi
Performance Application Programming Interface (PAPI) bindings.
This module binds <papi.h>
. PAPI provides portable access to hardware performance counters. For more information, see the homepage.
Note. All functions in this module except shutdown
raise Error
whenever the underlying PAPI call signals an error.
Note. All functions except init
and shutdown
raise Error (ENOINIT, _)
before initialisation.
For examples of use, consult examples.
v0.1.1 — homepage
Errors
type error
=
exception
Error of error * string
PAPI errors are signalled by raising
Error ((err, fname))
, wherefname
is the name of the failing function.
val pp_error : Stdlib.Format.formatter -> error -> unit
pp_error ppf err
pretty-printserr
onppf
.
val pp_exn_error : Stdlib.Format.formatter -> (error * string) -> unit
pp_exn_error ppf arg
pretty-prints theError
argumentarg
onppf
.
Initialisation
Events
type event
=
|
L1_DCM
|
L1_ICM
|
L2_DCM
|
L2_ICM
|
L3_DCM
|
L3_ICM
|
L1_TCM
|
L2_TCM
|
L3_TCM
|
CA_SNP
|
CA_SHR
|
CA_CLN
|
CA_INV
|
CA_ITV
|
L3_LDM
|
L3_STM
|
BRU_IDL
|
FXU_IDL
|
FPU_IDL
|
LSU_IDL
|
TLB_DM
|
TLB_IM
|
TLB_TL
|
L1_LDM
|
L1_STM
|
L2_LDM
|
L2_STM
|
BTAC_M
|
PRF_DM
|
L3_DCH
|
TLB_SD
|
CSR_FAL
|
CSR_SUC
|
CSR_TOT
|
MEM_SCY
|
MEM_RCY
|
MEM_WCY
|
STL_ICY
|
FUL_ICY
|
STL_CCY
|
FUL_CCY
|
HW_INT
|
BR_UCN
|
BR_CN
|
BR_TKN
|
BR_NTK
|
BR_MSP
|
BR_PRC
|
FMA_INS
|
TOT_IIS
|
TOT_INS
|
INT_INS
|
FP_INS
|
LD_INS
|
SR_INS
|
BR_INS
|
VEC_INS
|
RES_STL
|
FP_STAL
|
TOT_CYC
|
LST_INS
|
SYC_INS
|
L1_DCH
|
L2_DCH
|
L1_DCA
|
L2_DCA
|
L3_DCA
|
L1_DCR
|
L2_DCR
|
L3_DCR
|
L1_DCW
|
L2_DCW
|
L3_DCW
|
L1_ICH
|
L2_ICH
|
L3_ICH
|
L1_ICA
|
L2_ICA
|
L3_ICA
|
L1_ICR
|
L2_ICR
|
L3_ICR
|
L1_ICW
|
L2_ICW
|
L3_ICW
|
L1_TCH
|
L2_TCH
|
L3_TCH
|
L1_TCA
|
L2_TCA
|
L3_TCA
|
L1_TCR
|
L2_TCR
|
L3_TCR
|
L1_TCW
|
L2_TCW
|
L3_TCW
|
FML_INS
|
FAD_INS
|
FDV_INS
|
FSQ_INS
|
FNV_INS
|
FP_OPS
|
SP_OPS
|
DP_OPS
|
VEC_SP
|
VEC_DP
|
REF_CYC
PAPI
PRESET
events.The header file
papiStdEventDefs.h
, installed by PAPI, is the authoritative description of events.Another way to obtain event descriptions is to call
description
, or pretty-print them withpp_event
.
val name : event -> string
name e
is a human-readable name fore
.It returns
PAPI_event_info_t.name
, without the prefix"PAPI_"
.
val description : event -> string
description e
is a human-readable description ofe
.It returns
PAPI_event_info_t.long_descr
.
val query : event -> bool
query e
istrue
iff the hardware supports the evente
.
val pp_event : Stdlib.Format.formatter -> event -> unit
pp_event ppf e
pretty-prints a human-readable description one
onppf
.
Event sets
type eventset
Sets of events.
Note. Eventsets are handles to resources held by PAPI. The handles are recycled. Calls to
destroy
followed bycreate
can therefore return handles identical to previously destroyed handles, making destroyed eventsets live again.
val cleanup : eventset -> unit
cleanup es
removes counters fromes
.Calls
PAPI_cleanup_eventset
.
val destroy : eventset -> unit
destroy es
releases the resources backinges
.Calls
PAPI_destroy_eventset
.
val start : eventset -> unit
start es
starts counting the events ines
.Calls
PAPI_start
.
val stop : eventset -> unit
stop es
stops counting the events ines
.Calls
PAPI_stop
.
val reset : eventset -> unit
reset es
resets the counters of events ines
.Calls
PAPI_reset
.
val read : eventset -> ?off:int -> float array -> unit
read es ~off values
es
' event counters tovalues
.These values are written to
values.(off), ..., values.(off + n - 1)
wheren
isnum_events es
.off
defaults to0
.Calls
PAPI_read
.
val accum : eventset -> ?off:int -> float array -> unit
accum es ~off values
addses
' event counters tovalues
and resets them.These values are written to
values.(off), ..., values.(off + n - 1)
wheren
isnum_events es
.off
defaults to0
.Calls
PAPI_accum
.
Examples
Read the TSC and the actual number of cycles:
open Papi
let _ = init ()
let _ =
let es = create ()
and vs = Array.create_float 2 in
List.iter (add es) [REF_CYC; TOT_CYC];
start es;
long_running_fun ();
read es vs;
stop es; cleanup es; destroy es;
Fmt.pr "reference: %f, total: %f\n" vs.(0) vs.(1)
Create bracket that reads a set of events:
open Papi
let _ = init ()
let count_events ~events f =
let es = create ()
and vs = Array.create_float (List.length events) in
List.iter (add es) events;
start es;
let res = f () in
read es vs;
stop es; cleanup es; destroy es;
(res, vs)