home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / programming / timectrl / TmrCtlHelp < prev   
Text File  |  1997-08-13  |  7KB  |  222 lines
  1.   TimerCtrl Help File
  2.   ===================
  3.  
  4.    This module provides a veneer interface to IOC's Timer 1. It allows you to
  5. use the Timer and treat it in a fashion very similar to OS_Byte 19 if you wish.
  6. Other uses are possible too.
  7.  
  8. TimerCtrl SWI's.
  9. ----------------
  10.  
  11.    The chunk number for TimerCtrl is &459C0. All SWIs have the prefix
  12. 'TimerCtrl_'. SWI's in the chunk range are :-
  13.  
  14.     Offset # | Name
  15.     ---------+-----------------------------------
  16.       0      | Version
  17.       1      | SetRate
  18.       2      | ReadRate
  19.       3      | ActivateTimer
  20.       4      | DeActivateTimer
  21.       5      | WaitForTrigger
  22.       6      | FlagAddress
  23.       7      | ClearFlag
  24.       8      | ReadFlag
  25.       9      | LockTimer
  26.      10      | UnLockTimer
  27.      11      | ReadTimerLock
  28.      12      | SetCodeWord
  29.      13      | ReadCodeWord
  30.  
  31. SWI Interface details.
  32. ----------------------
  33.    TimerCtrl_Version
  34.    On Entry :-
  35.       R0 Undefined.
  36.    On Exit
  37.       R0 Version number * 100
  38.    Use :-
  39.        This SWI identifies the module version to you.
  40.  
  41.    TimerCtrl_SetRate
  42.    On Entry :-
  43.       R0 timer interval. No larger than &FFFF
  44.    On Exit :-
  45.       R0 preserved.
  46.    Errors :-
  47.       Bad Timing Rate.
  48.    Use :-
  49.        This sets the tick rate of the timer. The value passed in is in 2MHz
  50.    ticks. Due to IOC's limitations you may not specify an interval higher than
  51.    65536 ticks. (&FFFF) This resets the beat counter to zero. If the Timer is
  52.    active it resets the latch - this means the new beat rate won't take effect
  53.    till after an has interupt occured (which is when IOC reloads the counter
  54.    from the latch).
  55.  
  56.    TimerCtrl_ReadRate
  57.    On Entry :-
  58.       R0 Undefined.
  59.    On Exit :-
  60.       R0 current timer interval.
  61.    Use :-
  62.        This returns the current timer tick rate in 2MHz 'ticks'.
  63.  
  64.    TimerCtrl_ActivateTimer
  65.    On Entry :-
  66.       nothing
  67.    On Exit :-
  68.       nothing
  69.    Errors :-
  70.       Unable to claim IOC Timer.
  71.       The Timer is already active.
  72.    Use :-
  73.        This kicks the timer routine off with a timer interval as specified by
  74.    the SetRate SWI call.
  75.  
  76.    TimerCtrl_DeActivateTimer
  77.    On Entry :-
  78.       nothing
  79.    On Exit :-
  80.       nothing
  81.    Errors :-
  82.       The Timer is not active.
  83.       Unable to release vector.
  84.    Use :-
  85.        This shuts the timer down again.
  86.  
  87.    TimerCtrl_WaitForTrigger
  88.     On Entry :-
  89.        R0 number of 'beats' to wait for.
  90.     On Exit :-
  91.        R0 number of 'beats' that have occured.
  92.     Errors :-
  93.        Timer not active to wait for.
  94.     Use :-
  95.        This SWI seizes control and only returns it when the Timer routine ticks
  96.     off the specified number of 'beats' at the rate specified by
  97.     TimerCtrl_SetRate. Interupts must be enabled or this SWI will never return
  98.     control... It automatically clears the trigger flag to zero when exiting.
  99.     Control is returned when the trigger flag does count higher than the number
  100.     of beats specified. Negative numbers and zero will cause control to be
  101.     returned immediately.
  102.  
  103.    TimerCtrl_FlagAddress
  104.    On Entry :-
  105.       R0 undefined.
  106.    On Exit :-
  107.       R0 -> flag trigger word
  108.    Use :-
  109.       This returns the address of the flag trigger word. This flag is set non
  110.    zero when the timer does it's next 'click'. This is intended to be primarily
  111.    used with Wimp Pollwords.
  112.  
  113.    TimerCtrl_ClearFlag
  114.    On Entry :-
  115.       nothing
  116.    On Exit :-
  117.       nothing
  118.    Use :-
  119.        This sets the trigger flag to zero. It is only useful if you do not
  120.    intend using the WaitForTrigger SWI as that SWI automatically handles
  121.    clearing the flag. Again this SWI is intended to be used by applications
  122.    using Wimp Pollwords.
  123.  
  124.    TimerCtrl_ReadFlag
  125.    On Entry :-
  126.       nothing
  127.    On Exit :-
  128.       R0 current 'flag' count.
  129.    Use :-
  130.        This allows applications to see what the flag count is currently at and
  131.    thus is quite possibly very useful for timing chunks of code...
  132.  
  133.    TimerCtrl_LockTimer
  134.    On Entry :-
  135.       nothing
  136.    On Exit :-
  137.       nothing
  138.    Errors :-
  139.       Timer already locked.
  140.    Use :-
  141.        Locks the timer. Errors if the Timer is already locked.
  142.  
  143.    TimerCtrl_UnLockTimer
  144.    On Entry :-
  145.       nothing
  146.    On Exit :-
  147.       nothing
  148.    Use :-
  149.        Unlocks the Timer. Silently does so if the timer is already unlocked.
  150.  
  151.    TimerCtrl_ReadTimerLock
  152.    On Entry :-
  153.       R0 undefined
  154.    On Exit :-
  155.       R0 contains 0 or 1.
  156.    Use :-
  157.        Returns a 1 or a 0 to indicate whether the Timer is in an locked or
  158.    unlocked state.
  159.  
  160.    TimerCtrl_SetCodeWord
  161.    On Entry :-
  162.       R0 address to set.
  163.       R1 workspace pointer to be restored as R12 in interupt code.
  164.    On Exit :-
  165.       R0 preserved.
  166.       R1 preserved.
  167.    Use :-
  168.        This SWI takes the address given in R0 and sets it so that the interupt
  169.    routine will jump to that code the next time a beat occurs. The flag
  170.    incrementing is halted while this code jumping is enabled. Setting the
  171.    address to zero disables the function. The code jumped to should return to
  172.    the address given in R14 and should behave according to the rules laid down
  173.    in the PRMs for device drivers. The processor *will* be in IRQ mode with R0
  174.    in an undefined state.
  175.       The standard rules for the paging of memory on interupt driven code also
  176.    apply. (IE don't page the interupt routine out of memory unless you like
  177.    machine crashes.) Finally R1 takes a value that will be restored into R12 as
  178.    a workspace pointer.
  179.  
  180.    TimerCtrl_ReadCodeWord
  181.    On Entry :-
  182.       R0 undefined
  183.       R1 undefined
  184.    On Exit :-
  185.       R0 current address the code word is set to.
  186.       R1 current workspace pointer for the code.
  187.    Use :-
  188.       This allows programs to query the current setting of the Code Word and
  189.    workspace pointer for the code.
  190.  
  191. Error Messages.
  192. ---------------
  193.  
  194.    The Error range starts at &8061C0 and ends at &8061CF.
  195.  
  196.    Error # | Error Message
  197.    --------+-----------------------------------------------------------------
  198.       0    | Unknown TimerCtrl operation.
  199.       1    | Bad Timing Rate.
  200.       2    | The Timer is currently active - we can't change the interval.
  201.       3    | Unable to claim IOC Timer.
  202.       4    | The Timer is already active.
  203.       5    | The Timer is not active.
  204.       6    | Unable to release vector.
  205.       7    | Timer not active to wait for.
  206.       8    | Timer already locked.
  207.  
  208.   Version History
  209.   =========================================================================
  210.   |Version | Comments.                                                    |
  211.   =========================================================================
  212.   | 0.01   | Initial version. Not fully debugged yet but functional.      |
  213.   |        | (12 Sep 1993)                                                |
  214.   | 0.02   | Added the code word and flag counting functionality.         |
  215.   |        | (16 Sep 1993)                                                |
  216.   | 0.03   | Fixed a few logic errors in the code. (20 Sep 1993)          |
  217.   | 0.04   | Corrected the set code word SWI to actually store the code   |
  218.   |        | address in the right place in workspace. Also added the      |
  219.   |        | ability to specify an R12 value for the interupt code as a   |
  220.   |        | workspace pointer.                                           |
  221.   |        | (13 Aug 1997)                                                |
  222.   =========================================================================