ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/UTILITY/SYSTEM/MMCLK12.ZIP/MMCLOCK.DOC

Text File | 1990-08-01 | 9.8 KB | 233 lines

                 MMCLOCK.SYS

             An installable driver for the
            National Semiconductor MM58167A
             real-time clock/calendar chip

                 Version 1.2
                  June 1990

             Richard B. Wales
             UCLA Computer Science Dept.
             3531 Boelter Hall
             Los Angeles, CA 90024-1596
             [phone]
             Internet:  [e-mail]


WHAT IS MMCLOCK.SYS?

MMCLOCK.SYS is an installable device driver for a real-time clock/calendar
(PC or XT) based on the National Semiconductor MM58167A chip.  This chip is
used in various multifunction cards and clone motherboards.

Add-on clock cards usually come with some software for manipulating the date
and time on the card.  Many of these programs are inconvenient to use and/or
are of inferior quality.  The great majority of them do not understand about
leap year (which could give you minor headaches in 1992).  MMCLOCK.SYS per-
mits the clock card to be treated "transparently"; the system date/time is
automatically set on each reboot, and any changes to the date/time (e.g., via
the DOS commands DATE and TIME) automatically update the clock card without
the need to run any additional program.

MMCLOCK.SYS was written in assembly language and assembled using the Borland
Turbo Assembler (version 2.0).  The code has also been successfully assem-
bled using the Microsoft Macro Assembler (version 5.1).

INSTALLING THE DRIVER

In most cases, all that need be done is to put MMCLOCK.SYS on a disk drive
(generally C:) and add a DRIVER= line to the CONFIG.SYS file.  MMCLOCK.SYS
will automatically locate the clock/calendar (if present).

If MMCLOCK.SYS cannot find the clock/calendar, it may be that the hardware is
set up to use an unusual I/O port address.  In this case, you need to deter-
mine the port address used (possibly by disassembling the driver software
that came with the machine or card), and then include this address as an argu-
ment on the DRIVER= line.  For example:

            DRIVER=C:\BIN\MMCLOCK.SYS 280

Note that not all add-on clock/calendar cards use the MM58167A chip.  If your
clock card does not use this chip, MMCLOCK.SYS will not work for you.

If you use MMCLOCK.SYS, you should NOT use ANY other clock driver or other
software that may have been supplied with your clock card.  This is impor-
tant, because MMCLOCK.SYS reads and writes the date on the clock card in a
highly nonstandard manner that is completely incompatible with other drivers.

COMPATIBILITY CONSIDERATIONS

MMCLOCK.SYS works with the same kind of clock/calendar hardware as does the
Strickland clock driver (CLKDRV.SYS).  Any software which claims compatibil-
ity with CLKDRV.SYS should work equally well with MMCLOCK.SYS.

MMCLOCK.SYS IMPLEMENTATION DETAILS

The following information is not essential for the user of MMCLOCK.SYS, but
may be interesting to some users.

The MM58167A chip contains a 14-decimal-digit counter, plus 14 hexadecimal
digits (56 bits) of RAM.

The counter holds the month, day of the month, day of the week, and time of
day (hours, minutes, seconds, and milliseconds).

The RAM is officially designed to hold the same kind of information as the
counter -- in conjunction with an alarm-clock interrupt feature.  However,
most clock cards which use the MM58167A do not even try to use the alarm-
clock facility, so the RAM can in practice hold arbitrary data.

The counter data is accessed via eight consecutive I/O ports, thus:

     Port        High-order        Low-order
        number          nybble         nybble
    =================================================
     x+0        1/1000 sec          ZERO
     x+1         1/10 sec        1/100 sec
     x+2            seconds (2 digits)
     x+3            minutes (2 digits)
     x+4             hours (2 digits)
     x+5           ZERO            day of wk.
     x+6             day of month (2 digits)
     x+7             month (2 digits)

Wherever "2 digits" are indicated, the value is stored as binary coded deci-
mal (BCD) -- not as straight binary.

The "day of the week" portion of the counter cycles through the values 1
 through 7 inclusive.

The RAM is laid out in the same manner as the counter, and is accessed via
eight consecutive I/O ports (x+8 through x+15).  The two nybbles shown as
"ZERO" in the counter diagram above do not have RAM associated with them; any-
thing written to these two nybbles will be discarded, and the value read for
these nybbles will always be zero.

Except for the two "ZERO" nybbles, the RAM is not restricted to BCD values;
rather, any nybble may hold any 4-bit binary value.

