home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / program / debug / wimpdebug / !WimpDebug / Docs / TechInfo < prev    next >
Encoding:
Text File  |  1991-08-26  |  6.8 KB  |  136 lines
  1. > <WimpDebug$Dir>.Docs.TechInfo
  2.  
  3. *** WimpDebug technical information ***
  4. Last revised 26 August 1991
  5. Documents version 1.21
  6.  
  7.  
  8. ________________ Technical details (ARM SWI interface) ______________________
  9.  
  10.    The WimpDebug ARM SWI interface is very non-standard - it does not follow
  11. the SWI allocation scheme normally used by modules. This is caused by the
  12. need to pass on all parameters within the SWI number itself, often requiring
  13. 12 bits or more of data, which does not fit at all within the normal system
  14. of 64 SWI numbers per chunk.
  15.    In order to implement the ARM SWI scheme, WimpDebug claims the SWI
  16. hardware vector. Upon receiving an SWI call, it checks its number to find out
  17. if it's a debug SWI. If it is, it's processed, and control returns to the
  18. calling program; otherwise, the call is passed on to the previous owner of
  19. the SWI hardware vector (normally the operating system).
  20.    The WimpDebug SWI handler code looks like this:
  21.  
  22. ;==============================================================================
  23. ;                     SWI hardware vector handler
  24. ;==============================================================================
  25. SWIhandler      STMFD   SP!,{R10-R12,R14}; Get me some work registers
  26.                 BIC     R12,R14,#&FC000003; Fetch the SWI instruction
  27.                 LDR     R11,[R12,#-4]   ; which invoked the handler
  28.                 AND     R10,R11,#&FF0000; Is it one of my routines?
  29.                 TEQ     R10,#&FF0000
  30.                 BEQ     SWIhandler1     ; Branch to handler code if so
  31.  
  32. ; OS SWI received - pass it on
  33.  
  34.                 MOV     R10,PC          ; Restore the NZCV flags to the status
  35.                 BIC     R10,R10,#ms4    ;  they were in when my SWI handler
  36.                 AND     R11,R14,#ms4    ;  was entered
  37.                 TEQP    R10,R11
  38.                 LDR     R10,OldSWIvector; Branch to the old SWI handler by
  39.                 LDR     R10,[R10]       ;  replacing the stacked R14 with the
  40.                 STR     R10,[SP,#12]    ;  vector to the old handler     
  41.                 LDMFD   SP!,{R10-R12,PC}
  42.  
  43. ; One of my SWIs encountered - process it
  44.  
  45. SWIhandler1     ADR     R10,RegBuffer   ; Store unbanked regs.
  46.                 STMIA   R10!,{R0-R7}
  47.                 MOV     R0,R10          ; Move regbuffer ptr & SWI number
  48.                 MOV     R1,R11          ;  to the freed regs
  49.                 LDMFD   SP!,{R10-R12,R14}; Restore the workspace registers
  50.                 STMIA   R0!,{R8-R14}^   ; Store the top half of USR regs รท PC
  51.                 MOV     R0,R0           ;  (safety NOP)
  52.                 STR     R14,[R0]        ; R14_SVC holds R15_USR
  53.                 .
  54.                 .
  55.                 Show handler code
  56.                 .
  57.                 .
  58.  
  59. ; Exit from debug SWI handler
  60.  
  61. SWI_Exit        ADR     R14,RegBuffer   ; Restore R0-R12_USR
  62.                 LDMIA   R14!,{R0-R12}^
  63.                 MOV     R0,R0           ;  (safety NOP)
  64.                 LDR     R14,[R14,#8]    ; Fetch return address separately
  65.                 MOVS    PC,R14          ;  and exit with correct PSR status
  66.  
  67. RegBuffer       %       16*4
  68.  
  69.  
  70.    Although Acorn advise against claiming the SWI hardware vector, I figured
  71. it would be the best solution to use with this program. I have checked the
  72. behaviour of the module comprehensively, and I am quite certain that it
  73. behaves well when exposed to soft resets, RMTidy and other rough treatment.
  74. I have also tested it quite thoroughly with some test programs which did
  75. nothing but send display requests to WimpDebug in the background. I have
  76. been using the machine for long periods of time with WimpDebug and the test
  77. programs running while doing DTP work etc., and it has never crached or
  78. misbehaved. Of course, that doesn't prove anything about the reliability of
  79. WimpDebug, but at least it hasn't been left untested.
  80.  
  81.    The WimpDebug SWI handler does call normal OS SWIs, mainly for doing
  82. number conversions etc. But all the SWIs used are re-entrant, meaning that
  83. WimpDebug SWIs may be used safely when the processor is in IRQ mode. So if
  84. you find yourself writing an interrupt service routine, you can use
  85. WimpDebug then, too!
  86.  
  87.    No registers are altered by the ARM debug SWI routines. Note that
  88. WimpDebug will always display User Mode registers only - this implies that
  89. the SVC or IRQ versions of R13 and R14 can not be displayed.
  90.    WimpDebug will always trap and process any debug SWIs when the module is
  91. present in the machine; it doesn't matter whether the display window is open
  92. or not, or the WimpDebug task is not running. Thus, if you run a program in
  93. the Supervisor which issues debug SWIs, WimpDebug still catches any shown
  94. data. To see the end result, either use the *WDList command or enter the
  95. desktop and look at the display window.
  96.  
  97.    All debug SWIs may be executed conditionally, except those that expect
  98. literal data to follow the SWI instruction.
  99.  
  100.    "What happens if a debug SWI is issued and the WimpDebug module is not
  101. present in the machine?", I hear you ask. Well, to be honest, I'm not quite
  102. sure about it. I have experienced two possibilities: either the call is
  103. ignored completely (or so it appears), or an "Unknown SWI" error is given. I
  104. have not been able to sort out any systematic explanation of what is going
  105. on - it's really quite unpredictable.
  106.    Anyway, whatever is going on, it's not good programming to leave debug
  107. SWIs in a finished program, even if they seem to be completely harmless.
  108.  
  109.  
  110.  
  111. ____________________ Technical details: (Display window) ___________________
  112.  
  113.    The display window consists of 32 virtual text icons. Virtual because
  114. they are not part of the actual window definition, but drawn 'manually'
  115. whenever redraw requests are issued.
  116.  
  117.    The contents of the Display window icons is not altered directly by the
  118. various *commands or SWIs which display something. Instead, when something
  119. is to be shown, all the SWI does is to store away the necessary data in a
  120. buffer (there is one 256 char. buffer for each icon), which holds the text
  121. to be shown in the icon. In addition, information about the display style
  122. used and the (register) value given is stored.
  123.    For updating the contents of the display window, WimpDebug relies on
  124. receiving Null events from Wimp_Poll. Upon receiving such an event, all
  125. icons are checked to see if they have been flagged for update by the SWI
  126. handlers. Then, for all icons to be updated, the data stored in the buffer
  127. by the SWI handler is made the current icon data for that particular icon,
  128. and the icon is redrawn on the screen.
  129.    Thus, WimpDebug will correctly display all given values as long as the
  130. Wimp is working. If your program calls some debug SWIs and then terminates
  131. (perhaps with an error), then WimpDebug will show the values it did send
  132. the next time it receives a Null event.
  133.    In addition to null events, the *WDListIcons command also refreshes the
  134. contents of the icons, so that the information it shows is always up to
  135. date.
  136.