system_clock(3K) DG/UX R4.11MU05 system_clock(3K)
NAME
systemclock: lmestablishtimeout, lmcanceltimeout,
lmspecifymaxtimeouts, lmunspecifymaxtimeouts,
lmcreateclockevent, tmreadsystemclock - manipulate the system
clock
SYNOPSIS
#include "/usr/src/uts/aviion/ii/ilm.h"
#include "/usr/src/uts/aviion/ii/imisc.h"
#include "/usr/src/uts/aviion/ii/itm.h"
void lmcanceltimeout (
opaque32type timeoutid READONLY
)
void lmcreateclockevent (
lmeventptrtype eventptr, WRITEONLY
miscclockvalueptrtype incrementptr READONLY
)
void lmestablishtimeout (
miscclockvalueptrtype timeptr, READONLY
lmtimeoutroutineptrtype routineptr, READONLY
bit32etype argument, READONLY
lmtimeoutidptrtype timeoutidptr WRITEONLY
)
void lmspecifymaxtimeouts (
uint32type count READONLY
)
void lmunspecifymaxtimeouts (
uint32type count READONLY
)
void tmreadsystemclock (
miscclockvalueptrtype currenttimeptr WRITEONLY
)
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.
currenttimeptr
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
lmestablishtimeout routine.
DESCRIPTION
The following routines are described in this man page:
lmestablishtimeout Establish a timeout
lmcanceltimeout Cancel a previously established timeout
lmspecifymaxtimeouts Reserve space for timeouts
lmunspecifymaxtimeouts Free space for timeouts
lmcreateclockevent 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.
A lower-overhead, less precise timing mechanism is provided in
conjunction with eventflags; see eventflags(3K).
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 tmreadsystemclock 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 lmcreateclockevent to
create a clock event that will occur after some specified system time
interval. After you create the event, you await it using the
lmawaitevents 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 200 milliseconds:
lmcreateclockevent(&delayevent, &misctwohundredmilliseconds);
lmawaitevents(&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
request; a time-out of the I/O request; or termination of the I/O LWP
(Light-Weight Process, or thread). 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
lmspecifymaxtimeouts.
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 halt 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 lmestablishtimeout and lmcanceltimeout are
a matched set. One establishes the time-out and the other cancels
it; the time-out is still current until you call lmcanceltimeout.
You must call lmcanceltimeout once for each call to
lmestablishtimeout, 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. If you do not cancel the time-out
within 72 hours after it expires, your system may hang.
When you call lmestablishtimeout, it returns a time-out ID via a
pointer that is passed in as a parameter. You need this ID to cancel
the time-out. Canceling the time-out before the interval expires
will prevent your time-out routine from being called when the
interval expires, and will free resources for another time-out to
run.
The 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 lmspecifymaxtimeouts, you
must call lmunspecifymaxtimeouts.
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
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. 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
lmcanceltimeout
This routine cancels a previously-established timeout. You must
cancel a timeout, either before or after it expires. If you do not
cancel the timeout within 72 hours after it expires, your system may
hang.
lmestablishtimeout guarantees that the time-out ID is written into
the specified location before the time-out is queued, but after it
becomes legal to cancel the time-out. If the time-out is to be
canceled by some LWP other than the one that established it, care
must be taken to ensure that the canceling LWP reads the time-out ID
from the same memory location that lmestablishtimeout writes into,
rather than a copy of it, to avoid a timing window between when the
time-out is established (and possibly executed), and when the time-
out ID would be copied.
lmcreateclockevent
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
lmawaitevents to await the occurrence of this event. You do this
by specifying the event in lmawaitevents's event list.
Alternatively, see the imprecise timer mechanism in eventflags(3K).
lmestablishtimeout
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 lm_max_clock_ec_increment.
tmreadsystemclock
This routine returns the current value of the system clock.
lmspecifymaxtimeouts
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.
lmunspecifymaxtimeouts
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 lmspecifymaxtimeouts routine.
NOTES
An older family of routines, whose names start with "vp" is also
supported. The routines described here ("lm") are more efficient
and offer a slightly easier to use interface. The use of the vp
routines is deprecated.
Errors
None.
SEE ALSO
eventcounters(3K).
eventflags(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)