Kosovo Orphans' Appeal Charity CD/KosovoOrphansAppeal.iso/website/computer/wimp2/Docs/APIs

Text File | 1999-02-18 | 15KB | 405 lines

Wimp enhancer module API details (v0.34 - 17th February 1999):
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

The Wimp enhancer module provides kernel and wimp extensions and
enhancements for RISC-OS. This API documentation is split into several
sections: SWIs, Service Calls and the 17, 18 & 19 codes handler.

It is assumed that the programmer is familiar with Acorn RISC-OS and
especially with the operation and construction of programs for the Acorn
RISC-OS Wimp.


 SWIs:
 -=-=-
 Wimp2_Version                            (&C0040)
 On entry: Nothing
 On exit:
  R0=version of this module * 100
  R1=version of RISC-OS present * 100
  R2=version of floating point emulator * 100
  R3=number of Wimp2 processes currently running
  R4=base of Wimp2 heap
  R5=number of dynamic area used by Wimp2 (if on RO3.5+). Zero otherwise.
 Use:
   This call returns useful information about Wimp2 and its internals.

 Wimp2_ReadMonotonicTime                    (&C0041)
 On entry: Nothing
 On exit:
  R0=low word of timer
  R1=high word of timer
 Use:
   This call returns the value of a timer incremented 1000 times a second.

 Wimp2_CallAfter                        (&C0042)
 On entry:
  R0=time from now to call routine in ms
  R1=addr of routine
  R2=R12 on entry
 On exit: All preserved
 Use:
   This call calls the specified code at R1 after R0 milliseconds have
elapsed with R12 set to R2 on entry.
   Your code is called in supervisor mode with interrupts enabled and so you
should take the usual precautions for calling SWIs and such. Note that you
should not take time when called by this method as the system is
effectively hung while you are in this call. You may corrupt R0, R1 and R12
if you wish.

 Wimp2_StopCallAfter                        (&C0043)
 On entry:
  R0=addr of routine
  R1=R12 on entry
 On exit: All preserved
 Used:
   This call stops the scheduled call set up by Wimp2_CallAfter.

 Wimp2_Initialise                        (&C0044)
 On entry:
  R0=version of module expected * 100
  R1=ptr to name of this program instance
  R2=ptr to routine to handle poll codes 17, 18 & 19
 On exit:
  R0=version of this support module * 100
  R1=version of the RO Wimp * 100
  R2=Wimp2 task handle of this app
  R3=RO Wimp task handle of this app
 Use:
   This call registers your program with the Wimp2 multitasker. On your
behalf Wimp_Initialise is called, and preemptive multitasking is started
immediately. Service calls are issued during the execution of this call - see
below.
   NOTE: the routine for handling 17, 18 & 19 return codes is *immediately*
valid and may be started at any time - so make sure it's valid.

 Wimp2_Closedown                        (&C0045)
 On entry:
  R0=wimp task handle (0 for current task)
 On exit: Nothing
 Use:
   This call stops preemptively multitasking your task and calls
Wimp_CloseDown on your behalf. Normally you now exit using OS_Exit as per
normal - or if you wish you can continue execution.

 Wimp2_Poll                            (&C0046)
 On entry:
  R0=poll mask as for RO Wimp_Poll (except bit 0 has changed - see below)
  R1=ptr to 256 bytes to have poll data returned into
 On exit:
  R0=wimp poll reason code
  R1=preserved
  R2=second timer
 Use:
   Use this call to fetch wimp messages sent to you by other wimp tasks.
   Note however that if you have not called Wimp2_Poll recently that the
messages returned may be significantly out of date. Therefore you should
examine R2 against the last time you called Wimp2_Poll and if deemed
necessary, throw away messages returned. You should not need to throw away
redraw messages as these are collated for you anyway.
   Messages returned are identical in format to Wimp_Poll: except that of
the redraw window request message (1) which is returned as the following
format instead:
     +00: window handle
     +04: work area min x
     +08: work area min y
     +12: work area max x
     +16: work area max y
   This message upon being received should be passed to Wimp2_RedrawWindow -
see its entry for details.
   One difference between this call and RO Wimp_Poll is bit 0 - under RO,
this prevents code zeros returning. Under Wimp2, this suspends preemption
if there are no messages in the queue to be processed, only restarting it
if a new message arrives. In most cases this difference will not be
significant.
   Finally please note the poll mask does *not* affect results being returned
immediately - only new ones being received.

 Wimp2_RedrawWindow                        (&C0047)
 On entry:
  R1=ptr to redraw block (see Wimp2_Poll for format)
 On exit:
  R0=flag on whether to continue
 Use:
   This call is very similar to Wimp_UpdateWindow except that when called
preemption is halted. Wimp2_GetRectangle should then be called as
necessary in the same fashion as Wimp_GetRectangle.
   As said above, preemption is halted during the redraw cycle. Therefore
