system_clock(3K) DG/UX 5.4R3.00 system_clock(3K)
NAME
systemclock: vpestablishtimeout, vpcanceltimeout,
vpspecifymaxtimeouts, vpunspecifymaxtimeouts,
vpcreateclockevent, tmreadsystemclock - manipulate the system
clock
SYNOPSIS
#include "/usr/src/uts/aviion/ii/ivp.h"
#include "/usr/src/uts/aviion/ii/imisc.h"
#include "/usr/src/uts/aviion/ii/itm.h"
void vpcanceltimeout (timeoutid)
opaque32type timeoutid; /*READ ONLY*/
void vpcreateclockevent (eventptr, incrementptr)
vpeventptrtype eventptr; /*WRITE ONLY*/
miscclockvalueptrtype incrementptr; /*READ ONLY*/
opaque32type vpestablishtimeout (timeptr, routineptr, argument)
miscclockvalueptrtype timeptr; /*READ ONLY*/
vptimeoutroutineptrtype routineptr; /*READ ONLY*/
bit32etype argument; /*READ ONLY*/
void tmreadsystemclock (currtimeptr)
miscclockvalueptrtype currtimeptr; /*READ ONLY*/
void vpspecifymaxtimeouts (count)
uint32type count; /*READ ONLY*/
void vpunspecifymaxtimeouts (count)
uint32type count; /*READONLY*/
where:
argument A 32-bit value that is to be passed to the timeout
routine as an argument.
count The number of timeouts for which to reserve or release
space.
currtimeptr A pointer to where the current value of the system
clock is to be written.
eventptr A pointer to the event that is to be set up.
incrementptr Pointer to clock value to be added to current system
time. For increment values, use the clock constants
listed below under Constants and Data Structures.
routineptr A pointer to a routine that is to be called when the
timeout occurs.
timeptr A pointer to a clock value indicating the amount of
real time that is to elapse before the timeout occurs.
For increment values, use the clock constants listed
below under Constants and Data Structures.
timeoutid An opaque 32-bit identifier, the timeout ID of the
timeout to be canceled. This value is returned by the
vpestablishtimeout routine.
Licensed material--property of copyright holder(s) 1
system_clock(3K) DG/UX 5.4R3.00 system_clock(3K)
DESCRIPTION
The following routines are described in this man page:
vpestablishtimeout Establish a timeout
vpcanceltimeout Cancel a previously established timeout
vpspecifymaxtimeouts Reserve space for timeouts
vpunspecifymaxtimeouts Free space for timeouts
vpcreateclockevent Set up clock event for future time
tmreadsystemclock Return current value of system clock
Overview to Using Clock Routines
The kernel provides three sets of clock routines: 1) routines to
create an event that will occur at a specified time; 2) routines to
establish and cancel timeouts; and 3) a routine to read the system
clock.
The kernel maintains time via the system clock. The system clock is
a 64-bit logical counter that increments at a fixed rate in real
time. The counter is given value zero at system boot time. System
clock values are continuous and monotonically increasing. Continuous
means that the value of the system clock is not changed even if the
external time-of-day is changed. Therefore, you can use the system
clock to time intervals knowing its value will not be reset during
the interval.
The system clock maintains the time since the system was booted in
miscclockvaluetype units. A miscclockvaluetype unit is a
64-bit value where the high order 32 bits represent seconds and the
low order 32 bits represent a fraction of a second. The number of
significant bits in the fractional part of a second is determined by
the accuracy of the architecture-dependent hardware clock used to
implement the system time. miscclockvaluetype and pre-defined
values for it are shown in the Constants and Data Structures
subsection.
You can read the system clock using the vpreadsystemclock routine.
This may be useful for applications that are doing timing intervals.
The clock routines also let you schedule events based on system time.
You can use these clock events either asynchronously (time-outs) or
synchronously (clock events). You use clock eventcounters to await
for a time interval synchronously (suspended and thus without
continuing processing). You use the routine vpcreateclockevent to
create a clock event that will occur after some specified system time
interval. After you create the event, you await it using the
vpawaitec routine described in eventcounters(3K). That man page
also describes other routines you can use in manipulating
eventcounters. The following sample shows how to create a clock
event that will occur in 5 seconds:
vpcreateclockevent(&delayevent, &miscfiveseconds);
vpawaitec(&delayevent, (int32type)1, &resultindex);
Clock events are typically used in synchronous I/O requests. In this
application the driver will issue an I/O request and then suspend
waiting for one of three events to occur: the completion of the I/O
Licensed material--property of copyright holder(s) 2
system_clock(3K) DG/UX 5.4R3.00 system_clock(3K)
request; a time-out of the I/O request; or termination of the I/O
LWP. Upon awakening, the driver determines which event occurred and
performs the appropriate operations.
The DG/UX system provides time-out services for doing asynchronous
processing. With a time-out, the kernel is directed to call a
specified routine after a specified interval expires.
The kernel needs a certain amount of data space to handle a time-out.
Since it allocates this space dynamically at run-time, you must
declare the amount of space you will need. You do this by calling
vpspecifymaxtimeouts.
Be rational when setting this value; try not to allocate too many or
too few time-outs. Allocating too few time-outs is particularly
dangerous. If you ask for more than the specified maxtimeouts, the
system will panic because of insufficient resources. You should make
sure that you never have more concurrent time-outs than you
specified. The concurrency of time-outs, then, is also critical.
The time-out routines vpestablishtimeout and vpcanceltimeout are
a matched set. One establishes the time-out and the other cancels
it; the time-out is still current until you call vpcanceltimeout.
You must call vpcanceltimeout once for each call to
vpestablishtimeout, regardless of whether or not the time-out event
has occurred. You can cancel the time-out before it expires, but you
must cancel it after it expires.
When you call vpestablishtimeout, it returns a time-out ID. You
need this ID to cancel the time-out. Cancelling the time-out will
prevent your time-out routine from being called if the interval
expires, and will free resources for another time-out to run.
Your time-out routine will run at interrupt level with event
resources locked. Thus, it should not invoke event routines that
might lock event resources (and thus deadlock the system). This
includes advancing events and awaiting events. As an alternative,
you can have the routine return an eventcounter name to be advanced
by the higher LWP on behalf of the time-out routine when it is safe
to do so.
To release the data space allocated by vpspecifymaxtimeouts, you
must call vpunspecifymaxtimeouts.
Constants and Data Structures
This subsection describes the format of system clock values and the
general clock value constants that may be needed by other subsystems.
These constants are allocated in global memory, and the data types
are defined in imisc.h. Pointers to the constants are passed to the
clock management routines to specify time values. Generally useful
values are defined in this subsection; if a subsystem has a need for
a special clock value, it can define the value itself.
Try to avoid dependencies on the specifics of these structures, such
as size or location of fields, because these specifics may change in
Licensed material--property of copyright holder(s) 3
system_clock(3K) DG/UX 5.4R3.00 system_clock(3K)
later releases of the software. You can verify exact variable
definitions in the appropriate include file. The best way to avoid
such dependencies is to use kernel-supplied routines to manipulate
these structures.
miscclockvaluetype
typedef struct
{
uint32etype high;
uint32etype low;
}
miscclockvaluetype
This type describes a value that the system clock can have. The
clock value is treated as a 64-bit signed integer with time values
contained in the bottom 63 bits. (The bits are numbered such that
bit 63 is the most-significant bit, and bit 0 is the least
significant bit with bit 32 representing one second.) Actual
resolution of timing may vary but will be accurate to at least 10
milliseconds.
You may use the following defined constants in your driver:
miscfiveminutes
misconehundredseconds
misconeminute
misctenseconds
miscfiveseconds
miscthreeseconds
misctwoseconds
misconesecond
misconehalfsecond
misctwohundredfiftymilliseconds
misctwohundredmilliseconds
misctenmilliseconds
vpcanceltimeout
This routine cancels a previously established timeout.
vpcreateclockevent
This routine sets up a clock event for a specified (incrementptr)
time in the future. eventptr is set to an event. The value of the
eventcounter is set to make the event occur at current time plus the
increment.
For other routines used in servicing the event, see the
eventcounters(3K) man page. For example, you may want to use
vpawaitec to await the occurrence of this event. You do this by
specifying the event in vpawaitec's event list.
vpestablishtimeout
This routine establishes a timeout. The timeout will occur timeptr
time from the current time, and then the specified routine will be
called with the specified argument. The maximum allowed timeout
interval is the value of vp_max_clock_ec_increment.
Licensed material--property of copyright holder(s) 4
system_clock(3K) DG/UX 5.4R3.00 system_clock(3K)
tmreadsystemclock
This routine returns the current value of the system clock.
vpspecifymaxtimeouts
This routine reserves space for the specified number of timeouts. A
device driver should call it to reserve space for the maximum number
of timeouts it will ever have in effect simultaneously.
The space must be reserved before any timeouts are established. This
routine will presumably be called several times, once by each driver
in the system, as part of its initialization.
vpunspecifymaxtimeouts
This routine frees space for the specified number of timeouts. It is
intended to by used by a device driver to release space previously
allocated using the vpspecifymaxtimeouts routine.
DIAGNOSTICS
Return Value
For vpestablishtimeout:
timeoutid This value can be used only as an argument to
vpcanceltimeout.
For the other routines: none.
Errors
None.
SEE ALSO
eventcounters(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s) 5