PX4 Firmware
PX4 Autopilot Software http://px4.io
perf_counter.h
Go to the documentation of this file.
1 /****************************************************************************
2  *
3  * Copyright (C) 2012-2016 PX4 Development Team. All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in
13  * the documentation and/or other materials provided with the
14  * distribution.
15  * 3. Neither the name PX4 nor the names of its contributors may be
16  * used to endorse or promote products derived from this software
17  * without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
25  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
26  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
29  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30  * POSSIBILITY OF SUCH DAMAGE.
31  *
32  ****************************************************************************/
33 
34 /**
35  * @file perf_counter.h
36  * Performance measuring tools.
37  */
38 
39 #ifndef _SYSTEMLIB_PERF_COUNTER_H
40 #define _SYSTEMLIB_PERF_COUNTER_H value
41 
42 #include <stdint.h>
43 #include <px4_platform_common/defines.h>
44 
45 #define LATENCY_BUCKET_COUNT 8
46 
47 extern const uint16_t latency_bucket_count;
48 extern const uint16_t latency_buckets[LATENCY_BUCKET_COUNT];
49 extern uint32_t latency_counters[LATENCY_BUCKET_COUNT + 1];
50 
51 /**
52  * Counter types.
53  */
55  PC_COUNT, /**< count the number of times an event occurs */
56  PC_ELAPSED, /**< measure the time elapsed performing an event */
57  PC_INTERVAL /**< measure the interval between instances of an event */
58 };
59 
60 struct perf_ctr_header;
62 
64 
65 /**
66  * Create a new local counter.
67  *
68  * @param type The type of the new counter.
69  * @param name The counter name.
70  * @return Handle for the new counter, or NULL if a counter
71  * could not be allocated.
72  */
73 #ifndef perf_alloc // perf_alloc might be defined to be NULL in src/modules/px4iofirmware/px4io.h
74 __EXPORT extern perf_counter_t perf_alloc(enum perf_counter_type type, const char *name);
75 #endif
76 
77 /**
78  * Get the reference to an existing counter or create a new one if it does not exist.
79  *
80  * @param type The type of the counter.
81  * @param name The counter name.
82  * @return Handle for the counter, or NULL if a counter
83  * could not be allocated.
84  */
85 __EXPORT extern perf_counter_t perf_alloc_once(enum perf_counter_type type, const char *name);
86 
87 /**
88  * Free a counter.
89  *
90  * @param handle The performance counter's handle.
91  */
92 __EXPORT extern void perf_free(perf_counter_t handle);
93 
94 /**
95  * Count a performance event.
96  *
97  * This call only affects counters that take single events; PC_COUNT, PC_INTERVAL etc.
98  *
99  * @param handle The handle returned from perf_alloc.
100  */
101 __EXPORT extern void perf_count(perf_counter_t handle);
102 
103 /**
104  * Begin a performance event.
105  *
106  * This call applies to counters that operate over ranges of time; PC_ELAPSED etc.
107  *
108  * @param handle The handle returned from perf_alloc.
109  */
110 __EXPORT extern void perf_begin(perf_counter_t handle);
111 
112 /**
113  * End a performance event.
114  *
115  * This call applies to counters that operate over ranges of time; PC_ELAPSED etc.
116  * If a call is made without a corresponding perf_begin call, or if perf_cancel
117  * has been called subsequently, no change is made to the counter.
118  *
119  * @param handle The handle returned from perf_alloc.
120  */
121 __EXPORT extern void perf_end(perf_counter_t handle);
122 
123 /**
124  * Register a measurement
125  *
126  * This call applies to counters that operate over ranges of time; PC_ELAPSED etc.
127  * If a call is made without a corresponding perf_begin call. It sets the
128  * value provided as argument as a new measurement.
129  *
130  * @param handle The handle returned from perf_alloc.
131  * @param elapsed The time elapsed. Negative values lead to incrementing the overrun counter.
132  */
133 __EXPORT extern void perf_set_elapsed(perf_counter_t handle, int64_t elapsed);
134 
135 /**
136  * Set a counter
137  *
138  * This call applies to counters of type PC_COUNT. It (re-)sets the count.
139  *
140  * @param handle The handle returned from perf_alloc.
141  * @param count The counter value to be set.
142  */
143 __EXPORT extern void perf_set_count(perf_counter_t handle, uint64_t count);
144 
145 /**
146  * Cancel a performance event.
147  *
148  * This call applies to counters that operate over ranges of time; PC_ELAPSED etc.
149  * It reverts the effect of a previous perf_begin.
150  *
151  * @param handle The handle returned from perf_alloc.
152  */
153 __EXPORT extern void perf_cancel(perf_counter_t handle);
154 
155 /**
156  * Reset a performance counter.
157  *
158  * This call resets performance counter to initial state
159  *
160  * @param handle The handle returned from perf_alloc.
161  */
162 __EXPORT extern void perf_reset(perf_counter_t handle);
163 
164 /**
165  * Print one performance counter to stdout
166  *
167  * @param handle The counter to print.
168  */
169 __EXPORT extern void perf_print_counter(perf_counter_t handle);
170 
171 /**
172  * Print one performance counter to a fd.
173  *
174  * @param fd File descriptor to print to - e.g. 0 for stdout
175  * @param handle The counter to print.
176  */
177 __EXPORT extern void perf_print_counter_fd(int fd, perf_counter_t handle);
178 
179 /**
180  * Print one performance counter to a buffer.
181  *
182  * @param buffer buffer to write to
183  * @param length buffer length
184  * @param handle The counter to print.
185  * @param return number of bytes written
186  */
187 __EXPORT extern int perf_print_counter_buffer(char *buffer, int length, perf_counter_t handle);
188 
189 /**
190  * Print all of the performance counters.
191  *
192  * @param fd File descriptor to print to - e.g. 0 for stdout
193  */
194 __EXPORT extern void perf_print_all(int fd);
195 
196 
197 typedef void (*perf_callback)(perf_counter_t handle, void *user);
198 
199 /**
200  * Iterate over all performance counters using a callback.
201  *
202  * Caution: This will aquire the mutex, so do not call any other perf_* method
203  * that aquire the mutex as well from the callback (If this is needed, configure
204  * the mutex to be reentrant).
205  *
206  * @param cb callback method
207  * @param user custom argument for the callback
208  */
209 __EXPORT extern void perf_iterate_all(perf_callback cb, void *user);
210 
211 /**
212  * Print hrt latency counters.
213  *
214  * @param fd File descriptor to print to - e.g. 0 for stdout
215  */
216 __EXPORT extern void perf_print_latency(int fd);
217 
218 /**
219  * Reset all of the performance counters.
220  */
221 __EXPORT extern void perf_reset_all(void);
222 
223 /**
224  * Return current event_count
225  *
226  * @param handle The counter returned from perf_alloc.
227  * @return event_count
228  */
229 __EXPORT extern uint64_t perf_event_count(perf_counter_t handle);
230 
232 
233 #endif
#define LATENCY_BUCKET_COUNT
Definition: perf_counter.h:45
measure the time elapsed performing an event
Definition: perf_counter.h:56
#define __END_DECLS
Definition: visibility.h:59
__EXPORT void perf_print_counter_fd(int fd, perf_counter_t handle)
Print one performance counter to a fd.
__EXPORT void perf_print_latency(int fd)
Print hrt latency counters.
__EXPORT void perf_set_count(perf_counter_t handle, uint64_t count)
Set a counter.
perf_counter_type
Counter types.
Definition: perf_counter.h:54
__EXPORT void perf_end(perf_counter_t handle)
End a performance event.
Definition: I2C.hpp:51
__EXPORT void perf_print_counter(perf_counter_t handle)
Print one performance counter to stdout.
count the number of times an event occurs
Definition: perf_counter.h:55
const uint16_t latency_bucket_count
__EXPORT void perf_reset_all(void)
Reset all of the performance counters.
void(* perf_callback)(perf_counter_t handle, void *user)
Definition: perf_counter.h:197
Header common to all counters.
__EXPORT void perf_iterate_all(perf_callback cb, void *user)
Iterate over all performance counters using a callback.
#define __BEGIN_DECLS
Definition: visibility.h:58
enum perf_counter_type type
counter type
uint32_t latency_counters[LATENCY_BUCKET_COUNT+1]
__EXPORT uint64_t perf_event_count(perf_counter_t handle)
Return current event_count.
int fd
Definition: dataman.cpp:146
__EXPORT int perf_print_counter_buffer(char *buffer, int length, perf_counter_t handle)
Print one performance counter to a buffer.
__EXPORT void perf_cancel(perf_counter_t handle)
Cancel a performance event.
const char * name
Definition: tests_main.c:58
__EXPORT void perf_begin(perf_counter_t handle)
Begin a performance event.
struct perf_ctr_header * perf_counter_t
Definition: perf_counter.h:61
__BEGIN_DECLS __EXPORT perf_counter_t perf_alloc(enum perf_counter_type type, const char *name)
Create a new local counter.
__EXPORT perf_counter_t perf_alloc_once(enum perf_counter_type type, const char *name)
Get the reference to an existing counter or create a new one if it does not exist.
__EXPORT void perf_set_elapsed(perf_counter_t handle, int64_t elapsed)
Register a measurement.
__EXPORT void perf_count(perf_counter_t handle)
Count a performance event.
__EXPORT void perf_print_all(int fd)
Print all of the performance counters.
__EXPORT void perf_reset(perf_counter_t handle)
Reset a performance counter.
measure the interval between instances of an event
Definition: perf_counter.h:57
__EXPORT void perf_free(perf_counter_t handle)
Free a counter.
const uint16_t latency_buckets[LATENCY_BUCKET_COUNT]