you should try to make the redraw as quick as possible.
   Unlike Wimp_RedrawWindow, this call may also be called at any time to
update a window.

 Wimp2_GetRectangle                        (&C0048)
 On entry:
  R1=as for Wimp_GetRectangle
 On exit:
  R0 & R1 as for Wimp_GetRectangle
 Use:
   Use this call like Wimp_GetRectangle.

 Wimp2_OpenTemplate                        (&C0049)
 On entry:
  R1=as for Wimp_OpenTemplate
 On exit: Nothing
 Use:
   This call disables preemption and makes the call to Wimp_OpenTemplate for
you.

 Wimp2_CloseTemplate                        (&C004A)
 On entry: Nothing
 On exit: Nothing
 Use:
   This call makes the call to Wimp_CloseTemplate for you and reenables
preemption.

 Wimp2_NeedReset                        (&C004B)
 On entry: Nothing
 On exit:
  R0=zero if everything alright,
       ptr to error blk of error if reset required
 Use:
   Use this call to check if your error handler was called through an error
occuring during the execution of the module's preemption handlers.
   If R0 returns a non zero result, you can check the error code to see what
you should do. For example, if it is a fairly transient error (eg; Not a
block) which indicates data corruption of the module's lists then a restart
will more than likely work so you should shut yourself down using
Wimp2_Closedown and restart with Wimp2_Initialise.
   Finally, note that memory full errors get dealt with internally by the
preemptor routine and you should not receive these. If you do, something is
seriously wrong and you should quit rather than restart.

 Wimp2_ReportError                        (&C004C)
 On entry:
  R0=ptr to std error blk
  R1=flags
  R2=name of application
 On exit:
  R0=1 for OK, 2 for Cancel
 Use:
   Use this call to open a multitasking error box. This isn't implemented in
this version of Wimp2.

 Wimp2_EnumerateTasks                        (&C004D)
 On entry:
  R0=0 for first call
 On exit:
  R0=updated to internal pointer, becomes <0 when finished enumeration
  R1=Wimp2 task handle
  R2=RO task handle
  R3=name of task
  R4=maximum slice in ms this task can have
  R5=actual time in ms taken by this task so far
  R6=threads running in this task
 Use:
   Use this call to see what tasks are currently being preempted by the Wimp2
module.

 Wimp2_SetTaskData                        (&C004E)
 On entry:
  R1=Wimp2 task handle
  R4=maximum slice in ms to give to this whole task
     (0=leave the same, -1=effectively disables preemption)
  R5=new actual time taken
     (<0=leave the same)
 On exit:
  R0-R3=preserved
  R4=former max slice
 Use:
   Use this call to set the maximum slice and time taken for this Wimp2
task.

 Wimp2_KillProcess                        (&C004F)
 On entry:
  R0=Wimp2 task handle
 On exit:
  All registers preserved
 Use:
   Use this call to kill a specific Wimp2 process. Firstly, a quit message is
sent to the top of the process's poll queue. If the task has not quit in five
seconds, the process' environment vectors will be delinked and the exit
vector will be attempted. If this succeeds or returns an error, no matter, as
Wimp2_CloseDown and OS_Exit is called for the task on its behalf.
   This call is the severest way to shut down a Wimp2 process. It will leave
memory allocated, files open etc. and it should not be used except in an
emergency.
   Note that the call returns immediately, and if you are not a preempted
task you should call Wimp_Poll soon to allow the task a chance to process the
quit message.
   NOTE: This call is not implemented in the present version of the Wimp2
module

 Wimp2_CopyMemory                        (&C0060)
 On entry:
  R0=ptr to src
  R1=ptr to dest
  R2=length in bytes to copy
 On exit:
  All registers preserved
 Use:
   Use this call to copy memory from one place to another using an optimised
memory copying routine. The routine correctly handles overlapping areas and
non-word aligned sources or destinations or lengths.
   This routine can copy 44 bytes at a time, nearly the most possible on the
Arm processor. Hence it works especially well when copying large portions of
memory, although FIQ operation may be disrupted.
   Note that the routine is much slower when copying non-aligned areas ie;
two areas at the same offset from a word aligned address will use the fast
routine which uses direct 44 byte copies. Non aligned areas require bytes to
be shifted to match the new alignment and hence are far far slower.
   The routine has been optimised for the Arm6 processor ie; it assumes the
presence of at least a 4k instruction cache and a write buffer. This
configuration is not necessary for the correct operation of the routine
however.

 Wimp2_CopyStringXX                        (&C0061)
 On entry:
  R0=ptr to src
  R1=ptr to dest
  R2=lower terminating character
  R3=upper terminating character
 On exit:
  R1=ptr to terminator of dest
  R2=length of the string
 Use:
   Use this call to copy a string from one place to another using an
