PAPI_get_substrate_info(3)

1PAPI_get_substrate_info(3)           PAPI           PAPI_get_substrate_info(3)
2
3
4

NAME

6       PAPI_get_substrate_info - get information about the software substrate
7
8

SYNOPSIS

10       C Interface
11       #include <papi.h>
12       const PAPI_substrate_info_t *PAPI_get_substrate_info(void);
13       Fortran Interface
14       <none>
15
16

DESCRIPTION

18       This  function  returns  a  pointer  to a structure containing detailed
19       information about the software substrate on  which  the  program  runs.
20       This  includes versioning information, preset and native event informa‐
21       tion, details on event multiplexing, and more. For  full  details,  see
22       the structure listing below.
23
24

RETURN VALUES

26       On  success, the function returns a non-NULL pointer.  On error, a NULL
27       pointer is returned.
28
29

ERRORS

31       <none>
32
33

EXAMPLE

35       const PAPI_substrate_info_t *sbinfo = NULL;
36
37       if (PAPI_library_init(PAPI_VER_CURRENT) != PAPI_VER_CURRENT)
38         exit(1);
39
40       if ((sbinfo = PAPI_get_substrate_info()) == NULL)
41         exit(1);
42
43       printf("This substrate supports %d Preset Events and %d Native events.0,
44          sbinfo->num_preset_events, sbinfo->num_native_events);
45
46

DATA STRUCTURE

48       The C data structure returned by this function is found in  papi.h  and
49       reproduced below:
50
51          typedef struct _papi_substrate_option {
52            char name[PAPI_MAX_STR_LEN];            /* Name of the substrate we're using, usually CVS RCS Id */
53            char version[PAPI_MIN_STR_LEN];         /* Version of this substrate, usually CVS Revision */
54            char support_version[PAPI_MIN_STR_LEN]; /* Version of the support library */
55            char kernel_version[PAPI_MIN_STR_LEN];  /* Version of the kernel PMC support driver */
56            int num_cntrs;               /* Number of hardware counters the substrate supports */
57            int num_mpx_cntrs;           /* Number of hardware counters the substrate or PAPI can multiplex supports */
58            int num_preset_events;       /* Number of preset events the substrate supports */
59            int num_native_events;       /* Number of native events the substrate supports */
60            int default_domain;          /* The default domain when this substrate is used */
61            int available_domains;       /* Available domains */
62            int default_granularity;     /* The default granularity when this substrate is used */
63            int available_granularities; /* Available granularities */
64            int multiplex_timer_sig;     /* Signal number used by the multiplex timer, 0 if not */
65            int multiplex_timer_num;     /* Number of the itimer or POSIX 1 timer used by the multiplex timer */
66            int multiplex_timer_us;   /* uS between switching of sets */
67            int hardware_intr_sig;       /* Signal used by hardware to deliver PMC events */
68            int opcode_match_width;      /* Width of opcode matcher if exists, 0 if not */
69            int reserved_ints[4];
70            unsigned int hardware_intr:1;         /* hw overflow intr, does not need to be emulated in software*/
71            unsigned int precise_intr:1;          /* Performance interrupts happen precisely */
72            unsigned int posix1b_timers:1;        /* Using POSIX 1b interval timers (timer_create) instead of setitimer */
73            unsigned int kernel_profile:1;        /* Has kernel profiling support (buffered interrupts or sprofil-like) */
74            unsigned int kernel_multiplex:1;      /* In kernel multiplexing */
75            unsigned int data_address_range:1;    /* Supports data address range limiting */
76            unsigned int instr_address_range:1;   /* Supports instruction address range limiting */
77            unsigned int fast_counter_read:1;     /* Supports a user level PMC read instruction */
78            unsigned int fast_real_timer:1;       /* Supports a fast real timer */
79            unsigned int fast_virtual_timer:1;    /* Supports a fast virtual timer */
80            unsigned int attach:1;           /* Supports attach */
81            unsigned int attach_must_ptrace:1;    /* Attach must first ptrace and stop the thread/process*/
82            unsigned int edge_detect:1;           /* Supports edge detection on events */
83            unsigned int invert:1;                /* Supports invert detection on events */
84            unsigned int profile_ear:1;           /* Supports data/instr/tlb miss address sampling */
85            unsigned int grouped_cntrs:1;         /* Underlying hardware uses counter groups */
86            unsigned int reserved_bits:16;
87          } PAPI_substrate_info_t;
88
89
90

BUGS

92       If  called  before  PAPI_library_init()  the behavior of the routine is
93       undefined.
94
95