Manual Pages for UNIX Operating System command usage for man cpc_walk_generic_events_all

CPU Performance Counters Library Functions         cpc_npic(3CPC)



NAME
     cpc_npic,      cpc_caps,      cpc_cciname,       cpc_cpuref,
     cpc_walk_events_all,            cpc_walk_generic_events_all,
     cpc_walk_events_pic,            cpc_walk_generic_events_pic,
     cpc_walk_attrs  -  determine  CPU performance counter confi-
     guration

SYNOPSIS
     cc [ flag... ] file... -lcpc [ library... ]
     #include 

     uint_t cpc_npic(cpc_t *cpc);


     uint_t cpc_caps(cpc_t *cpc);


     const char *cpc_cciname(cpc_t *cpc);


     const char *cpc_cpuref(cpc_t *cpc);


     void cpc_walk_events_all(cpc_t *cpc, void *arg,
          void (*action)(void *arg, const char *event));


     void cpc_walk_generic_events_all(cpc_t *cpc, void *arg,
          void (*action)(void *arg, const char *event));


     void cpc_walk_events_pic(cpc_t *cpc, uint_t picno, void *arg,
          void (*action)(void *arg, uint_t picno, const char *event));


     void cpc_walk_generic_events_pic(cpc_t *cpc, uint_t picno,
          void *arg, void (*action)(void *arg, uint_t picno,
          const char *event));


     void cpc_walk_attrs(cpc_t *cpc, void *arg,
          void (*action)(void *arg, const char *attr));


DESCRIPTION
     The cpc_cciname() function returns a  printable  description
     of  the  processor performance counter interfaces, for exam-
     ple, the string UltraSPARC III+ & IV. This name  should  not
     be assumed to be the same as the name the manufacturer might
     otherwise ascribe to the processor. It simply names the per-
     formance counter interfaces as understood by the system, and
     thus names the set of performance counter events that can be



SunOS 5.11           Last change: 8 Oct 2008                    1






CPU Performance Counters Library Functions         cpc_npic(3CPC)



     described by that interface.


     The cpc_cpuref() function returns a string that describes  a
     reference  work  that  should be consulted to (allow a human
     to) understand the  semantics  of  the  performance  counter
     events  that  are  known  to the system. The string returned
     might be substantially longer than  80  characters.  Callers
     printing  to  a terminal might want to insert line breaks as
     appropriate.


     The cpc_npic() function returns the  number  of  performance
     counters accessible on the processor.


     The cpc_caps() function returns a bitmap containing the bit-
     wise  inclusive-OR  of  zero or more flags that describe the
     capabilities of the processor. If CPC_CAP_OVERFLOW_INTERRUPT
     is  present,  the processor can generate an interrupt when a
     hardware     performance     counter      overflows.      If
     CPC_CAP_OVERFLOW_PRECISE   is  present,  the  processor  can
     determine  precisely  which  counter   overflowed,   thereby
     affecting  the behavior of the overflow notification mechan-
     ism described in cpc_bind_curlwp(3CPC).


     The system maintains a list of  performance  counter  events
     supported  by  the underlying processor. Some processors are
     able to count all events on  all  hardware  counters,  while
     other  processors restrict certain events to be counted only
     on specific hardware counters. The system also  maintains  a
     list  of  processor-specific attributes that can be used for
     advanced configuration of the performance counter  hardware.
     These  functions allow applications to determine what events
     and attributes are supported by  the  underlying  processor.
     The reference work pointed to by cpc_cpuref() should be con-
     sulted to understand the reasons for and use of  the  attri-
     butes.


     The cpc_walk_events_all() function calls the action function
     on  each element of a global event list. The action function
     is called  with  each  event  supported  by  the  processor,
     regardless  of  which counter is capable of counting it. The
     action function is called only once for each event, even  if
     that event can be counted on more than one counter.


     The cpc_walk_events_pic() function calls the action function
     with  each  event  supported by the counter indicated by the
     picno argument, where picno  ranges  from  0  to  the  value



SunOS 5.11           Last change: 8 Oct 2008                    2






CPU Performance Counters Library Functions         cpc_npic(3CPC)



     returned by cpc_npic().


     The system maintains a list of platform independent  perfor-
     mance   counter   events   known   as  generic  events  (see
     generic_events(3CPC)).


     The cpc_walk_generic_events_all() function calls the  action
     function  on  each generic event available on the processor.
     The action  function  is  called  for  each  generic  event,
     regardless  of  which counter is capable of counting it. The
     action function is called only once for each event, even  if
     that event can be counted on more than one counter.


     The cpc_walk_generic_events_pic() function calls the  action
     function  with  each  generic event supported by the counter
     indicated by the picno argument, where picno ranges  from  0
     to the value returned by cpc_npic().


     The system maintains a list of attributes that can  be  used
     to  enable  advanced features of the performance counters on
     the  underlying  processor.  The  cpc_walk_attrs()  function
     calls the action function for each supported attribute name.
     See the reference material as returned  by  cpc_cpuref(3CPC)
     for the semantics use of attributes.

RETURN VALUES
     The  cpc_cciname()  function  always  returns  a   printable
     description of the processor performance counter interfaces.


     The cpc_cpuref()  function  always  returns  a  string  that
     describes a reference work.


     The cpc_npic() function always returns the number of perfor-
     mance counters accessible on the processor.


     The cpc_caps() function always returns a  bitmap  containing
     the bitwise inclusive-OR of zero or more flags that describe
     the capabilities of the processor.


     If the user-defined function  specified  by  action  is  not
     called,  the  cpc_walk_events_all(),  cpc_walk_events_pic(),
     cpc_walk_attrs(),     cpc_walk_generic_events_pic(),     and
     cpc_walk_generic_events_pic()  functions  set errno to indi-
     cate the error.



SunOS 5.11           Last change: 8 Oct 2008                    3






CPU Performance Counters Library Functions         cpc_npic(3CPC)



ERRORS
     The      cpc_walk_events_all(),       cpc_walk_events_pic(),
     cpc_walk_attrs(),     cpc_walk_generic_events_pic(),     and
     cpc_walk_generic_events_pic() functions will fail if:

     ENOMEM    There is not enough memory available.


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO
     cpc_bind_curlwp(3CPC),  generic_events(3CPC),  libcpc(3LIB),
     attributes(5)





























SunOS 5.11           Last change: 8 Oct 2008                    4