dali/integration-api/debug.h

   1 #ifndef DALI_INTEGRATION_DEBUG_H
   2 #define DALI_INTEGRATION_DEBUG_H
   3
   4 /*
   5  * Copyright (c) 2023 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <stdint.h>
  23 #include <cstring>
  24 #include <iostream>
  25 #include <list>
  26 #include <sstream>
  27 #include <string>
  28
  29 #include <dali/public-api/common/vector-wrapper.h>
  30 #include <dali/public-api/object/property-map.h>
  31
  32 // INTERNAL INCLUDES
  33 #include <dali/public-api/common/dali-common.h>
  34
  35 // Using Debug namespace alias shortens the log usage significantly
  36 namespace Dali
  37 {
  38 namespace Integration
  39 {
  40 namespace Log
  41 {
  42 }
  43 } // namespace Integration
  44 } // namespace Dali
  45 namespace Debug = Dali::Integration::Log;
  46
  47 namespace Dali
  48 {
  49 struct Vector2;
  50 struct Vector3;
  51 struct Vector4;
  52 class Matrix3;
  53 class Matrix;
  54 class Quaternion;
  55
  56 #if defined(DEBUG_ENABLED)
  57
  58 // Less opaque types for debugger
  59 typedef std::vector<Dali::Property::Value> DebugPropertyValueArray;
  60 using DebugIndexValuePair       = std::pair<Property::Index, Property::Value>;
  61 using DebugStringValueContainer = std::vector<Dali::StringValuePair>;
  62 using DebugIndexValueContainer  = std::vector<DebugIndexValuePair>;
  63
  64 struct DebugPropertyValueMap
  65 {
  66   DebugStringValueContainer stringValues;
  67   DebugIndexValueContainer  intValues;
  68 };
  69
  70 // Fake globals for gdb typedefs
  71 extern Dali::DebugPropertyValueArray gValueArray;
  72 extern Dali::DebugPropertyValueMap   gValueMap;
  73
  74 #endif
  75
  76 namespace Integration
  77 {
  78 namespace Log
  79 {
  80 enum DebugPriority
  81 {
  82   DEBUG,
  83   INFO,
  84   WARNING,
  85   ERROR
  86 };
  87
  88 /**
  89  * Used by logging macros to log a message
  90  * @param level debug level
  91  * @param format string format
  92  */
  93 DALI_CORE_API void LogMessage(enum DebugPriority level, const char* format, ...);
  94
  95 /**
  96  * Prefix macros to sync with dlog logger format
  97  * __MODULE__ macro also defined at dlog-internal.h
  98  */
  99 #ifndef DALI_LOG_FORMAT_PREFIX
 100 #ifndef __MODULE__
 101 #define __MODULE__ (std::strrchr(__FILE__, '/') ? std::strrchr(__FILE__, '/') + 1 : __FILE__)
 102 #endif
 103 #define DALI_LOG_FORMAT_PREFIX "%s: %s(%d) > "
 104 #define DALI_LOG_FORMAT_PREFIX_ARGS __MODULE__, __func__, __LINE__
 105 #endif
 106
 107 /**
 108  * Global logging macros to log a message along with function/class name and line
 109  * @param level debug level
 110  * @param format string format
 111  */
 112 #define LogMessageWithFunctionLine(level, format, ...)                            \
 113   LogMessage(level,                                                               \
 114              (std::string(DALI_LOG_FORMAT_PREFIX) + std::string(format)).c_str(), \
 115              DALI_LOG_FORMAT_PREFIX_ARGS,                                         \
 116              ##__VA_ARGS__)
 117
 118 /**
 119  * typedef for the logging function.
 120  */
 121 using LogFunction = void (*)(DebugPriority, std::string&);
 122
 123 /**
 124  * A log function has to be installed for every thread that wants to use logging.
 125  * This should be done by the adaptor.
 126  * The log function can be different for each thread.
 127  * @param logFunction the log function to install
 128  * @param logOpts the log options to save in thread
 129  */
 130 DALI_CORE_API void InstallLogFunction(const LogFunction& logFunction);
 131
 132 /**
 133  * A log function has to be uninstalled for every thread that wants to use logging.
 134  * The log function can be different for each thread.
 135  */
 136 DALI_CORE_API void UninstallLogFunction();
 137
 138 /********************************************************************************
 139  *                            Error/Warning  macros.                            *
 140  ********************************************************************************/
 141
 142 /**
 143  * Provides unfiltered logging for global error level messages
 144  */
 145 #define DALI_LOG_ERROR(format, ...) Dali::Integration::Log::LogMessageWithFunctionLine(Dali::Integration::Log::ERROR, format, ##__VA_ARGS__)
 146
 147 #define DALI_LOG_ERROR_NOFN(format, ...) Dali::Integration::Log::LogMessage(Dali::Integration::Log::ERROR, format, ##__VA_ARGS__)
 148
 149 #define DALI_LOG_WARNING_NOFN(format, ...) Dali::Integration::Log::LogMessage(Dali::Integration::Log::WARNING, format, ##__VA_ARGS__)
 150
 151 /**
 152  * Provides unfiltered logging for fps monitor
 153  */
 154 #define DALI_LOG_FPS(format, ...) Dali::Integration::Log::LogMessage(Dali::Integration::Log::INFO, format, ##__VA_ARGS__)
 155
 156 /**
 157  * Provides unfiltered logging for update status
 158  */
 159 #define DALI_LOG_UPDATE_STATUS(format, ...) Dali::Integration::Log::LogMessage(Dali::Integration::Log::INFO, format, ##__VA_ARGS__)
 160
 161 /**
 162  * Provides unfiltered logging for render information
 163  */
 164 #define DALI_LOG_RENDER_INFO(format, ...) Dali::Integration::Log::LogMessage(Dali::Integration::Log::INFO, format, ##__VA_ARGS__)
 165
 166 /**
 167  * Provides unfiltered logging for release
 168  */
 169 #define DALI_LOG_RELEASE_INFO(format, ...) Dali::Integration::Log::LogMessageWithFunctionLine(Dali::Integration::Log::INFO, format, ##__VA_ARGS__)
 170
 171 /**
 172  * Provides unfiltered logging for debuf information
 173  */
 174 #define DALI_LOG_DEBUG_INFO(format, ...) Dali::Integration::Log::LogMessageWithFunctionLine(Dali::Integration::Log::DEBUG, format, ##__VA_ARGS__)
 175
 176 #ifdef DEBUG_ENABLED
 177
 178 /**
 179  * Provides unfiltered logging for global warning level messages
 180  */
 181 #define DALI_LOG_WARNING(format, ...) Dali::Integration::Log::LogMessageWithFunctionLine(Dali::Integration::Log::WARNING, format, ##__VA_ARGS__)
 182
 183 #else // DEBUG_ENABLED
 184
 185 // Don't warn on release build
 186 #define DALI_LOG_WARNING(format, ...)
 187
 188 #endif
 189
 190 /********************************************************************************
 191  *                                    Filter                                    *
 192  ********************************************************************************/
 193
 194 #ifdef DEBUG_ENABLED
 195
 196 /**
 197  * Enumeration of logging levels.
 198  * Used by the filters to provide multiple log levels.
 199  * In general, the higher the value, the more debug is available for that filter.
 200  */
 201 enum LogLevel
 202 {
 203   NoLogging = 0,
 204   Concise   = 1,
 205   General   = 2,
 206   Verbose   = 3
 207 };
 208
 209 /**
 210  * The Filter object is used by the DALI_LOG_INFO macro and others to determine if the logging
 211  * should take place, and routes the logging via the platform abstraction's LogMessage.
 212  *
 213  * It provides a logging level. If this is set to zero, then DALI_LOG_INFO won't log anything.
 214  * It provides the ability to turn tracing on or off.
 215  *
 216  */
 217 class DALI_CORE_API Filter
 218 {
 219 public:
 220   /**
 221    * Test if the filter is enabled for the given logging level
 222    * @param[in] level - the level to test.
 223    * @return true if this level of logging is enabled.
 224    */
 225   bool IsEnabledFor(LogLevel level)
 226   {
 227     return level != Debug::NoLogging && level <= mLoggingLevel;
 228   }
 229
 230   /**
 231    * Test if trace is enabled for this filter.
 232    * @return true if trace is enabled;
 233    */
 234   bool IsTraceEnabled()
 235   {
 236     return mTraceEnabled;
 237   }
 238
 239   /**
 240    * Enable tracing on this filter.
 241    */
 242   void EnableTrace()
 243   {
 244     mTraceEnabled = true;
 245   }
 246
 247   /**
 248    * Disable tracing on this filter.
 249    */
 250   void DisableTrace()
 251   {
 252     mTraceEnabled = false;
 253   }
 254
 255   /**
 256    * Set the log level for this filter. Setting to a higher value than Debug::General also
 257    * enables General;
 258    */
 259   void SetLogLevel(LogLevel level)
 260   {
 261     mLoggingLevel = level;
 262   }
 263
 264   /**
 265    * Perform the logging for this filter.
 266    */
 267   void Log(LogLevel level, const char* format, ...);
 268
 269   /**
 270    * Create a new filter whose debug level and trace can be modified through the use of an
 271    * environment variable.
 272    *
 273    * @param[in] level The default log level
 274    * @param[in] trace The default trace level. If true, function tracing is on.
 275    * @param[in] environmentVariableName The environment variable name used in order to change the
 276    *                                    log level or trace.
 277    *
 278    * @info To modify logg level/trace at runtime, you can should define your filter as shown below:
 279    *
 280    * @code
 281    * Debug::Filter* filter = Debug::Filter::New( Debug::NoLogging, false, "FILTER_ENV" );
 282    * @endcode
 283    *
 284    * And to use it when running an executable:
 285    * @code
 286    * FILTER_ENV=3 dali-demo        // LogLevel Verbose,   Trace using default
 287    * FILTER_ENV=1,true dali-demo   // LogLevel Concise,   Trace ON
 288    * FILTER_ENV=2,false dali-demo  // LogLevel General,   Trace OFF
 289    * FILTER_ENV=0,true dali-demo   // LogLevel NoLogging, Trace ON
 290    * @endcode
 291    */
 292   static Filter* New(LogLevel level, bool trace, const char* environmentVariableName);
 293
 294   /**
 295    * Enable trace on all filters.
 296    */
 297   static void EnableGlobalTrace();
 298
 299   /**
 300    * Disable trace on all filters.
 301    */
 302   static void DisableGlobalTrace();
 303
 304   /**
 305    * Set log level for all filters.
 306    *
 307    * @param[in] level The log level
 308    */
 309   static void SetGlobalLogLevel(LogLevel level);
 310
 311 private:
 312   /**
 313    * Constructor.
 314    * @param[in] level - the highest log level.
 315    * @param[in] trace - whether this filter allows tracing.
 316    */
 317   Filter(LogLevel level, bool trace)
 318   : mLoggingLevel(level),
 319     mTraceEnabled(trace),
 320     mNesting(0)
 321   {
 322   }
 323
 324 public:
 325   // High level filters. If these filters are too broad for your current requirement, then
 326   // you can add a filter to your own class or source file. If you do, use Filter::New()
 327   // to tell this class about it.
 328
 329   static Filter* gRender;
 330   static Filter* gResource;
 331   static Filter* gGLResource;
 332   static Filter* gObject;
 333   static Filter* gImage;
 334   static Filter* gModel;
 335   static Filter* gNode;
 336   static Filter* gElement;
 337   static Filter* gActor;
 338   static Filter* gShader;
 339
 340 private:
 341   LogLevel mLoggingLevel;
 342   bool     mTraceEnabled;
 343
 344 public:
 345   int mNesting;
 346 };
 347
 348 #define DALI_LOG_FILTER_SET_LEVEL(filter, level) filter->SetLogLevel(level)
 349 #define DALI_LOG_FILTER_ENABLE_TRACE(filter) filter->EnableTrace()
 350 #define DALI_LOG_FILTER_DISABLE_TRACE(filter) filter->DisableTrace()
 351
 352 #else
 353
 354 #define DALI_LOG_FILTER_SET_LEVEL(filter, level)
 355 #define DALI_LOG_FILTER_ENABLE_TRACE(filter)
 356 #define DALI_LOG_FILTER_DISABLE_TRACE(filter)
 357
 358 #endif
 359
 360 /********************************************************************************
 361  *                            General Logging macros                            *
 362  ********************************************************************************/
 363
 364 #ifdef DEBUG_ENABLED
 365
 366 #define DALI_LOG_INFO(filter, level, format, ...)                                    \
 367   if(filter && filter->IsEnabledFor(level))                                          \
 368   {                                                                                  \
 369     filter->Log(level,                                                               \
 370                 (std::string(DALI_LOG_FORMAT_PREFIX) + std::string(format)).c_str(), \
 371                 DALI_LOG_FORMAT_PREFIX_ARGS,                                         \
 372                 ##__VA_ARGS__);                                                      \
 373   }
 374
 375 #define DALI_LOG_STREAM(filter, level, stream) \
 376   if(filter && filter->IsEnabledFor(level))    \
 377   {                                            \
 378     std::ostringstream o;                      \
 379     o << stream << std::endl;                  \
 380     filter->Log(level, "%s", o.str().c_str()); \
 381   }
 382
 383 #else // DEBUG_ENABLED
 384
 385 #define DALI_LOG_INFO(filter, level, format, ...)
 386 #define DALI_LOG_STREAM(filter, level, stream)
 387
 388 #endif // DEBUG_ENABLED
 389
 390 /********************************************************************************
 391  *                                  Trace Macros                                *
 392  ********************************************************************************/
 393
 394 /*
 395  * These macros allow the instrumentation of methods. These translate into calls
 396  * to LogMessage(INFO).
 397  */
 398
 399 #ifdef DEBUG_ENABLED
 400
 401 class DALI_CORE_API TraceObj
 402 {
 403 public:
 404   TraceObj(Filter* filter, const char* fmt, ...);
 405   ~TraceObj();
 406
 407 public:
 408   std::string mMessage;
 409   Filter*     mFilter;
 410 };
 411
 412 #define DALI_LOG_TRACE_METHOD_FMT(filter, format, ...) \
 413   Dali::Integration::Log::TraceObj debugTraceObj(filter, "%s: " format, ASSERT_LOCATION, ##__VA_ARGS__)
 414
 415 #define DALI_LOG_TRACE_METHOD(filter) \
 416   Dali::Integration::Log::TraceObj debugTraceObj(filter, ASSERT_LOCATION)
 417
 418 #else // DEBUG_ENABLED
 419
 420 #define DALI_LOG_TRACE_METHOD_FMT(filter, format, ...)
 421 #define DALI_LOG_TRACE_METHOD(filter)
 422
 423 #endif
 424
 425 /********************************************************************************
 426  *                              Extra object debug                              *
 427  ********************************************************************************/
 428
 429 #ifdef DEBUG_ENABLED
 430
 431 /**
 432  * Warning, this macro changes the current scope, so should usually be put at the
 433  * end of the class definition.
 434  *
 435  * Suggest that the value is usually set to the object's name.
 436  * Warning - this will increase the size of the object for a debug build.
 437  */
 438 #define DALI_LOG_OBJECT_STRING_DECLARATION \
 439 public:                                    \
 440   std::string mDebugString;
 441
 442 /**
 443  * Print all the actor tree names
 444  **/
 445 #define DALI_LOG_ACTOR_TREE(node)                                  \
 446   {                                                                \
 447     std::stringstream branch;                                      \
 448     Node*             tempNode = node;                             \
 449     while(tempNode)                                                \
 450     {                                                              \
 451       branch << "<" << tempNode->mDebugString << ">::";            \
 452       tempNode = tempNode->GetParent();                            \
 453     }                                                              \
 454     DALI_LOG_ERROR_NOFN("Actor tree: %s\n", branch.str().c_str()); \
 455   }
 456
 457 /**
 458  * Allows one object to set another object's debug string
 459  */
 460 #define DALI_LOG_SET_OBJECT_STRING(object, string) (object->mDebugString = string)
 461
 462 /**
 463  * Allows one object to set another object's std::string easily
 464  */
 465 #define DALI_LOG_FMT_OBJECT_STRING(object, fmt, ...) (object->mDebugString = FormatToString(fmt, ##__VA_ARGS__))
 466
 467 /**
 468  * Allows one object to get another object's debug string
 469  */
 470 #define DALI_LOG_GET_OBJECT_STRING(object) (object->mDebugString)
 471
 472 /**
 473  * Get the C string (for use in formatted logging)
 474  */
 475 #define DALI_LOG_GET_OBJECT_C_STR(object) (object->mDebugString.c_str())
 476
 477 /**
 478  * Filtered logging of the object's debug string
 479  */
 480 #define DALI_LOG_OBJECT(filter, object) DALI_LOG_INFO(filter, Debug::General, object->mDebugString)
 481
 482 #else // DEBUG_ENABLED
 483
 484 #define DALI_LOG_OBJECT_STRING_DECLARATION
 485 #define DALI_LOG_ACTOR_TREE(node)
 486 #define DALI_LOG_SET_OBJECT_STRING(object, string)
 487 #define DALI_LOG_FMT_OBJECT_STRING(object, fmt, ...)
 488 #define DALI_LOG_GET_OBJECT_STRING(object)
 489 #define DALI_LOG_GET_OBJECT_C_STR(object) ""
 490 #define DALI_LOG_OBJECT(filter, object)
 491
 492 #endif
 493
 494 /********************************************************************************
 495  *                            Time instrumentation                              *
 496  ********************************************************************************/
 497 #if defined(DEBUG_ENABLED)
 498
 499 /**
 500   * @brief Get the monotonic time since the clock's epoch.
 501   *
 502   * @param[out]  timeInNanoseconds  The time in nanoseconds since the reference point.
 503   *
 504   * @note The maximum value timeInNanoseconds can hold is 0xFFFFFFFFFFFFFFFF which is 1.844674407e+19. Therefore, this can overflow after approximately 584 years.
 505   */
 506 void GetNanoseconds(uint64_t& timeInNanoseconds);
 507
 508 #define DALI_LOG_TIMER_START(timeVariable) \
 509   uint64_t timeVariable##1;                \
 510   Debug::GetNanoseconds(timeVariable##1);
 511
 512 #define DALI_LOG_TIMER_END(timeVariable, filter, level, preString) \
 513   uint64_t timeVariable##2;                                        \
 514   Debug::GetNanoseconds(timeVariable##2);                          \
 515   DALI_LOG_INFO(filter, level, preString " %ld uSec\n", ((timeVariable##2 - timeVariable##1) / 1000));
 516
 517 #else // DEBUG_ENABLED
 518
 519 #define DALI_LOG_TIMER_START(timeVariable)
 520 #define DALI_LOG_TIMER_END(timeVariable, filter, level, preString)
 521
 522 #endif
 523
 524 } // namespace Log
 525 } // namespace Integration
 526 } // namespace Dali
 527
 528 #endif // DALI_INTEGRATION_DEBUG_H