OS/2 Shareware BBS: 10 Tools

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.