MS-DOS 2.0 Device Drivers

INTRODUCTION

In the past, DOS-device driver (BIOS for those who are
familiar with CP/M) communication has been mediated with
registers and a fixed-address jump-table. This approach
has suffered heavily from the following two observations:

o The old jump-table ideas of the past are fixed in
scope and allow no extensibility.

o The past device driver interfaces have been written
without regard for the true power of the hardware.
When a multitasking system or interrupt driven
hardware is installed a new BIOS must be written
largely from scratch.

In MSDOS 2.0, the DOS-device driver interface has changed
from the old jump-table style to one in which the device
drivers are linked together in a list. This allows new
drivers for optional hardware to be installed (and even
written) in the field by other vendors or the user himself.
This flexibility is one of the major new features of MS-DOS
2.0.

Each driver in the chain defines two entry points; the
strategy routine and the interrupt routine. The 2.0 DOS
does not really make use of two entry points (it simply calls
strategy, then immediately calls interrupt). This dual entry
point scheme is designed to facilitate future multi-tasking
versions of MS-DOS. In multi-tasking environments I/O must
be asynchronous, to accomplish this the strategy routine
will be called to queue (internally) a request and return
quickly. It is then the responsibility of the interrupt
routine to perform the actual I/O at interrupt time by picking
requests off the internal queue (set up by the strategy
routine), and process them. When a request is complete,
it is flagged as "done" by the interrupt routine. The DOS
periodically scans the list of requests looking for ones
flagged as done, and "wakes up" the process waiting for the
completion of the request.

In order for requests to be queued as above it is no
longer sufficient to pass I/O information in registers, since
many requests may be pending at any one time. Therefore
the new device interface uses data "packets" to pass request
information. A device is called with a pointer to a packet,
this packet is linked into a global chain of all pending
I/O requests maintained by the DOS. The device then links
the packet into its own local chain of requests for this
particular device. The device interrupt routine picks
requests of the local chain for processing. The DOS scans
the global chain looking for completed requests. These
packets are composed of two pieces, a static piece which
has the same format for all requests (called the static
request header), which is followed by information specific
to the request. Thus packets have a variable size and format.

At this points it should be emphasized that MS-DOS 2.0
does not implement most of these features, as future versions
will. There is no global or local queue. Only one request
is pending at any one time, and the DOS waits for this current
request to be completed. For 2.0 it is sufficient for the
strategy routine to simply store the address of the packet
at a fixed location, and for the interrupt routine to then
process this packet by doing the request and returning.
Remember: the DOS just calls the strategy routine and then
immediately calls the interrupt routine, it is assumed that
the request is completed when the interrupt routine returns.
This additional functionality is defined at this time so
that people will be aware and thinking about the future.

FORMAT OF A DEVICE DRIVER

A device driver is simply a relocatable memory image
with all of the code in it to implement the device (like
a .COM file, but not ORGed at 100 Hex). In addition it has
a special header at the front of it which identifies it as
a device, defines the strategy and interrupt entry points,
and defines various attributes. It should also be noted
that there are two basic types of devices.

The first is character devices. These are devices which
are designed to do character I/O in a serial manner like
CON, AUX, and PRN. These devices are named (ie. CON, AUX,
CLOCK, etc.), and users may open channels (FCBs) to do I/O
to them.

The second class of devices is block devices. These
devices are the "disk drives" on the system, they can do
random I/O in pieces called blocks (usually the physical
sector size) and hence the name. These devices are not
"named" as the character devices are, and therefore cannot
be "opened" directly. Instead they are "mapped" via the
drive letters (A,B,C, etc.).

Block devices also have units. In other words a single
driver may be responsible for one or more disk drives. For
instance block device driver ALPHA (please note that we cannot
actually refer to block devices by a name!) may be
responsible for drives A,B,C and D, this simply means that
it has four units (0-3) defined and therefore takes up four
drive letters. Which units correspond to which drive letters
is determined by the position of the driver in the chain
of all drivers: if driver ALPHA is the first block driver
in the device chain, and it defines 4 units (0-3), then they
will be A,B,C and D. If BETA is the second block driver
and defines three units (0-2), then they will be E,F and
G and so on. MS-DOS 2.0 is not limited to 16 block device
units, as previous versions were. The theoretical limit
is 63 (2^6 - 1), but it should be noted that after 26 the
drive letters get a little strange (like ] \ and ^). NOTE:
Character devices cannot define multiple units (this because
they have only one name).

