include/SLP_Dlog_PG.h

   1 /**
   2  @ingroup       SLP_PG
   3  @defgroup      SLP_PG_Dlog dlog
   4  @{
   5
   6 <h1 class="pg">Introduction</h1>
   7 Dlog logging service support sending log message to circular log device
   8
   9 <h1 class="pg">dlog Architecture</h1>
  10 @image html SLP_Dlog_PG_image001.png System Architecture of dlog
  11
  12 <h1 class="pg">dlog properties</h1>
  13 Sending log message to circular buffer. dlog APIs include Priority and Tag. By using priority and Tag, we can easily filtered messages what we want to see.
  14         <h2 class="pg">priority</h2>
  15 priority level incdicates the urgency of log message
  16
  17 <table>
  18 <tr>
  19         <th>Priority</th>
  20         <th>Description</th>
  21 </tr>
  22 <tr>
  23         <td>VERBOSE </td>
  24         <td>Verbose message. - compiled into application and logged at runtime only when debug mode. on release mode, this log message is strip.</td>
  25 </tr>
  26 <tr>
  27         <td>DEBUG</td>
  28         <td>Debug messasge. - always compiled into application, but not logged at runtime by default on release mode. on debug mode, this message will be logged at runtime.</td>
  29 </tr>
  30 <tr>
  31         <td>INFO</td>
  32         <td>Information message - Normal operational messages. above of this priority will always be logged.</td>
  33 </tr>
  34 <tr>
  35         <td>WARN</td>
  36         <td>Warning messages - not an error, but indication that an error will occur if action is not taken</td>
  37 </tr>
  38 <tr>
  39         <td>ERROR</td>
  40         <td>Error message - indicate error. </td>
  41 </tr>
  42 <tr>
  43         <td>FATAL</td>
  44         <td>Fatal message - Should be corrected immediately ( not used yet )</td>
  45 </tr>
  46 </table>
  47
  48         <h2 class="pg">Tag</h2>
  49 Used to identify the source of a log message.
  50 There is no naming limitation, but do not forget that tag is identification of module. Tag must be distinguishable from other tag.
  51 Simplified macro like LOGV, LOGD, LOGI, LOGW, LOGE uses declared LOG_TAG constant, so declare a LOG_TAG constant before you use dlog macro is a good convention.
  52 @code
  53 #define LOG_TAG "MyApp"
  54 @endcode
  55
  56 <h1 class="pg">list of dlog macro</h1>
  57 Macro name start with LOG prefix is for application. start with SLOG prefix is for framework, start with RLOG prefix is for radio. each macro write log message to separated log device such as main, system, radio.
  58
  59 <h1 class="pg">sample code</h1>
  60 Using simplified macro with current LOG_TAG
  61
  62 @code
  63 #define LOG_TAG "YOUR_APP"
  64 #include <dlog.h>
  65
  66 int function () {
  67         LOGD( "debug message from YOUR_APP \n");
  68         LOGI( "information message from YOUR_APP \n");
  69         LOGW( "warning message from YOUR_APP \n");
  70         LOGE( "error message from YOUR_APP \n");
  71 }
  72 @endcode
  73
  74 Using log macro allows you to specify a priority and a tag
  75
  76 @code
  77 #include <dlog.h>
  78
  79 #define TAG_DRM_SVC "drm_svc"
  80 #define TAG_DRM_WM "drm_wm"
  81 #define TAG_DRM_OEM "drm_oem"
  82
  83 int function () {
  84         LOG(LOG_DEBUG,TAG_DRM_SVC, "information message from drm_svc \n");
  85         LOG(LOG_WARN,TAG_DRM_WM, "warning message from drm_wm \n");
  86         LOG(LOG_ERROR,TAG_DRM_OEM, "error message from drm_oem \n");
  87 }
  88 @endcode
  89
  90 Using log macro allows you to pass in a varargs
  91
  92 @code
  93 #include <dlog.h>
  94
  95 #define TAG_DRM_SVC "drm_svc"
  96 #define TAG_DRM_WM "drm_wm"
  97 #define TAG_DRM_OEM "drm_oem"
  98
  99 int function (const char *fmt, ...) {
 100         va_list ap;
 101         va_start(ap, fmt);
 102         LOG_VA(LOG_DEBUG,TAG_DRM_WM, fmt, args);
 103         va_end(ap);
 104 }
 105 @endcode
 106 <h1 class="pg">dlogutil</h1>
 107         <h2 class="pg">Introduction</h2>
 108 You can use dlogutil command to view and follow the contents of the log buffers. The general usage is :
 109 @code
 110 dlogutil [<option>] ¡¦ [<filter-spec>] ¡¦
 111 @endcode
 112
 113         <h2 class="pg">Filtering log output</h2>
 114 Every log message has a <I>tag</I> and a <I>priority</I> associated with it.
 115 Filter expression follows this format <B><I>tag:priority</I></B> where <I>tag</I> indicates the tag of interest and <I>priority</I> indicates the minimum level of priority to report for that tag. You can add any number of tag:priority specifications in a single filter expression.
 116 The tag of a log message is a short indicating the system component from which the message originates
 117 The <I>priority</I> is one of the following character values, orderd from lowest to highest priority:<br>
 118 V - verbose<br>
 119 D - debug<br>
 120 I - info<br>
 121 W - warning<br>
 122 E - Error<br>
 123 F - Fatal<br>
 124
 125 for example, if you want to see MyApp tag and above of debug priority,
 126 @code
 127 # dlogutil MyApp:D
 128 @endcode
 129 if you want to see all log message above of info priority also,
 130 @code
 131 # dlogutil MyApp:D *:E
 132 @endcode
 133
 134         <h2 class="pg">List of logutil command options</h2>
 135
 136 <table>
 137 <tr>
 138         <th>Option</th>
 139         <th>Description</th>
 140 </tr>
 141 <tr>
 142         <td>-b <buffer> </td>
 143         <td>Alternate log buffer. The main buffer is used by default buffer. </td>
 144 </tr>
 145 <tr>
 146         <td>-c</td>
 147         <td>Clears the entire log and exits</td>
 148 </tr>
 149 <tr>
 150         <td>-d</td>
 151         <td>Dumps the log and exits.</td>
 152 </tr>
 153 <tr>
 154         <td>-f <filename></td>
 155         <td>Writes log to <filename>. The default is stdout</td>
 156 </tr>
 157 <tr>
 158         <td>-g</td>
 159         <td>Print the size of the specified log buffer and exits.</td>
 160 </tr>
 161 <tr>
 162         <td>-n <count></td>
 163         <td>Sets the maximum number of rotated logs to <count>. The default value is 4. Requires the -r option</td>
 164 </tr>
 165 <tr>
 166         <td>-r <Kbytes></td>
 167         <td>Rotates the log file every <Kbytes> of output. The default value is 16. Requires the -f option.</td>
 168 </tr>
 169 <tr>
 170         <td>-s</td>
 171         <td>Sets the default filter spec to silent.</td>
 172 </tr>
 173 <tr>
 174         <td>-v <format></td>
 175         <td>Sets the output format for log messages. The default is brief format. </td>
 176 </tr>
 177
 178 </table>
 179
 180
 181
 182 @}
 183 **/