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 */ 265