home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
hrtx11r0.zip
/
DOCS
/
MANUAL.INF
(
.txt
)
< prev
Wrap
OS/2 Help File
|
2001-06-29
|
36KB
|
1,133 lines
ΓòÉΓòÉΓòÉ 1. Document and driver version ΓòÉΓòÉΓòÉ
This document is valid for the following version of the Extended
High-Resolution Timer driver.
Version: 1.1r01
Build level: 195
ΓòÉΓòÉΓòÉ 2. IMPORTANT. Please read before using this driver ΓòÉΓòÉΓòÉ
Extended High-Resolution Timer driver set
Copyright (C) 2000-2001 Dr J A Gow.
IMPORTANT
PLEASE NOTE: This release is a PUBLIC RELEASE. This driver or
any of its components may not be redistributed
in whole or in part, and IN ANY FORM, without
the express written authorization of the author.
DISCLAIMER: While I have taken every care to ensure that
each release is reasonably stable, this
program/s are DEVICE DRIVERS and as such run
wholly or partially at Ring-0, the most
privileged level. There may be unforseen
situations in which failure could result in (but
not limited to) a kernel trap with possible data
loss. It is therefore advised that this software
is not used with machines upon which life
depends, or in applications which require 100%
availability. No liability whatsoever can be
accepted by the author for any loss of data,
machine damage etc. resulting from the use or
abuse of this software.
WARRANTIES: No warranties, explicit or implied, are provided
for this driver. It is used entirely at your own
risk.
TECHNICAL SUPPORT: Limited non-chargeable technical support for
this driver is available via email ONLY and at
the discretion of the author. This facility may
be withdrawn at any time without notice.
PLEASE READ ALL DOCUMENTATION BEFORE USING THIS DRIVER
ΓòÉΓòÉΓòÉ 2.1. Beta versions ΓòÉΓòÉΓòÉ
If you are an authorized recipient of beta versions, and this is such a
version, then further important information may be found in the file
BETANOTE.INF, if present. News!
ΓòÉΓòÉΓòÉ 2.2. Future releases ΓòÉΓòÉΓòÉ
Starting with the next major release number (V2.0), HRTX will be opensource.
This will allow time for completion of the direct timer-VDD interface and to
allow for exhaustive testing prior to release of the source. It should be noted
that once the source is released, I will only be supporting 'official'
versions. If you have modified the source, and those modifications are not part
of the 'official' source tree, then support will not be forthcoming.
Terms and conditions of use of the source code will be issued with the source
archive once it becomes available.
ΓòÉΓòÉΓòÉ 3. Versioning ΓòÉΓòÉΓòÉ
IT IS EXTREMELY IMPORTANT not to mix versions of the components of this driver,
or unpredictable results may occur. There is a utility supplied with the driver
set called VERSION. To display the version of any component of all releases of
this driver, simply use the command VERSION <filename>, where the <filename> is
the filename of the component you wish to check. Version number, build ID and
component name will be displayed. If a message 'No version information in this
file' is displayed you probably are running VERSION against the original
TIMER0.SYS or CLOCK01.SYS, or if unlucky have a corrupted file.
Note: Compatibility has been fully retained in CLOCK01.SYS. The new CLOCK01.SYS
is fully compatible with the original TIMER0.SYS and will cause no ill-effects
in such an arrangement. If the new TIMER0.SYS is used in conjunction with the
old CLOCK01.SYS however, the high resolution timer driver will simply not work.
Neither configuration will result in a system trap.
ΓòÉΓòÉΓòÉ 4. Files in archive ΓòÉΓòÉΓòÉ
ChangeLog.txt Contains changes made with different
builds
README.TXT Important breaking information
MANUAL.INF The user-manual for this driver (this
file)
ΓòÉΓòÉΓòÉ 5. Overview ΓòÉΓòÉΓòÉ
The Extended High-Resolution Timer driver set is intended as a general
replacement for the TIMER0.SYS and CLOCK01.SYS shipped with OS/2 Warp V4. It
may also work with Warp V3, but this has not been tested.
ΓòÉΓòÉΓòÉ 5.1. Design objectives ΓòÉΓòÉΓòÉ
This driver set was written to overcome a major problem with the TIMER0.SYS
high-resolution timer driver that is shipped with Warp 4 and higher.
In the original TIMER0.SYS, the hardware counter-0 is used to provide a
free-running counter generating interrupts at 1ms resolution. To do this it
must effectively detach counter-0 from DOS VDMs as DOS also makes use of
counter-0 to generate its timer tick interrupt. Owing to the possible demands
of VDMs to require direct access to counter-0, it becomes necessary to deny
them access to counter-0 while a TIMER0.SYS client is active. It is thus
impossible for VDMs to receive timer-tick interrupts while TIMER0 is in use.
This has ramifications for most DOS (and hence WinOS/2) MIDI programs where the
generic WinOS/2 audio and Soundblaster emulation interface is concerned as this
interface will not work in conjunction with any OS/2 audio MIDI PDD that uses
TIMER0. Once the OS/2 audio MIDI PDD is opened, TIMER0 is opened and VDMs no
longer receive timer tick interrupts - so the DOS or WinOS/2 MIDI player
running in the session no longer has any timing info and can no longer send
data. RTMIDI uses TIMER0 and suffers from the same limitation.
To fix this, it is necessary to find an alternative to the use of counter-0 for
the generation of the high-resolution timer interrupts. VDMs hit counter-0
directly, with access mediated by VTIMER.SYS, and DOS sets the timer frequency
on boot.
There are, however, two timer-based interrupts available in an OS/2 system. One
is the counter-0 interrupt discussed previously. The second is the periodic
interrupt generated by the real-time clock hardware and handled in CLOCK01.SYS.
This interrupt handler is responsible both for updating some of the timer-based
kernel variables, and also for providing callbacks to the kernel at 8Hz and
32Hz. The kernel uses these to aid in process scheduling.
It is possible to change the rate of the RTC interrupt. However, it is not
possible to change this to exactly 1ms. The 8Hz/32Hz kernel callback rates
should be preserved - it is thus possible to reprogram the RTC to generate
interrupts at 1024Hz, a convenient multiple of 32 and 8Hz. Modifications to the
RTC interrupt handler allow the system millisecond count to now be updated more
frequently while preserving the kernel callback rates. Furthermore, the IRQ
thread can be redirected into a new TIMER0.SYS which can provide 1/1024Hz
resolution or via a simple resampling technique, 1ms resolution.
ΓòÉΓòÉΓòÉ 5.2. Architecture of the new driver set ΓòÉΓòÉΓòÉ
The new driver set consists of two components. The first of these is a modified
CLOCK01.SYS. The second is a replacement TIMER0.SYS built from the ground up.
ΓòÉΓòÉΓòÉ 5.2.1. CLOCK01.SYS ΓòÉΓòÉΓòÉ
CLOCK01.SYS
This driver has been updated and the RTC interrupt code modified as described
in the design objectives and a small number of improvements made to the
structure of the code to clean it up somewhat. A protocol has been added to
allow communication between the new TIMER0.SYS and CLOCK01.SYS. Note, however,
that all existing communications mechanisms have been retained in the modified
CLOCK01.SYS, and the original TIMER0.SYS will work with the new CLOCK01.SYS in
the original manner (i.e. without the fix).
ΓòÉΓòÉΓòÉ 5.2.2. CLOCK02.SYS ΓòÉΓòÉΓòÉ
CLOCK02.SYS
An updated CLOCK02.SYS has not been developed and is not included in this
release. It is believed that this driver only supports some legacy hardware
(Microchannel machines). However, if you need it then please contact me and let
me know. If enough people require it then I will update this as well.
ΓòÉΓòÉΓòÉ 5.2.3. TIMER0.SYS ΓòÉΓòÉΓòÉ
TIMER0.SYS
The new TIMER0.SYS included in this package has been written from the
ground-up as a new implementation of the high-resolution timer and is not based
upon the original TIMER0.SYS. It does not affect the VDM timer, and provides up
to ten virtual independent timers which can individually support resolutions of
1/1024s or 1ms resampled.
It supports two different API models: compatibility model and extended model.
In the first model full compatibility is retained with the original TIMER0, and
TIMER0 clients will not need modification to work with the new TIMER0. The
second model can co-exist with the first and provides a handle-based API to the
virtual independent timers accessible in any execution context. Coming soon
Direct timer access from a VDD will be available from version 2.0. This will
allow a VDD to directly access the extended API by opening TIMER0 for IDC,
without requiring a second PDD to arbitrate the access.
ΓòÉΓòÉΓòÉ 6. System Requirements ΓòÉΓòÉΓòÉ
OS/2 Warp 4 or higher is required, preferably on a Pentium class system. There
is some speculation that the driver may also work on Warp 3 with a fixpack
applied, but this has not been tested.
ΓòÉΓòÉΓòÉ 7. Installation ΓòÉΓòÉΓòÉ
To install this driver, follow the sequence outlined below.
1. With the archive unpacked into a suitable directory, execute 'ddinstal'
from a command prompt, or select 'System Setup' -> 'Install/Remove' ->
'Device Driver Install'
2. Select the source directory as the path into which this archive was
unpacked. Then select the destination directory as 'C:'
3. Select 'Install', then from the list box 'Extended High-Resolution Timer
Driver'
4. The driver will then be installed. Reboot to complete the process.
5. If you are a developer and wish to code for the new HRTX API, then copy
the HRTX.H file to a directory in your INCLUDE path, or point your
compiler at the location where you expanded the zipfile.
ΓòÉΓòÉΓòÉ 8. Application support and programming guide ΓòÉΓòÉΓòÉ
As stated previously , the new HRT supports two API models. In the first model,
known as the compatibility API, full compatibility is maintained with the
original TIMER0 HRT. Existing HRT clients will not need rewriting in any way in
order to use the new timer. However, some enhancements have been made to this
API which extend its usefulness.
The second model, known as the enhanced API, is radically different. It is a
handle-based approach supporting individual timers, each of which can be
considered to be an entity in itself. Changes may be made to an individual
timer referenced by its handle without disrupting or affecting the operation of
other timers. Multiple processes and threads may use independent timers
simulataneously, or may share a timer provided the handle is known. It is also
possible to access the timer in any execution context - there is no
restrictions placed upon threads running in an interrupt context when using
this extended API. The extended API is similar in both ring 0 and ring 3
providing a uniform interface to both device drivers and user-mode
applications.
Details of the interface are given in this section.
ΓòÉΓòÉΓòÉ 8.1. Include file. ΓòÉΓòÉΓòÉ
Unlike the original HRT, which presented two distinct include files for ring-3
and ring-0 operation, the extended HRT presents a single unified include file
for use in either context (HRTX.H). If it is intended to write code for use
with the compatibility API alone, then it is perfectly feasible to use the
original HRT include files. These, however will not permit ready access to the
extended API.
ΓòÉΓòÉΓòÉ 8.2. Compatibility API ΓòÉΓòÉΓòÉ
For a detailed reference to the operation of the compatibility API, please
refer to the 'MMPM/2 Device Driver Programmer's Reference'. However, if the new
combined include file is to be used to develop new source, it should be noted
that some IOCtl and IDC function references have different names to those used
in the original. A list of the compatibility API functions may be found below.
The extended HRT additionally brings some important enhancements to the
compatibility API. These are also detailed below
ΓòÉΓòÉΓòÉ 8.2.1. Function list and cross-reference - ring 3 ΓòÉΓòÉΓòÉ
The following functions are available in the compatibility API for access from
ring-3 processes via IOCtls
ΓòÉΓòÉΓòÉ 8.2.1.1. IOCtl category ΓòÉΓòÉΓòÉ
All IOCtls are issued under the category HRTXIOCTL_CATEGORY (0x80).
ΓòÉΓòÉΓòÉ 8.2.1.2. Ring-3 usage issues and enhancements ΓòÉΓòÉΓòÉ
The usage from ring-3 of the compatibility API is identical to that of the
original HRT. Some enhancements have been made to the functionality, and these
are discussed below.
ΓòÉΓòÉΓòÉ 8.2.1.3. HRTXIOCTL_QUERYVERSION ΓòÉΓòÉΓòÉ
Identifier: HRTXIOCTL_QUERYVERSION
Context: N/A
Parameter packet: unused
Data packet: (ULONG) Composite version code is returned herein
Description: Returns a composite version code using the same structure
as defined in the original HRT. The macros presented in
the original include files for splitting the composite
version code up into its components are also present in
HRTX.H.
ΓòÉΓòÉΓòÉ 8.2.1.4. HRTXIOCTL_GETRESOLUTION ΓòÉΓòÉΓòÉ
Identifier: HRTXIOCTL_GETRESOLUTION
Context: N/A
Parameter packet: unused
Data packet: (ULONG) Resolution is returned in this ULONG
Description: This IOCtl returns the resolution of the timer attached to
the current process. This will be a value of 1 (1ms -
default) or -1 (1/1024Hz).
ΓòÉΓòÉΓòÉ 8.2.1.5. HRTXIOCTL_SETRESOLUTION ΓòÉΓòÉΓòÉ
Identifier: HRTXIOCTL_SETRESOLUTION
Context: N/A
Parameter packet: (ULONG) Resolution to set
Data packet: unused
Description: Sets the resolution of the timer attached to the current
process. Note that setting this resolution will only
affect this specific timer. Other processes using the
extended HRT will be unaffected as each timer is
encapsulated. The resolution can be 1 (1ms - default) or
-1 (1/1024Hz). Any other value will cause HRTXERR_BADPARAM
to be returned.
ΓòÉΓòÉΓòÉ 8.2.1.6. HRTXIOCTL_GETPOINTER ΓòÉΓòÉΓòÉ
Identifier: HRTXIOCTL_GETPOINTER
Context: N/A
Parameter packet: unused
Data packet: (FAR16) A FAR16 pointer to the timer count variable will
be placed here
Description: Returns a FAR16 pointer to the timer count variable of the
timer attached to the current process. This pointer is in
the LDT tiled region and the process may use a macro such
as SelToFlat to flatten it prior to use. The memory that
this region addresses is guaranteed to be valid, even
after the timer attached to this process has been
deregistered (although its contents are not guaranteed to
be specific after this time). Changes to this timer count
variable will not affect timers used by other processes,
or other timers registered using the extended API.
ΓòÉΓòÉΓòÉ 8.2.1.7. HRTXIOCTL_FREEPOINTER ΓòÉΓòÉΓòÉ
Identifier: HRTXIOCTL_FREEPOINTER
Context: N/A
Parameter packet: unused
Data packet: unused
Description: This API is provided for compatibility only. It does
absolutely nothing and changes no aspect of the timer.
ΓòÉΓòÉΓòÉ 8.2.1.8. HRTXIOCTL_BLOCKUNTIL ΓòÉΓòÉΓòÉ
Identifier: HRTXIOCTL_BLOCKUNTIL
Context: N/A
Parameter packet: (ULONG) Time to wait for.
Data packet: unused
Description: A thread calling this API will block for the number of
timer ticks (1ms per tick for RESOLUTION=1, (1/1024)ms per
tick for RESOLUTION=-1). This function is reentrant and a
maximum of ten threads per timer may be blocked at any one
time. Zero is a valid amount of time to wait; in this case
the thread will not block at all.
ΓòÉΓòÉΓòÉ 8.2.2. Function list and cross-reference - ring 0 ΓòÉΓòÉΓòÉ
The following functions are available in the compatibility API for access from
device drivers.
ΓòÉΓòÉΓòÉ 8.2.2.1. Ring-0 usage issues and enhancements ΓòÉΓòÉΓòÉ
The usage from ring-0 of the compatibility API is identical to that of the
original HRT. Some major enhancements have been made to the functionality, and
these are discussed below.
To attach to the extended HRT, just issue a DevHelp_AttachDD with the name
string as 'TIMER0$ '. This will return an entry point with the following
prototype.
int (_far _loadds _cdecl *FPFNHRTXIDC)(int Command, ULONG Parm1, ULONG Parm2)
to which calls should be directed. Note that C calling convention dictates that
the caller should clean up the argument list on the stack.
ΓòÉΓòÉΓòÉ 8.2.2.2. HRTXIDC_REGISTER ΓòÉΓòÉΓòÉ
Identifier: HRTXIDC_REGISTER
Context: Task, IRQ (NOT INIT)
Parm1: (FAR16) Address of callback function, to which the
extended HRT calls after the time specified in the second
parameter. The prototype for the callback function is:
void (_far _loadds *FPFNHRTXCALLBACK)(void);
Data packet: (ULONG) Number of timer ticks between callbacks
Description: Registers the use of a timer to the current process. Note
that if called on an IRQ thread, then it is only permitted
to modify the callback interval of an existing timer, not
to register a new one (behaves identically to the original
HRT in this respect). This is due to the inability to
relate the timer to a specific process at IRQ time.
However, it is worth noting that the handle based extended
API allows full access to the timers from an interrupt
thread, including registration and deregistration.
ΓòÉΓòÉΓòÉ 8.2.2.3. HRTXIDC_DEREGISTER ΓòÉΓòÉΓòÉ
Identifier: HRTXIDC_DEREGISTER
Context: Task only (NOT INIT or IRQ)
Parm1: (FAR16) Address of callback function, to which the
extended HRT calls after the time specified in the second
parameter. The prototype for the callback function is:
void (_far _loadds *FPFNHRTXCALLBACK)(void);
Data packet: unused
Description: Deregisters the timer attached to the current process.
With the compatibility API this may not be done on an IRQ
thread owing to the inability to determine the process
that owns the timer requiring deregistration. However, it
is worth noting that the handle based extended API allows
full access to the timers from an interrupt thread,
including registration and deregistration.
ΓòÉΓòÉΓòÉ 8.2.2.4. HRTXIDC_GETPOINTER ΓòÉΓòÉΓòÉ
Identifier: HRTXIDC_GETPOINTER
Context: Task only (NOT INIT or IRQ)
Parm1: (FPFAR16) FAR16 address of a location to receive the FAR16
pointer to the timer count variable.
Data packet: unused
Description: Returns a FAR16 pointer to the timer count variable of the
timer attached to the current process. The memory that
this pointer addresses is guaranteed to be valid, even
after the timer attached to this process has been
deregistered (although its contents are not guaranteed to
be specific after this time). Changes to this timer count
variable will not affect timers used by other processes,
or other timers registered using the extended API.
ΓòÉΓòÉΓòÉ 8.3. Extended API ΓòÉΓòÉΓòÉ
The Extended API introduces a new model for access to the extended HRT. It is a
handle-based model, where if the handle to a timer is known then this timer may
be accessed from any context. However, changes to one timer will not affect
other timers used elsewhere. The extended HRT supports up to ten concurrent
timers.
The API consists of a single set of functions, mirrored in ring-3 and ring-0.
The same functions may thus be accessed in the same manner from applications
and device drivers, with the exception of callback functions which only have
meaning in ring-0. A function is also provided to link the compatibility API
with the extended API by returning the handle to the timer owned by the current
process and registered through the compatiblity API (e.g. through opening the
driver with DosOpen). This way timers created using the compatibility API may
be accessed using the extended API, allowing existing clients to be enhanced
and developed without having to rewrite sections of code.
Identifiers of the extended API conform to the following pattern:
IOCtl: HRTXIOCTL_X_ccccccccc
IDC: HRTXIDC_X_ccccccccc
where ccccccccc is the command.
ΓòÉΓòÉΓòÉ 8.3.1. Function list and cross-reference - ring 0 and ring 3 ΓòÉΓòÉΓòÉ
The following functions are available in the compatibility API for access from
ring-3 processes via IOCtls and from ring-0 processes via the IDC protocol.
ΓòÉΓòÉΓòÉ 8.3.1.1. IOCtl category for ring-3 access to the extended API ΓòÉΓòÉΓòÉ
As with the compatibility API, all IOCtls are issued under the category
HRTXIOCTL_CATEGORY (0x80).
ΓòÉΓòÉΓòÉ 8.3.1.2. QUERYVERSION ΓòÉΓòÉΓòÉ
IOCTL-
Identifier: HRTXIOCTL_X_QUERYVERSION
Parameter packet: unused
Data packet: (VER) VER structure to fill with the current version
information
IDC-
Identifer: HRTXIDC_X_QUERYVERSION
Context: All
Parameter 1: unused
Parameter 2: (PVER) FAR16 pointer to a VER structure to fill with the
current version information
Description
Returns the extended version information by filling the VER structure passed
as a parameter. The VER structure has the following format.
typedef struct _VER {
unsigned char ver[7];
unsigned char build[5];
unsigned char desc[40];
} VER;
typedef VER * PVER;
The unsigned char arrays will be filled with the extended version information,
in zero-terminated string format. The bytes after the zero termination are not
guaranteed to be zero.
The strings have the following format.
Version string (ver):
A version string has the format 1.0a01, where:
1 - Major version number
. - Separator
0 - Minor version number
a - Status: a=alpha, b=beta, r=release
01 - Release number (01-99)
Build ID (build)
The build ID is a string representation of the build number, a four digit
integer from 0-9999
Description (desc)
A description string of the component.
ΓòÉΓòÉΓòÉ 8.3.1.3. QUERYCOMPATHANDLE ΓòÉΓòÉΓòÉ
IOCTL-
Identifier: HRTXIOCTL_X_QUERYCOMPATHANDLE
Parameter packet: unused
Data packet: (ULONG) ULONG to return the handle in.
IDC-
Identifer: HRTXIDC_X_QUERYCOMPATHANDLE
Context: Task only (NOT IRQ or INIT)
Parameter 1: unused
Parameter 2: (PULONG) Pointer to a ULONG in which to deposit the handle
Description
Provides a method of linking timers registered by the compatibility API to
allow them to be accessed using the extended API by returning the handle
associated with it. All timers managed by the extended HRT server have an
associated handle - but in the case of the compatibility API this handle is
hidden by the compatibility layer which maps the handle to a specific process.
To use this API it must be called in the context of the process which owns the
compatibility timer. The returned handle may then be used in any context with
any of the extended API functions.
ΓòÉΓòÉΓòÉ 8.3.1.4. CREATETIMER ΓòÉΓòÉΓòÉ
IOCTL-
Identifier: HRTXIOCTL_X_CREATETIMER
Parameter packet: unused
Data packet: (ULONG) ULONG in which to return the handle to the new
timer.
IDC-
Identifer: HRTXIDC_X_CREATETIMER
Context: All
Parameter 1: (FAR16) Address of callback function
Parameter 2: (PULONG). The contents of this address are modified by the
call and should be as follows.
Entry - Number of ticks between callbacks
Exit - The handle to the new timer
Description
Registers a timer for use by a client. The timer is registered and a handle to
it is returned. Any calls to extended API functions must use this handle to
reference the timer. There are no restrictions on where this handle may be
used - if other processes are made aware of the handle the timer may be shared
between processes.
ΓòÉΓòÉΓòÉ 8.3.1.5. DESTROYTIMER ΓòÉΓòÉΓòÉ
IOCTL-
Identifier: HRTXIOCTL_X_DESTROYTIMER
Parameter packet: (ULONG) ULONG containing handle of timer to deregister
Data packet: unused
IDC-
Identifer: HRTXIDC_X_DESTROYTIMER
Context: All
Parameter 1: (ULONG) ULONG containing handle of timer to deregister
Parameter 2: unused
Description
Deregisters a timer once a client has finished with it. Note that if a timer
created by the compatibility API and whose handle is determined through
QUERYCOMPATHANDLE is deregistered, then it will no longer be accessible from
the compatibility API either. Deregistration is not automatic on process exit,
so as not to leave orphaned resources it is essential to ensure that clients
deregister all timers once they have ceased to require access to them.
ΓòÉΓòÉΓòÉ 8.3.1.6. MODIFYCALLBACKTIMER ΓòÉΓòÉΓòÉ
IOCTL-
Note this function only has meaning in a ring-0 context and there is no ring-3
equivalent.
IDC-
Identifer: HRTXIDC_X_MODIFYCALLBACKTIMER
Context: All
Parameter 1: (ULONG) ULONG containing handle of timer to modify
Parameter 2: (ULONG) ULONG containing new callback period
Description
Alters the callback period of a timer in timer ticks.
ΓòÉΓòÉΓòÉ 8.3.1.7. SETRESOLUTION ΓòÉΓòÉΓòÉ
IOCTL-
Identifier: HRTXIOCTL_X_SETRESOLUTION
Parameter packet: (ULONG) ULONG containing handle of timer to deregister
Data packet: Resolution to set the timer to (1=1ms, -1=(1/1024)ms)
IDC-
Identifer: HRTXIDC_X_SETRESOLUTION
Context: All
Parameter 1: (ULONG) ULONG containing handle of timer to deregister
Parameter 2: (ULONG) Resolution to set the timer to (1=1ms,
-1=(1/1024)ms)
Description
Changes the resolution (frequency of timer ticks) of the current timer to that
specified. Values that are not -1 or 1 will cause an error to be returned.
ΓòÉΓòÉΓòÉ 8.3.1.8. GETRESOLUTION ΓòÉΓòÉΓòÉ
IOCTL-
Identifier: HRTXIOCTL_X_GETRESOLUTION
Parameter packet: (ULONG) ULONG containing handle of timer to deregister
Data packet: (ULONG) Resolution of the timer will be returned herein
IDC-
Identifer: HRTXIDC_X_GETRESOLUTION
Context: All
Parameter 1: (ULONG) ULONG containing handle of timer to deregister
Parameter 2: (PULONG) Resolution will be placed in this memory location
Description
Returns the resolution of the specified timer. This will either be 1 (1ms -
default) or -1 ((1/1024)ms )
ΓòÉΓòÉΓòÉ 8.3.1.9. BLOCKTHREAD ΓòÉΓòÉΓòÉ
IOCTL-
Identifier: HRTXIOCTL_X_BLOCKTHREAD
Parameter packet: (ULONG) ULONG containing handle of timer to deregister
Data packet: (ULONG) Number of timer ticks to block for
IDC-
Identifer: HRTXIDC_X_BLOCKTHREAD
Context: Task, (NOT IRQ)
Parameter 1: (ULONG) ULONG containing handle of timer to deregister
Parameter 2: (ULONG) Number of timer ticks to block for
Description
Blocks the thread calling into this API for the time specified and ties the
thread to the specified timer. Up to ten threads per timer may be blocked at
any one time. In ring-0, this function will return an error if called in an
interrupt context.
ΓòÉΓòÉΓòÉ 8.3.1.10. QUERYCOUNTADDR ΓòÉΓòÉΓòÉ
IOCTL-
Identifier: HRTXIOCTL_X_QUERYCOUNTADDR
Parameter packet: (ULONG) ULONG containing handle of timer to deregister
Data packet: (PULONG) Address into which a process-addressible linear
pointer to the ULONG timer count variable will be placed
IDC-
Identifer: HRTXIDC_X_QUERYCOUNTADDR
Context: Any
Parameter 1: (ULONG) ULONG containing handle of timer to deregister
Parameter 2: (FAR16) Address into which the FAR16 address of the timer
count variable will be placed.
Description
Returns the address of the timer count variable. Note that from an IOCtl, a
process-addressible linear pointer is returned. From an IDC, a FAR16 pointer
is returned.
ΓòÉΓòÉΓòÉ 8.3.2. Sample code - extended API ΓòÉΓòÉΓòÉ
The following sample code gives a very simple example of how to implement
timers using the extended API. It does not show the use of multiple timers, or
multiple threads blocking using a single timer.
The sample code may be found in the file SAMPLE\TEST.C
ΓòÉΓòÉΓòÉ 8.4. Main limitations: ΓòÉΓòÉΓòÉ
All applications that are clients of the original TIMER0 need no modification
to work with the new TIMER0.
ΓòÉΓòÉΓòÉ 9. Command line parameters ΓòÉΓòÉΓòÉ
All command line parameters are case insensitive.
ΓòÉΓòÉΓòÉ 9.1. TIMER0.SYS ΓòÉΓòÉΓòÉ
The following parameters are accepted by TIMER0.SYS on the load line in the
CONFIG.SYS.
BASEDEV=TIMER0.SYS <params>
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFLAG ΓöéRANGE ΓöéACTION Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé/Q Γöé- ΓöéLoad quietly Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 10. Troubleshooting. ΓòÉΓòÉΓòÉ
If you run into difficulty with this driver, then please first consult these
sections as the most common issues will be described here with the appropriate
solution. If this still does not resolve the problem then please contact me and
I will attempt to advise you.
ΓòÉΓòÉΓòÉ 10.1. Errors ΓòÉΓòÉΓòÉ
The following error codes may be returned from the driver in response to an
IOCtl or an IDC call.
ΓòÉΓòÉΓòÉ 10.1.1. HRTXERR_NOERROR ΓòÉΓòÉΓòÉ
Integer value: - 0x00
No error has occurred and the call has completed successfully
ΓòÉΓòÉΓòÉ 10.1.2. HRTXERR_MODONINT ΓòÉΓòÉΓòÉ
Integer value: - 0x01
Generated in response to an IDC call issued while in interrupt context when the
function requested is not available in this context.
ΓòÉΓòÉΓòÉ 10.1.3. HRTXERR_MAX_CLIENTS ΓòÉΓòÉΓòÉ
Integer value: - 0x02
Returned if an attempt is made to register more than 10 clients simultaneously,
or to block more than 10 threads simultaneously per timer.
ΓòÉΓòÉΓòÉ 10.1.4. HRTXERR_NOSUCHCLIENT ΓòÉΓòÉΓòÉ
Integer value: - 0x03
Returned from the compatibility API if a timer is not registered for this
process.
ΓòÉΓòÉΓòÉ 10.1.5. HRTXERR_BADPARAM ΓòÉΓòÉΓòÉ
Integer value: - 0x04
Returned from an IOCtl or an IDC function if an invalid parameter is submitted
ΓòÉΓòÉΓòÉ 10.1.6. HRTXERR_HRTCBFAIL. ΓòÉΓòÉΓòÉ
Integer value: - 0x05
Generated if a problem occurs in attaching to the modified CLOCK01.SYS. Be sure
that the correct version of CLOCK01.SYS is installed in the system.
ΓòÉΓòÉΓòÉ 10.1.7. HRTXERR_EARLYREGISTER ΓòÉΓòÉΓòÉ
Integer value: - 0x06
Generated if an attempt is made to register a client through the compatibility
API from ring-0 before or during INIT_COMPLETE.
ΓòÉΓòÉΓòÉ 10.1.8. HRTXERR_INVALIDHANDLE ΓòÉΓòÉΓòÉ
Integer value: - 0x07
Returned if an invalid handle is passed to the extended API.
ΓòÉΓòÉΓòÉ 11. Known bugs ΓòÉΓòÉΓòÉ
This file contains a list of known bugs, and consists of the last few major
entries in the problem database for this release. Please verify against this
list before submitting a bug report.
The driver version in the list is the version in which the bug was found. If
the bug is marked as FIXED then the version in which the fix was introduced is
also listed.
STATUS: This can be one of
FIXED: Problem is fixed in current release
PENDING: Problem is under investigation
QUEUED: Problem is awaiting attention
LIMITATION: Problem can not be fixed due to
limitations of system or architecture.
ΓòÉΓòÉΓòÉ 11.1. HRTX10a01/0001 ΓòÉΓòÉΓòÉ
Reported by:
STATUS: FIXED
Driver version: 1.0a01 - FIXED IN 1.1r01
OS/2 version: Warp 4
OS/2 Fixpack level: 14
CPU type: All
CPU speed: All
RAM MB: N/A
Description of problem
Threads blocked using HRTXIOCTL_X_BLOCKTHREAD or HRTXIOCTL_BLOCKUNTIL remain
blocked in the timer until time expires should the client process terminate
abnormally.
Error in header file is now corrected allowing ring-0 block calls to correctly
return on a process death
ΓòÉΓòÉΓòÉ 11.2. HRTX10r02/0001 ΓòÉΓòÉΓòÉ
Reported by: RI
STATUS: FIXED
Driver version: 1.0r03 - FIXED IN 1.0r03
OS/2 version: Warp 4
OS/2 Fixpack level: 14
CPU type: All
CPU speed: All
RAM MB: N/A
Description of problem
Driver traps on any calls to time set functions.
Swappable code segment in executable incorrectly flagged in executable header.
v1.0r03 corrected specifically this problem
ΓòÉΓòÉΓòÉ 11.3. HRTX10r03/0001 ΓòÉΓòÉΓòÉ
Reported by: MG
STATUS: PENDING
Driver version: 1.0r03
OS/2 version: Warp 4
OS/2 Fixpack level: 14
CPU type: All
CPU speed: All
RAM MB: N/A
Description of problem
Mysterious lockup in REXX scripts that use system wait calls. This has not
been observed elsewhere. Problem traced to the CLOCK01 portion of the driver,
but no clear indication of the cause has been found. Attempts to replicate the
behaviour have so far proved negative.
Fixed in version: N/A
ΓòÉΓòÉΓòÉ 11.4. HRTX10r03/0002 ΓòÉΓòÉΓòÉ
Reported by: RWK
STATUS: FIXED
Driver version: 1.0r03 - FIXED IN 1.1r01
OS/2 version: Warp 4
OS/2 Fixpack level: 14
CPU type: All
CPU speed: All
RAM MB: N/A
Description of problem
R0 Trap0D in RTMIDI apps.
Overwrite of the client callback address pointer by successive registration
from RTMIDI.DLL after MIDI.DLL had executed an IDC attachment.
Updated compatibility-mode client code has completely resolved this - I hope
*************************************
ΓòÉΓòÉΓòÉ 12. Reporting bugs ΓòÉΓòÉΓòÉ
To report a bug in the driver, please fill in the form which can be found in
the file DOC\BUGREP.TXT. However, please first verify the following before
submitting a report.
1. REPEATABILITY
The bug must be repeatable - i.e. you must be able to consistently
reproduce the effect on more than one occasion
2. PRE-EMINENCE
Please check against the file DOC\KNOWNBUG.TXT, if this file exists, to
see if the bug is already known about. If it is, and occurs under exactly
the same conditions (but possibly with different hardware), then please
do not report it - it is already known. However, if the bug occurs under
very different conditions, but is sufficiently similar in nature to a
report in DOC\KNOWNBUG.TXT, then please do report it quoting the bug
report number (top left hand corner of the header of each bug report in
DOC\KNOWNBUG.TXT) in the 'Reference current bug no:' field in the report
form and specifying the conditions under which the bug may be produced.
ΓòÉΓòÉΓòÉ 12.1. Submission ΓòÉΓòÉΓòÉ
To submit the report, please email the complete bug report form to me.
ΓòÉΓòÉΓòÉ 13. Contact details ΓòÉΓòÉΓòÉ
If you would like to contact me regarding this driver, or other matters,
suggestions for enhancements etc. please send email to
J.A.Gow@furrybubble.co.uk and I will attempt to resolve your query. Please note
however, that:
if( !POLITENESS) {
return I_WILL_IGNORE_YOUR_MESSAGE();
}
You get the drift! :)
ΓòÉΓòÉΓòÉ 14. Acknowledgements ΓòÉΓòÉΓòÉ
The further development of this driver would not have been possible had it not
been for the help and assistance of the following people whose contribution is
gratefully acknowledged:
Timur Tabi: Timur wrote the original high-resolution timer
implementation and has been very helpful during
the planning phase of this development with
suggestions and answers to my questions.
Roderick Klein: Roderick does a superb job of managing the web
site and the beta test programs, not to mention
considerable advice and encouragement
IBM: Without the CLOCKxx sources, usefully released
as part of the device driver kit, this fix would
not have been possible.
Sarah: Not forgetting Sarah, my wife, who willingly
eschewed many a romantic evening in front of a
roaring (imitation) coal fire for less romantic
evenings in front of the monitor in order to
develop this code to a high standard despite my
gruelling schedule as a research engineer.
Support like that is rare in today's society.