Input/Output Device Driver Reference/CLOCK$ Device Driver

This chapter discusses the physical CLOCK$ device driver.

Physical CLOCK$ Device Driver
The OS/2 operating system assumes that a CMOS real-time clock is available in the system. The CLOCK$ device defines and performs functions like any other character device, except that it is identified by a bit in the attribute WORD. The operating system uses this bit to identify the device driver; therefore, this device can take any name. The device has been named CLOCK$ to avoid possible conflicts with any files named CLOCK.

The CLOCK$ device is unique because the OS/2 operating system reads or writes a 6-byte sequence, which encodes the date and time. Writing to this device sets the date and time; reading from it gets the date and time. The following figure illustrates the binary time format used by the CLOCK$ device: The physical CLOCK$ device driver sets and maintains the following fields in the global InfoSeg:
 * TIME:Time, from 1-1-1980, in seconds
 * Milliseconds
 * Hours
 * Minutes
 * Seconds
 * Hundredths
 * Timer interval


 * DATE
 * Day
 * Month
 * Year
 * Day of week

The physical CLOCK$ device driver ensures that the date, time in seconds (from 1-1-1980), and time of day (hours, minutes, seconds) fields remain synchronized with the CMOS clock and that the hundredths of seconds field is correctly synchronized with the seconds field.

CMOS Clock
CLOCK$ is the device driver for the CMOS clock. The RTENTR routine is the task-time entry point to the Clock device driver. The requested functions are dispatched to worker routines.

RTENTR provides eight functions: A case control structure is used because a command table has only 8 valid entries of 28 options. Functions 6,7 and functions 8,9 have the same effect.
 * RTREAD(4)
 * STREDY(5)
 * STCOMP(6,7)
 * RTWRIT(8,9)
 * RTIOCT(16)
 * RTINIT(27)
 * RTINIT2(0)
 * BADCMD (all other functions)

All Other Functions
Input:
 * ES:BX= Address of Device Driver Request Packet
 * DS:= Points to Clock Device Driver Data Segment


 * Note:Parameter checking on input data to RTWRIT through this routine must be performed by the caller.

Output: Device Driver Request Packet filled in (for example, Status word set, date/time fields).

Equivalent Command Dispatch Table (Highest legal function is 27): ClkSwap:RTINIT2        ; 0 Initialize (2nd stage, special for clock) ClkSwap:BADCMD         ; 1 Media Check  these are unsupported ClkSwap:BADCMD         ; 2 Build BPB    functions. ClkSwap:BADCMD         ; 3 IOCTL input ClkSwap:RTREAD         ; 4 Input (Read) ClkSwap:STREDY         ; 5 Non-destructive read, no wait ClkSwap:STCOMP         ; 6 Input status ClkSwap:STCOMP         ; 7 Input flush ClkSwap:RTWRIT         ; 8 Output (Write) ClkSwap:RTWRIT         ; 9 Output with verify ClkSwap:BADCMD         ; 10 BADCMD ClkSwap:BADCMD         ; 11 BADCMD ClkSwap:BADCMD         ; 12 BADCMD ClkSwap:BADCMD         ; 13 BADCMD ClkSwap:BADCMD         ; 14 BADCMD ClkSwap:BADCMD         ; 15 BADCMD ClkSwap:RTIOCT         ; 16 Generic IOCTL ClkSwap:BADCMD         ; 17 BADCMD ClkSwap:BADCMD         ; 18 BADCMD ClkSwap:BADCMD         ; 19 BADCMD ClkSwap:BADCMD         ; 20 BADCMD ClkSwap:BADCMD         ; 21 BADCMD ClkSwap:BADCMD         ; 22 BADCMD ClkSwap:BADCMD         ; 23 BADCMD ClkSwap:BADCMD         ; 24 BADCMD ClkSwap:BADCMD         ; 25 BADCMD ClkSwap:BADCMD         ; 26 BADCMD ClkCode:RTINIT         ; 27 Initialize ClkSwap:BADCMD         ; 28 BADCMD here at table end


 * RTREAD
 * The Realtime Clock Read routine returns six bytes of date and time information in the form Date(word), Min, Hrs, Sec/100, Sec.
 * DevHlp_PhysToVirt converts the real address of the data buffer in the Device Driver Request Block (PktData) to a virtual address. DevHlp_UnPhysToVirt later restores the physical memory address.
 * RTREAD does not actually read the clock, but instead retrieves the data from the Global InfoSeg date/time data area.


 * STREDY:STREDY performs a non-destructive read operation with no-wait.
 * STCOMP:STCOMP sets the status to "complete".
 * RTWRIT:The Realtime Clock Write routine supports the device driver functions:
 * WRITE (function 8)
 * WRITE WITH VERIFY (function 9)

Set the Realtime Clock device with the date/time information and update the Global InfoSeg date/time variables accordingly. Set the stack frame to reserve the clock information as follows: DevHlp_PhysToVirt converts the real address of the data buffer in the Device Driver Request Block (PktData) to a virtual address. DevHlp_UnPhysToVirt later restores the physical memory address.


 * RTIOCT:The Realtime Clock Generic IOCTL routine supports the category 0Dh generic IOCTL commands by calling the appropriate worker routine.
 * RTINIT:RTINIT initializes data structures and the Realtime Clock device.
 * RTINIT2:There must be a delay hooking IRQ0 until after loadable device drivers/IFS are installed, because RIPL with ETHERNET/PC-NET uses IRQ0. The kernel calls the loadable device driver init with command 0, which then hooks the IRQ0. The RTINIT2 routine is then invoked.