system_clock(3K) DG/UX R4.11MU05 system_clock(3K)
NAME
system_clock: lm_establish_timeout, lm_cancel_timeout,
lm_specify_max_timeouts, lm_unspecify_max_timeouts,
lm_create_clock_event, tm_read_system_clock - manipulate the system
clock
SYNOPSIS
#include "/usr/src/uts/aviion/ii/i_lm.h"
#include "/usr/src/uts/aviion/ii/i_misc.h"
#include "/usr/src/uts/aviion/ii/i_tm.h"
void lm_cancel_timeout (
opaque32_type timeout_id READ_ONLY
)
void lm_create_clock_event (
lm_event_ptr_type event_ptr, WRITE_ONLY
misc_clock_value_ptr_type increment_ptr READ_ONLY
)
void lm_establish_timeout (
misc_clock_value_ptr_type time_ptr, READ_ONLY
lm_timeout_routine_ptr_type routine_ptr, READ_ONLY
bit32e_type argument, READ_ONLY
lm_timeout_id_ptr_type timeout_id_ptr WRITE_ONLY
)
void lm_specify_max_timeouts (
uint32_type count READ_ONLY
)
void lm_unspecify_max_timeouts (
uint32_type count READ_ONLY
)
void tm_read_system_clock (
misc_clock_value_ptr_type current_time_ptr WRITE_ONLY
)
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.
current_time_ptr
A pointer to where the current value of the system
clock is to be written.
event_ptr A pointer to the event that is to be set up.
increment_ptr 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.
routine_ptr A pointer to a routine that is to be called when the
timeout occurs.
time_ptr 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.
timeout_id An opaque 32-bit identifier, the timeout ID of the
timeout to be canceled. This value is returned by the
lm_establish_timeout routine.
DESCRIPTION
The following routines are described in this man page:
lm_establish_timeout Establish a timeout
lm_cancel_timeout Cancel a previously established timeout
lm_specify_max_timeouts Reserve space for timeouts
lm_unspecify_max_timeouts Free space for timeouts
lm_create_clock_event Set up clock event for future time
tm_read_system_clock 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 event_flags(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
misc_clock_value_type units. A misc_clock_value_type 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. misc_clock_value_type and pre-defined
values for it are shown in the Constants and Data Structures
subsection.
You can read the system clock using the tm_read_system_clock 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 lm_create_clock_event to
create a clock event that will occur after some specified system time
interval. After you create the event, you await it using the
lm_await_events routine described in event_counters(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:
lm_create_clock_event(&delay_event, &misc_two_hundred_milliseconds);
lm_await_events(&delay_event, (int32_type)1, &result_index);
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
lm_specify_max_timeouts.
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 max_timeouts, 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 lm_establish_timeout and lm_cancel_timeout are
a matched set. One establishes the time-out and the other cancels
it; the time-out is still current until you call lm_cancel_timeout.
You must call lm_cancel_timeout once for each call to
lm_establish_timeout, 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 lm_establish_timeout, 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 lm_specify_max_timeouts, you
must call lm_unspecify_max_timeouts.
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 i_misc.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.
misc_clock_value_type
typedef struct
{
uint32e_type high;
uint32e_type low;
}
misc_clock_value_type
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:
misc_five_minutes
misc_one_hundred_seconds
misc_one_minute
misc_ten_seconds
misc_five_seconds
misc_three_seconds
misc_two_seconds
misc_one_second
misc_one_half_second
misc_two_hundred_fifty_milliseconds
misc_two_hundred_milliseconds
misc_ten_milliseconds
lm_cancel_timeout
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.
lm_establish_timeout 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 lm_establish_timeout 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.
lm_create_clock_event
This routine sets up a clock event for a specified (increment_ptr)
time in the future. event_ptr 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
event_counters(3K) man page. For example, you may want to use
lm_await_events to await the occurrence of this event. You do this
by specifying the event in lm_await_events's event list.
Alternatively, see the imprecise timer mechanism in event_flags(3K).
lm_establish_timeout
This routine establishes a timeout. The timeout will occur time_ptr
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.
tm_read_system_clock
This routine returns the current value of the system clock.
lm_specify_max_timeouts
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.
lm_unspecify_max_timeouts
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 lm_specify_max_timeouts 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
event_counters(3K).
event_flags(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)