optimised copying routine. Specify a range of terminating characters using R2
and R3 eg; copy yea string terminated by anything from a 0 to a 31. Note that
the copied string is terminated by R2, not by the original terminator. The
routine correctly handles overlapping strings.

 Wimp2_FindStringLengthXX                    (&C0062)
 On entry:
  R0=ptr to string
  R1=lower terminating character
  R2=upper terminating character
 On exit:
  R0=ptr to terminating character
  R1=length of string
 Use:
   Use this call to find the length of a string which may be terminated by
any character between R1 and R2 inclusively. The routine is highly optimised
and so will find the length extremely quickly.

 Wimp2_Divide                            (&C0063)
 On entry:
  R0=number to be divided
  R1=number to divide by
 On exit:
  R0=result
  R1=modulus
 Use:
   Use this call to divide R0 by R1 returning the result and the modulus.
This call uses an optimised divide routine.



 Service Calls:
 -=-=-=-=-=-=-=
 Wimp2_PreWimpPoll                        (&C0040)
 On entry:
  R1=&C0040, this service call's number
  R2=Wimp2 task handle of the task about to have Wimp_Poll called for it
 On exit:
  Ensure all registers are the same ie; do not claim this call
 Use:
  This service call is issued by the Wimp2 module just prior to the call to
Wimp_Poll made by Wimp2 on the behalf of the preempted task.

 Wimp2_PostWimpPoll                        (&C0041)
 On entry:
  R1=&C0041, this service call's number
  R2=Wimp2 task handle of the task which has just received control
 On exit:
  Ensure all registers are the same ie; do not claim this call
 Use:
  This service call is issued by the Wimp2 module just after Wimp_Poll,
called by Wimp2 on the behalf of the preempted task, has returned. Also, if
poll code number two was returned by Wimp_Poll, suitable Wimp_RedrawWindow
and Wimp_GetRectangle calls will have been made to collect the necessary
bounding rectangles prior to this call.

 Wimp2_PreInitialise                        (&C0042)
 On entry:
  R1=&C0042, this service call's number
 On exit:
  Ensure all registers are the same ie; do not claim this call
 Use:
  This service call is issued by the Wimp2 module just after Wimp2_Initialise
is called. It is intended for the patch module so that it can not bother
trying to intercept the Wimp_Initialise Wimp2_Initialise does.

 Wimp2_PostInitialise                        (&C0043)
 On entry:
  R1=&C0043, this service call's number
 On exit:
  Ensure all registers are the same ie; do not claim this call
 Use:
  This service call is issued by the Wimp2 module just before
Wimp2_Initialise returns. It is intended for the patch module so that it can
not bother trying to intercept the Wimp_Initialise Wimp2_Initialise does.

 Wimp2_PointerLeavingWindow                    (&C0044)
 On entry:
  R1=&C0044, this service call's number
  R2=Wimp2 task handle of the task which has just received the message
 On exit:
  Set R1 to zero to claim call
 Use:
  This service call is issued by the Wimp2 module when a
Pointer_Leaving_Window (4) message is received by a Wimp2 task. This is to
allow a suitable Hourglass module patch to switch off the hourglass state for
that task.

 Wimp2_PointerEnteringWindow                    (&C0045)
 On entry:
  R1=&C0045, this service call's number
  R2=Wimp2 task handle of the task which has just received the message
 On exit:
  Set R1 to zero to claim call
 Use:
  This service call is issued by the Wimp2 module when a
Pointer_Entering_Window (5) message is received by a Wimp2 task. This is to
allow a suitable Hourglass module patch to switch on the hourglass state for
that task.






 17, 18 & 19 poll code API
 -=-=-=-=-=-=-=-=-=-=-=-=-

In C, your routine will be called as follows:

int routine(int msgno, int msgblk)

In assembler, this goes to:

R0=poll code number
R1=message block attached to poll code number

You should return in R0 a value to indicate what should be done with this
message:
 0: This causes the message to be placed in the normal message queue to be
handled by Wimp2_Poll called by the main process.
 1: This tells the module that the message has been dealt with and to take no
further action.
 2: This tells the module to halt preemption and feed the message to the next
Wimp2_Poll called, and thereafter restart preemption on the next after that
Wimp2_Poll called. This is intended for the wimp patch ONLY.
 Other return values are currently reserved.

Note that any changes you make to the message block pointed to by R1 are
permanent ie; it is directly the message block that will be put in the
message queue if R0=0 on exit. This can be advantageous or not.

Note also that this routine is NOT preempted. Therefore you should be fast to
finish your business. Also be aware that your have 256 bytes of stack
available and currently no more - if you extend over that you will invoke the
C stack extender and then things will become very nasty indeed as in fact the
stack resides in 'limbo' in RMA. So *ensure* this doesn't happen.

Please see the enclosed C example for how to implement this.