sdk/tools/log2lines/help.c

   1 /*
   2  * ReactOS log2lines
   3  * Written by Jan Roeloffzen
   4  *
   5  * - Help text and functions
   6  */
   7
   8 #include <stdio.h>
   9
  10 #include "version.h"
  11 #include "compat.h"
  12 #include "config.h"
  13 #include "options.h"
  14 #include "cmd.h"
  15 #include "help.h"
  16
  17 char *verboseUsage =
  18 "\n"
  19 "Description:\n"
  20 "  When <exefile> <offset> are given, log2lines works like raddr2line:\n"
  21 "      - The <exefile> <offset> combination can be repeated\n"
  22 "      - Also, <offset> can be repeated for each <exefile>\n"
  23 "      - NOTE: Some of the options below will have no effect in this form.\n"
  24 "  Otherwise it reads stdin and tries to translate lines of the form:\n"
  25 "      <IMAGENAME:ADDRESS>\n"
  26 "  The result is written to stdout.\n\n"
  27 "  <offset> or <ADDRESS> can be absolute or relative with the restrictions:\n"
  28 "  - An image with base < 0x400000 MUST be relocated to a > 0x400000 address.\n"
  29 "  - The offset of a relocated image MUST be relative.\n\n"
  30 "  log2lines uses a cache in order to avoid a directory scan at each\n"
  31 "  image lookup, greatly increasing performance. Only image path and its\n"
  32 "  base address are cached.\n\n"
  33 "Options:\n"
  34 "  -b   Use this combined with '-l'. Enable buffering on logFile.\n"
  35 "       This may solve loosing output on real hardware (ymmv).\n\n"
  36 "  -c   Console mode. Outputs text per character instead of per line.\n"
  37 "       This is slightly slower but enables to see what you type.\n\n"
  38 "  -d <directory>|<ISO image>\n"
  39 "       <directory>: Directory to scan for images. (Do not append a '" PATH_STR "')\n"
  40 "       <ISO image>: This option also takes an ISO image as argument:\n"
  41 "       - The image is recognized by the '.iso' or '.7z' extension.\n"
  42 "       - NOTE: The '.7z' and extracted '.iso' basenames must be identical,\n"
  43 "         which is normally true for ReactOS trunk builds.\n"
  44 "       - The image will be unpacked to a directory with the same name.\n"
  45 "       - The embedded reactos.cab file will also be unpacked.\n"
  46 "       - Combined with -f the file will be re-unpacked.\n"
  47 "       - NOTE: this ISO unpack feature needs 7z to be in the PATH.\n"
  48 "       Default: " DEF_OPT_DIR "\n\n"
  49 "  -f   Force creating new cache.\n\n"
  50 "  -F   As -f but exits immediately after creating cache.\n\n"
  51 "  -h   This text.\n\n"
  52 "  -l <logFile>\n"
  53 "       <logFile>: Append copy to specified logFile.\n"
  54 "       Default: no logFile\n\n"
  55 "  -L <logFile>\n"
  56 "       <logFile>: (Over)write copy to specified logFile.\n"
  57 "       Default: no logFile\n\n"
  58 "  -m   Prefix (mark) each translated line with '* '.\n\n"
  59 "  -M   Prefix (mark) each NOT translated line with '? '.\n"
  60 "       ( Only for lines of the form: <IMAGENAME:ADDRESS> )\n\n"
  61 "  -P <cmd line>\n"
  62 "       Pipeline command line. Spawn <cmd line> and pipeline its output to\n"
  63 "       log2lines (as stdin). This is for shells lacking support of (one of):\n"
  64 "       - Input file redirection.\n"
  65 "       - Pipelining byte streams, needed for the -c option.\n\n"
  66 "  -r   Raw output without translation.\n\n"
  67 "  -R <cmd>\n"
  68 "       Revision commands interfacing with SVN. <cmd> is one of:\n"
  69 "       - check:\n"
  70 "         To be combined with -S. Check each source file in the log and issue\n"
  71 "         a warning if its revision is higher than that of the tested build.\n"
  72 "         Also when the revison of the source tree is lower than that of the\n"
  73 "         tested build (for every source file).\n"
  74 "         In both cases the source file's -S output would be unreliable.\n"
  75 "       - update:\n"
  76 "         Updates the SVN log file. Currently only generates the index file\n"
  77 "         The SVN log file itself must be generated by hand in the sources\n"
  78 "         directory like this (-v is mandatory here):\n"
  79 "             svn log -v > svndb.log ('svn log' accepts also a range)\n"
  80 "         'svndb.log' and its index are needed for '-R regscan'\n"
  81 "       - regscan[,<range>]:\n"
  82 "         Scan for regression candidates. Essentially it tries to find\n"
  83 "         matches between the SVN log entries and the sources hit by\n"
  84 "         a backtrace (bt) command.\n"
  85 "         <range> is the amount of revisions to look back from the build\n"
  86 "         revision (default 500)\n"
  87 "         The output of '-R regscan' is printed after EOF. The 'Changed path'\n"
  88 "         lists will contain only matched files.\n"
  89 "         Limitations:\n"
  90 "         - The bug should really be a regression.\n"
  91 "         - Expect a number of false positives.\n"
  92 "         - The offending change must be in the sources hit by the backtrace.\n"
  93 "           This mostly excludes changes in headerfiles for example.\n"
  94 "         - Must be combined with -S.\n"
  95 "       Can be combined with -tTS.\n\n"
  96 "  -s   Statistics. A summary with the following info is printed after EOF:\n"
  97 "       *** LOG2LINES SUMMARY ***\n"
  98 "       - Translated:      Translated lines.\n"
  99 "       - Reverted:        Lines translated back. See -u option\n"
 100 "       - Retranslated:    Lines retranslated. See -U option\n"
 101 "       - Skipped:         Lines not translated.\n"
 102 "       - Differ:          Lines where (addr-1) info differs. See -tT options\n"
 103 "       - Differ(func/src):Lines where also function or source info differ.\n"
 104 "       - Rev conflicts:   Source files conflicting with build. See '-R check'\n"
 105 "       - Reg candidates:  Regression candidates. See '-R regscan'\n"
 106 "       - Offset error:    Image exists, but error retrieving offset info.\n"
 107 "       - Total:           Total number of lines attempted to translate.\n"
 108 "       Also some version info is displayed.\n\n"
 109 "  -S <context>[+<add>][,<sources>]\n"
 110 "       Source line options:\n"
 111 "       <context>: Source lines. Display up to <context> lines until linenumber.\n"
 112 "       <add>    : Optional. Display additional <add> lines after linenumber.\n"
 113 "       <sources>: Optional. Specify alternate source tree.\n"
 114 "       The environment variable " SOURCES_ENV " should be correctly set\n"
 115 "       or specify <sources>. Use double quotes if the path contains spaces.\n"
 116 "       For a reliable result, these sources should be up to date with\n"
 117 "       the tested revision (or try '-R check').\n"
 118 "       Can be combined with -tTR.\n"
 119 "       Implies -U (For retrieving source info) and -R check.\n\n"
 120 "  -t   Translate twice. The address itself and for (address-1).\n"
 121 "       Show extra filename, func and linenumber between [..] if they differ\n"
 122 "       So if only the linenumbers differ, then only show the extra\n"
 123 "       linenumber.\n\n"
 124 "  -T   As -t, but show only filename+func+linenumber for (address-1)\n\n"
 125 "  -u   Undo translations.\n"
 126 "       Lines are translated back (reverted) to the form <IMAGENAME:ADDRESS>\n"
 127 "       Also removes all lines previously added by this tool (e.g. see -S)\n\n"
 128 "  -U   Undo and reprocess.\n"
 129 "       Reverted to the form <IMAGENAME:ADDRESS>, and then retranslated\n"
 130 "       Implies -u.\n\n"
 131 "  -v   Show detailed errors and tracing.\n"
 132 "       Repeating this option adds more verbosity.\n"
 133 "       Default: only (major) errors\n\n"
 134 "  -z <path to 7z>\n"
 135 "       <path to 7z>: Specify path to 7z. See also option -d.\n"
 136 "       Default: '7z'\n"
 137 "\n"
 138 "CLI escape commands:\n"
 139 "  It is possible to change options and perform actions from the 'kdb:>' prompt\n"
 140 "  By prepending the `(backquote) character to the option.\n"
 141 "  Example: 'kdb:> `l new.log' changes the current logfile to 'new.log'.\n"
 142 "  Flag options like 'b' are given a numeric value of 0 (off) or 1 (on).\n"
 143 "  Options accepting a string as argument can be cleared by the value '" KDBG_ESC_OFF "'.\n"
 144 "  Some ClI commands are read only or not (entirely) implemented.\n"
 145 "  If no value is provided, the current one is printed.\n"
 146 "  There are a few extra ClI commands or with different behaviour:\n"
 147 "  - `a <module>:<reladdress>:\n"
 148 "    - Outputs absolute address e.g. for setting breakpoints.\n"
 149 "    - Do a 'mod' first to retrieve relocation info.\n"
 150 "  - `h : shows this helptext (without exiting)\n"
 151 "  - `q : quits log2lines\n"
 152 "  - `R regscan : the output is printed immediately (do a 'bt' first)\n"
 153 "  - `R regclear : clears previous regscan matches\n"
 154 "  - `s : the output is printed immediately\n"
 155 "  - `s clear : clears all statistics.\n"
 156 "  - `S : only <context> and <add> can be set.\n"
 157 "  - `v <level> : sets the current debug loglevel\n"
 158 "\n"
 159 "Option Examples:\n"
 160 "  Setup: A VMware machine with its serial port set to: '\\\\.\\pipe\\kdbg'.\n\n"
 161 "  Just recreate cache after a svn update or a new module has been added:\n"
 162 "       log2lines -F\n\n"
 163 "  Use kdbg debugger via console (interactive):\n"
 164 "       log2lines -c < \\\\.\\pipe\\kdbg\n\n"
 165 "  Use kdbg debugger via console, and append copy to logFile:\n"
 166 "       log2lines -c -l dbg.log < \\\\.\\pipe\\kdbg\n\n"
 167 "  Same as above, but for PowerShell:\n"
 168 "       log2lines -c -l dbg.log -P \"piperead -c \\\\.\\pipe\\kdbg\"\n\n"
 169 "  Use kdbg debugger to send output to logfile:\n"
 170 "       log2lines < \\\\.\\pipe\\kdbg > dbg.log\n\n"
 171 "  Re-translate a debug log:\n"
 172 "       log2lines -U -d bootcd-38701-dbg.iso < bugxxxx.log\n\n"
 173 "  Re-translate a debug log. Specify a 7z file, which wil be decompressed.\n"
 174 "  Also check for (address) - (address-1) differences:\n"
 175 "       log2lines -U -t -d bootcd-38701-dbg.7z < bugxxxx.log\n"
 176 "  Output:\n"
 177 "       <ntdll.dll:60f1 (dll/ntdll/ldr/utils.c:337[331] (LdrPEStartup))>\n\n"
 178 "  The following commands are equivalent:\n"
 179 "       log2lines msi.dll 2e35d msi.dll 2235 msiexec.exe 30a8 msiexec.exe 2e89\n"
 180 "       log2lines msi.dll 2e35d 2235 msiexec.exe 30a8 2e89\n\n"
 181 "  Generate source lines from backtrace ('bt') output. Show 2 lines of context:\n"
 182 "       log2lines -S 2 -d bootcd-38701-dbg.7z < bugxxxx.log\n"
 183 "  Output:\n"
 184 "       <msiexec.exe:2e89 (lib/3rdparty/mingw/crtexe.c:259 (__tmainCRTStartup))>\n"
 185 "       | 0258  #else\n"
 186 "       | 0259      mainret = main (\n"
 187 "       <msiexec.exe:2fad (lib/3rdparty/mingw/crtexe.c:160 (WinMainCRTStartup))>\n"
 188 "       | 0159    return __tmainCRTStartup ();\n"
 189 "       | 0160  }\n\n"
 190 "  Generate source lines. Show 2 lines of context plus 1 additional line and\n"
 191 "  specify an alternate source tree:\n"
 192 "       log2lines -S 2+1,\"c:\\ros trees\\r44000\" -d bootcd-44000-dbg < dbg.log\n"
 193 "  Output:\n"
 194 "       <msi.dll:2e35d (dll/win32/msi/msiquery.c:189 (MSI_IterateRecords))>\n"
 195 "       | 0188      {\n"
 196 "       | 0189          r = MSI_ViewFetch( view, &rec );\n"
 197 "       | ----\n"
 198 "       | 0190          if( r != ERROR_SUCCESS )\n\n"
 199 "  Use '-R check' to show that action.c has been changed after the build:\n"
 200 "       log2lines -s -d bootcd-43850-dbg.iso -R check -S 2  < dbg.log\n"
 201 "  Output:\n"
 202 "       <msi.dll:35821 (dll/win32/msi/registry.c:781 (MSIREG_OpenUserDataKey))>\n"
 203 "       | 0780      if (create)\n"
 204 "       | 0781          rc = RegCreateKeyW(HKEY_LOCAL_MACHINE, keypath, key);\n"
 205 "       <msi.dll:5262 (dll/win32/msi/action.c:2665 (ACTION_ProcessComponents))>\n"
 206 "       | R--- Conflict : source(44191) > build(43850)\n"
 207 "       | 2664              else\n"
 208 "       | 2665                  rc = MSIREG_OpenUserDataKey(comp->ComponentId,\n\n"
 209 "CLI Examples: (some are based on the option examples above)\n"
 210 "  Use '`R check' to show that action.c has been changed after the build:\n"
 211 "       kdb:> `R check\n"
 212 "       | L2L- -R is \"check\" (changed)\n"
 213 "       kdb:> bt\n"
 214 "       <msi.dll:35821 (dll/win32/msi/registry.c:781 (MSIREG_OpenUserDataKey))>\n"
 215 "       | 0780      if (create)\n"
 216 "       | 0781          rc = RegCreateKeyW(HKEY_LOCAL_MACHINE, keypath, key);\n"
 217 "       <msi.dll:5262 (dll/win32/msi/action.c:2665 (ACTION_ProcessComponents))>\n"
 218 "       | R--- Conflict : source(44191) > build(43850)\n"
 219 "       | 2664              else\n"
 220 "       | 2665                  rc = MSIREG_OpenUserDataKey(comp->ComponentId,\n\n"
 221 "       kdb:>\n\n"
 222 "  Generate source lines. Show 2 lines of context plus 1 additional line.\n"
 223 "  The -Uu options are dependent on -S:\n"
 224 "       kdb:> `S 2+1\n"
 225 "       | L2L- -u Undo is 1 (changed)\n"
 226 "       | L2L- -U Undo and reprocess is 1 (changed)\n"
 227 "       | L2L- -S Sources option is 2+1,\"C:\\ROS\\reactos\\\" \n"
 228 "       | L2L- (Setting source tree not implemented)\n"
 229 "       kdb:> bt\n"
 230 "       <msi.dll:2e35d (dll/win32/msi/msiquery.c:189 (MSI_IterateRecords))>\n"
 231 "       | 0188      {\n"
 232 "       | 0189          r = MSI_ViewFetch( view, &rec );\n"
 233 "       | ----\n"
 234 "       | 0190          if( r != ERROR_SUCCESS )\n"
 235 "       kdb:>\n\n"
 236 "  Change logfile:\n"
 237 "       kdb:> `l\n"
 238 "       | L2L- -l logfile is "" (unchanged)\n"
 239 "       kdb:> `l new.log\n"
 240 "       | L2L- -l logfile is \"new.log\" (changed)\n"
 241 "       kdb:> `l off\n"
 242 "       | L2L- -l logfile is "" (changed)\n"
 243 "       kdb:>\n\n"
 244 "  Set a breakpoint with help of 'mod' and '`a':\n"
 245 "       <msi.dll:2e35d (dll/win32/msi/msiquery.c:189 (MSI_IterateRecords))>\n"
 246 "       kdb:> mod (for kernel tracing usually only needed once)\n"
 247 "       -- mod output with reloc info\n"
 248 "       kdb:> `a msi.dll:2e35d\n"
 249 "       | L2L- Address: 0x00096ca0\n"
 250 "       kdb:> bpx 0x00096ca0\n\n"
 251 "\n";
 252
 253 void
 254 usage(int verbose)
 255 {
 256     fprintf(stderr, "log2lines " LOG2LINES_VERSION "\n\n");
 257     fprintf(stderr, "Usage: log2lines -%s {<exefile> <offset> {<offset>}}\n", optchars);
 258     if (verbose)
 259         fprintf(stderr, "%s", verboseUsage);
 260     else
 261         fprintf(stderr, "Try log2lines -h\n");
 262 }
 263
 264 /* EOF */