xref: /freebsd/lib/libpmc/pmc_capabilities.3 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\"    notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\"    notice, this list of conditions and the following disclaimer in the
10.\"    documentation and/or other materials provided with the distribution.
11.\"
12.\" This software is provided by Joseph Koshy ``as is'' and
13.\" any express or implied warranties, including, but not limited to, the
14.\" implied warranties of merchantability and fitness for a particular purpose
15.\" are disclaimed.  in no event shall Joseph Koshy be liable
16.\" for any direct, indirect, incidental, special, exemplary, or consequential
17.\" damages (including, but not limited to, procurement of substitute goods
18.\" or services; loss of use, data, or profits; or business interruption)
19.\" however caused and on any theory of liability, whether in contract, strict
20.\" liability, or tort (including negligence or otherwise) arising in any way
21.\" out of the use of this software, even if advised of the possibility of
22.\" such damage.
23.\"
24.\" $FreeBSD$
25.\"
26.Dd November 24, 2007
27.Os
28.Dt PMC_CAPABILITIES 3
29.Sh NAME
30.Nm pmc_capabilities ,
31.Nm pmc_cpuinfo ,
32.Nm pmc_ncpu ,
33.Nm pmc_npmc ,
34.Nm pmc_pmcinfo ,
35.Nm pmc_width
36.Nd retrieve information about performance monitoring counters
37.Sh LIBRARY
38.Lb libpmc
39.Sh SYNOPSIS
40.In pmc.h
41.Ft int
42.Fn pmc_capabilities "pmc_id_t pmc" "uint32_t *caps"
43.Ft int
44.Fn pmc_cpuinfo "const struct pmc_cpuinfo **cpu_info"
45.Ft int
46.Fn pmc_ncpu void
47.Ft int
48.Fn pmc_npmc "int cpu"
49.Ft int
50.Fn pmc_pmcinfo "int cpu" "struct pmc_pmcinfo **pmc_info"
51.Ft int
52.Fn pmc_width "pmc_id_t pmc" "uint32_t *width"
53.Sh DESCRIPTION
54These functions retrieve information about performance monitoring
55hardware.
56.Pp
57Function
58.Fn pmc_capabilities
59retrieves the hardware capabilities of a PMC.
60Argument
61.Fa pmc
62is a PMC handle obtained by a prior call to
63.Fn pmc_allocate .
64The function sets argument
65.Fa caps
66to a bitmask of capabilities supported by the PMC denoted by
67argument
68.Fa pmc .
69PMC capabilities are described in
70.Xr pmc 3 .
71.Pp
72Function
73.Fn pmc_cpuinfo
74retrieves information about the CPUs in the system.
75Argument
76.Fa cpu_info
77will be set to point to an internal structure with information about
78the system's CPUs.
79The caller should not free this pointer value.
80This structure has the following fields:
81.Bl -tag -width "pm_classes" -offset indent -compact
82.It pm_cputype
83Specifies the CPU type.
84.It pm_ncpu
85Specifies the number of CPUs in the system.
86.It pm_npmc
87Specifies the number of PMC rows per CPU.
88.It pm_nclass
89Specifies the number of distinct classes of PMCs in the system.
90.It pm_classes
91Contains an array of
92.Vt "struct pmc_classinfo"
93descriptors describing the properties of each class of PMCs
94in the system.
95.El
96.Pp
97Function
98.Fn pmc_ncpu
99is a convenience function that returns the number of CPUs in the
100system.
101.Pp
102Function
103.Fn pmc_npmc
104is a convenience function that returns the number of PMCs available
105in the CPU specified by argument
106.Fa cpu .
107.Pp
108Function
109.Fn pmc_pmcinfo
110returns information about the current state of the PMC hardware
111in the CPU specified by argument
112.Fa cpu .
113The location specified by argument
114.Fa pmc_info
115is set to point an array of
116.Vt "struct pmc_info"
117structures each describing the state of one PMC in the CPU.
118These structure contain the following fields:
119.Bl -tag -width pm_ownerpid -offset indent -compact
120.It pm_name
121A human readable name for the PMC.
122.It pm_class
123The PMC class for the PMC.
124.It pm_enabled
125Non-zero if the PMC is enabled.
126.It pm_rowdisp
127The disposition of the PMC row for this PMC.
128Row dispositions are documented in
129.Xr hwpmc 4 .
130.It pm_ownerpid
131If the hardware is in use, the process id of the owner of the PMC.
132.It pm_mode
133The PMC mode as described in
134.Xr pmc 3 .
135.It pm_event
136If the hardware is in use, the PMC event being measured.
137.It pm_flags
138If the hardware is in use, the flags associated with the PMC.
139.It pm_reloadcount
140For sampling PMCs, the reload count associated with the PMC.
141.El
142.Pp
143Function
144.Fn pmc_width
145is used to retrieve the width in bits of the hardware counters
146associated with a PMC.
147Argument
148.Fa pmc
149is a PMC handle obtained by a prior call to
150.Fn pmc_allocate .
151The function sets the location pointed to by argument
152.Fa width
153to the width of the physical counters associated with PMC
154.Fa pmc .
155.Sh RETURN VALUES
156Functions
157.Fn pmc_ncpu
158and
159.Fn pmc_npmc
160returns a positive integer if successful or -1 in case of an error.
161.Pp
162Functions
163.Fn pmc_capabilities ,
164.Fn pmc_cpuinfo ,
165.Fn pmc_pmcinfo
166and
167.Fn pmc_width
168return 0 if successful; otherwise the value -1 is returned and the
169global variable
170.Va errno
171is set to indicate the error.
172.Sh ERRORS
173A call to function
174.Fn pmc_capabilities
175may fail with the following errors:
176.Bl -tag -width Er
177.It Bq Er EINVAL
178The argument to the function was invalid.
179.El
180.Pp
181Calls to functions
182.Fn pmc_cpuinfo ,
183.Fn pmc_ncpu
184and
185.Fn pmc_npmc
186may fail with the following errors:
187.Bl -tag -width Er
188.It Bq Er ENXIO
189A prior call to
190.Fn pmc_init
191to initialize the PMC library had failed.
192.El
193.Pp
194A call to function
195.Fn pmc_pmcinfo
196may fail with the following errors:
197.Bl -tag -width Er
198.It Bq Er EINVAL
199The argument
200.Fa cpu
201specified a non-existent CPU.
202.It Bq Er ENXIO
203The argument
204.Fa cpu
205specified a disabled CPU.
206.El
207.Pp
208A call to function
209.Fn pmc_width
210may fail with the following errors:
211.Bl -tag -width Er
212.It Bq Er EINVAL
213The argument to the function was invalid.
214.El
215.Sh SEE ALSO
216.Xr pmc 3 ,
217.Xr pmc_allocate 3 ,
218.Xr pmc_get_driver_stats 3 ,
219.Xr pmc_name_of_capability 3 ,
220.Xr pmc_name_of_cputype 3 ,
221.Xr pmc_name_of_class 3 ,
222.Xr pmc_name_of_event 3 ,
223.Xr pmc_name_of_mode 3 ,
224.Xr hwpmc 4
225