ARM Club 3/TheARMClub_PDCD3.iso/programs/programming/timectrl/TmrCtlHelp

Text File | 1997-08-13 | 7.2 KB | 222 lines

  TimerCtrl Help File
  ===================

   This module provides a veneer interface to IOC's Timer 1. It allows you to
use the Timer and treat it in a fashion very similar to OS_Byte 19 if you wish.
Other uses are possible too.

TimerCtrl SWI's.
----------------

   The chunk number for TimerCtrl is &459C0. All SWIs have the prefix
'TimerCtrl_'. SWI's in the chunk range are :-

    Offset # | Name
    ---------+-----------------------------------
      0      | Version
      1      | SetRate
      2      | ReadRate
      3      | ActivateTimer
      4      | DeActivateTimer
      5      | WaitForTrigger
      6      | FlagAddress
      7      | ClearFlag
      8      | ReadFlag
      9      | LockTimer
     10      | UnLockTimer
     11      | ReadTimerLock
     12      | SetCodeWord
     13      | ReadCodeWord

SWI Interface details.
----------------------
   TimerCtrl_Version
   On Entry :-
      R0 Undefined.
   On Exit
      R0 Version number * 100
   Use :-
       This SWI identifies the module version to you.

   TimerCtrl_SetRate
   On Entry :-
      R0 timer interval. No larger than &FFFF
   On Exit :-
      R0 preserved.
   Errors :-
      Bad Timing Rate.
   Use :-
       This sets the tick rate of the timer. The value passed in is in 2MHz
   ticks. Due to IOC's limitations you may not specify an interval higher than
   65536 ticks. (&FFFF) This resets the beat counter to zero. If the Timer is
   active it resets the latch - this means the new beat rate won't take effect
   till after an has interupt occured (which is when IOC reloads the counter
   from the latch).

   TimerCtrl_ReadRate
   On Entry :-
      R0 Undefined.
   On Exit :-
      R0 current timer interval.
   Use :-
       This returns the current timer tick rate in 2MHz 'ticks'.

   TimerCtrl_ActivateTimer
   On Entry :-
      nothing
   On Exit :-
      nothing
   Errors :-
      Unable to claim IOC Timer.
      The Timer is already active.
   Use :-
       This kicks the timer routine off with a timer interval as specified by
   the SetRate SWI call.

   TimerCtrl_DeActivateTimer
   On Entry :-
      nothing
   On Exit :-
      nothing
   Errors :-
      The Timer is not active.
      Unable to release vector.
   Use :-
       This shuts the timer down again.

   TimerCtrl_WaitForTrigger
    On Entry :-
       R0 number of 'beats' to wait for.
    On Exit :-
       R0 number of 'beats' that have occured.
    Errors :-
       Timer not active to wait for.
    Use :-
       This SWI seizes control and only returns it when the Timer routine ticks
    off the specified number of 'beats' at the rate specified by
    TimerCtrl_SetRate. Interupts must be enabled or this SWI will never return
    control... It automatically clears the trigger flag to zero when exiting.
    Control is returned when the trigger flag does count higher than the number
    of beats specified. Negative numbers and zero will cause control to be
    returned immediately.

   TimerCtrl_FlagAddress
   On Entry :-
      R0 undefined.
   On Exit :-
      R0 -> flag trigger word
   Use :-
      This returns the address of the flag trigger word. This flag is set non
   zero when the timer does it's next 'click'. This is intended to be primarily
   used with Wimp Pollwords.

   TimerCtrl_ClearFlag
   On Entry :-
      nothing
   On Exit :-
      nothing
   Use :-
       This sets the trigger flag to zero. It is only useful if you do not
   intend using the WaitForTrigger SWI as that SWI automatically handles
   clearing the flag. Again this SWI is intended to be used by applications
   using Wimp Pollwords.

   TimerCtrl_ReadFlag
   On Entry :-
      nothing
   On Exit :-
      R0 current 'flag' count.
   Use :-
       This allows applications to see what the flag count is currently at and
   thus is quite possibly very useful for timing chunks of code...

   TimerCtrl_LockTimer
   On Entry :-
      nothing
   On Exit :-
      nothing
   Errors :-
      Timer already locked.
   Use :-
       Locks the timer. Errors if the Timer is already locked.

   TimerCtrl_UnLockTimer
   On Entry :-
      nothing
   On Exit :-
      nothing
   Use :-
       Unlocks the Timer. Silently does so if the timer is already unlocked.

   TimerCtrl_ReadTimerLock
   On Entry :-
      R0 undefined
   On Exit :-
      R0 contains 0 or 1.
   Use :-
       Returns a 1 or a 0 to indicate whether the Timer is in an locked or
   unlocked state.

   TimerCtrl_SetCodeWord
   On Entry :-
      R0 address to set.
      R1 workspace pointer to be restored as R12 in interupt code.
   On Exit :-
      R0 preserved.
      R1 preserved.
   Use :-
       This SWI takes the address given in R0 and sets it so that the interupt
   routine will jump to that code the next time a beat occurs. The flag
   incrementing is halted while this code jumping is enabled. Setting the
   address to zero disables the function. The code jumped to should return to
   the address given in R14 and should behave according to the rules laid down
   in the PRMs for device drivers. The processor *will* be in IRQ mode with R0
   in an undefined state.
      The standard rules for the paging of memory on interupt driven code also
   apply. (IE don't page the interupt routine out of memory unless you like
   machine crashes.) Finally R1 takes a value that will be restored into R12 as
   a workspace pointer.

   TimerCtrl_ReadCodeWord
   On Entry :-
      R0 undefined
      R1 undefined
   On Exit :-
      R0 current address the code word is set to.
      R1 current workspace pointer for the code.
   Use :-
      This allows programs to query the current setting of the Code Word and
   workspace pointer for the code.

Error Messages.
---------------

   The Error range starts at &8061C0 and ends at &8061CF.

   Error # | Error Message
   --------+-----------------------------------------------------------------
      0    | Unknown TimerCtrl operation.
      1    | Bad Timing Rate.
      2    | The Timer is currently active - we can't change the interval.
      3    | Unable to claim IOC Timer.
      4    | The Timer is already active.
      5    | The Timer is not active.
      6    | Unable to release vector.
      7    | Timer not active to wait for.
      8    | Timer already locked.

  Version History
  =========================================================================
  |Version | Comments.                                                    |
  =========================================================================
  | 0.01   | Initial version. Not fully debugged yet but functional.      |
  |        | (12 Sep 1993)                                                |
  | 0.02   | Added the code word and flag counting functionality.         |
  |        | (16 Sep 1993)                                                |
  | 0.03   | Fixed a few logic errors in the code. (20 Sep 1993)          |
  | 0.04   | Corrected the set code word SWI to actually store the code   |
  |        | address in the right place in workspace. Also added the      |
  |        | ability to specify an R12 value for the interupt code as a   |
  |        | workspace pointer.                                           |
  |        | (13 Aug 1997)                                                |
  =========================================================================