Here is what that special device header looks like:

Note that the device entry points are words. They must
be offsets from the same segment number used to point to
this table. Ie. if XXX.YYY points to the start of this
table, then XXX.strategy and XXX.interrupt are the entry
points.

A word about the Attribute field. This field is used
most importantly to tell the system whether this device is
a block or character device (bit 15). Most of other bits
are used to give selected character devices certain special
treatment (NOTE: these bits mean nothing on a block device).
Let's say a user has a new device driver which he wants to
be the standard input and output. Besides just installing
the driver he needs to tell SYSINIT (and the DOS) that he
wishes his new driver to override the current sti and sto
(the "CON" device). This is accomplished by setting the
attributes to the desired characteristics, so he would set
Bits 0 and 1 to 1 (note that they are separate!!). Similarly
a new CLOCK device could be installed by setting that
attribute, see the section at the end on the CLOCK device.
NOTE: that although there is a NUL device attribute, the
NUL device cannot be re-assigned. This attribute exists
for the DOS so that it can tell if the NUL device is being
used.

The NON IBM FORMAT bit applies only to block devices
and effects the operation of the get BPB device call (see
below).

The other bit of interest is the IOCTL bit which has
meaning on character or block devices. This bit tells the
DOS whether this device can handle control strings (via the
IOCTL system call).

If a driver cannot process control strings, it should
initially set this bit to 0. This tells the DOS to return
an error if an attempt is made (via IOCTL system call) to
send or receive control strings to this device. A device
which can process control strings should initialize it to
1. For drivers of this type, the DOS will make calls to
the IOCTL INPUT and OUTPUT device functions to send and
receive IOCTL strings (see IOCTL in the SYSTEM-CALLS
document).

The IOCTL functions allow data to be sent and received
by the device itself for its own use (to set baud rate, stop
bits, form length etc., etc.), instead of passing data over
the device channel as a normal read or write does. The
interpretation of the passed information is up to the device,
but it MUST NOT simply be treated as a normal I/O.

The SPECIAL bit applies only to character drivers and
more particularly to CON drivers. The new 2.0 interface
is a much more general and consistent interface than the
old 1.25 DOS interface. It allows for a number of additional
features of 2.0. It is also slower than 1.25 if old style
"single byte" system calls are made. To make most efficient
use of the interface all applications should block their
I/O as much as possible. This means make one XENIX style
system call to output X bytes rather than X system calls
to output one byte each. Also putting a device channel in
RAW mode (see IOCTL) provides a means of putting out
characters even FASTER than 1.25. To help alleviate the
CON output speed problem for older programs which use the
1 - 12 system calls to output large amounts of data the
SPECIAL bit has been implemented. If this bit is 1 it means
the device is the CON output device, and has implemented
an interrupt 29 Hex handler, where the 29 Hex handler is
defined as follows:

Interrupt 29h handlers

Input:
Character in AL

Function:
output the character in al to the user
screen.
Output:
None
Registers:
all registers except bx must be preserved.
No registers except for al have a known or
consistent value.

If a character device implements the SPECIAL bit, it
is the responsibility of the driver to install an address
at the correct location in the interrupt table for interrupt
29 Hex as part of its INIT code. IMPLICATION: There can
be only one device driver with the SPECIAL bit set in the
system. There is no check to insure this state.

WARNING: THIS FEATURE WILL NOT BE SUPPORTED IN FUTURE VERSIONS
OF THE OPERATING SYSTEM. IMPLICATION: Any application
(not device driver) which uses INT 29H directly will
not work on future versions, YOU HAVE BEEN WARNED.

