video_in_hal/nsframework/framework_unified/client/include/native_service/ns_plogger_if.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 //////////////////////////////////////////////////////////////////////////////////////////////////
  19 /// \file
  20 /// Declares functions and macros related to performance logging
  21 ///
  22 /// \ingroup  tag_NSLogger
  23 /// @{
  24 ///
  25 //////////////////////////////////////////////////////////////////////////////////////////////////
  26 /**
  27  * @file
  28  * @brief \~english Declares functions and macros related to performance logging
  29  *
  30  */
  31 /** @addtogroup BaseSystem
  32  *  @{
  33  */
  34 /** @addtogroup native_service
  35  *  @ingroup BaseSystem
  36  *  @{
  37  */
  38 /** @addtogroup framework_unified
  39  *  @ingroup native_service
  40  *  @{
  41  */
  42 /** @addtogroup native
  43  *  @ingroup framework_unified
  44  *  @{
  45  */
  46
  47 #ifndef NS_PLOGGER_IF_H_  // NOLINT  (build/header_guard)
  48 #define NS_PLOGGER_IF_H_
  49
  50 #include <native_service/frameworkunified_types.h>
  51
  52 #ifdef __cplusplus
  53 extern "C" {
  54 #endif
  55
  56 #define NS_PLOGQ "/NSplog"
  57 #define NS_SYSEVENTLOGQ "/NSSysEventLog"
  58
  59 /// Performance logging
  60 typedef enum _EPLOG_TIME_FORMAT {
  61   EPLOG_TIME_FORMAT_USEC,  ///< microseconds
  62   EPLOG_TIME_FORMAT_MSEC,  ///< miliseconds
  63   EPLOG_TIME_FORMAT_SEC,   ///< seconds
  64 } EPLOG_TIME_FORMAT;
  65
  66 typedef enum _EPLOG_OUTPUT_OPTION {
  67   EPLOG_SLOG     = 0x01,   ///< log to standard logging i.e. slogger
  68   EPLOG_MSGQ     = 0x02,   ///< log to message queue NSPlog
  69   EPLOG_TRACEEVENT = 0x04  ///< log to trace events
  70 } EPLOG_OUTPUT_OPTION;
  71
  72 ///////////////////////////////////////////////////////////////////////////////
  73 /// \ingroup  tag_NSLogger
  74 /// \brief    Performance LOG parameter
  75 ///////////////////////////////////////////////////////////////////////////////
  76 typedef struct _FRAMEWORKUNIFIEDLOGPPARAM {
  77   BOOL           bIsPLogEnabled;      ///< PLog enabled or disabled
  78   EPLOG_TIME_FORMAT  eTimeFormat;     ///< Time format when PLog is printed
  79   UI_64        ui64GapInuS;           ///< Gap in micro seconds
  80   UI_8           uiLogOutputOptions;  ///< Output log options
  81 } FRAMEWORKUNIFIEDLOGPPARAM, *LFRAMEWORKUNIFIEDLOGPPARAM;
  82
  83 ///////////////////////////////////////////////////////////////////////////////
  84 /// \ingroup  tag_NSLogger
  85 /// \brief    System event LOG parameter
  86 ///////////////////////////////////////////////////////////////////////////////
  87 typedef struct _FRAMEWORKUNIFIEDLOGSYSEVENTPARAM {
  88   BOOL           bIsSysEventLogEnabled;    ///< SysEvent log enabled or disabled
  89 } FRAMEWORKUNIFIEDLOGSYSEVENTPARAM, *LFRAMEWORKUNIFIEDLOGSYSEVENTPARAM;
  90
  91 extern FRAMEWORKUNIFIEDLOGPPARAM g_FrameworkunifiedLogPParams;
  92 extern FRAMEWORKUNIFIEDLOGSYSEVENTPARAM g_FrameworkunifiedLogSysEventParams;
  93
  94 #define PLOG_TEXT(args...) NSLogPrintPerformanceLog(__LINE__, __FUNCTION__, ## args)
  95 #define SYSEVENTLOG_TEXT(args...) NSLogSysEvent(__LINE__, __FUNCTION__, ## args)
  96 #define IS_PLOG_ENABLED() NsLogIsPLogEnabled()
  97 #define IS_SYSEVENTLOG_ENABLED() NSLogIsSysEventLogEnabled()
  98
  99 #ifdef __FRAMEWORKUNIFIEDLOG_NDEBUG_LEVEL2__
 100 #define FRAMEWORKUNIFIEDLOG_PERFORMANCE_DEBUG(print_fmt, args...) ((void)0)
 101 #else
 102 ///////////////////////////////////////////////////////////////////////////////
 103 /// \ingroup  tag_NSLogger
 104 /// \brief    FRAMEWORKUNIFIEDLOG_PERFORMANCE_DEBUG
 105 ///////////////////////////////////////////////////////////////////////////////
 106 /// Prints a performance log in PosixBasedOS001 system log. These logs can be viewed by using utility sloginfo.
 107 /// \note     This macro API is disable in Linux system
 108 ///           This macro API is disable if defined "__FRAMEWORKUNIFIEDLOG_NDEBUG_LEVEL2__"
 109 ///
 110 /// \param [in] print_fmt
 111 ///      PCSTR - Input string
 112 /// \param [in] args
 113 ///          string similar to that of a printf statement and data argments
 114 ///////////////////////////////////////////////////////////////////////////////
 115 #define FRAMEWORKUNIFIEDLOG_PERFORMANCE_DEBUG(print_fmt, args...) ((IS_PLOG_ENABLED()) ? PLOG_TEXT(print_fmt, ## args): ((void)0))
 116 #endif
 117
 118 ///////////////////////////////////////////////////////////////////////////////
 119 /// \ingroup  tag_NSLogger
 120 /// \brief    FRAMEWORKUNIFIEDLOG_PERFORMANCE
 121 ///////////////////////////////////////////////////////////////////////////////
 122 /// FRAMEWORKUNIFIEDLOG_PERFORMANCE is a logging API provided specifically for logging performance metrics.
 123 /// \note     This macro API is disable in Linux system
 124 ///           It should be used in few locations within an application. (Max 5 times per application).
 125 ///           It should never be used in place of FRAMEWORKUNIFIEDLOG.
 126 ///
 127 /// \param [in] print_fmt
 128 ///          string similar to that of a printf statement
 129 /// \param [in] args
 130 ///          Data arguments
 131 ///////////////////////////////////////////////////////////////////////////////
 132 #define FRAMEWORKUNIFIEDLOG_PERFORMANCE(print_fmt, args...) ((IS_PLOG_ENABLED()) ? PLOG_TEXT(print_fmt, ## args): ((void)0))
 133
 134 ///////////////////////////////////////////////////////////////////////////////
 135 /// FRAMEWORKUNIFIEDLOG_SYSTEMEVENT
 136 ///
 137 /// \param [in] print_fmt
 138 ///          string similar to that of a printf statement
 139 /// \param [in] args
 140 ///          Data arguments
 141 ///////////////////////////////////////////////////////////////////////////////
 142 #define FRAMEWORKUNIFIEDLOG_SYSTEMEVENT(print_fmt, args...) ((IS_SYSEVENTLOG_ENABLED()) ?\
 143   SYSEVENTLOG_TEXT(print_fmt, ## args): ((void)0))
 144
 145 ////////////////////////////////////////////////////////////////////////////////////////////////
 146 /// \ingroup NSLogPrintPerformanceLog
 147 /// \~english @par Brief
 148 ///        This macro API is disable in Linux system
 149 /// \~english @param [in]  f_ui16Line
 150 ///        const UI_16 - line number
 151 /// \~english @param [in] f_cFuncName
 152 ///        PCSTR - Function name. It takes __PRETTY_FUNCTION__
 153 /// \~english @param [in] print_fmt
 154 ///        PCSTR - Input string
 155 /// \~english @retval none
 156 /// \~english @par Prerequisite
 157 ///        - Work ony when AGL_STUB is disabled.
 158 /// \~english @par Change of internal state
 159 ///        - The internal state is not changed.
 160 /// \~english @par Conditions of processing failure
 161 ///        none
 162 /// \~english @par Detail
 163 ///        Prints a performance log in PosixBasedOS001 system log. These logs can be viewed by using utility sloginfo.
 164 ///        Log is in format: "Plog: Time[us]:x or o (if gap in cs):Line:Function Input string"\n
 165 ///        - Outputs in time units (microseconds/milliseconds/second) that can be set by the NSLogSetPlogTimeFormat.
 166 ///        - The time data to be output is added to the gap data described in the/dev/shmem/Plog.gap files.
 167 ///        - This information is output to the log output destinations (system log, NSPlog message queue, and event trace)
 168 ///          that can be set by the NSLogSetPlogOutputOptions.(Default: NSPLog message queue)
 169 ///        - PLOG_TEXT, Use this API from the FRAMEWORKUNIFIEDLOG_PERFORMANCE and FRAMEWORKUNIFIEDLOG_PERFORMANCE_DEBUG macros.\n
 170 ///               Continued:\n
 171 ///                 - PLOG_TEXT("Service Availability Status: %d", IsAvailable);
 172 ///                 - FRAMEWORKUNIFIEDLOG_PERFORMANCE("Service Availability Status: %d", IsAvailable);
 173 ///                 - FRAMEWORKUNIFIEDLOG_PERFORMANCE_DEBUG("Service Availability Status: %d", IsAvailable);
 174 /// \~english @par Classification
 175 ///        Public
 176 /// \~english @par Type
 177 ///        No match
 178 /// \~english @see
 179 ///        none
 180 ////////////////////////////////////////////////////////////////////////////////////////////////
 181 VOID NSLogPrintPerformanceLog(const UI_16 f_ui16Line, PCSTR f_cFuncName, PCSTR __format, ...);
 182
 183 ////////////////////////////////////////////////////////////////////////////////////////////////
 184 /// NSLogEnablePLog
 185 /// Enables/Disables the performance logging
 186 ///
 187 /// \param [in] f_bEnable
 188 ///      BOOL - TRUE- Enable performance logging, FALSE - Disable
 189 ///
 190 /// \return none
 191 ///
 192 ////////////////////////////////////////////////////////////////////////////////////////////////
 193 VOID NSLogEnablePLog(BOOL f_bEnable);
 194
 195 ////////////////////////////////////////////////////////////////////////////////////////////////
 196 /// \ingroup NsLogIsPLogEnabled
 197 /// \~english @par Brief
 198 ///        Is Enables/Disables the performance logging
 199 /// \~english @retval TRUE  current state of plog enable.
 200 /// \~english @retval FALSE current state of plog disable.
 201 /// \~english @par Prerequisite
 202 ///        -
 203 /// \~english @par Change of internal state
 204 ///        - The internal state is not changed.
 205 /// \~english @par Conditions of processing failure
 206 ///        -
 207 /// \~english @par Detail
 208 ///        Get the Performance Log enable/disable status.
 209 /// \~english @par Classification
 210 ///        Public
 211 /// \~english @par Type
 212 ///        No match
 213 /// \~english @see
 214 ///        NSLogEnablePLog
 215 ////////////////////////////////////////////////////////////////////////////////////////////////
 216 BOOL NsLogIsPLogEnabled(void);
 217
 218 ////////////////////////////////////////////////////////////////////////////////////////////////
 219 /// NSLogSetPlogTimeFormat
 220 /// Set the time format for performance logging.
 221 ///
 222 /// \param [in] f_ePlogTimeFormat
 223 ///      EPLOG_TIME_FORMAT - Time format for performance logging
 224 ///
 225 /// \return none
 226 ///
 227 ////////////////////////////////////////////////////////////////////////////////////////////////
 228 VOID NSLogSetPlogTimeFormat(EPLOG_TIME_FORMAT f_ePlogTimeFormat);
 229
 230 ////////////////////////////////////////////////////////////////////////////////////////////////
 231 /// NSLogSetPlogOutputOptions
 232 /// Set the output options for performance logging.
 233 ///
 234 /// \param [in] f_uiPlogOutputOption
 235 ///      UI_8 - Output option. Value is generated by or'ed value of enum EPLOG_OUTPUT_OPTION
 236 ///      e.g. EPLOG_SLOG | EPLOG_MSGQ
 237 ///
 238 /// \return none
 239 ///
 240 ////////////////////////////////////////////////////////////////////////////////////////////////
 241 VOID NSLogSetPlogOutputOptions(UI_8 f_uiPlogOutputOption);
 242
 243 ////////////////////////////////////////////////////////////////////////////////////////////////
 244 /// NSLogSysEvent()
 245 /// Prints system event log in message queue NSSyseventlog.
 246 ///
 247 /// \param [in] f_ui16Line
 248 ///      const UI_16 - line number
 249 /// \param [in] f_cFuncName
 250 ///      PCSTR - Function name. It takes __PRETTY_FUNCTION__
 251 /// \param [in] __format
 252 ///      PCSTR - Input string
 253 ///
 254 /// \return none
 255 ///
 256 ////////////////////////////////////////////////////////////////////////////////////////////////
 257 VOID NSLogSysEvent(const UI_16 f_ui16Line, PCSTR f_cFuncName, PCSTR __format, ...);
 258
 259 ////////////////////////////////////////////////////////////////////////////////////////////////
 260 /// NSLogEnableSysEventLog
 261 /// Enables/Disables the system event logging
 262 ///
 263 /// \param [in] f_bEnable
 264 ///      BOOL - TRUE- Enable system event logging, FALSE - Disable
 265 ///
 266 /// \return none
 267 ///
 268 ////////////////////////////////////////////////////////////////////////////////////////////////
 269 VOID NSLogEnableSysEventLog(BOOL f_bEnable);
 270
 271 ////////////////////////////////////////////////////////////////////////////////////////////////
 272 /// NSLogIsSysEventLogEnabled
 273 /// Is Enables/Disables the system event logging
 274 ///
 275 /// \return SysEventLogEnabled
 276 ///         BOOL - current state of sys event log(enable/disable).
 277 ////////////////////////////////////////////////////////////////////////////////////////////////
 278 BOOL NSLogIsSysEventLogEnabled(void);
 279
 280 #ifdef __cplusplus
 281 }
 282 #endif
 283 #endif /* NS_PLOGGER_IF_H_ */  // NOLINT  (build/header_guard)
 284 /** @}*/
 285 /** @}*/
 286 /** @}*/
 287 /** @}*/
 288 /// @}