1 /* Copyright (C) 2014-2023 by Arm Limited. All rights reserved.
3 * Redistribution and use in source and binary forms, with or without
4 * modification, are permitted provided that the following conditions
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
14 * 3. Neither the name of the copyright holder nor the names of its
15 * contributors may be used to endorse or promote products derived from
16 * this software without specific prior written permission.
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
21 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
24 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
25 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
26 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
27 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 #ifndef STREAMLINE_ANNOTATE_H
32 #define STREAMLINE_ANNOTATE_H
35 * ANNOTATE_DEFINE Deprecated and no longer used
37 * ANNOTATE_SETUP Execute at the start of the program before other ANNOTATE macros are called
39 * For defining integer counters where the numeric value is in the range 0...1<<63-1:
41 * ANNOTATE_DELTA_COUNTER Define a delta counter
42 * ANNOTATE_ABSOLUTE_COUNTER Define an absolute counter
43 * ANNOTATE_COUNTER_VALUE Emit a counter value
45 * For defining fractional (float/double) counters:
47 * NB: The float value is converted to an integer value in the above range using some fixed multiplier, so for example
48 * to send a float value in the range 0.000...1.000, with 3-decimal places accuracy, use a modifier value of 1000.
49 * The float values will be converted to integers between 0 ... 1000.
51 * ANNOTATE_DELTA_COUNTER_SCALE Define a delta counter with scaling
52 * ANNOTATE_ABSOLUTE_COUNTER_SCALE Define an absolute counter with scaling
53 * ANNOTATE_COUNTER_VALUE_SCALE Emit a counter value with scaling
55 * For defining CAM views, which visualize multiple linked 'jobs' within a Gantt-like view:
57 * CAM_VIEW_NAME Name the custom activity map view
58 * CAM_TRACK Create a new custom activity map track
59 * CAM_JOB Add a new job to a CAM track, use gator_get_time() to obtain the time in nanoseconds
61 * For defining textual annotations:
63 * NB: Channels and groups are defined per thread. This means that if the same
64 * channel number is used on different threads they are in fact separate
65 * channels. A channel can belong to only one group per thread. This means
66 * channel 1 cannot be part of both group 1 and group 2 on the same thread.
68 * ANNOTATE_NAME_GROUP(group, str) Name a group
69 * ANNOTATE_NAME_CHANNEL(channel, group, str) Name a channel and link it to a group
70 * ANNOTATE(str) String annotation
71 * ANNOTATE_CHANNEL(channel, str) String annotation on a channel
72 * ANNOTATE_COLOR(color, str) String annotation with color
73 * ANNOTATE_CHANNEL_COLOR(channel, color, str) String annotation on a channel with color
74 * ANNOTATE_END() Terminate an annotation
75 * ANNOTATE_CHANNEL_END(channel) Terminate an annotation on a channel
77 * For sending image annotations:
79 * ANNOTATE_VISUAL(data, length, str) Image annotation with optional string
81 * For sending bookmark annotations:
83 * ANNOTATE_MARKER() Marker annotation
84 * ANNOTATE_MARKER_STR(str) Marker annotation with a string
85 * ANNOTATE_MARKER_COLOR(color) Marker annotation with a color
86 * ANNOTATE_MARKER_COLOR_STR(color, str) Marker annotation with a string and color
89 /* ESC character, hex RGB (little endian) */
90 #define ANNOTATE_RED 0x0000ff1b
91 #define ANNOTATE_BLUE 0xff00001b
92 #define ANNOTATE_GREEN 0x00ff001b
93 #define ANNOTATE_PURPLE 0xff00ff1b
94 #define ANNOTATE_YELLOW 0x00ffff1b
95 #define ANNOTATE_CYAN 0xffff001b
96 #define ANNOTATE_WHITE 0xffffff1b
97 #define ANNOTATE_LTGRAY 0xbbbbbb1b
98 #define ANNOTATE_DKGRAY 0x5555551b
99 #define ANNOTATE_BLACK 0x0000001b
101 #define ANNOTATE_COLOR_CYCLE 0x00000000
102 #define ANNOTATE_COLOR_T1 0x00000001
103 #define ANNOTATE_COLOR_T2 0x00000002
104 #define ANNOTATE_COLOR_T3 0x00000003
105 #define ANNOTATE_COLOR_T4 0x00000004
115 enum gator_annotate_counter_class
123 enum gator_annotate_display
125 ANNOTATE_AVERAGE = 1,
132 enum gator_annotate_series_composition
134 ANNOTATE_STACKED = 1,
139 enum gator_annotate_rendering_type
146 void gator_annotate_setup(void);
147 uint64_t gator_get_time(void);
148 void gator_annotate_fork_child(void);
149 void gator_annotate_flush(void);
150 void gator_annotate_str(uint32_t channel, const char* str);
151 void gator_annotate_color(uint32_t channel, uint32_t color, const char* str);
152 void gator_annotate_name_channel(uint32_t channel, uint32_t group, const char* str);
153 void gator_annotate_name_group(uint32_t group, const char* str);
154 void gator_annotate_visual(const void* data, uint32_t length, const char* str);
155 void gator_annotate_marker(const char* str);
156 void gator_annotate_marker_color(uint32_t color, const char* str);
157 void gator_annotate_counter(uint32_t id,
161 enum gator_annotate_counter_class counter_class,
162 enum gator_annotate_display display,
165 enum gator_annotate_series_composition series_composition,
166 enum gator_annotate_rendering_type rendering_type,
167 int average_selection,
170 size_t activity_count,
171 const char* const* activities,
172 const uint32_t* activity_colors,
175 const char* description);
176 void gator_annotate_counter_value(uint32_t core, uint32_t id, int64_t value);
177 void gator_annotate_counter_time_value(uint32_t core, uint32_t id, uint64_t time, int64_t value);
178 void gator_annotate_activity_switch(uint32_t core, uint32_t id, uint32_t activity, uint32_t tid);
179 void gator_cam_track(uint32_t view_uid, uint32_t track_uid, uint32_t parent_track, const char* name);
180 void gator_cam_job(uint32_t view_uid,
187 uint32_t primary_dependency,
188 size_t dependency_count,
189 const uint32_t* dependencies);
190 void gator_cam_job_start(uint32_t view_uid,
196 void gator_cam_job_set_dependencies(uint32_t view_uid,
199 uint32_t primary_dependency,
200 size_t dependency_count,
201 const uint32_t* dependencies);
202 void gator_cam_job_stop(uint32_t view_uid, uint32_t job_uid, uint64_t time);
203 void gator_cam_view_name(uint32_t view_uid, const char* name);
205 #define ANNOTATE_DEFINE extern int gator_annotate_unused
207 #define ANNOTATE_SETUP gator_annotate_setup()
209 #define ANNOTATE(str) gator_annotate_str(0, str)
210 #define ANNOTATE_CHANNEL(channel, str) gator_annotate_str(channel, str)
211 #define ANNOTATE_COLOR(color, str) gator_annotate_color(0, color, str)
212 #define ANNOTATE_CHANNEL_COLOR(channel, color, str) gator_annotate_color(channel, color, str)
213 #define ANNOTATE_END() gator_annotate_str(0, NULL)
214 #define ANNOTATE_CHANNEL_END(channel) gator_annotate_str(channel, NULL)
215 #define ANNOTATE_NAME_CHANNEL(channel, group, str) gator_annotate_name_channel(channel, group, str)
216 #define ANNOTATE_NAME_GROUP(group, str) gator_annotate_name_group(group, str)
218 #define ANNOTATE_VISUAL(data, length, str) gator_annotate_visual(data, length, str)
220 #define ANNOTATE_MARKER() gator_annotate_marker(NULL)
221 #define ANNOTATE_MARKER_STR(str) gator_annotate_marker(str)
222 #define ANNOTATE_MARKER_COLOR(color) gator_annotate_marker_color(color, NULL)
223 #define ANNOTATE_MARKER_COLOR_STR(color, str) gator_annotate_marker_color(color, str)
225 #define ANNOTATE_DELTA_COUNTER(id, title, name) \
226 gator_annotate_counter(id, \
231 ANNOTATE_ACCUMULATE, \
243 ANNOTATE_COLOR_CYCLE, \
245 #define ANNOTATE_ABSOLUTE_COUNTER(id, title, name) \
246 gator_annotate_counter(id, \
263 ANNOTATE_COLOR_CYCLE, \
265 #define ANNOTATE_COUNTER_VALUE(id, value) gator_annotate_counter_value(0, id, value)
267 #define ANNOTATE_DELTA_COUNTER_SCALE(id, title, name, modifier) \
268 gator_annotate_counter(id, \
273 ANNOTATE_ACCUMULATE, \
285 ANNOTATE_COLOR_CYCLE, \
287 #define ANNOTATE_ABSOLUTE_COUNTER_SCALE(id, title, name, modifier) \
288 gator_annotate_counter(id, \
305 ANNOTATE_COLOR_CYCLE, \
307 #define ANNOTATE_COUNTER_VALUE_SCALE(id, value, modifier) \
310 uint64_t __scaledvalue = (uint64_t)((value) * (modifier) + 0.5f); \
311 gator_annotate_counter_value(0, id, __scaledvalue); \
314 #define ANNOTATE_COUNTER_TIME_VALUE_SCALE(id, time, value, modifier) \
317 uint64_t __scaledvalue = (uint64_t)((value) * (modifier) + 0.5f); \
318 gator_annotate_counter_time_value(0, id, time, __scaledvalue); \
321 #define CAM_TRACK(view_uid, track_uid, parent_track, name) gator_cam_track(view_uid, track_uid, parent_track, name)
322 #define CAM_JOB(view_uid, job_uid, name, track, start_time, duration, color) \
323 gator_cam_job(view_uid, job_uid, name, track, start_time, duration, color, -1, 0, 0)
324 #define CAM_JOB_DEP(view_uid, job_uid, name, track, start_time, duration, color, dependency) \
326 uint32_t __dependency = dependency; \
327 gator_cam_job(view_uid, job_uid, name, track, start_time, duration, color, -1, 1, &__dependency); \
329 #define CAM_JOB_DEPS(view_uid, job_uid, name, track, start_time, duration, color, dependency_count, dependencies) \
330 gator_cam_job(view_uid, job_uid, name, track, start_time, duration, color, -1, dependency_count, dependencies)
331 #define CAM_JOB_START(view_uid, job_uid, name, track, time, color) \
332 gator_cam_job_start(view_uid, job_uid, name, track, time, color)
333 #define CAM_JOB_SET_DEP(view_uid, job_uid, time, dependency) \
335 uint32_t __dependency = dependency; \
336 gator_cam_job_set_dependencies(view_uid, job_uid, time, -1, 1, &__dependency); \
338 #define CAM_JOB_SET_DEPS(view_uid, job_uid, time, dependency_count, dependencies) \
339 gator_cam_job_set_dependencies(view_uid, job_uid, time, -1, dependency_count, dependencies)
340 #define CAM_JOB_STOP(view_uid, job_uid, time) gator_cam_job_stop(view_uid, job_uid, time)
341 #define CAM_VIEW_NAME(view_uid, name) gator_cam_view_name(view_uid, name)
347 #endif /* STREAMLINE_ANNOTATE_H */