In order to "make" a device driver that SYSINIT can
install, a memory image or .EXE (non-IBM only) format file
must be created with the above header at the start. The
link field should be initialized to -1 (SYSINIT fills it
in). The attribute field and entry points must be set
correctly, and if the device is a character device, the name
field must be filled in with the name (if a block device
SYSINIT will fill in the correct unit count). This name
can be any 8 character "legal" file name. In fact SYSINIT
always installs character devices at the start of the device
list, so if you want to install a new CON device all you
have to do is name it "CON". The new one is ahead of the
old one in the list and thus preempts the old one as the
search for devices stops on the first match. Be sure to
set the sti and sto bits on a new CON device!

NOTE: Since SYSINIT may install the driver anywhere, you
must be very careful about FAR memory references. You
should NOT expect that your driver will go in the same
place every time (The default BIOS drivers are exempted
from this of course).

INSTALLATION OF DEVICE DRIVERS

Unlike past versions MS-DOS 2.0 allows new device drivers
to be installed dynamically at boot time. This is
accomplished by the new SYSINIT module supplied by Microsoft,
which reads and processes the CONFIG.SYS file. This module
is linked together with the OEM default BIOS in a similar
manner to the way FORMAT is built.

One of the functions defined for each device is INIT.
This routine is called once when the device is installed,
and never again. The only thing returned by the init routine
is a location (DS:DX) which is a pointer to the first free
byte of memory after the device driver, (like a terminate
and stay resident). This pointer method can be used to "throw
away" initialization code that is only needed once, saving
on space.

Block devices are installed the same way and also return
a first free byte pointer as above, additional information
is also returned:

o The number of units is returned, this determines
logical device names. If the current maximum logical
device letter is F at the time of the install call,
and the init routine returns 4 as the number of units,
then they will have logical names G, H, I and J.
This mapping is determined by by the position of
the driver in the device list and the number of units
on the device (stored in the first byte of the device
name field).

o A pointer to a BPB (Bios Parameter Block) pointer
array is also returned. This will be similar to
the INIT table used in previous versions, but will
have more information in it. There is one table
for each unit defined. These blocks will be used
to build a DPB (Drive Parameter Block) for each of
the units. The pointer passed to the DOS from the
driver points to an array of n word pointers to BPBs
where n is the number of units defined. In this
way if all units are the same, all of the pointers
can point to the same BPB, saving space. NOTE: this
array must be protected (below the free pointer set
by the return) since the DPB will be built starting
at the byte pointed to by the free pointer. The
sector size defined must be less than or equal to
the maximum sector size defined at default BIOS init
time. If it isn't the install will fail. One new
piece of DPB info set from this table will be a "media
descriptor byte". This byte means nothing to the
DOS, but is passed to devices so that they know what
form of a DPB the DOS is currently using for a
particular Drive-Unit.

Block devices may take several approaches; they may be
dumb or smart. A dumb device would define a unit (and
therefore a DPB) for each possible media drive combination.
Unit 0 = drive 0 single side, unit 1 = drive 0 double side,
etc. For this approach media descriptor bytes would mean
nothing. A smart device would allow multiple media per unit,
in this case the BPB table returned at init must define space
large enough to accommodate the largest possible media
supported. Smart drivers will use the "media byte" to pass
around info about what media is currently in a unit. NOTE:
If the DPB is a "hybrid" made to get the right sizes, it
should give an invalid "media byte" back to the DOS.

The BOOT (default BIOS) drivers are installed pretty
much as above. The preset device list is scanned. If block
drivers are encountered they are installed as above (with
the exception that the break is not moved since the drivers
are already resident in the BIOS). Note that the logical
drive letters are assigned in list order, thus the driver
which is to have logical A must be the first unit of the
first block device in the list. The order of character
devices is also important. There must be at least 4 character
devices defined at boot which must be the first four devices
(of either type), the first will become standard input,
standard output, and standard error output. The second will
become standard auxiliary input and output, the third will
become standard list output, and the forth will become the
date/time (CLOCK) device. Thus the BIOS device list must
look like this:

->CON->AUX->PRN->CLOCK->any other block or character devices

THE DRIVER

A device driver will define the following functions:

Command Function
Code

