home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dd2.zip / DD.DOC < prev    next >
Encoding:
Text File  |  1995-05-02  |  14.5 KB  |  376 lines
  1. dd
  2. ==
  3.     Version   1.00
  4. (C) Copyright Marc Remes 1993
  5.  
  6.  
  7. Highlights
  8.  
  9. dd is a minimal, but powerful debug-shell for Os2. It provides you a
  10. list of DosDebug events your program generates, with at appropriate
  11. times source-level information. Being non-interactive, it loads the 
  12. debuggee extremely fast, almost no regular time is taken by dd.
  13. The more obvious exceptions as ACCESS_VIOLATION, are accompanied by
  14. registerdump and linenumber, sourcefile and function of occurence, 
  15. all the way up the stack to your main or your _beginned thread.
  16. Never run without it. It beats ipmd, no overhead, but oh so handy...
  17.  
  18.  
  19. Files
  20.  
  21. dd.exe starts up your.exe in trace-mode, listing events as they happen.
  22. The list is written to your.ddD. Information is parsed - in idle time -
  23. from your.map and written to your.ddI.
  24. dd.exe are in fact two programs. Using the i switch on dd, you do not
  25. activate the debugger, but work with dd's information.
  26. With dd I you can write .ddI to your.exe. dd I parses your.map
  27. and writes the .ddI to the end of your.exe. Also you can run a check
  28. on your.ddI.
  29. When dd is debugging your.exe, dd will search .ddI consecutively
  30. in your.exe, in your.ddI, or will try to build it from your.map.
  31. If no .ddI is found, your.exe (or .dll) is debugged without symbolic
  32. info.
  33.  
  34.  
  35. Specs
  36.  
  37. You need .map files with linenumber information for the sources
  38. you want debugged. Currently only link386 .map files are known to
  39. be parsed correctly,
  40. link386 must be given at least /M /DE /L or no .ddI can be built.
  41. icc must have of course -Ti.
  42. The system runs fine on this tools.ini
  43. CFLAGS = -C -Ses -Q -W3 -Kabeprx -Gdmsen- -Mp -Ti -Fd- -O-
  44. LFLAGS  = /NoLogo /Map /LineNumbers /Debug /NoI
  45. CC      = icc $(CFLAGS)
  46. LINK    = link386 $(LFLAGS)
  47. The executables are made and tested with icc.exe and link386.exe. 
  48. You cannot interact with dd except for Ctrl-C, which is
  49. about the fastest method of terminating a program, and Pause, which could
  50. pause your program.
  51. dd supports .exe's running multiple threads, loading multiple .dlls.
  52.  
  53. Usage 
  54.  
  55. dd   [/V[erbose]] <prog[.exe]> [arg1] [arg2] [...]
  56.      Debug - in /Verbose mode - prog.exe arg1 arg2
  57.  
  58. dd takes only one switch, /V merely puts out some more information,
  59. mainly debug info about dd itself. /V must precede program, which is
  60. mandatory. You can specify 256 bytes of arguments to program. 
  61.  
  62. dd I [/Flags]     <prog[.exe]> [prog.dll] [[/Flags] <more*.dll>
  63.      Work with dd's information on prog.exe
  64.      Where /Flags can be:
  65.      [/B]                   Build ddI
  66.      [/D]                   Delete .map after build
  67.      [/DDEBUG]              Delete DebugInfo from executable
  68.      [/C[heck]]             Check ddI
  69.      [/I[nfo]]              Display contents of ddI
  70.      [/MAPFILE:<file.map>]  Use file.map to build ddI
  71.      [/M:<[hex][dec]>]      Map EIP (hex/dec) in executable
  72.  
  73. Though the dd I step is not really necessary, it has some nice features.
  74. No flags implies /C, a check is run on the .ddI. Flags must proceed
  75. mandatory .exe/.dll.
  76. /B builds the .ddI by parsing .map and appends .ddI to the .exe/.dll when
  77. possible, .map is specified with /MAPFILE:this.map or created by using
  78. filenamebase padded with .map. .map must be current, i.e. not out of date
  79. in respect to .exe/.dll. Because link386 first writes .exe and then .map,
  80. a margin of 60 seconds is allowed to allow long linktimes. When this
  81. margin is not enough, touch .map.
  82. When short on diskspace, dd I /D deletes the .map after building .ddI.
  83. When even more short on diskspace, dd I /DDEBUG deletes icc/ipmd
  84. debuginformation, but not .ddI. 
  85. /C checks .ddI and displays brief contents. /V displays .ddI in full.
  86. /M:hex/dec searches a certain EIP in an executable, nice post-mortem,
  87. EIP is masked 0x0000FFFF, so multiple occurrences can happen.
  88.  
  89. Examples :                                                           
  90.  dd.exe dd.exe I dd.exe
  91.    DosDebugs dd.exe I dd.exe
  92.  dd dd I dd
  93.    Same thing
  94.  dd I dd.exe
  95.    Checks for dd.ddI, and summarizes
  96.  dd I /I *.exe
  97.    Checks for all .exe .ddI, displays full .ddI and summarizes
  98.  dd I /B dd.exe
  99.    Uses dd.map to build dd.exe's .ddI
  100.  dd I /MAPFILE:other.map dd.dll
  101.    Uses other.map to build dd.dll's ddI,
  102.    useful when .exe and .dll with same basename                      
  103.  dd I /M:0x10032 *.exe *.dll
  104.    Searches in all .exe and .dll for sourceline where EIP == 0x010032,
  105.    or 0x020032, or 0x1FA90032
  106.  dd I /B /D /DDEBUG your.exe
  107.    Builds your.ddI from your.map, deletes your.map and
  108.    deletes link386's DebugInformation from your.exe
  109.  dd your.exe
  110.    DosDebugs your.exe, starts a search for .ddI, and tells you
  111.    how come you trapped X/0.
  112.  
  113. Also try:
  114. dd dd I /T dd
  115.  
  116. I always run my programs through dd. It loads in no time, gives
  117. online debugging info and leaves .ddD for later inspection.
  118.  
  119.  
  120. Internals
  121.  
  122. dd DosStarts your.exe with TraceOpt = 1, and connects to your.exe by 
  123. the DosDebug API. dd repeately receives notifications from DosDebug, 
  124. reacting by giving appropriate DosDebug commands. 
  125. On LibLoad notifications valid addresses for module are determined and 
  126. .ddI is searched/build in idle time.
  127. LibLoads from system libpaths are ommitted from the list, except when /V
  128. is used.
  129. ThreadCreate stores thread's stackpointer and stacksize.
  130. Exception notifications show modulename of occurence and description.
  131. For DBG_X_PRE_FIRST_CHANCE and DBG_X_STACK_INVALID the stack is always
  132. dumped, matching EIPs on the stack with loaded .ddI. 
  133. For DBG_X_FIRST_CHANCE, DBG_X_LAST_CHANCE notifications, currently only
  134. XCPT_ACCESS_VIOLATION, XCPT_INTEGER_DIVIDE_BY_ZERO,
  135. XCPT_FLOAT_DIVIDE_BY_ZERO, XCPT_FLOAT_STACK_CHECK and 
  136. XCPT_FLOAT_DENORMAL_OPERAND generate this dump.
  137.  
  138. The stack is inspected in rather a crude way. No stackframe calculation
  139. is done, instead every long on the stack from ESP to its top is checked
  140. for being a valid EIP in the loaded .ddI.
  141. This eliminates dumps à la DDE4MBS: calling DDE4MBS:, but leads to 
  142. frequent hits. Therefore every hit is doublechecked for having a
  143. CALL assembly-opcode just before point of return. Currently only opcodes 
  144. for CALL rel, CALL r/m, CALL ptr and CALL Reg are checked as valid callees.
  145. Functions allocating a lot of uninitialized stackspace, will evidently 
  146. leave, on the stack, valid return-addresses to previously called functions.
  147. These addresses could possible be checked valid afterwards, but can
  148. quickly filtered out with source at hand.
  149.  
  150. dd will in no way interfere with the execution of the debuggee,
  151. exceptions are just passed through after inspection.
  152.                             
  153. Conflicts arise between ipmd and dd when debugging the same .dll.
  154.  
  155. Documentation referenced when writing this code, is to be found in
  156. ToolKt20's guiref20.inf.
  157.  
  158. dd.exe itself is compiled __DEBUG_ALLOC__ and statically linked,
  159. DDE4MBSI-linked code - faster, smaller - on simple request.
  160.  
  161.  
  162. Coming up
  163.  
  164. .ddS, source excerpts from offending code.
  165. .ddX, an associative stackdump
  166. A bonus when running the 999th process
  167. ? Commandline
  168. ? Sourcecode
  169.  
  170.  
  171. Special thanks
  172.  
  173. to Dr. Dobbs for the Journal
  174. to my friends at KB Brussels for alpha-testing
  175.  
  176.  
  177. Conditions of use
  178.  
  179. I garantee nothing and certainly do not take responsability on you
  180. using the program.
  181. This program isn't freeware, shareware or any-where. It is software
  182. I hope you will appreciate. 
  183. You may distribute the code as you wish, provided this .doc stays with it.
  184.  
  185. Any bugs, requests, __DEBUG_ALLOC__dmps, typo's, WIBNTH,
  186. please leave a message at IBMBBS Belgium, 32 2 718 6010.
  187. In any case WYSIWYG
  188.  
  189.  
  190. Best regards
  191.  
  192. Marc Remes
  193.  
  194.  
  195.     Version   2.00
  196.  
  197. Highlights
  198.  
  199. Finally version 2.00, as promised I deliver .ddX, which in course
  200. became .ddT, still no bonus, no commandline, but better yet
  201. complete sourcecode for you to hack at will.
  202. This also will be the final version I distribute for dd. I think
  203. the program now does its job better as ever, and is very complete.
  204. At least as much complete as I want it to be. Again feel free
  205. to enhance.
  206. Sourcecode is provided as is, no comments.
  207. You'll see work in progress, lazy, quirky, often written in
  208. separate stages, guessing, to hungarian or not, but I personally
  209. garantee some nice excerpts and fine thoughts.
  210. And no bugs I presume.
  211.  
  212.  
  213. Files
  214.  
  215. dd.exe still starts up your.exe in trace-mode, writing to .ddD, 
  216. reading from .ddI. When using the T switch more elaborate
  217. stackinformation is written to .ddT. .ddT contains hex/ascii
  218. stackdump, and strings pointed to by the stack.
  219. You can now manipulate link386 /DebugInformation, extract it
  220. to .deB files.
  221.  
  222.  
  223. Specs
  224.  
  225. Things stand as they were, but now you have sourcecode.
  226. I coded ANSI with occasional obligate systemcalls. 
  227. When you run into SYS1804 concerning DDE4MBS.DLL, you're not
  228. running IBMC, at least not libpathing to its .dlls, compile and 
  229. link the program using your tools. I leave you dd.m and tools.ini.
  230. If make fails to build dd.ddI at the end, use shipped dd.ddI and
  231. type 'dd T7'. If this gives you output as
  232.  
  233. Tue Jun  1 23:26:28 1993
  234. $ 147  1   DBG_N_SUCCESS      Connected C:\WORK\DD.EXE
  235. $ 147  1   DBG_N_ModuleLoad   928  C:\WORK\DD.EXE
  236. $ 147  1   DBG_N_ThreadCreate 
  237. $ 147  1   DBG_N_ModuleLoad   944  C:\IBMC\DLL\DDE4MBS.DLL
  238. $ 147  1   DBG_N_Exception    <C:\IBMC\DLL\DDE4MBS.DLL>   FIRST_CHANCE
  239.            XCPT_ACCESS_VIOLATION WRITE_ACCESS
  240.  00010000   22 :C:\Work\ddm.c                       "main"
  241.  0001087c   50 :C:\Work\ddT.c                       "ddT7"
  242.  0001090f   72 :C:\Work\ddT.c                       "ddT"
  243.  00010c47  201 :C:\Work\ddm.c                       "ParseArgs"
  244.  000100c0   52 :C:\Work\ddm.c                       "main"
  245. CS:EIP  005B:1A02C1A4         15BA11C0
  246. EAX 00000000 EBX 00000002 ECX 0000000A EDX 0000002A  DS 0053 ES 0053
  247. EBP 000255B8 ESP 0002544C EDI 00000000 ESI 00020281  SS 0053 FS 150B GS 0000
  248. $ 147  1   DBG_N_Exception    <C:\OS2\DLL\DOSCALL1.DLL>   FIRST_CHANCE
  249.            XCPT_PROCESS_TERMINATE
  250. $ 147  1   DBG_N_ThreadTerm   99   not in DosExitList
  251. $ 147  1   DBG_N_ProcTerm     99   TC_EXIT      ExitList done
  252. $ 147  0   DBG_N_SUCCESS
  253. Tue Jun  1 23:26:38 1993
  254.  
  255. the system did exactly what icc, link386 and dd would do at this
  256. time of day.
  257. More probably you need to adapt ddi.c's DdiBuild() to parse 
  258. the mapfile your linker produces. The rest should compile OK 
  259. provided you have an ANSI-compiler and access to OS2 headers.
  260. If you do not have a compiler this program is not (yet) for you.
  261. With the Tn switches the debugger debugs itself.
  262. dd nows turns the pointer when dumping.
  263.  
  264.  
  265. Usage 
  266.  
  267. Some more options: the T switch, the Tn switch, /BDDI,
  268. manipulate .deB files.
  269.  
  270.  dd   [/Flags]     <1[.exe]> [arg1] [arg2] [..]  DosDebug one
  271.  dd T [/Flags]     <1[.exe]> [arg1] [arg2] [..]  DosDebug & dump .ddT
  272.       [/F<file.ddD>]         Write trace to file.ddD
  273.       [/V[erbose]]           Verbose mode
  274.  dd Tn                       Desinfects dd.exe for 1 < n > 9
  275.  dd I [/Flags]     <1[.exe]> [2.dll] [[/Flags] <?.dll>]
  276.       [/B]                   Build ddI
  277.       [/BDDI]                Build ddI and write .ddI
  278.       [/D]                   Delete .map after build
  279.       [/DDEBUG]              Delete DebugInfo from executable
  280.       [/MDEBUG]              Move DebugInfo to .deB
  281.       [/ADEBUG]              Add .deB to executable
  282.       [/C[heck]]             Check ddI
  283.       [/I[nfo]]              Display contents of ddI
  284.       [/MAPFILE:<file.map>]  Use file.map to build ddI
  285.       [/M:<[hex][dec]>]      Map EIP (hex/dec) in executable
  286.  
  287.  
  288. Internals
  289.  
  290. You will discover internals as you read the code. Debugging
  291. is done in a _beginned thread, ddI reading/building is done in
  292. yet an other one. Trial and error left me with thrDD
  293. tracing-loop, from where ddEvent is called. Important events are:
  294.  - ModuleLoad, where valid addresses are collected and .ddI is read
  295.  - ThreadCreate, where base of stack is stored
  296.  - Exception, where module, stack and registers are dumped
  297. dd now dumps all exceptions except XCPT_SIGNAL, 
  298. XCPT_PROCESS_TERMINATE, XCPT_ASYNC_PROCESS_TERMINATE.
  299.  
  300. ddExec.c is the front end source, dd.c handles the actual
  301. debug-events and ddi.c manipulates .ddI. ddm.c contains main()
  302. and parses arguments, ddT?.c are the testfiles. 
  303.  
  304. With the Tn switch the debugger debugs itself, dd T1 goes straight
  305. to the access violation from ddT1() in ddT1.c, hereby checking 
  306. if .ddI is OK,
  307. The TTn debugs cmd's copy to dd to ddd, debugs building ddd.ddI
  308. and finally debugs ddd debugging dd going wild. The ddd.exe step
  309. is necessary because .ddd files are kept open some of the time
  310. and dd dd dd /T3 would fail to write to open dd.ddd. dd ddd dd /t3
  311. writes intermediate ddd.ddd.
  312.  
  313. For all you lucky guys using IBM C Set/2(++), no need to debug 
  314. the debugger. #include ddexec.h, link dd.obj+ddi.obj+ddexec.obj
  315. and your program will trace started childprocesses. 
  316. There may be some quirks with combinations of with EXEC_ flags,
  317. not fully tested, but ddm.c's EXEC_ flags will do the job nicely,
  318. or perform some debug/compile cycles.
  319.  
  320. Heapspace was originally allocated by malloc. Frequently calling
  321. realloc, with necceasry memmov's, led to mrMalloc, which gets
  322. memory from DosAllocMem, commiting memory when needed.
  323.  
  324. .ddT files are created by, at Exception time, hex/ascii dumping
  325. the stack, and then checking for all longs on the stack wether
  326. they are strings or wether they are themselves addresses, pointers
  327. to other data, hereby displaying all ascii-Z strings and
  328. sourcecode information up to 8 levels deep. Can take a longer time
  329. with large stacks.
  330.  
  331. When you want to move dd to a different compiler/linker
  332. only DdiBuild() in ddi.c needs to be rewritten to build .ddI
  333. from the mapfile. Fill in the DDI struct correctly and dd
  334. will run even different languages.
  335.  
  336. MkDir .\OB2 or nMake dd.m will fail.
  337.  
  338. Due to the T switch, debugged executable starting with letter T
  339. must be qualified by filename.extention to dd.
  340.  
  341. Manipulating .deB files works when no resources are rc-compiled
  342. to the executable. I always keep my .res in a separate .dll.
  343.  
  344.  
  345. Coming up
  346.  
  347. As I understand C Set++ V3 will have a new linker, probably will
  348. need to parse the .map file it produces. Obviously the PowerPC will
  349. need support.
  350. If and when I find the time. 
  351.  
  352.  
  353. Special thanks
  354.  
  355. as above
  356. and credit to an IBMer whose name escaped, for his ExecPgmTitle()
  357. which has the trace-option added.
  358.  
  359.  
  360. Conditions of use
  361.  
  362. as above
  363. I still don't garantee anything and do not take responsability
  364. on you using the program.
  365. Please distribute, keep the .doc with it, and use it. 
  366.  
  367.  
  368. Any bugs, enhancements, __DEBUG_ALLOC__dmps, typo's, WIBNTH,
  369. please as above.
  370. WYS is still WYG, but now at least YouKnowWhatYouGet.
  371.  
  372.  
  373. Best regards
  374.  
  375. Marc Remes
  376.