dali/internal/trace/streamline/streamline_annotate.h

   1 /* Copyright (C) 2014-2023 by Arm Limited. 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  *
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  *
  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.
  13  *
  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.
  17  *
  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.
  29  */
  30
  31 #ifndef STREAMLINE_ANNOTATE_H
  32 #define STREAMLINE_ANNOTATE_H
  33
  34 /*
  35  *  ANNOTATE_DEFINE                              Deprecated and no longer used
  36  *
  37  *  ANNOTATE_SETUP                               Execute at the start of the program before other ANNOTATE macros are called
  38  *
  39  *  For defining integer counters where the numeric value is in the range 0...1<<63-1:
  40  *
  41  *  ANNOTATE_DELTA_COUNTER                       Define a delta counter
  42  *  ANNOTATE_ABSOLUTE_COUNTER                    Define an absolute counter
  43  *  ANNOTATE_COUNTER_VALUE                       Emit a counter value
  44  *
  45  *  For defining fractional (float/double) counters:
  46  *
  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.
  50  *
  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
  54  *
  55  *  For defining CAM views, which visualize multiple linked 'jobs' within a Gantt-like view:
  56  *
  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
  60  *
  61  *  For defining textual annotations:
  62  *
  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.
  67  *
  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
  76  *
  77  *  For sending image annotations:
  78  *
  79  *  ANNOTATE_VISUAL(data, length, str)           Image annotation with optional string
  80  *
  81  *  For sending bookmark annotations:
  82  *
  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
  87  */
  88
  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
 100
 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
 106
 107 #include <stddef.h>
 108 #include <stdint.h>
 109
 110 #ifdef __cplusplus
 111 extern "C"
 112 {
 113 #endif
 114
 115   enum gator_annotate_counter_class
 116   {
 117     ANNOTATE_DELTA = 1,
 118     ANNOTATE_ABSOLUTE,
 119     ANNOTATE_ACTIVITY,
 120     ANNOTATE_INCIDENT
 121   };
 122
 123   enum gator_annotate_display
 124   {
 125     ANNOTATE_AVERAGE = 1,
 126     ANNOTATE_ACCUMULATE,
 127     ANNOTATE_HERTZ,
 128     ANNOTATE_MAXIMUM,
 129     ANNOTATE_MINIMUM
 130   };
 131
 132   enum gator_annotate_series_composition
 133   {
 134     ANNOTATE_STACKED = 1,
 135     ANNOTATE_OVERLAY,
 136     ANNOTATE_LOG10
 137   };
 138
 139   enum gator_annotate_rendering_type
 140   {
 141     ANNOTATE_FILL = 1,
 142     ANNOTATE_LINE,
 143     ANNOTATE_BAR
 144   };
 145
 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,
 158                                   const char*                            title,
 159                                   const char*                            name,
 160                                   int                                    per_cpu,
 161                                   enum gator_annotate_counter_class      counter_class,
 162                                   enum gator_annotate_display            display,
 163                                   const char*                            units,
 164                                   uint32_t                               modifier,
 165                                   enum gator_annotate_series_composition series_composition,
 166                                   enum gator_annotate_rendering_type     rendering_type,
 167                                   int                                    average_selection,
 168                                   int                                    average_cores,
 169                                   int                                    percentage,
 170                                   size_t                                 activity_count,
 171                                   const char* const*                     activities,
 172                                   const uint32_t*                        activity_colors,
 173                                   uint32_t                               cores,
 174                                   uint32_t                               color,
 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,
 181                          uint32_t        job_uid,
 182                          const char*     name,
 183                          uint32_t        track,
 184                          uint64_t        start_time,
 185                          uint64_t        duration,
 186                          uint32_t        color,
 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,
 191                                uint32_t    job_uid,
 192                                const char* name,
 193                                uint32_t    track,
 194                                uint64_t    time,
 195                                uint32_t    color);
 196   void     gator_cam_job_set_dependencies(uint32_t        view_uid,
 197                                           uint32_t        job_uid,
 198                                           uint64_t        time,
 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);
 204
 205 #define ANNOTATE_DEFINE extern int gator_annotate_unused
 206
 207 #define ANNOTATE_SETUP gator_annotate_setup()
 208
 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)
 217
 218 #define ANNOTATE_VISUAL(data, length, str) gator_annotate_visual(data, length, str)
 219
 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)
 224
 225 #define ANNOTATE_DELTA_COUNTER(id, title, name) \
 226   gator_annotate_counter(id,                    \
 227                          title,                 \
 228                          name,                  \
 229                          0,                     \
 230                          ANNOTATE_DELTA,        \
 231                          ANNOTATE_ACCUMULATE,   \
 232                          NULL,                  \
 233                          1,                     \
 234                          ANNOTATE_STACKED,      \
 235                          ANNOTATE_FILL,         \
 236                          0,                     \
 237                          0,                     \
 238                          0,                     \
 239                          0,                     \
 240                          NULL,                  \
 241                          NULL,                  \
 242                          0,                     \
 243                          ANNOTATE_COLOR_CYCLE,  \
 244                          NULL)
 245 #define ANNOTATE_ABSOLUTE_COUNTER(id, title, name) \
 246   gator_annotate_counter(id,                       \
 247                          title,                    \
 248                          name,                     \
 249                          0,                        \
 250                          ANNOTATE_ABSOLUTE,        \
 251                          ANNOTATE_MAXIMUM,         \
 252                          NULL,                     \
 253                          1,                        \
 254                          ANNOTATE_STACKED,         \
 255                          ANNOTATE_FILL,            \
 256                          0,                        \
 257                          0,                        \
 258                          0,                        \
 259                          0,                        \
 260                          NULL,                     \
 261                          NULL,                     \
 262                          0,                        \
 263                          ANNOTATE_COLOR_CYCLE,     \
 264                          NULL)
 265 #define ANNOTATE_COUNTER_VALUE(id, value) gator_annotate_counter_value(0, id, value)
 266
 267 #define ANNOTATE_DELTA_COUNTER_SCALE(id, title, name, modifier) \
 268   gator_annotate_counter(id,                                    \
 269                          title,                                 \
 270                          name,                                  \
 271                          0,                                     \
 272                          ANNOTATE_DELTA,                        \
 273                          ANNOTATE_ACCUMULATE,                   \
 274                          NULL,                                  \
 275                          modifier,                              \
 276                          ANNOTATE_STACKED,                      \
 277                          ANNOTATE_FILL,                         \
 278                          0,                                     \
 279                          0,                                     \
 280                          0,                                     \
 281                          0,                                     \
 282                          NULL,                                  \
 283                          NULL,                                  \
 284                          0,                                     \
 285                          ANNOTATE_COLOR_CYCLE,                  \
 286                          NULL)
 287 #define ANNOTATE_ABSOLUTE_COUNTER_SCALE(id, title, name, modifier) \
 288   gator_annotate_counter(id,                                       \
 289                          title,                                    \
 290                          name,                                     \
 291                          0,                                        \
 292                          ANNOTATE_ABSOLUTE,                        \
 293                          ANNOTATE_MAXIMUM,                         \
 294                          NULL,                                     \
 295                          modifier,                                 \
 296                          ANNOTATE_STACKED,                         \
 297                          ANNOTATE_FILL,                            \
 298                          0,                                        \
 299                          0,                                        \
 300                          0,                                        \
 301                          0,                                        \
 302                          NULL,                                     \
 303                          NULL,                                     \
 304                          0,                                        \
 305                          ANNOTATE_COLOR_CYCLE,                     \
 306                          NULL)
 307 #define ANNOTATE_COUNTER_VALUE_SCALE(id, value, modifier)             \
 308   do                                                                  \
 309   {                                                                   \
 310     uint64_t __scaledvalue = (uint64_t)((value) * (modifier) + 0.5f); \
 311     gator_annotate_counter_value(0, id, __scaledvalue);               \
 312   } while(0)
 313
 314 #define ANNOTATE_COUNTER_TIME_VALUE_SCALE(id, time, value, modifier)  \
 315   do                                                                  \
 316   {                                                                   \
 317     uint64_t __scaledvalue = (uint64_t)((value) * (modifier) + 0.5f); \
 318     gator_annotate_counter_time_value(0, id, time, __scaledvalue);    \
 319   } while(0)
 320
 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)          \
 325   {                                                                                                   \
 326     uint32_t __dependency = dependency;                                                               \
 327     gator_cam_job(view_uid, job_uid, name, track, start_time, duration, color, -1, 1, &__dependency); \
 328   }
 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)                       \
 334   {                                                                                \
 335     uint32_t __dependency = dependency;                                            \
 336     gator_cam_job_set_dependencies(view_uid, job_uid, time, -1, 1, &__dependency); \
 337   }
 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)
 342
 343 #ifdef __cplusplus
 344 }
 345 #endif
 346
 347 #endif /* STREAMLINE_ANNOTATE_H */