0 INIT
1 MEDIA CHECK (Block only, NOP for character)
2 BUILD BPB " " " " "
3 IOCTL INPUT (Only called if device has IOCTL)
4 INPUT (read)
5 NON-DESTRUCTIVE INPUT NO WAIT (Char devs only)
6 INPUT STATUS " " "
7 INPUT FLUSH " " "
8 OUTPUT (write)
9 OUTPUT (Write) with verify
10 OUTPUT STATUS " " "
11 OUTPUT FLUSH " " "
12 IOCTL OUTPUT (Only called if device has IOCTL)

As mentioned before, the first entry point is the strategy
routine which is called with a pointer to a data block. This
call does not perform the request, all it does is queue it
(save the data block pointer). The second interrupt entry
point is called immediately after the strategy call. The
"interrupt" routine is called with no parameters, its primary
function is to perform the operation based on the queued
data block and set up any returns.

The "BUILD BPB" and "MEDIA CHECK" are the interesting
new ones, these are explained by examining the sequence of
events in the DOS which occurs when a drive access call (other
than read or write) is made:

I. Turn drive letter into DPB pointer by looking
for DPB with correct driver-unit number.

II. Call device driver and request media check for
Drive-Unit. DOS passes its current Media
descriptor byte (from DPB). Call returns:

Media Not Changed
Media Changed
Not Sure
Error

Error - If an error occurs the error code should
be set accordingly.

Media Not changed - Current DPB and media byte
are OK, done.

Media Changed - Current DPB and media are wrong,
invalidate any buffers for this unit, and
goto III.

Not Sure - If there are dirty buffers for this
unit, assume DPB and media byte are OK and
done. If nothing dirty, assume media changed,
invalidate any buffers for unit, and goto
III.

NOTE: If a hybrid DPB was built at init and
an invalid Media byte was set, the driver
should return media changed when this invalid
media byte is encountered.

III. Call device driver to build BPB with media byte
and buffer.

What the driver must do at step III is determine the
correct media that is currently in the unit, and return a
pointer to a BPB table (same as for the install call). This
table will be used as at init to build a correct DPB for
the unit If the determined media descriptor byte in the table
turns out to be the same as the one passed in, then the DOS
will not build a new table, but rather just use the old one.
Therefore in this case the driver doesn't have to correctly
fill in the other entries if desired.

The build BPB call also gets a pointer to a one sector
buffer. What this buffer contains is determined by the NON
IBM FORMAT bit in the attribute field. If the bit is zero
(device is IBM format compatible) then the buffer contains
the first sector of the first FAT, in particular the FAT
ID byte is the first byte of this buffer. NOTE: It must
be true that the BPB is the same, as far as location of the
FAT is concerned, for all possible media. This is because
this first FAT sector must be read BEFORE the actual BPB
is returned. If the NON IBM FORMAT bit is set then the
pointer points to one sector of scratch space which may be
used for anything.

CALL FORMAT

When the DOS calls a device driver to perform a finction,
it passes a structure (Drive Request Structure) in ES:BX
to perform operations and does a long call to the driver's
strategy entry point. This structure is a fixed length header
(Static Request Header) followed by data pertinent to the
operation being performed. NOTE: It is the drivers
responsibility to preserve machine state.

STATUS WORD

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+---+---+--+--+--+--+---+---+--+--+--+--+--+--+--+--+
| E | | B | D | |
| R | RESERVED | U | O | ERROR CODE (bit 15 on)|
| R | | I | N | |
+---+---+--+--+--+--+---+---+--+--+--+--+--+--+--+--+

The status word is zero on entry and is set by the driver
interrupt routine on return.

Bit 8 is the done bit, it means the operation is complete.
For the moment the Driver just sets it to one when it exits,
in the future this will be set by the interrupt routine to
tell the DOS the operation is complete.

Bit 15 is the error bit, if it is set then the low 8
bits indicate the error:

0 Write Protect violation
(NEW) 1 Unknown Unit
2 Drive not ready
(NEW) 3 Unknown command
4 CRC error
(NEW) 5 Bad Drive Request Structure length
6 Seek error
(NEW) 7 Unknown media
8 Sector not found
(NEW) 9 Printer out of paper
A Write Fault
(NEW) B Read Fault
C General Failure

