home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD1.3 / Text_Autodocs / timer.doc < prev    next >
Encoding:
Text File  |  1992-09-12  |  6.4 KB  |  225 lines
  1. TABLE OF CONTENTS
  2.  
  3. timer.device/--background--
  4. timer.device/AddTime
  5. timer.device/CmpTime
  6. timer.device/SubTime
  7. timer.device/TR_ADDREQUEST
  8. timer.device/TR_GETSYSTIME
  9. timer.device/TR_SETSYSTIME
  10.  
  11.  
  12. timer.device/--background--                   timer.device/--background--
  13.  
  14.    TIMER REQUEST
  15.        A time request is a non standard IO Request.  It has an IORequest
  16.        followed by a timeval structure.
  17.  
  18.    TIMEVAL
  19.        A timeval structure consists of two longwords.  The first is
  20.        the number of seconds, the latter is the fractional number
  21.        of microseconds.  The microseconds must always be "normalized"
  22.        e.g. the longword must be between 0 and one million.
  23.  
  24.    UNITS
  25.        The timer contains two units -- one that is precise but
  26.        inaccurate, the other that has little system overhead,
  27.        is very stable over time, but only has limitied resolution.
  28.  
  29.    UNIT_MICROHZ
  30.        This unit uses a programmable timer in the 8520 to keep
  31.        track of its time.  It has precision down to about 2
  32.        microseconds, but will drift as system load increases.
  33.        The timer is typically accurate to within five percent.
  34.  
  35.    UNIT_VBLANK
  36.        This unit is driven by the vertical blank interrupt.  It
  37.        is very stable over time, but only has a resolution of
  38.        16667 microseconds (or 20000 microseconds in PAL land).
  39.        The timer is very cheap to use, and should be used by
  40.        those who are waiting for long periods of time (typically
  41.        1/2 second or more).
  42.  
  43.    LIBRARY
  44.     In addition to the normal device calls, the timer also supports
  45.     three direct, library like calls.  They are for manipulating
  46.     timeval structures.  Addition, subtraction, and comparison
  47.     are supported.
  48.  
  49.    BUGS
  50.     In the V1.2/V1.3 release, the timer device has problems with
  51.     very short time requests.  When one of these is made, other
  52.     timer requests may be finished inaccurately.  A side effect
  53.     is that AmigaDOS requests such as "Delay(0);" or
  54.     "WaitForChar(x,0);" are unreliable. 
  55.  
  56. timer.device/AddTime                                       timer.device/AddTime
  57.  
  58.    NAME
  59.     AddTime - add one time request to another
  60.  
  61.    SYNOPSIS
  62.     AddTime( Dest, Source ), timer.device
  63.              A0    A1     A6
  64.  
  65.         void AddTime(struct *timeval, struct *timeval);
  66.  
  67.    FUNCTION
  68.     This routine adds one timeval structure to another.  The
  69.     results are stored in the destination (Dest + Source -> Dest)
  70.  
  71.     A0 and A1 will be left unchanged
  72.  
  73.    INPUTS
  74.     Dest, Source -- pointers to timeval structures.
  75.  
  76.    EXCEPTIONS
  77.  
  78.    SEE ALSO
  79.  
  80.    BUGS
  81.  
  82.  
  83. timer.device/CmpTime                                       timer.device/CmpTime
  84.  
  85.    NAME
  86.     CmpTime - Compare two timeval structures
  87.  
  88.    SYNOPSIS
  89.     result = CmpTime( Dest, Source ), timer.device
  90.     D0                A0    A1      A6
  91.  
  92.         BYTE CmpTime(struct *timeval, struct *timeval);
  93.  
  94.    FUNCTION
  95.     This routine compares two timeval structures.
  96.  
  97.     A0 and A1 will be left unchanged
  98.  
  99.    INPUTS
  100.     Dest, Source -- pointers to timeval structures.
  101.  
  102.    RESULTS
  103.     result = -1    if Dest has more time than Source
  104.     result =  0    if Dest has the same time as Source
  105.     result = +1    if Dest has less time than Source
  106.  
  107.    EXCEPTIONS
  108.  
  109.    SEE ALSO
  110.  
  111.    BUGS
  112.         Former versions of this AutoDoc had the sense of the result wrong.
  113.  
  114.  
  115. timer.device/SubTime                                       timer.device/SubTime
  116.  
  117.    NAME
  118.     SubTime - subtract one time request from another
  119.  
  120.    SYNOPSIS
  121.     SubTime( Dest, Source ), timer.device
  122.              A0    A1     A6
  123.  
  124.         void SubTime(struct *timeval, struct *timeval);
  125.  
  126.    FUNCTION
  127.     This routine subtracts one timeval structure from another.  The
  128.     results are stored in the destination (Dest - Source -> Dest)
  129.  
  130.     A0 and A1 will be left unchanged
  131.  
  132.    INPUTS
  133.     Dest, Source -- pointers to timeval structures.
  134.  
  135.    EXCEPTIONS
  136.  
  137.    SEE ALSO
  138.  
  139.    BUGS
  140.  
  141.  
  142. timer.device/TR_ADDREQUEST                           timer.device/TR_ADDREQUEST
  143.  
  144.    NAME
  145.        TR_ADDREQUEST -- submit a request to time time
  146.  
  147.    FUNCTION
  148.        Ask the timer to count off a specified amount of time.  The timer will
  149.        chain this request with its other requests, and will reply the message
  150.        back to the user when the timer counts down to zero.
  151.  
  152.        The message may be forced to finish early with an AbortIO()/WaitIO()
  153.        pair.
  154.  
  155.    TIMER REQUEST
  156.        io_Message      mn_ReplyPort initialized
  157.        io_Device       preset by timer in OpenDevice
  158.        io_Unit         preset by timer in OpenDevice
  159.        io_Command      TR_ADDREQUEST
  160.        io_Flags        IOF_QUICK allowable
  161.        tr_time         a timeval structure specifiy how long until
  162.                            the driver will reply
  163.  
  164.    RESULTS
  165.        tr_time         will contain junk
  166.  
  167.    SEE ALSO
  168.        exec/AbortIO
  169.        exec/WaitIO
  170.  
  171. timer.device/TR_GETSYSTIME                           timer.device/TR_GETSYSTIME
  172.  
  173.    NAME
  174.        TR_GETSYSTIME -- get the system time
  175.  
  176.    FUNCTION
  177.        Ask the timer what time it is.  The system time starts
  178.        off at zero at power on, but may be initialized via
  179.        the TR_SETSYSTIME call.
  180.  
  181.        System time is monotonically increasing, and guaranteed
  182.        to be unique (except of someone sets the time backwards).
  183.        The time is incremented every vertical blank by the
  184.        vertical blanking interval;  in addition it is changed
  185.        every time someone asks what time it is.  This way
  186.        the return value of the system time is unique
  187.        and unrepeating.
  188.  
  189.    TIMER REQUEST
  190.        io_Message      mn_ReplyPort initialized
  191.        io_Device       preset by timer in OpenDevice
  192.        io_Unit         preset by timer in OpenDevice
  193.        io_Command      TR_ADDREQUEST
  194.        io_Flags        IOF_QUICK allowable
  195.  
  196.    RESULTS
  197.        tr_time         the timeval structure will be filled in with
  198.                            the current system time
  199.  
  200.  
  201. timer.device/TR_SETSYSTIME                           timer.device/TR_SETSYSTIME
  202.  
  203.    NAME
  204.        TR_SETSYSTIME -- set the system time
  205.  
  206.    FUNCTION
  207.        Set the systems idea of what time it is.  The system
  208.        starts out at time "zero" so it is safe to set it
  209.        forward to the "real" time.  However care should be taken
  210.        when setting the time backwards.  System time
  211.        is speced as being monotonically increasing.
  212.  
  213.    TIMER REQUEST
  214.        io_Message      mn_ReplyPort initialized
  215.        io_Device       preset by timer in OpenDevice
  216.        io_Unit         preset by timer in OpenDevice
  217.        io_Command      TR_ADDREQUEST
  218.        io_Flags        IOF_QUICK allowable
  219.        tr_time         a timeval structure with the current system
  220.                           time
  221.  
  222.    RESULTS
  223.        none
  224.  
  225.