home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / appsswi / !ReadMe next >
Text File  |  1995-10-22  |  15KB  |  283 lines
  1. WimpSWIVe       0.05 (30 Oct 1995)
  2. ==================================
  3.  
  4.  
  5.  NewerLook needs to trap Wimp_ SWIs in order to provide its new error
  6. windows. The only official way to trap SWIs is to trap the SWI hardware
  7. vector, but even this is not recommended. It takes much code to implement
  8. properly in *all* circumstances (about 30K of source code in Desktop Hacker),
  9. and can slow the machine down, quite considerably when there are multiple
  10. claimants.
  11.  
  12.  It is, however, possible to trap Wimp_ SWIs by providing another module
  13. with the same SWI chunk and names. This method is much quicker and easier,
  14. but it is - as I’ll happily admit - rather dodgy. One of the problems is
  15. that only one module can do this at a time. So if NewerLook had a module
  16. that used this method, it wouldn’t work properly when another program tried
  17. to do the same thing. (And you know some program will.)
  18.  
  19.  Thus, I have separated the trapping code from the action code (which resides
  20. in another module), and released this module separately. It can manage SWI
  21. claims and releases dynamically, a bit like vectors. Actually, quite a lot
  22. like vectors. You can use it in your own programs if you like. Here’s how.
  23.  
  24.  Because WimpSWIVe uses the Wimp’s SWI chunk, it cannot provide its own
  25. SWIs. Instead, it communicates using a Wimp SWI, namely Wimp_RegisterFilter.
  26. Here is the WimpSWIVe specification for Wimp_RegisterFilter.
  27.  
  28.  
  29.             |                                             Wimp_RegisterFilter
  30.             |                                                    (SWI &400F5)
  31.             |
  32.             | Used by the Filter Manager to register or deregister a filter
  33.             | OR used to register SWI claims and releases with WimpSWIVe
  34.             |
  35.   On entry: | R0 = reason code:
  36.             |         &49575357 (“WSWI”) for WimpSWIVe operation (see below)
  37.             |         anything else for filter operation (see RISC OS 3
  38.             |         Programmers’ Reference Manual, page 3-224)
  39.             | R1 = SWI word:
  40.             |         bits 0-5 : offset in SWI chunk of SWI to claim/release
  41.             |         bit  6   : ignore bits 0-5 and claim all Wimp_ SWIs
  42.             |         bits 7-29: undefined, leave unset
  43.             |         bit  30  : high priority if set, else low priority
  44.             |         bit  31  : claim if set, else release
  45.             | R2 = value to be passed in R12 on entry to code
  46.             | R3 = address of SWI pre-trapping code, or 0 if none needed
  47.             | R4 = address of SWI post-trapping code, or 0 if none needed
  48.             |
  49.    On exit: | Registers preserved
  50.             |
  51. Interrupts: | Interrupts may be enabled
  52.             | Fast interrupts may be enabled
  53.             |
  54.  Processor: | Processor is in SVC mode
  55.             |
  56. Reentrancy: | SWI is not re-entrant
  57.             |
  58.        Use: | In WimpSWIVe usage, this SWI is used to claim or release SWIs.
  59.             | The pre-trapping code specified is called before the SWI is
  60.             | called, and the post-trapping code afterwards.
  61.             |
  62.             | High-priority pre-code is called before low priority pre-code.
  63.             | (And high-priority post-code is called after low priority
  64.             | post-code.) This is important because one piece of pre-code
  65.             | could intercept a SWI call before another bit got a look in.
  66.             | You should use high-priority code for monitoring and register-
  67.             | altering code. If your pre-code is at all likely to intercept
  68.             | a SWI, you must use low-priority code. In effect, low-priority
  69.             | code is ‘closer’ to the real SWI.
  70.             |
  71.             | Pre-trapping code conditions:
  72.             |
  73.             | On entry: R0-R8 = registers passed to SWI
  74.             |           R9    = offset into chunk of SWI called
  75.             |           R12   = value specified when RegisterFilter called
  76.             |           R13   = full, descending stack
  77.             |           R14   = return address
  78.             |  On exit: R0-R8 = may be altered to change effect of SWI
  79.             |           R9    = preserved, or -1 to intercept SWI
  80.             |
  81.             | Pre-trapping code is entered in SVC mode, with interrupts
  82.             | disabled. If R9=-1 on exit, the SWI is not called. Instead,
  83.             | any outstanding post-code is called, and the caller is returned
  84.             | to with the supplied R0-R8 and PSR flags. An error may be
  85.             | signified by pointing R0 to an error block and setting the V
  86.             | flag on return as normal, when intercepting. (See footnote 1.)
  87.             |
  88.             | If more than one client has claimed a SWI, it is the earliest
  89.             | claimant’s pre-trapping code that is called last - new
  90.             | claimants take priority (though high-priority always beats low-
  91.             | priority, of course). If interception occurs, any post-trapping
  92.             | code for claims where the pre-trapping code (if any) has
  93.             | already been executed are also executed. In effect, you are
  94.             | guaranteed that you will get a post-trap event if you have had
  95.             | a pre-trap. (See footnote 2.)
  96.             |
  97.             |
  98.             | Post-trapping code conditions:
  99.             |
  100.             | On entry: R0-R8 = registers passed back from SWI
  101.             |           R9    = offset into chunk of SWI called
  102.             |           R12   = value specified when RegisterFilter called
  103.             |           R13   = full, descending stack
  104.             |           R14   = return address
  105.             |  On exit: R0-R8 = may be altered to change perceived results
  106.             |           PSR flags may be altered to change perceived results
  107.             |           (for example to flag an error).
  108.             |
  109.             | Post-trapping code is entered in SVC mode, with interrupts
  110.             | disabled.
  111.             |
  112.             | If more than one client has claimed a SWI, it is the earliest
  113.             | claimant’s post-trapping code that is called first, subject
  114.             | to priority. (See footnote 2.)
  115.             |
  116.             | Remember that your post-trapping code may well be entered in an
  117.             | error condition. So check whether the V flag is set on entry,
  118.             | and return if it is (if you return with the S flag (MovS Pc,R14
  119.             | or LdmFd R13!,{...,Pc}^, the flags are unaffected). Never
  120.             | change the PSR flags by accident.
  121.             |
  122.             |
  123.             | Unlike OS_Claim, this SWI will not remove previous instances of
  124.             | claims with the same values. The release routine also only
  125.             | removes one instance of the values at a time.
  126.             |
  127.             | Claiming the Wimp_RegisterFilter SWI only traps the normal
  128.             | filter-based use of the SWI. Under no circumstances should you
  129.             | call Wimp_RegisterFilter with WimpSWIVe usage in your trapping
  130.             | code. If you really must claim or release a SWI when some other
  131.             | SWI is executed, use a CallBack to do it. (See the RISC OS 3
  132.             | Programmers’ Reference Manual, page 1-319.)
  133.             |
  134.             | Don’t post-trap Wimp_Poll(Idle) or Wimp_StartTask: it’s a bad
  135.             | idea. WimpSWIVe deals with it adequately, but there are all
  136.             | sorts of simply horrid implications. Trapping Wimp_Poll is
  137.             | easy anyway, using the old filter system.
  138.             |
  139.             | And finally, don’t use the ‘claim all SWIs’ flag unless you
  140.             | really want all the SWIs. Don’t use it for trapping a number
  141.             | of different SWIs, use many separate claims: the speed
  142.             | difference will be negligable, and you needn’t worry about
  143.             | Wimp_Poll. The ‘claim all SWIs’ flag is unlikely to be widely
  144.             | useful - a Wimp SWI logging program seems to be the only
  145.             | possible user.
  146.             |
  147.     Errors: | Bad value passed to WIMP in R0
  148.             |    if WimpSWIVe is not loaded, the attempt to use this SWI in
  149.             |    the WimpSWIVe manner will cause this error
  150.             | Bad WimpSWIVe release
  151.             |    releasing a SWI you had not