Bit 9 is the busy bit which is set only by status calls (see
STATUS CALL below).

Here is the data block format for each function:

READ or WRITE - ES:BX (Including IOCTL) ->
+------------------------------------+
| 13-BYTE Static Request Header |
+------------------------------------+
| BYTE Media descriptor from DPB |
+------------------------------------+
| DWORD transfer address |
+------------------------------------+
| WORD byte/sector Count |
---+------------------------------------+---
| WORD starting sector number |
| (ignored on Char Devs) |
+------------------------------------+

In addition to setting the status word, the driver must
set the Sector count to the actual number of sectors (or
bytes) transferred. NOTE: No error check is performed on
an IOCTL I/O call, driver MUST correctly set the return sector
(byte) count to the actual number of bytes transferred,
however.

NOTE: THE FOLLOWING APPLIES TO BLOCK DEVICE DRIVERS.

Under certain circumstances the BIOS may be asked to
do a write operation of 64K bytes which seems to be a "wrap
around" of the transfer address in the BIOS I/O packet. This
arises due to an optimization added to the write code in
MS-DOS. It will only manifest on user WRITEs which are within
a sector size of 64K bytes on files which are "growing" past
the current EOF. IT IS ALLOWABLE FOR THE BIOS TO IGNORE
THE BALANCE OF THE WRITE WHICH "WRAPS AROUND" IF IT SO
CHOOSES. For instance a WRITE of 10000H bytes worth of
sectors with a transfer address of XXX:1 could ignore the
last two bytes (remember that a user program can never request
an I/O of more than FFFFH bytes and cannot wrap around (even
to 0) in his transfer segment, so in this case the last two
bytes can be ignored).

NON DESRUCTIVE READ NO WAIT - ES:BX ->
+------------------------------------+
| 13-BYTE Static Request Header |
+------------------------------------+
| BYTE read from device |
+------------------------------------+

This call is analogous to the console input status call
on MS-DOS 1.25. If the character device returns Busy bit
= 0 (characters in buffer), then the next character that
would be read is returned. This character is NOT removed
from the input buffer (hence the term Non Destructive Read).
In essence this call allows the DOS to look ahead one input
character.

MEDIA CHECK - ES:BX ->
+------------------------------------+
| 13-BYTE Static Request Header |
+------------------------------------+
| BYTE Media Descriptor from DPB |
+------------------------------------+
| BYTE returned |
+------------------------------------+

In addition to setting status word, driver must set the
return byte.

Return Byte :
-1 Media has been changed
0 Don't know if media has been changed
1 Media has not been changed

If the driver can return -1 or 1 (by having a door-lock
or other interlock mechanism) the performance of MSDOS 2.0
is enhanced as the DOS need not reread the FAT for each
directory access.

If the NON IBM FORMAT bit of the device is set, then
the DWORD Transfer Address points to a one sector buffer
which can be used for any purpose. If the NON IBM FORMAT
bit is 0, then this buffer contains the first sector of the
FAT; in this case the driver must not alter this buffer (this
mode is useful if all that is desired is to read the FAT
ID byte).

If IBM compatible format is used (NON IBM FORMAT BIT
= 0), then it must be true that the first sector of the first
FAT is located at the same sector on all possible media.
This is because the FAT sector will be read BEFORE the media
is actually determined.

In addition to setting status word, driver must set the
Pointer to the BPB on return.

In order to allow for many different OEMs to read each
other's disks, the following standard is suggested: The
information relating to the BPB for a particular piece of
media is kept in the boot sector for the media. In
particular, the format of the boot sector is:

+------------------------------------+
| 3 BYTE near JUMP to boot code |
+------------------------------------+
| 8 BYTES OEM name and version |
---+------------------------------------+---
B | WORD bytes per sector |
P +------------------------------------+
B | BYTE sectors per allocation unit |
+------------------------------------+
| | WORD reserved sectors |
V +------------------------------------+
| BYTE number of FATs |
+------------------------------------+
| WORD number of root dir entries |
+------------------------------------+
| WORD number of sectors in logical |
^ | image |
| +------------------------------------+
B | BYTE media descriptor |
P +------------------------------------+
B | WORD number of FAT sectors |
---+------------------------------------+---
| WORD sectors per track |
+------------------------------------+
| WORD number of heads |
+------------------------------------+
| WORD number of hidden sectors |
+------------------------------------+

