Character Device Monitors
Character Device Monitors provide a mechanism for applications or subsystems to monitor all characters passing through a device driver.
This mechanism allows any registered process to remove, insert or modify the information passing through the device.
The OS/2 monitor mechanism consists of the OS/2 monitor calls and the monitor dispatcher device helper. The monitor calls provide the interface for the monitor to interact with the device driver and the monitor's own input/output data buffers. The monitor dispatcher device helper handles the interfaces for the device driver and the mechanics of passing data from the output buffer of one monitor to the input buffer of the next monitor in the chain.
Monitor Details Monitor
DosMonOpen DosMonReg Dos Mon Close
Thread(s)
Dos Mon Read Dos Mon Write
Monitor Dispatcher DevHlp MonitorCreate DevHlp Register DevHlp Deregister OPEN
REGISTER (IOCTL)
Monitor DosMonOpen DosMonReg DosMonClose
Thread(s) DosMonRead DosMonWrite
Dev Hip MonWrite Mon Flush
(Notify Call)
Device Driver
CLOSE - - - Deregister
[
Monitor Processes
A character device monitor is an application process, or part of an application process; that is, it runs at protection level 3 using
standard OS/2 function calls (DosMonXXX) to interact with the device driver and the monitor's own input and output data buffers.
For a process to gain access to a device driver's data stream for character monitoring, the monitor must do the following:
1. Issue the DosMonOpen call to establish a connection to the device driver for monitors. DosMonOpen gets a device handle that will be used in subsequent DosMonReg and DosMonClose calls.
2. Issue the DosMonReg call to register a pair of input and output buffers with the device driver and monitor dispatcher. After the monitor is installed in the monitor chain, the monitor dispatcher automatically moves data between monitors (if there is more than one in the chain) and between the last monitor in the chain and the device driver's monitor chain buffer.
The device handle for monitors returned from a DosMonOpen call is unique to that process. A process needs to call DosMonOpen only once per character device whose data stream(s) it wishes to monitor.
If a process issues more than one DosMonOpen call to the same device, the same device handle will be returned. A process may then register one or more monitors on the same device handle for moni-tors.
Note: Until the monitor returns successfully from the DosMonReg call, no characters will enter the monitor's input buffer. It is the appli-cation's responsibility to synchronize completion of the DosMonReg call and the subsequent monitoring of the data stream with device input into the data stream. See the diagrams on pages 6-51 and 6-52 for examples.
After a monitor has gained access to the data stream, it may remove, insert, modify or view all characters in data records passing through the data stream by:
1. Issuing the DosMonRead call to move a data record from its input buffer to a private data area that the monitor process can access freely, and
2. Issuing the DosMonWrite call to move a data record from the monitor process private buffer into its output buffer.
A data record is defined minimally as a WORD containing flags mean-ingful to the monitors and devices whose data stream they are moni-toring. The flag WORD is always the first WORD in the data record. A monitor can modify the data record received on the last DosMonRead call before calling DosMonWrite to return it to the device's data stream. However, because the character device driver is sensitive to these flags and to the entire data record, the monitor application should never alter this order within a data record and must conform to device driver "rules" on filtering data records. Refer to Chapter 9, Device Drivers for device-specific descriptions of flag WORDs and data records.
Data movement from the monitor's input buffer (DosMonRead) and into the monitor's output buffer (DosMonWrite) is synchronized with the device driver and monitor dispatcher. When a data record is moved into the monitor's input buffer, the monitor process is signaled by the monitor dispatcher that a data record is available for
DosMonRead. When DosMonRead completes movement of one data record, the monitor dispatcher is signalled that a data record has been removed and there is now more room for new data records.
The opposite is true for DosMonWrite.
Note: Monitors get control of all data in a data stream before an application can read it. Therefore, a monitor's processing must be fast, performing no 110 or semaphore waits. For example, there is no recovery if a monitor application does a read for a character from the device driver API buffer when it has not yet moved the character through its input and output buffers into the device driver monitor chain buffer. Complex processing in a monitor should be performed within a monitor thread separate from that which makes
DosMonRead and DosMonWrite calls.
When a process no longer wishes to monitor a character device's data stream, it relinquishes its access to the data streams by calling DosMonClose. DosMonClose is issued with a specific opened device handle for monitors, as returned from a previous DosMonOpen. All monitors for the current process that registered using this handle (those monitoring the particular character device) are terminated.
Pseudo code for a simple keystroke monitor is:
·*****************************************
' ; SIMPLE CHARACTER DEVICE MONITOR
;*****************************************
CALL DosSetPrty ;Set this monitor's thread
; priority high GET ACCESS TO THE DEVICE'S DATA STREAM
CALL DosMonOpen ;get a device handle for monitors for
; the application
CALL DosMonReg ;register a pair of input and output
; buffers as a monitor WHILE [we want to monitor the data stream]
CALL DosMonRead ;read a data record from the monitor's
;input buffer
;process, or filter, the data record (keystroke) CALL DosMonWrite ;write a filtered data record into the
;monitor's output buffer END WHILE
CALL DosMonClose ;close all monitors from this
;application registered on the same
;device handle
Below is a diagram that shows how monitors fit into the system struc-ture and how OS/2 supports these functions.
There are three interfaces in this diagram. They are labeled:
1. Program to device driver interface
2. Device driver to monitor dispatcher interface 3. Monitor dispatcher to monitor process interface
( 1) . - - - !
PROGRAM/
SUBSYSTEM AREA
l l
ProgramsProcess
Buffers (B) IPC
-.-~-;-~-~-~-~---~~~--.-:.-~--~-:~-~-;~:-~-:,----.-~:~:~:-_~]-~--Device Driver .... .----~ (DevHelp)
(A) DataFlow
Control Flow Interfaces
1. Program to device driver
This interface establishes a monitor connection and tears it down.
This is the registration process.
• Open: DosMonOpen gets a handle to use for monitor registra-tion.
• Registration: DosMonReg registers monitor and data buffers.
2. Device driver to monitor dispatcher
This interface is provided with DevHlp routines to do the following:
• MonitorCreate: Creates a chain of monitors.
• Register: Adds a monitor to a chain.
• Deregister: Removes a monitor from a chain.
• MonWrite: Passes data records to a monitor.
• MonFlush: Removes data from the monitor chain.
3. Monitor dispatcher to monitor process
The monitor dispatcher coordinates movement of data between the device driver and monitor input/output buffers.
Module Description
• (A) Monitor Dispatcher: This package is common to all device drivers and serves the device drivers and the monitors in user space.
• (B) Monitor Buffer Management: Applications are responsible for allocating their own monitor buffers, and setting the first WORD of each buffer equal to the length of the buffer. The monitor dis-patcher starts and manages all buffers for registered monitors.