CPU Performance Counters Library Functions    cpcgetcpuver(3CPC)



NAME
     cpcgetcpuver, cpcgetcciname, cpcgetcpuref,  cpcgetusage,
     cpcgetnpic,  cpcwalknames  -  determine  CPU  performance
     counter configuration

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

     int cpcgetcpuver(void);


     const char *cpcgetcciname(int cpuver);


     const char *cpcgetcpuref(int cpuver);


     const char *cpcgetusage(int cpuver);


     uintt cpcgetnpic(int cpuver);


     void cpcwalknames(int cpuver, int regno, void *arg,
          void (*action)(void *arg, int regno,  const char *name,
          uint8t bits));


DESCRIPTION
     The cpcgetcpuver() function  returns  an  abstract  integer
     that  corresponds to the distinguished version of the under-
     lying processor.  The library distinguishes between  proces-
     sors  solely  on  the basis of their support for performance
     counters, so the version returned should not be  interpreted
     in  any other way. The set of values returned by the library
     is unique across all processor implementations.


     The cpcgetcpuver() function returns -1 if the library  can-
     not  support  CPU performance counters on the current archi-
     tecture.  This may be because  the  processor  has  no  such
     counter hardware, or because the library is unable to recog-
     nize it. Either way, such a return value indicates that  the
     configuration functions described on this manual page cannot
     be used.


     The cpcgetcciname() function returns a  printable  descrip-
     tion  of  the  processor  performance counter interfaces-for
     example, the string UltraSPARC I&I.  Note  that  this  name
     should  not  be  assumed  to  be  the  same  as the name the



SunOS 5.11          Last change: 28 Mar 2005                    1






CPU Performance Counters Library Functions    cpcgetcpuver(3CPC)



     manufacturer might otherwise ascribe to the  processor.   It
     simply  names  the  performance counter interfaces as under-
     stood by the library, and thus names the set of  performance
     counter  events  that can be described by that interface. If
     the cpuver argument is unrecognized,  the  function  returns
     NUL.


     The cpcgetcpuref() 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 library. If the cpuver argument
     is unrecognized,  the  function  returns  NUL.  The  string
     returned  might  be substantially longer than 80 characters.
     Callers printing to a terminal might  want  to  insert  line
     breaks as appropriate.


     The cpcgetusage() function returns a compact description of
     the   getsubopt()-oriented   syntax   that  is  consumed  by
     cpcstrtoevent(3CPC). It is returned  as  a  space-separated
     set  of  tokens  to  allow  the caller to wrap lines at con-
     venient boundaries. If the cpuver argument is  unrecognized,
     the function returns NUL.


     The cpcgetnpic()  function  returns  the  number  of  valid
     fields  in  the  cepic[] array of a cpceventt data struc-
     ture.


     The library maintains a list of events that it believes  the
     processor  capable of measuring, along with the bit patterns
     that must be set in the corresponding control register,  and
     which    counter   the   result   will   appear   in.    The
     cpcwalknames() function calls  the  action()  function  on
     each  element  of  the list so that an application can print
     appropriate help on the set of events known to the  library.
     The arg parameter is passed uninterpreted from the caller on
     each invocation of the action() function.


     If the parameters specify  an  invalid  or  unknown  CPU  or
     register  number,  the  function  silently  returns  without
     invoking the action function.

USAGE
     Prior to calling any of these functions, applications should
     call  cpcaccess(3CPC)  to  determine  if  the  counters are
     accessible on the system.





SunOS 5.11          Last change: 28 Mar 2005                    2






CPU Performance Counters Library Functions    cpcgetcpuver(3CPC)



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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     MT-Safe                     
    
     Interface Stability          Obsolete                    
    


SEE ALSO
     cpc(3CPC),       cpcaccess(3CPC),        cpccciname(3CPC),
     cpccpuref(3CPC),                            cpcnpic(3CPC),
     cpcwalkeventsall(3CPC)libcpc(3LIB), attributes(5)

NOTES
     The  cpcgetcpuver(),   cpcgetcciname(),   cpcgetcpuref(),
     cpcgetusage(),  cpcgetnpic(),  and  cpcwalknames() func-
     tions exist for binary compatibility only. Source containing
     these  functions  will  not  compile.  These  functions  are
     obsolete and might be removed in a future release.  Applica-
     tions   should   use   cpccciname(3CPC),  cpccpuref(3CPC),
     cpcnpic(3CPC), and cpcnpic(3CPC) instead.


     Only SPARC processors are described by the SPARC version  of
     the  library,  and  only x86 processors are described by the
     x86 version of the library.






















SunOS 5.11          Last change: 28 Mar 2005                    3