The three words at the end are optional, the DOS doesn't
care about them (since they are not part of the BPB). They
are intended to help the BIOS understand the media. Sectors
per track may be redundant (could be figured out from total
size of the disk). Number of heads is useful for supporting
different multi-head drives which have the same storage
capacity, but a different number of surfaces. Number of
hidden sectors is useful for supporting drive partitioning
schemes.

Currently, the media descriptor byte has been defined
for a small range of media:

5 1/4" diskettes:

Flag bits:
01h - on -> 2 double sided

All other bits must be on.

8" disks:
FEh - IBM 3740 format, singled-sided, single-density,
128 bytes per sector, soft sectored, 4 sectors
per allocation unit, 1 reserved sector, 2 FATs,
68 directory entries, 77*26 sectors

FDh - 8" IBM 3740 format, singled-sided,
single-density, 128 bytes per sector, soft
sectored, 4 sectors per allocation unit, 4
reserved sectors, 2 FATs, 68 directory entries,
77*26 sectors

FEh - 8" Double-sided, double-density, 1024 bytes
per sector, soft sectored, 1 sector per allocation
unit, 1 reserved sector, 2 FATs, 192 directory
entries, 77*8*2 sectors

STATUS Calls - ES:BX ->
+------------------------------------+
| 13-BYTE Static Request Header |
+------------------------------------+

All driver must do is set status word accordingly and
set the busy bit as follows:

o For output on character devices: If it is 1 on
return, a write request (if made) would wait for
completion of a current request. If it is 0, there
is no current request and a write request (if made)
would start immediately.

o For input on character devices with a buffer a return
of 1 means, a read request (if made) would go to
the physical device. If it is 0 on return, then
there are characters in the devices buffer and a
read would return quickly, it also indicates that
the user has typed something. The DOS assumes all
character devices have an input type ahead buffer.
Devices which don't have them should always return
busy = 0 so that the DOS won't hang waiting for
something to get into a buffer which doesn't exist.

FLUSH Calls - ES:BX ->
+------------------------------------+
| 13-BYTE Static Request Header |
+------------------------------------+

This call tells the driver to flush (terminate) all
pending requests that it has knowledge of. Its primary use
is to flush the input queue on character devices.

The number of units, break address, and BPB pointer are
set by the driver.

FORMAT OF BPB (Bios Parameter Block) -

+------------------------------------+
| WORD Sector size in Bytes |
| Must be at least 32 |
+------------------------------------+
| BYTE Sectors/Allocation unit |
| Must be a power of 2 |
+------------------------------------+
| WORD Number of reserved sectors |
| May be zero |
+------------------------------------+
| BYTE Number of FATS |
+------------------------------------+
| WORD Number of directory entries |
+------------------------------------+
| WORD Total number of sectors |
+------------------------------------+
| BYTE Media descriptor |
+------------------------------------+
| WORD Number of sectors occupied by |
| FAT |
+------------------------------------+

THE CLOCK DEVICE

One of the most popular add on boards seems to be "Real
Time CLOCK Boards". To allow these boards to be integrated
into the system for TIME and DATE, there is a special device
(determined by the attribute word) which is the CLOCK device.
In all respects this device defines and performs functions
like any other character device (most functions will be "set
done bit, reset error bit, return). When a read or write
to this device occurs, exactly 6 bytes are transferred. This
I/O can be thought of as transferring 3 words which correspond
exactly to the values of AX, CX and DX which were used in
the old 1.25 DOS date and time routines. Thus the first
two bytes are a word which is the count of days since 1-1-80.
The third byte is minutes, the fourth hours, the fifth
hundredths of seconds, and the sixth seconds. Reading the
CLOCK device gets the date and time, writing to it sets the
date and time.
�����������������������������������������������������������������������