home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / misc / tornado / t2demo010a1 / APIs next >
Text File  |  1996-12-07  |  6KB  |  152 lines
  1. Tornado II support module API details:
  2. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  3.  
  4. Note that these SWIs implement a Win32 API interface but do not provide all
  5. the facilities Win32 does (mainly in the security area). This is not apparent
  6. when using the module through the C veneers though.
  7.  
  8.  Tornado_Initialise                        (&C0000)
  9.  On entry:
  10.   R0=version of support module expected * 100
  11.   R1=ptr to name of this program instance
  12.   R2=ptr to routine to handle poll codes 17, 18 & 19
  13.   R3=RO Wimp task handle of this app
  14.  On exit:
  15.   R0=version of this support module * 100
  16.   R1=version of RISC-OS we're running on here * 100
  17.  Use:
  18.    This call initialises the program instance calling it as a preemptable
  19. multithreading multitaskable client. From this call hence the program code
  20. will be preempted. You must already have set yourself up as a Wimp task with
  21. Wimp_Initialise.
  22.    NOTE: the routine for handling 17, 18 & 19 return codes is *immediately*
  23. valid and may be started at any time - so make sure it's valid.
  24.    Note also that on return of this call the current code becomes a thread
  25. and other threads may be created that run alongside it. You must take account
  26. of this before calling this call ie; be absolutely sure you're ready for it.
  27.  
  28.  
  29.  Tornado_Closedown                        (&C0001)
  30.  On entry:
  31.   R0=wimp task handle (0 for current task)
  32.  On exit: Nothing
  33.  Use:
  34.    This call shuts down the program instance calling it as a preemptable
  35. multithreading multitaskable client. Henceforth your code will NOT be
  36. preempted. You should now exit using Wimp_CloseDown and OS_Exit and per
  37. normal - or if you wish you can continue execution. Note that you should NOT
  38. use Tornado_CloseDown and then Tornado_Initialise again to suspend preemption
  39. for a while - either make your code fully preemptable or don't use this
  40. module at all.
  41.    All threads other than the one calling this also get terminated
  42. *immediately*, so if they have any open file handles or memory they simply
  43. get lost. It might be an idea to terminate all threads through (i) waiting
  44. for them to finish using Tornado_WaitForMultipleObjects or (ii) calling
  45. Tornado_TerminateThread which will cause an exception within the thread and
  46. cause its error handler to be called.
  47.  
  48.  Tornado_Poll                            (&C0002)
  49.  On entry:
  50.   R1=ptr to 256 bytes to have poll data returned into
  51.  On ext:
  52.   R0=wimp poll reason code
  53.  Use:
  54.    Use this call to fetch wimp messages sent to you by other wimp tasks,
  55. preferably in your main thread (ie; your process thread).
  56.    Note however that if you have not called Tornado_Poll recently that the
  57. messages returned may be significantly out of date. Therefore you should
  58. follow the recommendations for writing multithreading applications as
  59. outlined in 'Guidelines'.
  60.  
  61.  ************ THE FOLLOWING SWI'S ARE NOT CURRENTLY IMPLEMENTED ************
  62.  
  63.  Tornado_CreateThread                        (&Cxxxx)
  64.  On entry:
  65.   R0=ptr to security attributes (N/I)
  66.   R1=initial thread stack size in bytes or zero for default
  67.   R2=address of thread function
  68.   R3=argument for new thread
  69.   R4=creation flags (N/I - leave as zero)
  70.  On exit:
  71.   R0 corrupted if R1=0
  72.   R1=thread id
  73.  Use:
  74.    Use this call to create a thread in your code. The security attributes
  75. and the creation flags are currently N/I and should be left as zero.
  76.    If the thread id returned is zero then the thread create has failed.
  77. Examine R0 which will contain the standard error block to see why.
  78.    The thread is entered with a1 (R0) equal to R3 on entry to this
  79. call. The thread code must return an integer which then can be retreived
  80. using Tornado_GetExitCodeThread.
  81.  
  82.  Tornado_ExitThread                        (&Cxxxx)
  83.  On entry:
  84.   R0=exit code
  85.  On exit: Never returns
  86.  Use:
  87.    This call terminates the current thread and attachs the exit code to the
  88. threads handle, and then marks that handle as signaled.
  89.    This is the preferred method of ending a thread. However, the main thread
  90. (as in the one that called Tornado_Initialise) should NOT end by this method
  91. - instead it should call Tornado_Closedown.
  92.  
  93.  Tornado_TerminateThread                    (&Cxxxx)
  94.  On entry:
  95.   R0=thread id
  96.   R1=exit code to be returned by the thread
  97.  On exit: Nothing
  98.  Use:
  99.    This call forcibly terminates a thread. While the thread's stack is
  100. removed and the thread killed off, anything that the thread was doing (eg;
  101. file work etc) will NOT be killed off and thus keep using system resources.
  102. Therefore you should use this call with a great deal of care.
  103.  
  104.  Tornado_ReadMonotonicTime                    (&Cxxxx)
  105.  On entry: Nothing
  106.  On exit:
  107.   R0=low word of timer
  108.   R1=high word of timer
  109.  Use:
  110.    This call returns the value of a timer incremented 1000 times a second.
  111.  
  112.  Tornado_CallAfter                        (&Cxxxx)
  113.  On entry:
  114.   R0=time from now to call routine in ms
  115.   R1=addr of routine
  116.   R2=R12 on entry
  117.  On exit: All preserved
  118.  Use:
  119.    This call calls the specified code in R1 after R0 milliseconds have
  120. elapsed with R12 set to R2 on entry.
  121.  
  122.  
  123.  
  124. 17, 18 & 19 poll code API
  125. -=-=-=-=-=-=-=-=-=-=-=-=-
  126.  
  127. In C, your routine will be called as follows:
  128.  
  129. int routine(int msgno, int msgblk)
  130.  
  131. In assembler, this goes to:
  132.  
  133. R0=poll code number
  134. R1=message block attached to poll code number
  135.  
  136. You should return in R0 a value to indicate what should be done with this
  137. message - 0 causes the message to be placed in the normal message queue to be
  138. handled by Tornado_Poll called by the main process. 1 tells tornado that the
  139. message has been dealt with and to take no further action.
  140.  
  141. Note that any changes you make to the message block pointed to by R1 are
  142. permanent ie; it is directly the message block that will be put in the
  143. message queue if R0=0 on exit. This can be advantageous or not.
  144.  
  145. Note also that this routine is NOT preempted. Therefore you should be fast to
  146. finish your business. Also be aware that your have 256 bytes of stack
  147. available and currently no more - if you extend over that you will invoke the
  148. C stack extender and then things will become very nasty indeed as in fact the
  149. stack resides in 'limbo' in RMA. So *ensure* this doesn't happen.
  150.  
  151. Please see the enclosed C example for how to implement this.
  152.