The MM58167A also has several status and control registers.  In particular,
one status register indicates whether the clock has ticked during a "read" or
"write" operation.  Since some hardware implementations may not provide
access to the status and control registers, MMCLOCK.SYS does not use them.
Instead, after the counter information has been read/written, MMCLOCK.SYS
reads back the low-order position of the counter and compares it with the
value originally read/written.  If the re-read value does not match the orig-
inal value, the read/write is repeated.

The MM58167A chip has two major flaws which complicate efforts to use it as a
perpetual clock/calendar.  The first problem is that it has no provisions for
keeping track of the year.  The second problem (a logical consequence of the
first) is that it has no concept of a leap year.  Many drivers or other soft-
ware for the MM58167A simply store the year somewhere in the RAM; this tech-
nique doesn't work very well for leap year, however.  Since the RAM may be
used in just about any desired fashion at all, though, it is possible to get
around these problems through clever, unorthodox use of the RAM.

MMCLOCK.SYS handles the date in a manner that completely bypasses the issue
of leap years.  The fourth and fifth byte of the clock chip's RAM are used to
store a 16-bit integer representing the number of days since January 1, 1980.
Each time the date is set in this manner, the "month" and "day" portions of
the clock counter are set to January 1, no matter what the real date might be.

When MMCLOCK.SYS reads the date from the clock, it examines both the count of
days in the RAM and the date information in the counter.  The month and day
from the counter are not used "as is", but are instead translated into an
integer number of days elapsed since January 1.  This number is added to the
RAM's day count to give the current date.

The "day count" technique turns out to be especially convenient, as this is
precisely the format in which DOS expects a clock driver to handle the date
anyway.  MMCLOCK.SYS doesn't need to convert between the day count and a con-
ventional month/day/year format (DOS already does that).  Further, there is
no need to be concerned about leap years.

Whenever the date has advanced since the last time it was set (i.e., whenever
the "month" and "day" information in the counter says something other than
January 1), MMCLOCK.SYS rewrites the date in the RAM and the counter.  This
prevents the month/day information in the counter from getting too high, and
simplifies the task of translating month and day into a number of days.  The
resetting of the date is skipped, however, if the time on the clock is 23:59;
this averts the possibility that the time might roll over to midnight (and a
new day) while the date is being rewritten.

Whenever the time of day is reset, MMCLOCK.SYS also updates the BIOS time-of-
day count (via INT 1AH, function 1).  As a result, any programs which depend
on the BIOS time-of-day count at 0040:006CH will work OK.


REQUIREMENTS FOR A DOS CLOCK DRIVER

The following information may be useful for the programmer who wishes to
write a DOS driver for a different clock/calendar card.  It is assumed that
the reader already understands the basics for writing an installable device
driver under DOS.

The "attribute word" for a clock driver should be 8008H.

The driver needs to handle the various possible I/O requests as follows:

     0 (initialize)
        Initialize the driver.

     4 (read)
        Read the date/time.

     8 (write)
     9 (write and verify)
        Write the date/time.

     1 (media check)
     2 (build parameter block)
     6 (current input status)
     7 (flush input buffers)
    10 (current output status)
    11 (flush output buffers)
    13 (open)
    14 (close)
        Set DONE status bit, but do nothing else.

     5 (non-destructive read)
        Set BUSY, ERROR, and DONE status bits, but do nothing else.

     3 (I/O control read)
    12 (I/O control write)
    15 (removable media check)
    16 (output until busy)
        Set UNKNOWN, ERROR, and DONE status bits, but do nothing
        else.

For "read" and "write" operations, DOS communicates with the clock driver
via a six-byte buffer with the following format (all fields are in straight
binary, not BCD):

    Byte    Meaning

    0-1    Date (16-bit count of days elapsed since 1 January 1980;
        low-order byte comes first).

     2    Minutes (0-59).

     3    Hours (0-23).

     4    Hundredths of a second (0-99).

     5    Seconds (0-59).

CONDITIONS FOR USING MMCLOCK.SYS

MMCLOCK.SYS is Copyright 1990 by Richard B. Wales.  It may be freely used by
anyone without charge.  You may distribute it to anyone, but you may not
charge anything (beyond a nominal copying or communications charge).  You may
not distribute the MMCLOCK.SYS file alone, but you must distribute the source
code and this documentation along with it.  You may not distribute a modified
version of MMCLOCK.SYS, its source, or this documentation unless you clearly
indicate what you have modified.

The author (Richard B. Wales) believes that MMCLOCK.SYS is bug-free.  How-
ever, he is not responsible for any damages which you may incur as a result
of using MMCLOCK.SYS -- including incidental or consequential damages -- even
if he has been informed in advance of the possibility of such damages.  Use
of MMCLOCK.SYS is completely at your own risk, and you accept full responsi-
bility for its use.