home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / inc&ad2.0 / text_autodocs / timer.doc < prev    next >
Text File  |  1992-09-01  |  10KB  |  381 lines
  1. TABLE OF CONTENTS
  2.  
  3. timer.device/--background--
  4. timer.device/AbortIO
  5. timer.device/AddTime
  6. timer.device/CmpTime
  7. timer.device/GetSysTime
  8. timer.device/ReadEClock
  9. timer.device/SubTime
  10. timer.device/TR_ADDREQUEST
  11. timer.device/TR_GETSYSTIME
  12. timer.device/TR_SETSYSTIME
  13. timer.device/--background--                       timer.device/--background--
  14.  
  15.    TIMER REQUEST
  16.     A time request is a non standard IO Request.  It has an IORequest
  17.     followed by a timeval structure or an eclockval structure.
  18.  
  19.    TIMEVAL
  20.     A timeval structure consists of two longwords.  The first is
  21.     the number of seconds, the latter is the fractional number
  22.     of microseconds.  The microseconds must always be "normalized"
  23.     e.g. the longword must be between 0 and one million.
  24.  
  25.    ECLOCKVAL
  26.     A eclockval structure consists of two longwords.  The first is
  27.     the high order 32 bits of a 64 bit number and the second is the
  28.     the low order 32 bits.  The 64 bit number is a count of "E" clock
  29.     ticks.  The "E" clock frequency is related to the master clock
  30.     frequency of the machine and can be determined by calling the
  31.     ReadEClock() library like call.
  32.  
  33.    UNITS
  34.     The timer contains five units -- two designed to accuratly measure
  35.     short intervals, one that has little system overhead and is very
  36.     stable over time, and two that work like an alarm clock.
  37.  
  38.    UNIT_MICROHZ
  39.     This unit uses the programmable timers in the 8520s to keep track
  40.     of its time.  It has precision down to about 2 microseconds, but
  41.     will drift as system load increases.  The accuracy of this unit
  42.     is the same as that of the master clock of the machine.  This unit
  43.     uses a timeval in its timerequest.
  44.  
  45.    UNIT_VBLANK
  46.     This unit uses a strobe from the power supply to keep track of its
  47.     time or the "E" clock on machines without power supply strobes.
  48.     It is very stable over time, but only has a resolution of that of
  49.     the vertical blank interrupt.  This unit is very cheap to use, and
  50.     should be used by those who are waiting for long periods of time
  51.     (typically 1/2 second or more).  This unit uses a timeval in its
  52.     timerequest.
  53.  
  54.    UNIT_ECLOCK
  55.     This unit is exacly the same as UNIT_MICROHZ except that it uses
  56.     an eclockval instead of a timeval in its timerequest.
  57.  
  58.    UNIT_WAITUNTIL
  59.     This unit waits until the systime is greater than or equal to the
  60.     time in the timeval in the timerequest.  This unit has the same
  61.     resolution and accuracy as that of UNIT_VBLANK.
  62.  
  63.    UNIT_WAITECLOCK
  64.     This unit waits until the E-Clock value as returned by ReadEClock()
  65.     is greater than or equal to the eclockval in the timerequest. This
  66.     unit has the same resolution and accuracy as that of UNIT_ECLOCK.
  67.  
  68.    LIBRARY
  69.     In addition to the normal device calls, the timer also supports
  70.     several direct, library like calls.
  71.  
  72.    BUGS
  73.     In the V1.2/V1.3 release, the timer device has problems with
  74.     very short time requests.  When one of these is made, other
  75.     timer requests may be finished inaccurately.  A side effect
  76.     is that AmigaDOS requests such as "Delay(0);" or
  77.     "WaitForChar(x,0);" are unreliable. 
  78.  
  79. timer.device/AbortIO                                     timer.device/AbortIO
  80.  
  81.    NAME
  82.     AbortIO -- Remove an existing timer request.
  83.  
  84.    SYNOPSIS
  85.     error = AbortIO( timerequest )
  86.     D0               A1
  87.  
  88.     LONG AbortIO( struct timerequest * );
  89.  
  90.    FUNCTION
  91.     This is an exec.library call.
  92.  
  93.     This routine removes a timerquest from the timer.  It runs in
  94.     the context of the caller.
  95.  
  96.    INPUTS
  97.     timerequest - the timer request to be aborted
  98.  
  99.    RETURNS
  100.     0  if the request was aborted, io_Error will also be set to
  101.         IOERR_ABORTED.
  102.     -1 otherwise
  103.  
  104.    NOTES
  105.     This function may be called from interrupts.
  106.  
  107.    SEE ALSO
  108.     exec.library/AbortIO()
  109.  
  110.    BUGS
  111.  
  112. timer.device/AddTime                                     timer.device/AddTime
  113.  
  114.    NAME
  115.     AddTime -- Add one time request to another.
  116.  
  117.    SYNOPSIS
  118.     AddTime( Dest, Source )
  119.              A0    A1
  120.  
  121.     void AddTime( struct timeval *, struct timeval *);
  122.  
  123.    FUNCTION
  124.     This routine adds one timeval structure to another.  The
  125.     results are stored in the destination (Dest + Source -> Dest)
  126.  
  127.     A0 and A1 will be left unchanged
  128.  
  129.    INPUTS
  130.     Dest, Source -- pointers to timeval structures.
  131.  
  132.    NOTES
  133.     This function may be called from interrupts.
  134.  
  135.    SEE ALSO
  136.     timer.device/CmpTime(),
  137.     timer.device/SubTime()
  138.  
  139.    BUGS
  140.  
  141. timer.device/CmpTime                                     timer.device/CmpTime
  142.  
  143.    NAME
  144.     CmpTime -- Compare two timeval structures.
  145.  
  146.    SYNOPSIS
  147.     result = CmpTime( Dest, Source )
  148.     D0                A0    A1
  149.  
  150.     LONG CmpTime( struct timeval *, struct timeval *);
  151.  
  152.    FUNCTION
  153.     This routine compares timeval structures
  154.  
  155.     A0 and A1 will be left unchanged
  156.  
  157.    INPUTS
  158.     Dest, Source -- pointers to timeval structures.
  159.  
  160.    RESULTS
  161.     result will be   0 if Dest has same time as source
  162.                     -1 if Dest has more time than source
  163.                     +1 if Dest has less time than source
  164.  
  165.    NOTES
  166.     This function may be called from interrupts.
  167.  
  168.    SEE ALSO
  169.     timer.device/AddTime(),
  170.     timer.device/SubTime()
  171.  
  172.    BUGS
  173.     Older version of this document had the sense of the return
  174.     codes wrong; the code hasn't changed but the document has.
  175.  
  176. timer.device/GetSysTime                               timer.device/GetSysTime
  177.  
  178.    NAME
  179.     GetSysTime -- Get the system time. (V36)
  180.  
  181.    SYNOPSIS
  182.     GetSysTime( Dest )
  183.                 A0
  184.  
  185.     void GetSysTime( struct timeval * );
  186.  
  187.    FUNCTION
  188.     Ask the system what time it is.  The system time starts off at
  189.     zero at power on, but may be initialized via the TR_SETSYSTIME
  190.     timer.device command.
  191.  
  192.     System time is monotonocally increasing and guarenteed to be
  193.     unique (except when the system time is set back).
  194.  
  195.     A0 will be left unchanged.
  196.  
  197.     This function is less expensive to use than the TR_GETSYSTIME
  198.     IORequest.
  199.  
  200.    INPUTS
  201.     Dest -- pointer to a timeval structure to hold the system time.
  202.  
  203.    RESULTS
  204.     Dest -- the timeval structure will contain the system time.
  205.  
  206.    NOTES
  207.     This function may be called from interrupts.
  208.  
  209.    SEE ALSO
  210.     timer.device/TR_GETSYSTIME,
  211.     timer.device/TR_SETSYSTIME,
  212.  
  213.    BUGS
  214.  
  215. timer.device/ReadEClock                               timer.device/ReadEClock
  216.  
  217.    NAME
  218.     ReadEClock -- Get the current value of the E-Clock. (V36)
  219.  
  220.    SYNOPSIS
  221.     E_Freq = ReadEClock( Dest )
  222.     D0                   A0
  223.  
  224.     ULONG ReadEClock ( struct EClockVal * );
  225.  
  226.    FUNCTION
  227.     This routine calculates the current 64 bit value of the E-Clock
  228.     and stores it in the destination EClockVal structure. The count
  229.     rate of the E-Clock is also returned.
  230.  
  231.     A0 will be left unchanged
  232.  
  233.     This is a low overhead function designed so that very short
  234.     intervals may be timed.
  235.  
  236.    INPUTS
  237.     Dest -- pointer to an EClockVal structure.
  238.  
  239.    RETURNS
  240.     Dest -- the EClockVal structure will contain the E-Clock time
  241.     E_Freq -- The count rate of the E-Clock (tics/sec).
  242.  
  243.    NOTES
  244.     This function may be called from interrupts.
  245.  
  246.    SEE ALSO
  247.  
  248.    BUGS
  249.  
  250. timer.device/SubTime                                     timer.device/SubTime
  251.  
  252.    NAME
  253.     SubTime -- Subtract one time request from another.
  254.  
  255.    SYNOPSIS
  256.     SubTime( Dest, Source )
  257.              A0    A1
  258.  
  259.     void SubTime( struct timeval *, struct timeval *);
  260.  
  261.    FUNCTION
  262.     This routine subtracts one timeval structure from another.  The
  263.     results are stored in the destination (Dest - Source -> Dest)
  264.  
  265.     A0 and A1 will be left unchanged
  266.  
  267.    INPUTS
  268.     Dest, Source -- pointers to timeval structures.
  269.  
  270.    NOTES
  271.     This function may be called from interrupts.
  272.  
  273.    SEE ALSO
  274.     timer.device/AddTime(),
  275.     timer.device/CmpTime()
  276.  
  277.    BUGS
  278.  
  279. timer.device/TR_ADDREQUEST                         timer.device/TR_ADDREQUEST
  280.  
  281.    NAME
  282.     TR_ADDREQUEST -- Submit a request to wait a period of time.
  283.  
  284.    FUNCTION
  285.     Ask the timer to wait a specified amount of time before
  286.     replying the timerequest.
  287.  
  288.     The message may be forced to finish early with an
  289.     AbortIO()/WaitIO() pair.
  290.  
  291.    TIMER REQUEST
  292.     io_Message      mn_ReplyPort initialized
  293.     io_Device       preset by timer in OpenDevice
  294.     io_Unit         preset by timer in OpenDevice
  295.     io_Command      TR_ADDREQUEST
  296.     io_Flags        IOF_QUICK permitted (but ignored)
  297.     tr_time         a timeval structure specifying how long the 
  298.                         device will wait before replying
  299.  
  300.    RESULTS
  301.     tr_time         will be zeroed
  302.  
  303.    NOTES
  304.     This function may be called from interrupts.
  305.  
  306.     Previous to 2.0, the tr_time field was documented as containing
  307.     junk when the timerequest was returned.
  308.  
  309.    SEE ALSO
  310.     timer.device/AbortIO(),
  311.     timer.device/TimeDelay(),
  312.  
  313.    BUGS
  314.  
  315. timer.device/TR_GETSYSTIME                         timer.device/TR_GETSYSTIME
  316.  
  317.    NAME
  318.     TR_GETSYSTIME -- get the system time.
  319.  
  320.    FUNCTION
  321.     Ask the system what time it is.  The system time starts off at
  322.     zero at power on, but may be initialized via the TR_SETSYSTIME
  323.     call.
  324.  
  325.     System time is monotonically increasing, and guaranteed to be
  326.     unique (except when the system time is set backwards).
  327.  
  328.    TIMER REQUEST
  329.     io_Message      mn_ReplyPort initialized
  330.     io_Device       preset by timer in OpenDevice
  331.     io_Unit         preset by timer in OpenDevice
  332.     io_Command      TR_GETSYSTIME
  333.     io_Flags        IOF_QUICK permitted
  334.  
  335.    RESULTS
  336.     tr_time         a timeval structure with the current system
  337.                         time
  338.  
  339.    NOTES
  340.     This function may be called from interrupts.
  341.  
  342.    SEE ALSO
  343.     timer.device/TR_SETSYSTIME,
  344.     timer.device/GetSysTime(),
  345.  
  346.    BUGS
  347.  
  348. timer.device/TR_SETSYSTIME                         timer.device/TR_SETSYSTIME
  349.  
  350.    NAME
  351.     TR_SETSYSTIME -- Set the system time.
  352.  
  353.    FUNCTION
  354.     Set the system idea of what time it is.  The system starts out
  355.     at time "zero" so it is safe to set it forward to the real
  356.     time.  However, care should be taken when setting the time
  357.     backwards.  System time is generally expected to monotonically
  358.     increasing.
  359.  
  360.    TIMER REQUEST
  361.     io_Message      mn_ReplyPort initialized
  362.     io_Device       preset by timer in OpenDevice
  363.     io_Unit         preset by timer in OpenDevice
  364.     io_Command      TR_GETSYSTIME
  365.     io_Flags        IOF_QUICK permitted
  366.     tr_time         a timeval structure with the current system
  367.                         time
  368.  
  369.    RESULTS
  370.     tr_time         will contain junk
  371.  
  372.    NOTES
  373.     This function may be called from interrupts.
  374.  
  375.    SEE ALSO
  376.     timer.device/TR_GETSYSTIME,
  377.     timer.device/GetSysTime(),
  378.  
  379.    BUGS
  380.  
  381.