@database "timer"
@master "ADCD_v1.2:IncludesD/Inc&AD1.3/doc/timer.doc"

@Node Main "timer.doc"
@TOC 1.3Includes_Autodocs/Autodocs

@{" --background-- " Link "--background--"}    @{" TR_ADDREQUEST " Link "TR_ADDREQUEST"}
@{" AddTime() " Link "AddTime()"}         @{" TR_GETSYSTIME " Link "TR_GETSYSTIME"}
@{" CmpTime() " Link "CmpTime()"}         @{" TR_SETSYSTIME " Link "TR_SETSYSTIME"}
@{" SubTime() " Link "SubTime()"}

@EndNode

@Node "--background--" "timer.device/--background--"

TIMER REQUEST
    A time request is a non standard IO Request.  It has an @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17}
    followed by a @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structure.

TIMEVAL
    A @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structure consists of two longwords.  The first is
    the number of seconds, the latter is the fractional number
    of microseconds.  The microseconds must always be "normalized"
    e.g. the longword must be between 0 and one million.

UNITS
    The timer contains two units -- one that is precise but
    inaccurate, the other that has little system overhead,
    is very stable over time, but only has limitied resolution.

UNIT_MICROHZ
    This unit uses a programmable timer in the 8520 to keep
    track of its time.  It has precision down to about 2
    microseconds, but will drift as system load increases.
    The timer is typically accurate to within five percent.

UNIT_VBLANK
    This unit is driven by the vertical blank interrupt.  It
    is very stable over time, but only has a resolution of
    16667 microseconds (or 20000 microseconds in PAL land).
    The timer is very cheap to use, and should be used by
    those who are waiting for long periods of time (typically
    1/2 second or more).

LIBRARY
    In addition to the normal device calls, the timer also supports
    three direct, library like calls.  They are for manipulating
    @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structures.  Addition, subtraction, and comparison
    are supported.

BUGS
    In the V1.2/V1.3 release, the timer device has problems with
    very short time requests.  When one of these is made, other
    timer requests may be finished inaccurately.  A side effect
    is that AmigaDOS requests such as "Delay(0);" or
    "WaitForChar(x,0);" are unreliable.

@EndNode

@Node "AddTime()" "timer.device/AddTime"

NAME
    AddTime - add one time request to another

SYNOPSIS
    AddTime( Dest, Source ), timer.device
             A0    A1        A6

    void AddTime(struct *timeval, struct *timeval);

FUNCTION
    This routine adds one @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structure to another.  The
    results are stored in the destination (Dest + Source -> Dest)

    A0 and A1 will be left unchanged

INPUTS
    Dest, Source -- pointers to @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structures.

EXCEPTIONS

SEE ALSO

BUGS

@EndNode

@Node "CmpTime()" "timer.device/CmpTime"

NAME
    CmpTime - Compare two @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structures

SYNOPSIS
    result = CmpTime( Dest, Source ), timer.device
    D0                A0    A1        A6

    BYTE CmpTime(struct *timeval, struct *timeval);

FUNCTION
    This routine compares two @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structures.

    A0 and A1 will be left unchanged

INPUTS
    Dest, Source -- pointers to @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structures.

RESULTS
    result = -1     if Dest has more time than Source
    result =  0     if Dest has the same time as Source
    result = +1     if Dest has less time than Source

EXCEPTIONS

SEE ALSO

BUGS
     Former versions of this AutoDoc had the sense of the result wrong.

@EndNode

@Node "SubTime()" "timer.device/SubTime"

NAME
    SubTime - subtract one time request from another

SYNOPSIS
    SubTime( Dest, Source ), timer.device
             A0    A1        A6

    void SubTime(struct *timeval, struct *timeval);

FUNCTION
    This routine subtracts one @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structure from another.  The
    results are stored in the destination (Dest - Source -> Dest)

    A0 and A1 will be left unchanged

INPUTS
    Dest, Source -- pointers to @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structures.

EXCEPTIONS

SEE ALSO

BUGS

@EndNode

@Node "TR_ADDREQUEST" "timer.device/TR_ADDREQUEST"

NAME
    TR_ADDREQUEST -- submit a request to time time

FUNCTION
    Ask the timer to count off a specified amount of time.  The timer will
    chain this request with its other requests, and will reply the message
    back to the user when the timer counts down to zero.

    The message may be forced to finish early with an @{"AbortIO()/WaitIO()" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/WaitIO()"}
    pair.

TIMER REQUEST
    io_Message      mn_ReplyPort initialized
    io_Device       preset by timer in @{"OpenDevice" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/OpenDevice()"}
    io_Unit         preset by timer in @{"OpenDevice" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/OpenDevice()"}
    io_Command      TR_ADDREQUEST
    io_Flags        IOF_QUICK allowable
    tr_time         a @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structure specifiy how long until
                        the driver will reply

RESULTS
    tr_time         will contain junk

SEE ALSO
    @{"exec/AbortIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/serial/AbortIO()"}
    @{"exec/WaitIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/WaitIO()"}

@EndNode

@Node "TR_GETSYSTIME" "timer.device/TR_GETSYSTIME"

NAME
    TR_GETSYSTIME -- get the system time

FUNCTION
    Ask the timer what time it is.  The system time starts
    off at zero at power on, but may be initialized via
    the @{"TR_SETSYSTIME" Link "TR_SETSYSTIME"} call.

    System time is monotonically increasing, and guaranteed
    to be unique (except of someone sets the time backwards).
    The time is incremented every vertical blank by the
    vertical blanking interval;  in addition it is changed
    every time someone asks what time it is.  This way
    the return value of the system time is unique
    and unrepeating.

TIMER REQUEST
    io_Message      mn_ReplyPort initialized
    io_Device       preset by timer in @{"OpenDevice" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/OpenDevice()"}
    io_Unit         preset by timer in @{"OpenDevice" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/OpenDevice()"}
    io_Command      @{"TR_ADDREQUEST" Link "TR_ADDREQUEST"}
    io_Flags        IOF_QUICK allowable

RESULTS
    tr_time         the @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structure will be filled in with
                        the current system time

@EndNode

@Node "TR_SETSYSTIME" "timer.device/TR_SETSYSTIME"

NAME
    TR_SETSYSTIME -- set the system time

FUNCTION
    Set the systems idea of what time it is.  The system
    starts out at time "zero" so it is safe to set it
    forward to the "real" time.  However care should be taken
    when setting the time backwards.  System time
    is speced as being monotonically increasing.

TIMER REQUEST
    io_Message      mn_ReplyPort initialized
    io_Device       preset by timer in @{"OpenDevice" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/OpenDevice()"}
    io_Unit         preset by timer in @{"OpenDevice" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/OpenDevice()"}
    io_Command      @{"TR_ADDREQUEST" Link "TR_ADDREQUEST"}
    io_Flags        IOF_QUICK allowable
    tr_time         a @{"timeval" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/timer.h/Main" 22} structure with the current system
                       time

RESULTS
    none

@EndNode

