1# Intel Hardware Performance Monitor Data Collection
2
3See chapters 18,19 of the Intel Architecture Software Developer's Manual.
4
5## IOCTLs
6
7Several ioctls are provided to control performance data collection.
8
9### *ioctl_cpuperf_get_properties*
10
11```
12ssize_t ioctl_cpuperf_get_properties(int fd, cpuperf_properties_t* props);
13```
14
15Return various aspects of PMU properties in |*props|.
16
17Returns 0 on success or a negative error code.
18
19### *ioctl_cpuperf_alloc_trace*
20
21```
22ssize_t ioctl_cpuperf_alloc_trace(int fd, const ioctl_cpuperf_alloc_t* alloc);
23```
24
25Allocate various resources needed to perform a trace.
26This must be called before staging a configuration and starting a trace.
27This must be called while tracing is stopped.
28
29Returns 0 on success or a negative error code.
30
31### *ioctl_cpuperf_free_trace*
32
33```
34ssize_t ioctl_cpuperf_free_trace(int fd);
35```
36
37Free all resources allocated by a preceding all to
38*ioctl_cpuperf_alloc_trace()*.
39This must be called while tracing is stopped.
40
41Returns 0 on success or a negative error code.
42
43### *ioctl_cpuperf_get_alloc*
44
45```
46ssize_t ioctl_cpuperf_get_alloc(int fd, cpuperf_alloc_t* alloc);
47```
48
49Fetch the trace configuration passed in to a preceding call to
50*ioctl_cpuperf_alloc_trace()*.
51
52Returns 0 on success or a negative error code.
53
54### *ioctl_cpuperf_stage_config*
55
56```
57ssize_t ioctl_cpuperf_stage_config(int fd, const cpuperf_config_t* config);
58```
59
60Configure data collection. |*config| specifies the events to collect
61and the rate at which to collect them.
62This must be called while tracing is stopped.
63
64Returns 0 on success or a negative error code.
65
66### *ioctl_cpuperf_get_config*
67
68```
69ssize_t ioctl_cpuperf_get_config(int fd, cpuperf_config_t* config);
70```
71
72Fetch the configuration passed in to a preceding call to
73*ioctl_cpuperf_stage_config()*.
74
75Returns 0 on success or a negative error code.
76
77### *ioctl_pmu_get_buffer_handle*
78
79```
80ssize_t ioctl_cpuperf_get_buffer_handle(
81    int fd, const ioctl_cpuperf_buffer_handle_req_t* rqst,
82    zx_handle_t* handle);
83```
84
85Fetch the handle of the VMO for the given descriptor.
86Each CPU is given a separate VMO and the descriptor is the cpu's number.
87This must be called while tracing is stopped.
88
89Returns 0 on success or a negative error code.
90
91### *ioctl_cpuperf_start*
92
93```
94ssize_t ioctl_cpuperf_start(int fd);
95```
96
97Start data collection.
98This must be called while tracing is stopped.
99
100Returns 0 on success or a negative error code.
101
102
103### *ioctl_cpuperf_stop*
104
105```
106ssize_t ioctl_cpuperf_stop(int fd);
107```
108
109Stop tracing and collect any remaining data from each cpu.
110This may be called even if tracing is already stopped.
111
112Returns 0 on success or a negative error code.
113
114## Usage
115
116Here's a sketch of typical usage:
117
1181) *ioctl_cpuperf_alloc_trace(fd, &alloc)*
1192) *ioctl_cpuperf_stage_config(fd, &config)*
1203) *ioctl_cpuperf_start(fd)*
1214) launch program one wishes to trace
1225) *ioctl_cpuperf_stop(fd)*
1236) fetch handles for each vmo, and process data
1247) *ioctl_cpuperf_free_trace(fd)* [this will free each buffer as well]
125