home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / pd / programming / debug-utils / sim / docs / postsim.doc < prev    next >
Text File  |  1993-03-16  |  21KB  |  575 lines
  1.  
  2. -------------------------------------------------------------------------------
  3.  
  4.                                   PostSIM
  5.  
  6.                       S.I.M. Postmortem Debug Server
  7.                                Version 0.85
  8.  
  9.                   Copyright © 1992/1993 by Stefan Walter
  10.                             ALL RIGHTS RESERVED
  11.  
  12. -------------------------------------------------------------------------------
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                Documentation
  19.  
  20.  
  21.                          last edited on: 09.03.93
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29. ===============================================================================
  30. 1.      Introduction
  31. ===============================================================================
  32.  
  33.  
  34. PostSIM  basically  is  a  sophisticated  crash handler.  It will catch all
  35. exceptions  which  do  not  occur  in  supervisor  mode  and  all  calls to
  36. exec.library's  Alert()  and  Debug().  Additionally to basic features like
  37. ending or suspending crashed tasks, PostSIM also allows symbolic postmortem
  38. debugging.
  39.  
  40. PostSIM can be used for different objectives.  It can be used as preventive
  41. measurement against crashes and software failure requesters, giving you the
  42. chance  not  only  to  suspend  or end a crashed process but also to have a
  43. closer look at what went wrong.  If you are developing applications, having
  44. PostSIM  installed  in  the  background  can be very useful.  You can debug
  45. right  then  when  the program fails, which is a big help for searching the
  46. reason for those nasty hard_to_reproduce crashes.
  47.  
  48. PostSIM  also  allows  you  to  partially get program to work that break on
  49. higher  versions  of  the  OS  or because of 680x0 processors, due to cache
  50. problems or the typical privileged 'MOVE SR,<ea>' instruction.
  51.  
  52. Finally  PostSIM  allows  also  active  debugging.   If  you know that your
  53. program  has  a  bug,  you  can  insert  and  assemble  or  compile ILLEGAL
  54. instructions  or  calls  to  Debug() at strategic places in your program or
  55. where  you  assume  the  bug to be.  When you run the program, PostSIM gets
  56. invoked and you can monitor the program from then on.  Very useful to debug
  57. objects like file handlers etc.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66. ===============================================================================
  67. 2.      Installation
  68. ===============================================================================
  69.  
  70.  
  71. PostSIM  needs to be run *BEFORE* any crashes happen.  Therefore it should be
  72. installed  from the startup-sequence, but it can also be started later from
  73. the CLI/Shell.  Start from the Workbench is not allowed.
  74.  
  75. For a proper installation of PostSIM do the following:
  76.  
  77.  
  78.  
  79.       - Copy  the  file 'PostSIM' to a suitable location.  Possible choices
  80.         would  be  the 'C' directory or the directory where you have stored
  81.         the rest of your debugging toolkit.
  82.  
  83.  
  84.       - If  you haven't configured a copy of SIM yet, do this now and store
  85.         the copy in the 'C:' directory or somewhere else.
  86.  
  87.  
  88.       - Copy  the  symbol  definition  file  for your version of OS or your
  89.         custom  definition  file  to  the  'S:' directory as 'bug.libfile'.
  90.         PostSIM  and  SIMBug  share the same definition file.  PostSIM does
  91.         not  require  a  symbol definition file to work.  If you don't want
  92.         symbols for library calls, leave out this step.
  93.  
  94.         The  information about how to edit or to create a custom definition
  95.         file can be found in a seperate documentation.
  96.  
  97.  
  98.       - If  you  want  installation  at  startup,  execute  PostSIM in your
  99.         startup-sequence.
  100.  
  101.  
  102.  
  103. PostSIM accepts the following options when started:
  104.  
  105.  
  106.  
  107.          -s (path)      (path)  specifies where PostSIM shall look for SIM.
  108.                         This  must  be stated if you do not have stored SIM
  109.                         in either the current or the 'C' directory.
  110.  
  111.  
  112.          -k (key)       (key)  specifies  the hotkey with which PostSIM can
  113.                         be   invoked.    (key)  is  a  hexadeciaml  number.
  114.                         default is:
  115.  
  116.                            $00190019 (Ctrl-LShift-LAlt-p).
  117.  
  118.                         A  description  of  how  the  number is built up is
  119.                         located at the end of the decomentation.
  120.  
  121.  
  122.          -w (win)       (win)  specifies  the  console window PostSIM shall
  123.                         open when invoked.  Default is:
  124.  
  125.                            'CON:0/0/550/150/PostSIM v0.85'.
  126.  
  127.                         If  the  default window is too small to contain the
  128.                         full  texts  with the system font you use, use this
  129.                         option to specify a larger window.
  130.  
  131.  
  132.          -l             Will  force PostSIM to load SIM immediately when it
  133.                         is installed.
  134.  
  135.  
  136.          -d             Will  force  PostSIM to patch the Debug() vector of
  137.                         exec.library directly to SIM's JSR entrance.
  138.  
  139.                         This   option  will  automatically  load  SIM  when
  140.                         PostSIM is installed (see option -l).
  141.  
  142.  
  143.          -q             Supresses  the  title text when installing and only
  144.                         prints   the  installation  message.   Useful  when
  145.                         installing PostSIM in the startup-sequence.
  146.  
  147.  
  148.          -h             Disables   automatic   printing  of  all  available
  149.                         commands when PostSIM gets invoked.
  150.  
  151.  
  152.          ?              Prints a brief overview of the options and does not
  153.                         install PostSIM.
  154.  
  155.  
  156.  
  157. A sample command line could look like this:
  158.  
  159.  
  160.  
  161.          PostSIM -qlhd -sbin/sim -k$190030 -w"CON:0/0/640/200/PostSIM Window"
  162.  
  163.  
  164.  
  165. When  PostSIM  fails  to install itself, it will return the following error
  166. messages:
  167.  
  168.  
  169.  
  170.          - PostSIM successfully installed.
  171.  
  172.                    PostSIM could be installed and is now working.
  173.  
  174.  
  175.  
  176.          - Unable to open port.
  177.  
  178.                    PostSIM could not open the port needed to handle
  179.                    crashes and was therefore not installed.
  180.  
  181.  
  182.  
  183.          - Unable to load SIM.
  184.  
  185.                    PostSIM could not load SIM at installation.
  186.  
  187.  
  188.  
  189. Executing PostSIM again has the same effect as pressing the hotkey.
  190.  
  191. While  PostSIM waits in the background, memory consumption limits itself to
  192. ca. 17  KBytes  plus the memory required for a process (ca. 5-13 KBytes)
  193. plus the memory for SIM and its display (ca. 68 Kbytes) if it is loaded at
  194. installation.
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203. ===============================================================================
  204. 3.      Invoking PostSIM
  205. ===============================================================================
  206.  
  207.  
  208. PostSIM can get invoked for the following reasons:
  209.  
  210.  
  211.  
  212.         - An exception happens.
  213.  
  214.         - A task calls Alert().
  215.  
  216.         - A task calls Debug().
  217.  
  218.         - Debugging with SIM is suspended with the quit command of SIM.
  219.  
  220.         - PostSIM's copy of SIM was called from another task and the
  221.           quit command of SIM is used.
  222.  
  223.         - The hotkey to invoke PostSIM is pressed.
  224.  
  225.         - PostSIM is executed again.
  226.  
  227.  
  228.  
  229. In  any  of  these  cases,  PostSIM  will  suspend the task which called it
  230. (except for invokation due to the hotkey), open a console window and call
  231. WBToFront() and DisplayBeep().
  232.  
  233. If  SIM  hasn't been loaded yet, it will attempt to do so.  If SIM can't be
  234. found  at  the  custom,  the current and the 'C' directory, a filerequester
  235. pops  up.   If  you  cancel it, SIM will not be loaded and debugging is not
  236. possible.
  237.  
  238. PostSIM  then  loads  the  symbol  definition file if it could be found and
  239. generates a symbol list if no error in the definition file was found.
  240.  
  241. Then the reason for the invokation is displayed.  If PostSIM was invoked by
  242. the  user and there are crashes stored in the storage list, their number is
  243. displayed  instead.   If  the  reason  was a crash, PostSIM also prints the
  244. tasks  address,  name  and  the  CLI  number  and the loaded command if the
  245. crashed task is a CLI process.  Last the results of a few sanity checks are
  246. printed.   The  sanity  checks  consist  of  a informing you if Forbid() or
  247. Disable()  was  broken,  if the stackpointer is not within the stack of the
  248. crashed  task/process  and  if its PC is not within the ROM or any hunks of
  249. the program loaded.
  250.  
  251. Finally  PostSIM lists all available commands if this isn't suppressed with
  252. the 'h' option.  Then it waits for commands.
  253.  
  254.  
  255.  
  256. If  more  then one task has crashed, they are queued up.  You can only deal
  257. with  one  task at a time.  If the queue isn't empty, the following message
  258. appears in the window title bar:
  259.  
  260.  
  261.         *** [n] crashes waiting in queue.
  262.  
  263.  
  264. If  a  task  crashes  while PostSIM's window is open, it is also put in the
  265. queue,  the  window  title  bar  is  updated  and  a  call  to WBToFront(),
  266. DisplayBeep() and ActivateWindow() is done.
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275. ===============================================================================
  276. 4.      Commands
  277. ===============================================================================
  278.  
  279.  
  280. Interaction  with  PostSIM  is  done with one letter commands which in most
  281. cases  don't have further arguments.  Not all commands are allowed at every
  282. kind of invokation, i.e.  the 'D'/Debug command has no sence if PostSIM was
  283. invoked  by  hotkey.   The  available commands can be listed with the '?'
  284. command.
  285.  
  286.  
  287. The following commands exist:
  288.  
  289.  
  290.  
  291. Q       Terminates PostSIM.  This is only allowed when no crash is pending,
  292.         the storage list is empty and debugging is not in progress.
  293.  
  294.         If  while removing all patches a changed task traphandler is found,
  295.         information  about  the  task  is  given  and  the possibilities to
  296.         restore this one or all, not to restore it, not to restore any more
  297.         or  to  cancel.   If you have run any other debugger after PostSIM,
  298.         you shoud quit it before you end PostSIM.
  299.  
  300.  
  301. H       Holds  PostSIM.   If  no  crash is pending, this command closes the
  302.         window and puts PostSIM on stand-by.
  303.  
  304.  
  305. N       Creates  a  new  CLI/Shell.   This  command  requires the 'Run' and
  306.         'NewCLI' cli commands in the 'C' directory if they aren't resident.
  307.  
  308.  
  309. E       Enters  SIM  as  subroutine.   Basically of use if you lost control
  310.         while debugging or for short peeking of the system.  System symbols
  311.         are  available.   Do  not  change  the  stack pointers or the PC or
  312.         PostSIM will crash.
  313.  
  314.  
  315. I       If  a crash has happened, this command displays further information
  316.         about  register  contents  and  the  task/process  of  the  crashed
  317.         program.
  318.  
  319.  
  320. R       Regenerates the system symbols.  You can use this command to update
  321.         device,  library  base or task symbols after new libraries, devices
  322.         or tasks have been installed.
  323.  
  324.  
  325. U       Updates  the  traphandlers  of all tasks.  This command may be used
  326.         after   another   program  (i.e.   another  debugger)  changed  the
  327.         traphandler  of  a  task  and you want this traphandler pointing at
  328.         PostSIM again.
  329.  
  330.         If  a changed task traphandler is found, information about the task
  331.         is  given  and  the possibilities to update this one or all, not to
  332.         update it, not to update any more or to cancel.
  333.  
  334.  
  335. S       Suspends  the  task that crashed by letting it wait forever.  There
  336.         is no way back to safely reactivate a tasks that has benn suspended
  337.         with this command.  Think carefully befure using it.
  338.  
  339.  
  340. X       Ends  the  crashed  program by either calling Exit() or by reseting
  341.         the stack and performing an additional RTS.
  342.  
  343.  
  344. O       Lets  the  old traphandler deal with the crash.  This allows you to
  345.         pass  control  to  another  debugging  tool that has been installed
  346.         before PostSIM or to see the standard software failure requester.
  347.  
  348.  
  349. Y       Loads symbols from an executable.  The symbols are relocated on the
  350.         segment list of the loaded command of the crashed process.
  351.  
  352.         If  the  name of the executable isn't specified with the command, a
  353.         file requester pops up.
  354.  
  355.         Problems  may  occur  with programs that detach from the CLI, where
  356.         the  segment  list of the program in memory does not match the hunk
  357.         structure of the executable.
  358.  
  359.  
  360. D       Start  debugging.   Passes control over the program that crashed to
  361.         SIM.   PostSIM  therefore  sets  the  task  traphandle of that task
  362.         directly  to  SIM.   You  can use the quit command of SIM to return
  363.         control   to   PostSIM  or  to  suspend  debugging  and  return  to
  364.         multitasking.
  365.  
  366.         PostSIM removes its window and returns to stand-by.
  367.  
  368.  
  369. C       Terminates debugging and lets go the task that crashed.
  370.  
  371.  
  372. A       If  the  invokation reason was a call to Alert(), this command lets
  373.         the task complete the call.
  374.  
  375.  
  376. G       Terminates  debugging  and  resets  SIM.   This command needs to be
  377.         executed  if  you terminated debugging of the last crash and didn't
  378.         leave SIM with 'quit' then.
  379.  
  380.  
  381. P       Stores the crash in the storage list.
  382.  
  383.  
  384. W (n)   Gets the first or (n)th crash from the storage list.
  385.  
  386.  
  387. L       Lists all crashes in the storage list.
  388.  
  389.  
  390. T       Lists  all tasks and processes with their address, state, priority,
  391.         CLI  number,  name  plus name of the loaded command.  The output is
  392.         paged,  after  one  page has been printed and there is more to see,
  393.         you  can press either <CTRL-C> to abort or any other key to see the
  394.         next page.
  395.  
  396.  
  397. Z       Intercepts  any  task  specified by its task control block address.
  398.         The addresses can be found using the 'T' command.
  399.  
  400.         If  the  task  to  be  intercepted is in the ready list, it will be
  401.         stoped before it will execute the next instruction.  If the task is
  402.         in  waitstate,  PostSIM will wait until the tasks becomes activated
  403.         somehow,  then  PostSIM  will  let  it  complete the call to Wait()
  404.         before it is stopped.
  405.  
  406.         If a task could be intercepted, it will be dealt with like it would
  407.         have  crashed and activated PostSIM.  You can either debug the task
  408.         using the 'D' command or put it in the storage list to freeze it.
  409.  
  410.  
  411. ?       Displays all available commands.
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420. ===============================================================================
  421. 5.      Debugging
  422. ===============================================================================
  423.  
  424.  
  425. When  a  task crashes, it is put to waitstate by calling Wait(), regardless
  426. whether  it  has  called  Disable()  or  Forbid()  before or not.  This can
  427. remotely  lead  to futher crashes depending what the program was doing when
  428. it crashed, i.e.  if it was meddling with the task or memory lists.
  429.  
  430. When  you  intend  to  debug  a  crashed task, you can do this with the 'D'
  431. command.   If  an  exception  caused  the  crash,  the  PC  points  to  the
  432. instruction  which  caused the exception.  If it was Alert(), The PC points
  433. to  the  real Alert() function, if you don't want to see the alert, perform
  434. an RTS, i.e.  with SIM's AMIGA-SHIFT-R shortcut.
  435.  
  436. If  you need to suspend debugging for whatever reason, use the quit command
  437. of SIM.  You then return to PostSIM where you can use the 'D' command again
  438. to  continue  to  debug  or  the  'C'  command to continue execution of the
  439. program and to end the debugging of this task.
  440.  
  441. When  you have finished debugging, don't leave SIM with 'Exit'.  Use 'Quit'
  442. instead.   You  return  to PostSIM.  There you finish debugging by entering
  443. the  'C'  command.   If  you  don't  do  this, you will need to use the 'G'
  444. command to grab SIM again when you need to do further debugging.
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453. ===============================================================================
  454. 6.      The Hotkey
  455. ===============================================================================
  456.  
  457.  
  458. PostSIM's  default  hotkey to invoke PostSIM is CTRL-LALT-LSHIFT-P.  If you
  459. desire  to  have  another hotkey or if the default one interacts with other
  460. applications  you  have installed, you can specify your own when installing
  461. PostSIM using the 's' option.
  462.  
  463. The  hotkey is defined as a number similar to a rawkey.  The hotkey's value
  464. is ORed together from the desired qualifiers and a key:
  465.  
  466.         Qualifiers:
  467.  
  468.                 LEFT SHIFT:              $00000001
  469.                 RIGHT SHIFT:             $00000002
  470.                 CAPSLOCK:                $00000004
  471.                 CONTROL:                 $00000008
  472.                 LEFT ALT:                $00000010
  473.                 RIGHT ALT:               $00000020
  474.                 LEFT AMIGA:              $00000040
  475.                 RIGHT AMIGA:             $00000080
  476.                 MIDDLE BUTTON:           $00001000
  477.                 RIGHT BUTTON:            $00002000
  478.                 LEFT BUTTON:             $00004000
  479.  
  480.  
  481.  
  482.         Keys (refering to American keyboard!):
  483.  
  484.                 A       $00200000                S       $00210000
  485.                 B       $00350000                T       $00140000
  486.                 C       $00330000                U       $00160000
  487.                 D       $00220000                V       $00340000
  488.                 E       $00120000                W       $00110000
  489.                 F       $00230000                X       $00320000
  490.                 G       $00240000                Y       $00150000
  491.                 H       $00250000                Z       $00310000
  492.                 I       $00170000                1       $00010000
  493.                 J       $00260000                2       $00020000
  494.                 K       $00270000                3       $00030000
  495.                 L       $00280000                4       $00040000
  496.                 M       $00370000                5       $00050000
  497.                 N       $00360000                6       $00060000
  498.                 O       $00180000                7       $00070000
  499.                 P       $00190000                8       $00080000
  500.                 Q       $00100000                9       $00090000
  501.                 R       $00130000                0       $000a0000
  502.  
  503.                 -       $000b0000                '       $002a0000
  504.                 =       $000c0000                $       $002b0000
  505.                 \       $000d0000                <       $00300000
  506.                 [       $001a0000                ,       $00380000
  507.                 ]       $001b0000                .       $00390000
  508.                 ;       $00290000                /       $003a0000
  509.  
  510.                 ESC     $00450000                TAB     $00420000
  511.                 F1      $00500000                CR      $00440000
  512.                 F2      $00510000                CTRL    $00630000
  513.                 F3      $00520000                CAPS    $00620000
  514.                 F4      $00530000                LSHIFT  $00600000
  515.                 F5      $00540000                RSHIFT  $00610000
  516.                 F6      $00550000                LALT    $00640000
  517.                 F7      $00560000                RALT    $00650000
  518.                 F8      $00570000                LAMIGA  $00660000
  519.                 F9      $00580000                RAMIGA  $00670000
  520.                 F10     $00590000                C-UP    $004c0000
  521.                 |       $00000000                C-DOWN  $004d0000
  522.                 BCKSPC  $00410000                C-LEFT  $004f0000
  523.                 DEL     $00460000                C-RIGHT $004e0000
  524.                 HELP    $005f0000
  525.  
  526.  
  527.  
  528.         Keys of keypad:
  529.  
  530.                 1       $001d0000                0       $000f0000
  531.                 2       $001e0000                .       $003c0000
  532.                 3       $001f0000                [       $005a0000
  533.                 4       $002d0000                ]       $005b0000
  534.                 5       $002e0000                /       $005c0000
  535.                 6       $002f0000                *       $005d0000
  536.                 7       $003d0000                -       $004a0000
  537.                 8       $003e0000                +       $005e0000
  538.                 9       $003f0000                ENTER   $00000000
  539.  
  540.  
  541.  
  542. An example: The default hotkey CTRL-LALT-LSHIFT-P:
  543.  
  544.                 LEFT SHIFT:     $00000001
  545.                 CONTROL:        $00000008 OR
  546.                 LEFT ALT:       $00000010 OR
  547.                 P               $00190000 OR
  548.                 ===========================
  549.                                 $00190019
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558. ===============================================================================
  559. 7.      Final notes
  560. ===============================================================================
  561.  
  562.  
  563. PostSIM  is  part  of  the  distribution  of SIM and may only be copied and
  564. distributed along with the entier distribution.
  565.  
  566. If you find any bugs in PostSIM, the system symbol definition files or SIM,
  567. you  are  kindly  asked to report these to me in order to fix them.  Please
  568. look  at the end of the documentation of SIM for both my physical or e-mail
  569. address.
  570.  
  571.  
  572.  
  573. Happy bug-hunting! :)
  574.  
  575.