|
|
MICROSOFT(R)
MS(tm)-DOS
Adaptation Guide
Last Updated on JULY 24, 1987in conjunction with the MS-DOS 3.30 FINAL RELEASE
Microsoft Corporation
Information in this document is subject to change withoutnotice and does not represent a commitment on the part ofMicrosoft Corporation. The software described in thisdocument is furnished under a license agreement ornon-disclosure agreement. The software may be used orcopied only in accordance with the terms of that agreement.It is against the law to copy the MS-DOS Disk OperatingSystem on magnetic tape, disk, or any other medium for anypurpose other than the purchaser's personal use.
Copyright (C) Microsoft Corporation, 1982, 1983, 1984, 1985, 1986
INTEL is a registered trademark of Intel Corporation.
IBM is a registered trademark of International BusinessMachines Corporation.
Microsoft, the Microsoft logo, and MS-DOS are registeredtrademarks of Microsoft Corporation.
XENIX is a trademark of Microsoft Corporation.
TABLE OF CONTENTS
CHAPTER 1 MS-DOS INSTALLATION KIT
1.1 README.DOC File 1-1
CHAPTER 2 MS-DOS DEVELOPMENT TOOLS
CHAPTER 3 INSTALLING MS-DOS
CHAPTER 4 DISK STRUCTURE AND BOOTSTRAP LOADING CHAPTER 5 RESIDENT DEVICE DRIVERS
CHAPTER 6 SYSINIT AND MS-DOS INITIALIZATION
CHAPTER 7 WRITING THE FORMAT MODULE
CHAPTER 8 TROUBLE SHOOTING
APPENDIX A CUSTOMIZATION OF MS-DOS AND INTERNATIONALIZATION
A.1 Customizing MS-DOS A-1 A.2 ECS Considerations -- MS-DOS 2.25 A-2 A.3 Input A-3 A.4 Output A-3
APPENDIX B HOW TO UPGRADE A 2.X BIOS TO 3.X
APPENDIX C HOW TO UPGRADE A 3.1 BIOS TO 3.2
APPENDIX D DEVICE DRIVERS - CHAPTER 2 MS-DOS 3.20 PROGRAMMER'S REFERENCE
APPENDIX E MS-DOS 2.25 DEVICE DRIVER EXTENSIONS
APPENDIX F MS-DOS 2.25 APPLICATION LEVEL INTERFACE EXTENSION
APPENDIX G SPECIAL DOC
APPENDIX H PROGRAMMING RECOMMENDATIONS - CHAPTER 7 MS-DOS 3.20 PROGRAMMER'S REFERENCE
GLOSSARY OF MS-DOS TERMS
CONTENTS CHAPTER 1 MS-DOS INSTALLATION KIT
1.1 README.DOC File 1-1
1.2 Contents 1-1
1.3 Common Questions and Answers 1-2
1.4 MS-DOS Hardware Requirements 1-3
1.5 MS-DOS Overview 1-5
CHAPTER 1
MS-DOS INSTALLATION KIT
1.1 README.DOC FILE
Check the README.DOC file on DISTRIBUTION DISKETTES forversion specific information and any addenda to this document.
1.2 CONTENTS
The MS-DOS 3.21 Installation Kit is provided on 5-1/4" high capacity1.2 Megabyte disks. It consists of the MS-DOS DISTRIBUTIONDISKETTES that include files formerly foundversion.
Included with the kit is a Sample MS-DOS 2.XX/3.XX Implementation.The sample implementation runs on all members of the IBM PC family and is intended to be functionally equivalent to the IBM implementation. The purpose of this sample is to assist Microsoft OEMs with their MS-DOS installations, but can also be used directly as part of the OEMsproduct. IO.SYS, the BIOS, has been intended to be self documenting and Microsoft will support services for it as it run on IBM PCs.
Included in the kit is a copy of the current Microsoft(R) Macro Assemblerfeaturing SYMDEB, the symbolic debugger. The full MASM retail package isno longer provided.
The installation kit also includes four manuals:
MS-DOS User's Guide. This is an introduction to ______ ______ _____ MS-DOS, including how to start the system and use applications.
MS-DOS User's Reference Manual. This manual ______ ______ _________ ______ explains hierarchical directories, the MS-DOS file structure, and MS-DOS commands and utilities. This manual is new in 3.XX.
MS-DOS Programmer's Reference Manual. This manual ______ ____________ _________ ______ includes a summary of all published system calls and MS-DOS structures.
MS-DOS Adaptation Guide. This manual describes how ______ __________ _____ to implement MS-DOS on OEM machines. This guide is available on diskette only and is the text you are now reading.
MS-DOS INSTALLATION KIT Page 1-2
1.3 COMMON QUESTIONS AND ANSWERS
Q. What kind of development machine do you recommend?
A. Microsoft recommends that an MS-DOS machine be used as a development tool in preparing software for your target machine. Using an MS-DOS machine avoids problems with incompatible assemblers and object module formats. You may want to read standard MS-DOS disk formats. Using the development machine to build a system disk for the target machine simplifies the implementation process.
Q. Are sources available?
A. Sources for MS-DOS are not available (except for the sample BIOS implementation).
Q. What language is MS-DOS written in?
A. The source code for MS-DOS and most utilities is written in 8086 assembler code. It is compatible with the macro facility found in Microsoft Macro Assembler for the MS-DOS operating system. The format of the object modules provided is a subset of the INTEL(R) format, and may not be compatible with non-Microsoft linkers.
Q. What does an MS-DOS implementor need to know?
A. To install MS-DOS, you will need to be familiar with systems programming in 8086 assembler language. This means you should have experience in writing device drivers for disk drives, keyboards, printers, and other peripherals.
Q. How long does it take to install MS-DOS?
A. This depends on whether the low-level I/O routines are already written. The record time for getting MS-DOS up and running on a new machine is one weekend. In this case, all of the low-level routines were in ROM. Typically, a complete customer-ready MS-DOS implementation takes two or more months.
MS-DOS INSTALLATION KIT Page 1-3
Q. Are there any consultants who do MS-DOS implementations?
A. Microsoft can supply a list of consultants who have done MS-DOS implementations. Microsoft cannot make any recommendations regarding the competence of these consultants.
Q. Do you recommend that we have an In Circuit Emulator (ICE) for our machine?
A. Yes. Since there are no MS-DOS debugging tools that can be used to debug the boot sequence, an ICE is very helpful.
1.4 MS-DOS HARDWARE REQUIREMENTS
To be compatible with the MS-DOS operating system, a machinemust conform to certain hardware characteristics. Thesecharacteristics are as follows:
o The processor must be INTEL 8086 compatible.
o The Interrupt vector locations 20H through 3FH must be reserved for MS-DOS.
o Four character device drivers and one block device driver are required. They must recognize the MS-DOS device driver call format.
o An ANSI terminal driver must be implemented. (MS-DOS sends an ANSI escape sequence to clear the console.)
o A logical disk, as described in this document, must be available to MS-DOS. A disk format table, as described in this document, should be present in the first logical sector of each disk. Logical sectors must be a multiple of 64 bytes in size.
o Random Access Memory (RAM) should be contiguous from the point where MS-DOS is located through top of memory.
o MS-DOS requires a minimum of 128K of RAM (depending on IO.SYS size). Microsoft recommends a minimum configuration of 128K non-video RAM and 192K for future products.
The sample BIOS that is provided has been designed to only run ona machine with the exact architecture of IBM PC family. If MS-DOS can run on the OEMs hardware using the sample BIOS, thenthe hardware is compatible with the IBM PC family architecture.
MS-DOS INSTALLATION KIT Page 1-4
In addition to these minimum requirements, the followinghardware features are recommended for optimum performance aswell as compatibility with new Microsoft products. Featuresrecommended for performance on 2.0 and higher systems arestarred.
o *An interrupt-driven keyboard with a type-ahead buffer (Interrupt-driven I/O for all devices).
o *Direct memory access.
o *Non-interlaced disks.
o *Disk door locks or a detection mechanism to check if disks have been changed.
o Support of standard MS-DOS disk formats.
o User-addressable bit-mapped video display with minimum resolution of 640 by 200 pixels.
o Programmable interval timer.
o Mouse support.
o RS-232 and printer interfaces.
o Minimum 192K RAM memory.
o A Scroll Lock/Break key that puts a Control-S and Control-C at the beginning of the keyboard type-ahead buffer when pressed.
MS-DOS INSTALLATION KIT Page 1-5
1.5 MS-DOS OVERVIEW
An MS-DOS implementation requires seven components:
1. The resident device drivers (the IO.SYS file), a collection of hardware-specific device drivers that must be written by the OEM. The resident device drivers are called by MS-DOS to handle I/O requests. These device drivers may be partly ROM resident or may be completely RAM resident.
2. The SYSINIT Module(s), (SYSINIT1.OBJ and SYSINIT2.OBJ in 3.xx and only SYSINIT.OBJ in 2.xx) and SYSIMES.OBJ, Microsoft-supplied modules which are linked to the resident device drivers and initialize the system. The file that contains these device drivers is named IO.SYS (on the IBM(R) PC, this file is named IBMBIO.COM).
3. MSDOS.SYS, the hardware-independent disk operating system supplied by Microsoft. (On the IBM PC, this file is named IBMDOS.COM.)
4. COMMAND.COM, the command interpreter program that reads and interprets keyboard input, executes "built-in" commands like DIR, and initiates external programs.
5. Bootstrap loader, the OEM-supplied module that loads the IO.SYS and MSDOS.SYS files into memory. MSDOS.SYS may optionally be loaded by IO.SYS. A sample bootstrap loader has been provided with the OEM kit. This sample bootstrap loader is compatible with the IBM PC family.
6. A system ROM which may optionally perform diagnostics on power-up or reset. The system ROM loads the boot sector into RAM and transfers control to it.
7. MS-DOS utilities, including FORMAT, for which Microsoft modules are provided and a hardware-specific section must be written by the OEM. NOTE: Refer to the MS-DOS 3.3 specific portions for use of the hardware independent FORMAT utility.
MS-DOS INSTALLATION KIT
CONTENTS
CHAPTER 2 MS-DOS DEVELOPMENT TOOLS
EDLIN Text Editor 2-1
Microsoft Macro Assembler 2-1
Microsoft Linker (MS-LINK) 2-2
MS-DEBUG 2-2
EXE2BIN 2-2
FORMAT 2-2
CHAPTER 2
MS-DOS DEVELOPMENT TOOLS
An assembler, text editor, linker, and other utilities arerequired for completing an MS-DOS implementation. We assumethat your development machine has the following standardutilities:
EDLIN Text Editor
The EDLIN text editor provided with MS-DOS for your development machine may be used to prepare assembler source files. The version of EDLIN on MS-DOS 2.x and 3.x release disks is for versions 2.x and 3.x only, and will not run under MS-DOS 1.x. A third party full screen text editor (not a word processor) may be more efficient for manipulating source files.
Microsoft Macro Assembler
A complimentary copy of the current Microsoft Macro Assembler is provided with the MS-DOS installation kit. The assembler is not actually a part of MS-DOS; it must be licensed separately if you wish to ship it to your customers. The Cross-Reference Utility (MS-CREF), included with Microsoft Macro Assembler, can be used to make cross-reference listings of assembler programs. The Microsoft Macro Assembler package will only run under MS-DOS 2.XX and later operating systems. The output of the assembler is a relocatable object module (.OBJ file type) which conforms to a subset of the INTEL MCS 86 object module format description. Refer to the MS-DOS Programmer's Reference Manual for ______ ____________ _________ ______ information on the INTEL MCS 86 object module format description.
MS-DOS DEVELOPMENT TOOLS Page 2-2
Microsoft Linker (MS-LINK)
Your MS-DOS development machine should include a linker named LINK.EXE. Use LINK.EXE for linking object modules (.OBJ files) produced by the Microsoft Macro Assembler. The output of the Linker is a file with an .EXE format. This is an executable program requiring a special loader that is part of MS-DOS. Refer to the MS-DOS Programmer's Reference Manual for details on ______ ____________ _________ ______ .EXE formats.
SYMDEB
SYMDEB.EXE is the MS-DOS symbolic debugger. The debugger can do absolute disk reads and writes. You may use this facility to write your bootstrap loader program into the boot sector. Note that since MS-DOS is not reentrant, this debugger may not be used to set break points within the DOS or device drivers.
EXE2BIN
The EXE2BIN.EXE utility supplied with your MS-DOS development machine must be used for converting output from the Linker (.EXE files) to a pure binary (core image) format not requiring a special loader. Note that only .COM files may execute out of ROM.
FORMAT
The FORMAT program (FORMAT.EXE) supplied with your MS-DOS development machine may be used to format a boot disk for the target machine, assuming both machines have compatible media.
EXEFIX
EXEFIX is a special purpose utility used for building SORT. It sets the maximum memory allocation.
MS-DOS DEVELOPMENT TOOLS
CONTENTS
CHAPTER 3 INSTALLING MS-DOS
CHAPTER 3
INSTALLING MS-DOS
If you are using an MS-DOS machine for development and yourtarget machine will read MS-DOS standard disk formats,follow these steps to implement MS-DOS.
NOTE: The steps involved in developing IO.SYS are not necessary if the sample BIOS provided with the OEM kit is used. This sample can also be used for technical reference.
1. Using a text editor on your development machine, write the 8086 assembler source code for the resident device drivers. The resident device drivers are the hardware-specific routines that will be accessed by MS-DOS to perform I/O. There must be a minimum of five device drivers: four ____ character drivers and one block device driver (the disk drive on most systems). In addition to the device drivers, you may want to include some code for hardware initialization. The source file should be named IO.ASM and must not contain a STACK segment.
For more information, see: MS-DOS Programmer's Reference Manual ______ ____________ _________ ______ IO.ASM on the distribution disk The resident device driver section of this manual
2. Use MASM.EXE, the macro assembler provided with your MS-DOS installation kit to assemble your device driver code. MASM will create a file called IO.OBJ, which is in a special object module format (a subset of INTEL's object module format).
For more information, see: Microsoft Macro Assembler Manual (Macro Assembler _________ _____ _________ ______ section)
3. Use LINK.EXE, the Microsoft Linker, to link your IO.OBJ module to appropriate SYSINIT.OBJ module(s)and the appropriate SYSIMES.OBJ module. The modules must be linked in this order:
2.xx IO.OBJ+SYSINIT.OBJ+SYSIMES.OBJ
3.XX IO.OBJ+SYSINIT1.OBJ+SYSINIT2.OBJ+SYSIMES.OBJ
The output file should be named IO.EXE. You INSTALLING MS-DOS Page 3-2
may get the message "Warning, no STACK segment" while linking the module. This is a warning message and is normal with some versions of the linker.
For more information, see: Microsoft Macro Assembler Manual (Chapter 3 LINK: _________ _____ _________ ______ A Linker)
4. The file created in step 3 is an .EXE file which is in a special format recognized by the .EXE loader. Since the .EXE loader is not available at boot time, the IO.EXE file must be converted to a pure binary core image file. This is done with the EXE2BIN utility provided with the MS-DOS release on your development machine. The EXE2BIN utility must know exactly where the code will reside in memory to resolve any FAR references. You will be prompted for the base address, the absolute segment address where the code will begin. The resultant file must be named IO.SYS. EXE2BIN will change the name when you type the following command line:
EXE2BIN IO.EXE IO.SYS
------------------------------------------------------------| || Note || || It is the responsibility of the bootstrap loader to || locate IO.SYS at the location you specified as the base || address. The location itself is arbitrary, since one || of the parameters that the resident device driver code || passes to SYSINIT is the location of the first device || driver. || ||__________________________________________________________|
For more information, see: MS-DOS User's Reference Manual (Chapter 3) ______ ______ _________ ______
5. Customize the function key table in DOSMES.ASM.
6. Use MSDOSBLD.BAT on the distribution disk to assemble appropriate object modules and link them with those already provided to form MSDOS.SYS.
7. Write a bootstrap loader program using the text editor. This step is not necessary if the sample bootstrap loader included in the OEM kit is used. The sample bootstrap loader can also be used for technical reference. Name this file BOOT.ASM. We assume that you have a system ROM which will load the first sector of the system disk into memory when you turn on or reset the compter. Ideally, the bootstrap loader fits into the first sector of the boot disk. In addition to the loader, information relating to the BIOS Parameter Block (BPB) should be kept in the boot sector of the disk. The format of the boot INSTALLING MS-DOS Page 3-3
sector is described in Chapter 4.
The bootstrap loader loads IO.SYS and MSDOS.SYS into memory. MS-DOS can be located any place in memory above IO.SYS. (IO.SYS can alternately be used to load MSDOS.SYS.) Loading IO.SYS and MSDOS.SYS is simple because these two files must always be the first files on the disk. This means that a bootstrap loader could simply load a series of consecutive sectors into memory. Your bootstrap loader may also read in the first sector of the directory before it loads IO.SYS to verify that these files are the first files on the disk.
For more information, see: MS-DOS Programmer's Reference Manual ______ ____________ _________ ______ (Chapter 2) MS-DOS Adaptation Guide (Chapter 4) ______ __________ _____
8. Assemble, link, and convert to binary (using EXE2BIN) the BOOT.ASM file to produce BOOT.BIN.
9. Format a non-system disk using your MS-DOS development machine.
10. Using the MS-DOS Copy command, copy IO.SYS, MSDOS.SYS, and appropriate version of COMMAND.COM to the formatted disk.
11. Using DEBUG.COM on the development machine, load BOOT.BIN and write it to the first sector of the formatted disk. This can be done as follows:
DEBUG -N BOOT.BIN -L (loads BOOT.BIN) -W 100 0 0 1 (writes BOOT.BIN to drive 0 sector 0) -Q
Note: More operations may be required depending on how your boot program is organized.
For more information, see: Microsoft Macro Assembler Manual (Chapter 4 SYMDEB: _________ _____ _________ ______ A Symbolic Debug Utility
The formatted disk should now be bootable by your system. INSTALLING MS-DOS Page 3-4
12. Write the source code for the hardware-specific part of the FORMAT program. The MS-DOS 3.3 version of the FORMAT utility has been structured so that the hardware specific portions have been placed solely in IO.SYS. Minimal work should be required for the OEM use of the MS-DOS 3.2 FORMAT utility. Assemble and link this to the FORMAT.OBJ and FORMES.OBJ files supplied by Microsoft. The modules must be linked in the following order:
2.XX: FORMAT.OBJ+FORMES.OBJ+OEMFOR.OBJ
where OEMFOR.OBJ is your hardware-specific module. Use EXE2BIN to convert the OEMFOR.EXE file produced to FORMAT.COM.
3.XX: FORMAT.OBJ+FORPROC.OBJ+FORMES.OBJ+OEMFOR.OBJ+PRINTF.OBJ
where OEMFOR is your hardware-specific module. Although the PRINTF.OBJ module is the last module specified, it does not follow the OEM module in the memory image.
For more information, see:
MS-DOS Adaptation Guide (Chapter 7) ______ __________ _____ OEMFOR.ASM Disk file of sample OEM FORMAT module MS-DOS User's Reference Manual (Format Command, ______ ______ _________ ______ Chapter 3) MS-DOS Programmer's Reference Manual (Chapter 3) ______ ____________ _________ ______
13. Install the MS-DOS OEM serial number.
For information on how this is done, refer to the README.DOC on the distribution diskette.
14. Modify SORTMES.ASM as appropriate.
15. Build SORT executable with SORTBLD.BAT.
16. Modify PRINT source modules as appropriate
17. Build PRINT executable with PRINTBLD.BAT
INSTALLING MS-DOS
CONTENTS
CHAPTER 4 DISK STRUCTURE AND BOOTSTRAP LOADING 4.1 Reserved Area 4-1 4.2 File Allocation Table 4-2
4.3 MS-DOS File System Limits 4-4 4.3.1 Disk Format Identification 4-6 4.4 The role of the Boot Sector 4-7
CHAPTER 4
DISK STRUCTURE AND BOOTSTRAP LOADING
MS-DOS disks are divided into four logical data areas.
1. Reserved sectors (boot sector)
2. File Allocation Tables
3. Root directory
4. Data area which may include subdirectories as well as program and data files
When creating non-standard disks or non-removable media(such as hard disks), the logical disk which your device _______driver presents to MS-DOS must conform to the abovestandard. The physical layout may be completely different. ________For example, you may want to implement a partitioning schemeon the hard disk so that it can be shared by multipleoperating systems. In this case, either the device driveror firmware maps the physical structure into an MS-DOSlogical layout. The MS-DOS file system can even belogically implemented within another operating system's filestructure.
4.1 RESERVED AREA
The reserved area is the first part of the disk and istypically used for boot purposes. Some machines notspecifically designed for MS-DOS may use track 0 for specialpurposes (it may even have a different sector size than therest of the disk). In this case, the entire track should bemarked as reserved so that the device driver will mapMS-DOS's logical sector 0 to the beginning of track 1instead of track 0.
It may be difficult to fit the required boot informationinto a single sector. Note that disk formats using 128- or256-byte sectors and without any firmware support may DISK STRUCTURE AND BOOTSTRAP LOADING Page 4-2
require several sectors.
4.2 FILE ALLOCATION TABLE
The File Allocation Table (FAT) is the most important data structure on the disk. Two copies are usually kept at the OEM's option. (Two copies need not be kept for a virtual RAM disk because, in this case, the media cannot be damaged.) MS-DOS files are allocated in "allocation units" or "clusters".Each cluster is some number of sectors. The number of sectors per allocation unit must be a power of 2 which fits in a byte.Thus, the complete list of possible values is: 1, 2, 4, 8, 16, 32, 64, 128.
The FAT is a physical map of the allocation units in thedata area of the disk. There is one FAT entry for eachallocation unit on the disk plus two reserved entries at thebeginning of the FAT. The entries serve as a linked list ofpointers. For a complete discussion of FAT structure, referto Chapter 3 of the MS-DOS Programmer's Reference Manual. ______ ____________ _________ ______
FAT size can be determined by the following formula:
FAT = Q * ( T - R - D + 2) -------------------- Q * N + ( A * S )
FAT is the number of sectors needed for one FAT and will usually not be an integer. It must be rounded up to the next integer value. Q is the number 1.5 for 12-bit FAT entries and 2.0 for 16-bit FAT entries. T is the total number of sectors on the disk. R is the number of reserved sectors. D is the number of root directory sectors (there must be 32 bytes for each directory entry). A is the number of sectors per cluster or allocation unit. N is the number of file allocation tables on the disk. S is the number of bytes per sector.
MS-DOS 3.x can use 16-bit FAT pointers whenever the total DISK STRUCTURE AND BOOTSTRAP LOADING Page 4-3
number of clusters on the disk exceeds 4085 (=4096-10; twoare reserved at the beginning, and eight are reserved at theend). Although the FAT entries are 16 bits, the presentsoftware only works with 15 bits (up to 32766 clusters).
____________________________________________________________| || Important || || Be careful when reducing cluster size as it can cause || significant performance degradation. Reducing cluster || size results in increased fragmentation, a larger FAT || to buffer (increasing the number of disk accesses); and || increasing the FAT entries from 12 to 16-bit expands || the FAT size by 33%. || ||__________________________________________________________|
The FORMAT program will create a proper FAT. The FAT has anentry for each allocation unit in the data area of the disk.It also contains two extra entries at the beginning. Theserepresent reserved clusters. The first cluster of the dataregion of the disk is cluster 2.
The first (0th cluster) of these two reserved entries can beused to indicate the format of the disk. Only the low 8bits are used, and this byte is often referred to as theFATID byte. The high 4 bits (high byte if a 16-bit FAT) ofthis first cluster are all set (=1).
The FATID byte is restricted to be in the range 0F8H to0FFH, inclusive (8 possible values). The FATID byte is alsoan end-of-file (EOF) mark. If a FAT chain contains a zeroentry (which should never happen), it will point to this EOFmarker. The second (1st cluster) of these two reservedentries is always 0FFFH (0FFFFH for a 16-bit FAT), which isan end-of-file mark.
DISK STRUCTURE AND BOOTSTRAP LOADING Page 4-4
Figure 4.1 illustrates the first two clusters of a 12-bitFile Allocation Table.
FAT BYTE 00 01 02 03 XXH XXH XXH XXH----->Byte 3 || || || Middle 4 bits | || High and middle 4 bits of of cluster 0 | || cluster 1 (always F) | | High 4 bits of Low 4 bits of | cluster 0 (always F) cluster 0 | | | Low 4 bits of cluster |------------------| 1 (always F) | FATID BYTE
Figure 4.1. First Two Entries of the FAT (12-bit)
4.3 MS-DOS FILE SYSTEM LIMITS
The following figure shows the file storage limitationswithin MS-DOS.
| MS-DOS 2.x | Both | MS-DOS 3.x _______________|______________|_____________|_______________|FAT entry size |12 bits | |12 or 16 bits ||Sector size | |64b-32Kb | ||No. of Sectors | |Max of 64K | ||Cluster size | |1-128 sectors| ||Max. disk size |4085 clusters |64K sectors |32766 clusters||Max. file size | |Disk size | |________________|______________|_____________|______________|
All ranges in the table are inclusive. As well as the abovelimitations, there are also various limits as noted below:
1. FAT entry size. This is the only file storage limit difference between MS-DOS 2.XX and 3.XX; it significantly increases the maximum number of clusters and hence the maximum disk size allowed. MS-DOS 3.x determines whether a 12- or 16-bit FAT is in use by calculating the number of disk clusters from the BPB. If the number of clusters is less than or equal to 4085, a 12-bit FAT is in use; otherwise, a 16-bit FAT is assumed. A 16-bit FAT cannot be used if the total number of clusters is less than DISK STRUCTURE AND BOOTSTRAP LOADING Page 4-5
or equal to 4085.
Some existing MS-DOS applications (such as copy protection schemes and disk maintenance utilities) bypass MS-DOS and manipulate the FAT directly. These existing applications will cause problems with 16-bit FATs until the applications are updated to recognize the 16-bit FATs.
2. Sector Size. Must be a multiple of 64 bytes.
3. No. of Sectors. The number of sectors is limited to 64K because 16-bit sector numbers are passed to the device drivers.
4. Cluster Size. The cluster size (bytes/cluster = sectors/cluster * bytes/sector) must be less than 64K because MS-DOS uses 16-bit arithmetic.
Sectors/Cluster must be a power of 2 in the range 1-128.
Excessively small cluster sizes can seriously degrade performance. Refer to the MS-DOS ______ Programmer's Reference Manual for sample disk ____________ _________ ______ formats.
5. Max. Disk Size. MS-DOS 2.XX: Lesser of 4085 clusters or 64K sectors (For example, 64K*512 byte sectors = 32Mb disk). MS-DOS 3.XX: Lesser of 32766 clusters or 64K sectors.
The total number of sectors is limited to 64K due to the use of 16-bit arithmetic.
The maximum number of possible clusters is calculated by the following:
FAT entry size (2 -10 Reserved)
Reserved: 8 FAT ID/EOF (F8-FF) 2 RESERVED (0,1) ------------------------------------------------------------ | | | Note | | | | However, some MS-DOS utilities (such as Chkdsk and | | Recover) restrict the total FAT size to 32K entries, | DISK STRUCTURE AND BOOTSTRAP LOADING Page 4-6
| hence the MS-DOS 3.x limit of 32,766 clusters and not | | 65,525 (216-11). | | | |__________________________________________________________|
There are 10 MS-DOS reserved FAT entries; two at the front of the FAT, and eight at the end: DISK STRUCTURE AND BOOTSTRAP LOADING Page 4-7
4086 = 4K -10 32766 = 32K -2
The 8 reserved clusters are in the range 65528-65536.
6. Max. File Size. Files cannot be split across disks; therefore, the maximum file size is normally the maximum disk size. The file size is also restricted by a 32-bit file pointer. This means that the maximum possible file size is 4 gigabytes:
32 4 million K, 2 -1
4.3.1 Disk Format Identification
Beginning with MS-DOS 2.0, Microsoft is promoting the use ofa media descriptor table in the boot sector. This tablecontains both a physical description (number of sectors,sides, tracks, etc.) and a logical description (number ofFATs, directory entries, etc.) of the disk layout. Themedia description table allows MS-DOS to accommodate futurefloppy disk formats, or formats defined by othermanufacturers but not generated by your FORMAT utility.Your device driver should assume that the media descriptiontable exists if the first byte of the boot sector is thefirst byte of a 3-byte (near) jump or a 2-byte jump. DISK STRUCTURE AND BOOTSTRAP LOADING Page 4-8
4.4 THE ROLE OF THE BOOT SECTOR
Typically, the system ROM will load the reserved (boot)sector or sectors into memory at power-up or restart. Werecommend that the boot sector do the following:
1. It should read the first sector of the directory and verify that the first two files on the disk are IO.SYS and MSDOS.SYS, in that order.
You may choose to have your FORMAT utility generate different boot sectors for each disk format. Or, you may create a universal boot sector to read the media description table and determine where to find the first directory sector both logically and physically.
2. If the boot code does not find the MS-DOS files in the directory, then the boot sector should prompt the operator that an attempt has been made to boot from a non-bootable disk. You determine how the user should continue ("Strike any key" or "Turn power off").
3. The boot sector must read in the IO.SYS and MSDOS.SYS files. Alternatively, the boot sector may read in only IO.SYS, and IO.SYS may then read in MSDOS.SYS. Only IO.SYS needs to be contiguous on the disk.
The boot sector must know or calculate where those files physically begin on the disk (right after the last directory sector) and how long they are (contained in directory entries). You must code (or calculate) the location at which they should be loaded into memory in the boot sector.
4. The boot sector must transfer control to your entry point in IO.SYS.
The boot sector does not load COMMAND.COM, as it will be loaded by SYSINIT.
The SYS command allows users to transfer the operatingsystem onto a formatted disk that contains no files orcontains an old version of the operating system of equal orgreater size. For the MS-DOS 2.XX version on the IBM PC, theSYS command was modified to transfer MS-DOS 2.XX system filesonto old 1.XX disks. The new MSDOS.SYS can be placed on thedisk in a non-contiguous format. (IO.SYS is stillcontiguous because the new IO.SYS is smaller than the DISK STRUCTURE AND BOOTSTRAP LOADING Page 4-9
combined sizes of the old IO.SYS and MSDOS.SYS.) The bootsector is only responsible for loading IO.SYS, although itmust check that MSDOS.SYS is the second file on the disk.Therefore, IO.SYS may load a non-contiguous MSDOS.SYS.
The logic to facilitate checking through the FAT entriesmust be added to IO.SYS because the logic normally residesin the not-yet-loaded MSDOS.SYS. The logic resides in theinstallation part of IO.SYS so that it will be overwrittenwhen MSDOS.SYS is loaded. This technique should only beused to use the SYS command to transfer a new, bigger MS-DOSonto an old disk. It is not useful if you do not have olddisks to support in the field. Note that the various FATentries for a non-contiguous MSDOS.SYS may reside indifferent FAT sectors making it necessary to read more thanjust the first FAT sector into memory.
There is an example of a boot sector on the OEM Sample MS-DOS Implementation Diskette. DISK STRUCTURE AND BOOTSTRAP LOADING
CONTENTS
CHAPTER 5 RESIDENT DEVICE DRIVERS
5.1 Introduction 5-1 5.2 Bit 4 5-3 5.3 Installation of Device Drivers 5-5 5.4 The CLOCK Device 5-5
5.5 INIT (Command Code 0) 5-6 5.6 Media Check 5-7
5.7 DMA Boundary Violation 5-9
CHAPTER 5
RESIDENT DEVICE DRIVERS
------------------------------------------------------------| || Note || || Chapter 2, "Device Drivers," in the MS-DOS Programmer's || Reference Manual contains a description of MS-DOS || device drivers. Additional information applicable to || OEM is included here. || |------------------------------------------------------------
5.1 INTRODUCTION
The IO.SYS file is composed of the "resident" devicedrivers. This forms the MS-DOS Basic Input Output System(BIOS), and these drivers are called upon by MS-DOS tohandle I/O requests initiated by application programs.
One of the most powerful features of MS-DOS is the abilityto add new devices such as printers, plotters, or mouseinput devices without rewriting the BIOS. The MS-DOS BIOSis "configurable;" that is, new drivers can be added andexisting drivers can be pre-empted. Non-resident devicedrivers may be easily added by a user at boot time via the"DEVICE =" entry in the CONFIG.SYS file. In this section,these non-resident drivers are called "installable" devicedrivers to distinguish them from drivers in the IO.SYS file,which are considered the resident drivers.
At boot time, a minimum of five resident device drivers (four character devices and one block device) must be present. These drivers are in a linked list: the headerof each one contains a DWORD pointer to the next. The lastdriver in the chain has an end-of-list marker of -1, -1 (allbits on).
Each driver in the chain has two entry points: the strategyentry point and the interrupt entry point. MS-DOS 2.XX/3.XXdoes not take advantage of the two entry points: it calls RESIDENT DEVICE DRIVERS Page 5-2
the strategy routine, then immediately calls the interruptroutine.
The dual entry points facilitate future multitaskingversions of MS-DOS. In multitasking environments, I/O mustbe asynchronous; to accomplish this, the strategy routinewill be called to (internally) queue a request and returnquickly. It is then the responsibility of the interruptroutine to perform the I/O at interrupt time by gettingrequests from the internal queue and processing them. Whena request is completed, it is flagged as "done" by theinterrupt routine. MS-DOS periodically scans the list ofrequests looking for those that are flagged as done, and"wakes up" the process waiting for the completion of therequest.
When requests are queued in this manner, it is no longersufficient to pass I/O information in registers, since manyrequests may be pending at any time. Therefore, the MS-DOS2.x/3.x device interface uses "packets" to pass requestinformation. These request packets are of variable size andformat, and are composed of two parts:
1. The static request header, which has the same format for all requests.
2. A section that has information specific to the type of request.
A driver is called with a pointer to a packet. Inmultitasking versions, this packet will be linked into aglobal chain of all pending I/O requests maintained byMS-DOS.
The 2.XX and 3.XX versions of MS-DOS do not implement aglobal or local queue. Only one request is pending at anyone time. The strategy routine must store the address ofthe packet at a fixed location, and the interrupt routine(which is called immediately after the strategy routine)should process the packet by completing the request andreturning. It is assumed that the request is completed whenthe interrupt routine returns.
To make a device driver that SYSINIT can install, a .BIN(core image) or .EXE format file must be created with thedevice driver header at the beginning of the file. The linkfield should be initialized to -1 (SYSINIT fills it in).Device drivers that are part of the BIOS should have theirheaders point to the next device in the list and the lastheader should be initialized to -1,-1. The BIOS must be aBIN (core image) format file produced by using the utilityEXE2BIN.
.EXE format installable device drivers may be used in RESIDENT DEVICE DRIVERS Page 5-3
non-IBM versions of MS-DOS before 3.0. The reason for thisrestriction is that on the IBM PC, the .EXE loader is located in COMMAND.COM, which is not present at the time that installable devices are being loaded.
The attribute field and entry points must be set correctly.If the device is a character device, the name field must befilled in. (This name can be any 8-character legalfilename). If it is a block device, SYSINIT will fill in thecorrect unit count. SYSINIT always installs characterdevices at the start of the device list, so if you want toinstall a new CON device, simply name it CON. The new onewill be placed ahead of the old one in the list and willpre-empt the old one because the search for devices stops onthe first match.
Be sure to set the standard input (sti) and standard output(sto) bits on a new CON device.
------------------------------------------------------------| || Note || || Since SYSINIT may install the driver anywhere, be || careful when coding FAR memory references. You || should NOT expect that your installable driver will be || located in the same place every time. This does not || apply for the resident device drivers. || ||__________________________________________________________|
5.2 BIT 4
In the MS-DOS Programmer's Reference Manual, bit 4 of the ______ ____________ _________ ______device driver header format is defined as reserved. Itactually has special meaning.
Bit 4, the special bit, applies to CON drivers. The newinterface supports many new features, but it is slower thanMS-DOS 1.x if old style "single-byte" system calls are made.To make most efficient use of the interface, allapplications should block their I/O as much as possible.For example, you should make one XENIX-style system call tooutput x number of bytes rather than x system calls tooutput one byte each.
RESIDENT DEVICE DRIVERS Page 5-4
Putting a device channel in raw mode provides an even fasterway to output characters. (See the Glossary for anexplanation of "raw" mode.) Bit 4, has been implemented toalleviate the CON output speed problem for older programsthat use system calls 01H to 0BH to output large amounts ofdata. If this bit is 1, the device is CON and an Interrupt29H has been implemented, where the 29H handler is definedas follows:
CONSOLE OUTPUT via INT 29H handler
Input: Character in AL
Function: Output the character in AL to the screen at the current cursor location.
Output: None
Registers: All registers except BX must be preserved. No registers except AL have a known or consistent value.
If a character device implements the special bit, the drivermust install an address at the correct location in theinterrupt table for Interrupt 29H. Only one device drivercan have the special bit set in the system. There is nocheck to ensure this state.
____________________________________________________________| || Warning || || This feature may not be supported in future versions of || MS-DOS. Any application (not device driver) that uses || Interrupt 29H directly will not work on future versions.|| In addition, the console device driver must be tested || with bit 4 not set to ensure that it will work with such || future versions of MS-DOS. || |____________________________________________________________
The headers of resident drivers should point to the nextdevice in the list and the last header should be initializedto -1,-1. IO.SYS must be a .COM format file.
RESIDENT DEVICE DRIVERS Page 5-5
5.3 INSTALLATION OF DEVICE DRIVERS
MS-DOS 2.XX/3.XX allows new device drivers to be installeddynamically at boot time. This is accomplished by theSYSINIT module(s) supplied by Microsoft, which read(s) andprocesses the CONFIG.SYS file. The resident driver sourcefile (IO.ASM) is assembled and linked to the appropriate SYSINITmodule(s) and SYSIMES.OBJ. The resultant .EXE file mustbe converted via EXE2BIN to create the file IO.SYS. Thisshould be the first file that appears on the system disk.
When block drivers are installed, the logical drive lettersare assigned in list order; thus, the driver that will havelogical A must be the first unit of the first block devicein the list. The order of character devices is alsoimportant. There must be at least four character devicesdefined at boot time. The first four character devices mustbe as follows:
1. Standard input, standard output, and standard error output (CON)
2. Standard auxiliary input and output (AUX)
3. Standard list output (PRN)
4. Date/time (CLOCK)
The linked list of device drivers must look like this:
->CON->AUX->PRN->CLOCK->any other block or character devices
5.4 THE CLOCK DEVICE
The CLOCK device is used by MS-DOS 2.XX/3.XX for marking filecontrol blocks and directory entries with date and time aswell as providing date/time services to applicationprograms. It is unique in that MS-DOS will read or write a6-byte sequence which encodes the date and time. A write tothis device will set the date and time and a read will getthe date and time.
Figure 5.1 illustrates the binary date and time format usedby the CLOCK device. RESIDENT DEVICE DRIVERS Page 5-6
byte 0 byte 1 byte 2 byte 3 byte 4 byte 5+--------+--------+---------+--------+--------+---------+| | | | | | ||days since 1-1-80| minutes | hours | sec/100| seconds ||low byte|hi byte | | | | |+--------+--------+---------+--------+--------+---------+
Figure 5.1. CLOCK Device Format
5.5 INIT (COMMAND CODE 0)
One of the functions defined for each device is INIT. Thisroutine is called only when the device is installed. It isused for initializing character and block devices.
Figure 5.2 illustrates the format of INIT.
+------------------------------------+ | 13-BYTE Request Header | +------------------------------------+ | BYTE # of units | +------------------------------------+ | DWORD Break Address | +------------------------------------+ | DWORD Pointer to BPB array | | (not set by character devices) | +------------------------------------+
Figure 5.2. INIT Format
For resident character devices:___ ________ _________ _______
No parameters are passed, and none are returned.
For resident block drivers:___ ________ _____ _______
Unlike character device drivers, block device drivers mustreturn a number of parameters. The following data arereturned:
1. The number of units defined by this block device driver. This is used to determine logical device names. If the current maximum logical device letter is F at the time of installation, and the INIT routine returns 4 as the number of units, then those units will have the logical names G, H, I and J. This mapping is determined by the position of RESIDENT DEVICE DRIVERS Page 5-7
the driver in the device list and the number of units defined by the device (stored in the first byte of the device name field). You must return this number at offset 13D in the INIT call, even though the number of units is stored in the device header.
2. A DWORD pointer to an array of WORD offsets to BPBs (BIOS Parameter Blocks). There must be one entry for each unit defined by the device driver. If the device driver defines two units, then the DWORD pointer points to the first of two one-word offsets which, in turn, point to BPBs. If both BPBs are the same, this will allow you to save space by entering two offsets to the same location.
The BPB is used by MS-DOS to create an internal DOSstructure. The BPBs that are returned by the residentdevice drivers are scanned to determine the largest sectorsize. This number is used to set the cache buffer size.
Installable block devices cannot have larger sector sizesthan those defined by the resident drivers. For thisreason, you may want to use dummy BPBs to reserve space.Use an invalid media byte so that when you later report thecorrect BPB for the unit. MS-DOS will build the correctinternal DOS structure for the particular drive unit.
5.6 MEDIA CHECK
The MEDIA CHECK function is called when there is a pendingdrive access call other than a file read or write (i.e accessto the "FILENAME space" - Open, Close, Get_disk_size, INT 25H,INT 26H, etc.). Its purpose is to determine whether the mediain the drive has been changed. Note that the previous media IDbyte is passed to the device driver. Although the old media IDbyte is the same as the new one, the disk may have been changedand a new disk may be in the drive; therefore, the FAT, anddirectory and data sectors for the unit are invalid.
MS-DOS 3.XX imposes stricter conditions than MS-DOS 2.XX onwhen media changes are allowed. This can lead to MEDIACHECK routines that seemed to work correctly under MS-DOS2.XX causing problems under MS-DOS 3.XX.
MS-DOS performance is greatly improved if MEDIA CHECK uses adoorlock or some other detection method so that it canguarantee that no disk change has occurred; then MS-DOSdoes not have to reread the FAT before each directoryaccess.
MEDIA CHECK can directly use the door-lock mechanism toreturn "Disk not changed." However, the door-lock mechanism
RESIDENT DEVICE DRIVERS Page 5-8
indicating that the door has been opened does notnecessarily mean that the disk has been changed, since theuser could have reinserted the same disk. MEDIA CHECKroutines that return "Disk has been changed" just becausethe door has been opened will cause problems under MS-DOS3.x, but not under MS-DOS 2.XX.
The recommended behavior for MEDIA CHECK is to return asfollows:
Disk has not been changed - whenever the door lock indicates that the door has not been opened
Don't know - under all other circumstances
It is possible for MEDIA CHECK to try to determine whether adisk has really been changed by checking the Volume ID;however, many disks have no Volume ID. Therefore, it issafer and quicker for MEDIA CHECK to simply return "Don'tknow." The action that MS-DOS takes depends on the state ofits internal file storage buffers. In general, if "Don'tknow" is returned when MS-DOS has data in its internalbuffers (data that needs to be written out), MS-DOS willassume no disk change has occurred. Otherwise, with emptybuffers or all buffers "clean", MS-DOS assumes the disk hasbeen changed.
The possible problems caused by an incorrect MEDIA CHECKroutine can be checked as follows:
1. Load MS-DOS 3.XX 2. Ensure the disk is write-protected 3. COPY FILE1 FILE2 4. Write Protect Error from MS-DOS 5. Remove the write protection from the disk 6. Reinsert the disk in the drive 7. Press "R" to cause MS-DOS to retry 8. Copy success message
If an incorrect MEDIA CHECK routine is in use, the Dircommand will show FILE2 with a size of zero bytes, andChkdsk will report "lost clusters." Note that the copyprocess always returns the success message even with anincorrect MEDIA CHECK routine.
The above test should also be repeated with a "Drive NotReady" error condition instead of the Write Protect error.The same symptoms will be displayed.
For more information on MEDIA CHECK, refer to the MS-DOS ______Programmer's Reference Manual.____________ _________ _______ RESIDENT DEVICE DRIVERS Page 5-9
5.7 DMA BOUNDARY VIOLATIONS
Some OEMs check for any DMA boundary violations on diskoperations. If a DMA boundary violation error is detectedthen action is taken to prevent this error from beingreported to the DOS. The sample IO.SYS handles the problem inthe following way. The operation is tried and if a DMA boundaryviolation is reported, then a flag (in this case bl) is setto indicate that we need to do a memory swap to avoid theboundary problem. The sector of data that causes the DMAboundary violation is transfered into an internal bufferthat belongs to IO.SYS and then is copied into the bufferspecified in the original request.
In other words, the request is broken into several piecesconsisting of a request for the data up to the DMA boundaryviolation, then the one sector of data that causes the DMA boundary violation (in the sample IO.SYS SwapMemory routine is responsiblefor doing this), and then the rest of the request as specifiedby the original disk operation.
Applications do not depend on this feature in any direct way.However, if you do not implement the DMA boundary checking thenit would be possible for an application to get an INT24 error becauseof the DMA boundary problem and thus behave differentlydepending on how the BIOS was implemented.
CHAPTER 6 SYSINIT AND MS-DOS INITIALIZATION
6.1 Introduction 6-1 6.2 The Role of SYSINIT 6-3 6.3 COMMAND.COM 6-5
CHAPTER 6
SYSINIT AND MS-DOS INITIALIZATION
6.1 INTRODUCTION
In addition to implementing the resident drivers andperforming any hardware initialization, the IO.ASM code mustinitialize certain external variables. These variables aredeclared public in the SYSINIT module(s) to which the IO.OBJmodule is linked. The public variables and their functionsare described below.
CURRENT_DOS_LOCATION WORD
This is the paragraph location where the bootstrap loader(or, optionally, IO.SYS) has loaded MSDOS.SYS into memory.Typically, MSDOS.SYS is located immediately after IO.SYS.
FINAL_DOS_LOCATION WORD
Since SYSINIT immediately relocates itself to high memory,there will be a hole right after the resident drivers. Bytelling SYSINIT the paragraph where you want it to relocateMSDOS.SYS, you can fill up this hole plus overlay any codethat IO.SYS used for hardware initialization at boot time.SYSINIT will move MSDOS.SYS down to this location,conserving space. This location also defines where memorystarts for MS-DOS.
DEVICE_LIST DWORD
IO.SYS must tell SYSINIT where the linked list of devicedrivers begins. This is the location of the CON devicedriver header; the information is passed to MS-DOS so thatthe drivers can be accessed. SYSINIT AND MS-DOS INITIALIZATION Page 6-2
MEMORY_SIZE WORD
This word is the paragraph number of the highest location inRAM. If you do not initialize MEMORY_SIZE, SYSINIT will doa memory scan to determine the amount of memory. It doesthis by reading every 16 bytes starting at 32K, writing anarbitrary pattern, reading it back for a match, andreturning the original value. It stops when it gets amismatch. If your system has parity memory, you mustdeclare this value, since writing to nonexistent memory willcause a parity error.
MS-DOS should be implemented in systems with contiguousmemory.
DEFAULT_DRIVE BYTE
If you can boot MS-DOS from several drives, you must tellSYSINIT which drive you booted from so it can findCONFIG.SYS and COMMAND.COM. This variable should be set asfollows: drive A = 1, drive B = 2, etc. If DEFAULT_DRIVEis not set, the default drive (drive A) is assumed.
BUFFERS BYTE
This is the default number of sector buffers for the system.The BUFFERS value may be overridden by the user in theCONFIG.SYS file. On versions of MS-DOS up to 3.1, the defaultnumber of buffers is 2. On versions of MS-DOS after 3.1, 3 buffers will be allocated if there is a floppy drive in the hardware configuration with a capacity greater than 360KB.Beginning with 3.3, if memory size is greater than 128K, then5 buffers will be allocated, and if memory is greater than256K 10 will be allocated; if memory is greater than 512K, 15buffers will be allocated.The value specified for the number of buffers must be greater than or equal to 1.
FILES BYTE
This is the default number of open files that system calls2FH-62H can access. This value may be overridden by theuser in the CONFIG.SYS file. Its default setting in SYSINITis 8. Values of less than 5 are ignored.
The entry point in SYSINIT should be defined as a FAR labelin IO.SYS as follows:
EXTRN SYSINIT:FAR
After IO.SYS code has performed any hardware initializationand has set the above external variables, it should do a FARjump to this label.
SYSINIT AND MS-DOS INITIALIZATION Page 6-3
You must provide a FAR procedure in the IO.ASM code which isnot subject to being overlayed when SYSINIT relocatesMS-DOS. This procedure is called RE_INIT. It should bedeclared as follows:
RE_INIT: PROC FAR ........ ........ RET RE_INIT ENDP
The RE_INIT procedure is called by SYSINIT after MS-DOS isinstalled. On entry, DS:0 points to a 100H-byte programsegment prefix which represents the Program Segment Prefixof SYSINIT and IO.SYS taken together. This is not a normalprogram because no memory is allocated to it; therefore, ifyou allocate and load or Exec, you may overlay this block.SYSINIT is located in the top 10K of memory. Do not write __ ___ _____there. The space above the 100H byte header at DS:100 is_____available for temporary use during RE_INIT.
The RE_INIT routine can be used to perform functions such asto print headers and read files, and it is handy for IO.SYSdebugging. If you don't need to use this procedure, simplydo a return (RET). Note that starting with MS-DOS 3.XX,RE_INIT may not use FCB system calls. ------------------------------------------------------------| || Warning || || RE_INIT must not change any registers or flags. || ||__________________________________________________________|
Beginning with MS-DOS 3.2, another FAR procedure must be provided inIO.ASM. The name of this procedure is STACKINIT.The purpose of this procedure is to initialize a hardware stack switching algorithm. If some of the hardware interrupt handlers in theROM BIOS of the OEM hardware system are stack intensive, then this initialization routine would be used to direct the processingof the hardware interrupt handlers to another portion of code in IO.ASM. This code will save the current stack setup and switch stacks to an internal space on occurrence of a hardware interrupt.When the stack has been switched the original interrupt handler is called. The rest of the interrupt handling will use the internal stack and not the stack that was in use when the interrupt occurred.When the interrupt handler returns the stack is set to its originalstate. The advantage of this feature is that there is greater system reliability since a dedicated stack space is being used for interrupt handling. The OEM should determine which hardware interrupt handlers are stack intensive and redirect only those interrupts to the stack switching code in IO.ASM.This procedure is similar to the FAR procedure RE_INIT in that the code is not subject to being overlayed when SYSINIT relocates MS-DOS. The procedure STACKINIT should be declared in the same fashion as RE_INIT.After MS-DOS is installed, SYSINIT calls the procedure STACKINIT. If thisprocedure is not going to be used, then simply do a return or the OEMcan assemble SYSINIT with the conditional STACKSW set to FALSE. On entryto this routine, there are three data variables that are available.These pieces of data reside in the SYSINIT segment. The following declarations should be made in IO.ASM to access these variables.
SYSINITSEG SEGMENT PUBLIC 'SYSTEM_INIT' EXTRN STACK_ADDR:DWORD EXTRN STACK_SIZE:WORD EXTRN STACK_COUNT:WORD SYSINITSEG ENDS
These variables are set by SYSINIT and can be changed by using theSTACKS option in CONFIG.SYS. The full syntax of the STACKS option is:
STACKS=STACK_COUNT,STACK_SIZE
where STACK_COUNT is the number of stacks (range 8 to 64, default 9) STACK_SIZE is the stack size (range 32 to 512 bytes, default 128)
The variable STACK_ADDR is the FAR address of the space that SYSINIThas allocated for the internal stacks.
Beginning with MS DOS 3.3, there is a special case for STACKS=0,0.This will result in no dynamic stacks being provided. DOS will notintercept any interrupts and will only use it own standard stack.
____________________________________________________________| || Warning || || STACKINIT must not change any registers or flags. || |------------------------------------------------------------
6.2 THE ROLE OF SYSINIT
The following steps illustrate the role of SYSINIT in MS-DOSinitialization:
1. When SYSINIT gains control from the IO.SYS initialization code, it determines the size of memory (performing a scan if requested, based on value of MEMORY-SIZE) and, based on the highest paragraph and the size of SYSINIT, it relocates itself to high memory. SYSINIT AND MS-DOS INITIALIZATION Page 6-4
2. Running in high memory, SYSINIT moves MSDOS.SYS from the CURRENT_DOS_LOCATION to the FINAL_DOS_LOCATION as specified by IO.SYS (see the memory maps in Section 6.3, "COMMAND.COM").
3. SYSINIT does a FAR call to MS-DOS. MS-DOS has initialization code which steps through the linked list of device drivers and performs the INIT call to each. The copyright message is then printed out on the screen.
4. After initializing the resident devices, building drive parameter blocks for the resident block devices, and installing a sector buffer, MS-DOS does a FAR return to SYSINIT.
During MS-DOS initialization, MS-DOS examines the BIOS Parameter Blocks (BPBs) returned by the INIT call to the block devices. It uses the largest sector size it finds as the default buffer size for all buffers. For this reason, the initial BPBs may be used to reserve space for an installable device with a larger sector size rather than reflecting the format of the installed disk. In this case, these dummy BPBs must have media bytes that do not have the same value as those used in real BPBs.
5. SYSINIT calls RE_INIT in IO.ASM to allow the OEM to print headers or handle any other initialization. ------------------------------------------------------------| || Warning || || Do not attempt to modify memory. || ||__________________________________________________________|
6. After IO.SYS returns control to SYSINIT, SYSINIT attempts to open the CONFIG.SYS file. If found, this file is loaded in memory and all characters are turned to uppercase. It is then parsed looking for keywords such as DEVICE, BUFFERS, and SHELL. Any new devices are loaded, added to the linked list, and installed via the INIT call. Character devices are added to the front of the list, and new block devices are added to the end. Thus, a new CON device can supplant an existing resident CON device. This provides the facility to reconfigure IO.SYS except for the Resident Disk Block device driver.
SYSINIT AND MS-DOS INITIALIZATION Page 6-5
7. SYSINIT allocates all of the memory it needs to protect the buffers, installed device driver code, and IO.SYS. It sets the "owner" of the memory to a special value to ensure that this block of memory is never deallocated.
8. SYSINIT closes all file handles, and then reopens CON, AUX, and PRN. This enables a new CON, AUX or PRN device to replace the resident devices.
9. SYSINIT allocates memory for the buffers.
10. SYSINIT allocates memory for hardware stacks and calls STACKINIT to initialize the hardware stack switching algorithm (only in versions of DOS 3.2 and later).
11. SYSINIT executes COMMAND.COM.
12. COMMAND.COM allocates memory for its transient portion and moves it.
MS-DOS is now up and running.
6.3 COMMAND.COM
During its initialization, COMMAND.COM allocates memory forits transient part and reloads it. The transient part ofCOMMAND, which contains the internal commands (Copy, Dir,Date, Time, etc.), resides in unprotected memory when auser's program is loaded into the Transient Program Area(TPA). It will be overlaid by programs needing the space.When a user program terminates to the COMMAND resident, thetransient is checked to see if reloading is necessary. SYSINIT AND MS-DOS INITIALIZATION Page 6-6
Each of the following memory maps represents a step in theMS-DOS initialization process.
+-----------------------------+| | High memory| || || |+-----------------------------+ Loaded at arbitrary| Bootstrap loader | location by system ROM+-----------------------------+ XX:00| || || || || || || || || || || |+-----------------------------+ Segment 40H| Interrupt Vector Table |+-----------------------------+ -0:00
Memory organization in an MS-DOSsystem after the system ROMhas loaded the boot sector. SYSINIT AND MS-DOS INITIALIZATION Page 6-7
+-----------------------------+| | High memory| || |+- - - - - - - - - - - - - - -+| Spent bootstrap loader |+- - - - - - - - - - - - - - -+| || || |+-----------------------------+| | MS-DOS disk operating| MSDOS.SYS | system in temporary| | location| |+-----------------------------+ Microsoft-supplied| SYSINIT | system initialization+- - - - - - - - - - - - - - -+ module (part of IO.SYS)| || IO.SYS | IO.SYS (may begin at+-----------------------------+ any location)| Interrupt Vector Table |+-----------------------------+
Memory after bootstrap loaderloads IO.SYS and MSDOS.SYS. SYSINIT AND MS-DOS INITIALIZATION Page 6-8
+-----------------------------+| SYSINIT | High memory| relocates itself to highmem |+-----------------------------+| || || || || |+-----------------------------+| || MS-DOS structures, buffers, | SYSINIT loads installable| hardware stack space, | drivers and buffers here| and installable drivers | +-----------------------------+| || MSDOS.SYS relocated by | SYSINIT moves MS-DOS| SYSINIT to fill hole in | down to OEM-designated| memory. | FINAL_DOS_LOCATION| |+-----------------------------+| IO.SYS |+-----------------------------+| Interrupt Vector Table |+-----------------------------+
Memory during system initializationperformed by SYSINIT module. SYSINIT AND MS-DOS INITIALIZATION Page 6-9
+-----------------------------+| COMMAND.COM | High memory| (transient) |+-----------------------------+| | Start of TPA will vary| Transient Program Area | with # of drivers,| (TPA) | buffers, etc.+-----------------------------+| COMMAND.COM (resident) | COMMAND.COM loads its+-----------------------------+ transient part into top| | of largest available| MS-DOS structures, buffers | memory| hardware stack space, | | and installable drivers | +-----------------------------+| || || MSDOS.SYS || || |+-----------------------------+| || IO.SYS || resident device drivers |+-----------------------------+| Interrupt Vector Table |+-----------------------------+
Memory after SYSINIT installs command interpreter.
This represents the normal configurationduring MS-DOS operation. SYSINIT AND MS-DOS INITIALIZATION
CONTENTS
CHAPTER 7A WRITING THE FORMAT MODULE FOR MS-DOS 3.20/3.21
7.1 Introduction 7-1 7.2 Format Modules and the ES Register 7-9 7.3 Changing the Logical Format of Disks 7-9
CHAPTER 7B
WRITING THE FORMAT MODULE MS-DOS 3.20/3.21
HIGHLIGHTS OF CHANGES IN 3.2X OVER PREVIOUS 2.XX FORMAT VERSION:
o FORMAT is now designed to be an .EXE file.
o The FBIGFAT variable has been introduced for 16-bit FAT support.
o ALLOCATEFAT routine allows space for the FAT to be dynamically allocated.
o Hardware specific functionality assumed to be provided by device drivers.
HIGHLIGHTS OF CHANGES IN 3.20 OVER PREVIOUS FORMAT VERSIONS:
The intention of the MS-DOS 3.2 FORMAT utility is to reduce the amount of OEM work and also move any machine dependencies to the device drivers (software BIOS). The following are the new features of the MS-DOS 3.2 FORMAT utility:
o FORMAT is now designed to be hardware independent. The FORMAT utility no longer makes calls directly to the ROM BIOS to perform the format operation. The direct calls to the ROM BIOS have been replaced with MS-DOS system calls (Generic IOCTL's) that perform the necessary format functions. The responsibility for interacting with the ROM BIOS to deal with the formating functions is now placed in the OEM's device drivers.
o The current head and cylinder being formated is displayed in the layout: Head: %d Cylinder: %d
o Two new switches have been added to FORMAT. The new switches are: /N:xx - Specifies the number of sectors/cylinder on the media.
/T:yy - Specifies the number of tracks on the media.
These two options will only be useful if the ROM BIOS has support to deal with changing of the disk drive parameters.
o FORMAT will no longer format the default drive if no drive was specified on the command line.
7.1 INTRODUCTION
The MS-DOS Format command formats a new disk, clears the FATand directory, and optionally copies system files andCOMMAND.COM to the new disk. The 3.2X Format utility nolonger requires the hardware specific code supplied by theOEM in previous versions. Instead, Format relies on thedrive device driver to provide the functionality requiredto format a track on that drive. The Format utility uses aGENERIC_IOCTL function request to access the drive devicedriver to format a track on the drive. If the device driverdoes not support a format track function the Format utilitywill not be able to format the drive.
FORMAT is shipped in two hardware-independent objectmodules. These must be linked to a system configurationdependant module written by the OEM. The following sectiondescribes the routines required in this module. A sampleOEM format module is included on the MS-DOS release disksto assist in writing these routines.
The syntax for the Format command is:
Format drive: [/switch1][/switch2]...[/switch16]
"drive:" is a legal drive specification. As many as 16 legal switches can be included in the command line.
7.2 CODE AND DATA FROM THE OEM
As the OEM may need to tailor the FORMAT module for a particularsystem configuration the OEM must supply the routines and dataitems which are specific to that configuration. The OEM shouldproduce a module, eg. OEMFOR.ASM, which contains the following(NEAR) data items;
SWITCHLIST DOSFILE BIOSFILE
and the following (NEAR) routines;
OEMDONE WRITEBOOTSECTOR CHECKSWITCHES LASTCHANCETOSAVEIT
The detailed description of the data items required to be declaredpublic in the OEM's module is as follows;
SWITCHLIST
A string of bytes. The first byte is count n, followed by n characters that are the switches to be accepted by the command line scanner. Alphabetic characters must be in uppercase (the numeric characters 0-9 are allowed). The last six switches, normally "/N","/T","/C","/O", "/V" and "/S", have predefined meanings.
The "/S" switch is the switch that causes the system files IO.SYS, MSDOS.SYS, and COMMAND.COM to be transferred to the disk after it is formatted, thus making a system disk. The switch can be some letter other than "S", but the last switch in the list is assumed to have the meaning "transfer system," regardless of what the particular letter is.
The second to the last switch, "/V", causes FORMAT to prompt the user for a volume label after the disk is formatted. As with "/S", the particular letter is not important but rather the position in the list.
The third to the last switch, "/O", causes FORMAT to produce an IBM Personal Computer DOS version 1.x-compatible disk. Normally FORMAT causes a 0 byte to be placed in the first byte of each directory entry instead of the 0E5H free entry designator. This markedly increases the performance of a directory search due to an optimization in the DOS. Disks made with this switch cause trouble on IBM PC DOS 1.x versions which did not have this optimization. The 0 byte fools IBM 1.x versions into thinking these entries are allocated instead of free. Note that IBM Personal Computer DOS version 2.10 and MS-DOS version 1.25 have no trouble with these disks, since they have the same optimization. The "/O" switch causes FORMAT to redo the directory with a 0E5H byte at the start of each entry so that the disk may be used with 1.x versions of IBM PC DOS, as well as with MS-DOS 1.25/2.XX and IBM PC DOS 2.00/2.10. This switch should only be given when needed because it takes a fair amount of time for FORMAT to perform the conversion, and it noticeably decreases 1.25 and 2.x performance on disks with few directory entries.
A "/C" switch is specified for "Clear". This switch should cause the formatting operation to be bypassed (within DISKFORMAT or BADSECTOR). This is provided as a time-saving convenience to the user, who may wish to "start fresh" on a previously formatted and used disk.
The "/T:<xx>" option is used to specify the number of tracks that Format will place on a floppy disk.
The "/N:<xx>" option is used to specify the number of sectors per track that Format will use to format a floppy disk.
BIOSFILE & DOSFILE
The BIOSFILE and DOSFILE data strings are used to specify the filenames for the hidden BIOS and DOS system files written to the formatted disk when the /s option is selected. The filename strings should be null terminated root directory specifications commencing with a dummy non-zero drive letter byte which will be modified by the FORMAT module at run-time. eg.
BIOSFILE db "x:\IO.SYS",0 DOSFILE db "x:\MSDOS.SYS",0
The following data is declared PUBLIC in Microsoft'sFORMAT module and may be used by the OEM's moduleas required.
SWITCHMAP
A WORD value with a bit vector indicating which switches are included in the command line. The correspondence of the bits to the switches is determined by SWITCHLIST. The extreme right (highest-addressed) switch in SWITCHLIST (which must be the system transfer switch, normally "/S") corresponds to bit 0, the second from the right, normally "/V" to bit 1, etc. For example, if SWITCHLIST is the string "7,'AGI2OVS'", and the user specifies "/G/S" on the command line, then bit 6 will be 0 (/A not specified), bit 5 will be 1 (/G specified), bits 4,3,2 and 1 will be 0 (neither I,2,O or V specified), and bit 0 will be 1 (/S specified).
FBIGFAT
BYTE which takes on one of two possible values, 0 or 0FFH. WARNING: Any value other than 0 or 0FFH will cause FORMAT to do very odd things. The value 0 indicates that the disk being formatted will have a 12-bit FAT. The value 0FFH means that the disk being formatted will have a 16-bit FAT.
DRIVE
A byte value containing the drive specified in the command line. 0=A, 1=B, etc.
DRIVELETTER
A byte value containing the ASCII value of the drive letter specified in the command line.
DEVICEPARAMETES
A structue containing the device parameters of the drive to be formatted. The format of the DEVICEPARAMETERS data structure is as follows;
DP_SpecialFunctions : BYTE DP_DeviceType : BYTE DP_DeviceAttributes : WORD DP_Cylinders : WORD DP_MediaType : BYTE DP_BPB : BPB DP_TrackTableEntries : WORD DP_sectorTable : BYTE TABLE
INBUFF
A string buffer used to return a character string entered from the keyboard in the user_string routine in the FORMAT module.
CURRENTHEAD
A word value containing the drive head which was being formatted when an error occurred.
CURRENTCYLINDER
A word value containing the drive cylinder which was being formatted when an error occured.
FLASTCHANCE
A byte value used to flag whether a format message is to printed at the start of a format attempt.
NUMSECTORS
A word value containing the number of sectors specified in the command line with the /n switch.
TRACKCNT
A word value containing the number of sectors specified in the command line with the /t switch.
The detailed description of the routines required to be declaredpublic in the OEM's module is as follows;
OEMDONE
This routine is called after the formatting has been completed, the disk directory has been initialized and the system has been transferred if specified. It is called once for each disk to be formatted. This gives the chance for any finishing up operations, if needed. If the OEM desires extra files to be put on the formatted disk by default, or according to a switch, this could be done in OEMDONE. The OEMDONE routine should also check for the /b switch and, if present, should notify the FORMAT module of a non-standard system size by calling the ADDTOSYSTEMSIZE routine in the FORMAT module.
The following data items form the inputs to the OEMDONE routine;
SwitchMap : A WORD vaule indicating which switches were selected. The format of the SwitchMap is as described previously.
The OEMDONE outputs should be;
Carry Flag : Set on error, else clear. If an error status is returned by OEMDONE, the error message "Format failure" and a prompt for another disk will be displayed.
WRITEBOOTSECTOR
This routine is called once for each disk formatted after the format has occured but prior to installing a system on the disk. The routine writes the OEM specific boot sector(s) to the disk. The first boot sector must be written to the disk with an initialized BPB. The boot code may be contained within the OEMFOR module and copied to the boot sectors by this routine or may be written to the boot sectors after the format using a separate OEM utility as long as the BPB is written in this routine. The functionality of the code and data required in the boot sector(s) is discussed in detail in section 4.4 . If an error occurs while writing the boot sector(s) the routine should display an error message and return with the carry flag set.
CHECKSWITCHES
This routine is called once before any disks have been formatted. It is used to verify that the switches selected are a legal combination for the drive type to be formatted and to modify the drive device parameters according to the selected switches if they are valid. For example the valid swith combinations for supported drive types could be;
Disk Type Valid switches
160/180KB /l /4 /8 /b /n /t /v /s 320/360KB /l /4 /8 /b /n /t /v /s 720KB /n /t /v /s 1.2MB /n /t /v /s Hard disk /v /s
The CHECKSWITCH routine is included in the OEMFOR module so that the OEM may decide what action to take for an OEM specific drive type with the switch combination selected.
The following data items form the inputs to the CHECKSWITCHES routine;
deviceParameters : A data structure containing the drive parameters for the drive to be formatted. The fields of this structure are as descibed previously.
SwitchMap : A WORD vaule indicating which switches were selected. The format of the SwitchMap is as described previously.
NumSectors : A WORD value containing the number of sectors specified with the /n switch if it was present in the command line.
NumTracks : A WORD value containing the number of tracks specified with the /t option if it was present in the command line.
The CHECKSWITCHES outputs should be;
Carry Flag : Set on error, else clear.
deviceParameters : Device parameters to use in the format operation. Should have been modified by CHECKSWITCES if a legal switch combination specifies parameter modification.
NumSectors : If the /n switch was not present in the command line then the CHECKSWITCHES routine should initialize the NumSectors WORD from the deviceParamaters structure.
Trackcnt : If the /t switch was not present in the command line then the CHECKSWITCHES routine should initialize the Trackcnt WORD from the deviceParamaters structure.
LASTCHANCETOSAVEIT
This routine is called when an error, other than a write protect or not ready error, occurs during the disk format. It gives the OEM a chance to modify the disk parameters to be used in the format operation. The format will then be tried with these parameters. An example of when this could be used is if the format fails on the second head (track zero), the OEM may want to try formatting the disk single sided.
The LASTCHANCETOSAVEIT inputs are:
deviceParameters : A data structure containing the drive parameters for the drive being formatted when the error occurred. The fields of this structure are as described previously.
currentCylinder : A WORD value indicating the drive cylinder on which the error occurred.
currentHead : A WORD value indicating the drive head on which the error occurred.
The LASTCHANCETOSAVEIT outputs should are:
Carry Flag : Set if the error was fatal and no attempt is to be made to re-format the drive, else clear.
deviceParameters : Modified to contain the new parameters for the re-format, if a re-format attempt required.
fLastChance : A BYTE value set to TRUE if an attempt to re-format the drive is required. This prevents multiple format messages for a single drive format.
The following routines are declared PUBLIC in Microsoft'sFORMAT module and may be used by the OEMFOR moduleas required.
ADDTOSYSTEMSIZE
Adds to the number of sectors reserved for the system.
INPUTS : ax = size of system file in bytes.
OUTPUTS : None.
PRINTSTRING
Displays a character string.
INPUTS : dx = near pointer to null terminated string.
OUTPUTS : None.
STD_PRINTF
Displays a character string.
INPUTS : dx = near pointer to a near pointer to a null terminated string.
OUTPUTS : None.
CRLF
Outputs a carriage return and linefeed to the console.
INPUTS : None.
OUTPUTS : None.
USER_STRING
Get a string from the keyboard.
INPUTS : None.
OUTPUTS : Zero flag set if <CR> only was enterred. String length in BYTE at offset INBUFF + 1. Console input in INBUFF commencing at offset INBUFF +2.
Once the OEM-supplied module has been prepared, it must belinked with Microsoft's FORMAT.OBJ module, and theFORMES.OBJ module. In 3.XX, there are additional formatmodules that must be linked in. If the OEM-supplied moduleis called OEMFOR.OBJ, then use the following linker command;
link format forproc formes oemfor printf;
This command produces an executable file called FORMAT.EXE.NOTE: The OEM's module CAN NOT make the assumption, as itcould in the previous versions, that it is at the "end" ofthe memory image. It must use function 48h (allocatememory) if required.
7.3 FORMAT MODULES AND THE ES REGISTER
If an OEM-written FORMAT module, such as OEMDONE, makes use ofthe ES register, the value of ES should be established by theOEM's code. The contents of the ES register cannot be assumed.
CONTENTS
CHAPTER 7B WRITING THE FORMAT MODULE FOR MS-DOS 2.25/3.10
7.1 Introduction 7-1 7.2 Format Modules and the ES Register 7-9 7.3 Changing the Logical Format of Disks 7-9
CHAPTER 7B
WRITING THE FORMAT MODULE MS-DOS 2.25/3.10
HIGHLIGHTS OF CHANGES IN 3.XX OVER PREVIOUS 2.XX FORMAT VERSION:
o FORMAT is now designed to be an .EXE file.
o The FBIGFAT variable has been introduced for 16-bit FAT support.
o ALLOCATEFAT routine allows space for the FAT to be dynamically allocated.
7.1 INTRODUCTION
The MS-DOS Format command formats a new disk, clears the FATand directory, and optionally copies system files andCOMMAND.COM to the new disk. Since the Format command mustperform functions that have no equivalent in MS-DOS functioncalls, FORMAT is shipped in two hardware-independent objectmodules. These must be linked to a hardware-specific modulewritten by the OEM. The following section describes theroutines required in this module. A sample OEM formatmodule is included on the MS-DOS release disks to assist inwriting these routines.
The syntax for the Format command is:
Format [drive:][/switch1][/switch2]...[/switch16]
"drive:" is a legal drive specification. If it is omitted, the default drive will be used. As many as 16 legal switches can be included in the command line.
WRITING THE FORMAT MODULE Page 7-2
In 3.XX the OEM must supply six (NEAR) routines to the program alongwith seven data items. In 2.XX the OEM must supply five (NEAR) routinesto the program along with six data items. The names of the routines are:
ALLOCATEFAT INIT DISKFORMAT BADSECTOR WRTFAT DONE
ALLOCATEFAT is used only in 3.XX.
Their flow of control (by the Microsoft module) is likethis:
| +-------------+ | ALLOCATEFAT | +-------------+ | +---------+ | INIT | +---------+ | |<------------------------------++------------+ || DISKFORMAT | |+------------+ | |<-------+ |+-----------+ |-This loop is done |- This loop is| BADSECTOR | | for each group of | done once for+-----------+ | bad sectors | each disk to be |----->--+ | formatted. If | | variable HARDFLAG+----------+ | is set then the| | | loop is only| WRTFAT | | performed once.+----------+ | | | +------+ | | DONE | | +------+ | +---->--------------------------+
The ALLOCATEFAT, INIT, DISKFORMAT, and BADSECTOR routinesare free to use any MS-DOS system calls, except for callsthat cause disk accesses on the disk being formatted. DONEmay use any calls, since by the time it is called the new ___disk has been formatted. WRITING THE FORMAT MODULE Page 7-3
The following data must be declared PUBLIC in a moduleprovided by the OEM:
SWITCHLIST
A string of bytes. The first byte is count n, followed by n characters that are the switches to be accepted by the command line scanner. Alphabetic characters must be in uppercase (the numeric characters 0-9 are allowed). The last three switches, normally "/O", "/V" and "/S", have pre-defined meanings.
The "/S" switch is the switch that causes the system files IO.SYS, MSDOS.SYS, and COMMAND.COM to be transferred to the disk after it is formatted, thus making a system disk. The switch can be some letter other than "S", but the last switch in the list is assumed to have the meaning "transfer system," regardless of what the particular letter is.
The second to the last switch, "/V", causes FORMAT to prompt the user for a volume label after the disk is formatted. As with "/S", the particular letter is not important but rather the position in the list.
The third to the last switch, "/O", causes FORMAT to produce an IBM Personal Computer DOS version 1.x-compatible disk. Normally FORMAT causes a 0 byte to be placed in the first byte of each directory entry instead of the 0E5H free entry designator. This markedly increases the performance of a directory search due to an optimization in the DOS. Disks made with this switch cause trouble on IBM PC DOS 1.x versions which did not have this optimization. The 0 byte fools IBM 1.x versions into thinking these entries are allocated instead of free. Note that IBM Personal Computer DOS version 2.10 and MS-DOS version 1.25 have no trouble with these disks, since they have the same optimization. The "/O" switch causes FORMAT to redo the directory with a 0E5H byte at the start of each entry so that the disk may be used with 1.x versions of IBM PC DOS, as well as with MS-DOS 1.25/2.XX and IBM PC DOS 2.00/2.10. This switch should only be given when needed because it takes a fair amount of time for WRITING THE FORMAT MODULE Page 7-4
FORMAT to perform the conversion, and it noticeably decreases 1.25 and 2.x performance on disks with few directory entries.
Up to 16 switches are permitted. Normally a "/C" switch is specified for "Clear". This switch should cause the formatting operation to be bypassed (within DISKFORMAT or BADSECTOR). This is provided as a time-saving convenience to the user, who may wish to "start fresh" on a previously formatted and used disk.
HARDFLAG
BYTE location which specifies whether the OEM routine is formatting a fixed disk or a drive with removable media. A zero means removable media; any other value indicates a fixed disk. The status of this byte only affects the messages printed by the main FORMAT module. This value should be set or reset by the OEM-supplied INIT routine.
FATID
BYTE location containing the value to be used in the first byte of the FAT. Must be in the range F8H to FFH.
STARTSECTOR
WORD location containing the sector number of the first sector of the data area.
FATSPACE
WORD location containing the address of the start of the FAT area. A FAT built in this area will be written to disk using the OEM-supplied WRTFAT subroutine. 6K is sufficient to store any 12-bit FAT. This area must not overlap the FREESPACE area.
FREESPACE
WORD location that contains the address of the start of free memory space. This is where the system will be loaded by the Microsoft module for transferring to the newly formatted disk. Memory should be available from this address to the end of memory, so it is typically the address of the end of the OEM module. WRITING THE FORMAT MODULE Page 7-5
FBIGFAT
BYTE which takes on one of two possible values, 0 or 0FFH. WARNING: Any value other than 0 or 0FFH will cause FORMAT to do very odd things. The value 0 indicates that the disk being formatted will have a 12-bit FAT. The value 0FFH means that the disk being formatted will have a 16-bit FAT. See ALLOCATEFAT call, below, for details. FBIGFAT is used only in 3.XX.
The following routines must be declared PUBLIC in theOEM-supplied module:
ALLOCATEFAT
ALLOCATEFAT is used only in 3.XX. It is an initialization routine. This routine is called once at the start of the FORMAT run after the switches have been processed. This routine must set the correct values of FBIGFAT, FATSPACE, and FREESPACE.
With only 12-bit FATs it was convenient to allocate a FAT area of 6K (maximum size of a 12-bit FAT) as part of the memory image of FORMAT. With the advent of 16-bit FATs in DOS 3.XX this is no longer convenient; the maximum size of of a FAT is 32K. ALLOCATEFAT is a dynamic space allocator that allocates enough memory to hold the FAT by setting the values of FATSPACE and FREESPACE. ALLOCATEFAT must also set FBIGFAT so that FORMAT knows whether the disk has a 12 or a 16-bit FAT.
FBIGFAT must be set consistently with the following FAT rule (see below).
The 16-bit FAT rule:
- Any disk with less than 4086 clusters has a ____ ____ 12-bit FAT. - Any disk with greater than or equal to 4086 _______ ____ __ _____ __ clusters has a 16-bit FAT.
The OEM FORMAT module cannot force a 16-bit FAT if the total number of clusters is less than 4086. Similarly, you cannot have a 12-bit FAT on a disk with more than 4085 clusters. If the OEM module does not set FBIGFAT consistently with the 16-bit FAT rule, the disk will not be formatted correctly, and MS-DOS will not access the disk in the proper manner. WRITING THE FORMAT MODULE Page 7-6
Currently, there is no error return from ALLOCATEFAT. It should exit with CARRY CLEAR, however, so that it is consistent with the other routines. The Microsoft 3.XX FORMAT.OBJ is responsible for checking that the memory needed for the FAT is actually available to the system. It will produce a "Insufficient memory for system transfer" error when memory is inadequate. This error is produced when memory is inadequate for both "/S" and non "/S" procedures.
INIT
An initialization routine. This routine is called once at the start of the FORMAT run after the switches have been processed. This routine should perform any functions that need to be done once per FORMAT run. An example of what this routine might do is read the boot sector into a buffer so that it can be transferred to the new disks by DISKFORMAT. If this routine returns with the CARRY flag set, it indicates an error, and FORMAT will print "Format failure" and quit. This feature detects conflicting switches (like specifying both single and double density) and causes the FORMAT routine to abort.
DISKFORMAT
Formats the disk according to the options indicated by the switches and the value of FATID must be defined when it returns (although INIT may have already done it). This routine is called once for each disk to be formatted. If necessary, it must transfer the bootstrap loader. If any error conditions are detected, the carry flag is set. FORMAT will report a "Format failure" and prompt for another disk. (If you only require a clear directory and FAT, all that DISKFORMAT must do is set the appropriate FATID, if this has not already been done by INIT.
BADSECTOR
Reports the sector number of any bad sectors that may have been found during the formatting of the disk. This routine is called at least once for each disk to be formatted, and is called repeatedly until the AX register is zero or the carry flag is set. The carry flag is used just as in DISKFORMAT to indicate an error, and FORMAT handles it in the same way. The first sector in the data area must be in STARTSECTOR for the returns from this routine to be interpreted correctly. If there are bad sectors, BADSECTOR must return a sector number in WRITING THE FORMAT MODULE Page 7-7
register BX, the number of consecutive bad sectors in register AX, and clear the carry flag. FORMAT will then process the bad sectors and call BADSECTOR again. When BADSECTOR returns with AX = 0, there are no more bad sectors; FORMAT clears the directory and goes on to DONE. For this last return, BX need not contain anything meaningful.
FORMAT processes bad sectors by determining their corresponding allocation unit and marking that unit with an FF7H in the File Allocation Table. CHKDSK understands the FF7H mark as a flag for bad sectors and accordingly reports the number of bytes marked in this way.
Actual formatting of the disk can be done in BADSECTOR instead of DISKFORMAT on a "report as you go" basis. Formatting continues until a group of bad sectors is encountered; BADSECTOR then reports them by returning with AX and BX set. FORMAT will then call BADSECTOR again and formatting can continue.
WRTFAT
This routine is called after the disk is formatted and bad sectors have been reported. It writes all copies of the FAT from the area of memory referenced by FATSPACE to the drive just formatted. It may be possible to use INT 26H to perform the write, or a direct BIOS call. Whether this is possible depends on whether the FAT ID byte is used by the BIOS to determine the media in the drive. If it is, these methods will probably fail because there is no FATID byte on the disk yet (in this case WRTFAT's primary job is to get the FATID byte out on the disk).
DONE
This routine is called after the formatting has been completed, the disk directory has been initialized, and the system has been transferred if specified. It is called once for each disk to be formatted. This gives the chance for any finishing-up operations, if needed. If the OEM desires extra files to be put on the disk by default, or according to a switch, this could be done in DONE. WRITING THE FORMAT MODULE Page 7-8
Again, as in BADSECTOR and DISKFORMAT, carry flag set on return means an error has occurred; "Format failure" will be printed and FORMAT will prompt for another disk.
The following data is declared PUBLIC in Microsoft'sFORMAT module:
SWITCHMAP
A WORD value with a bit vector indicating which switches are included in the command line. The correspondence of the bits to the switches is determined by SWITCHLIST. The extreme right (highest-addressed) switch in SWITCHLIST (which must be the system transfer switch, normally "/S") corresponds to bit 0, the second from the right, normally "/V" to bit 1, etc. For example, if SWITCHLIST is the string "7,'AGI2OVS'", and the user specifies "/G/S" on the command line, then bit 6 will be 0 (/A not specified), bit 5 will be 1 (/G specified), bits 4,3,2 and 1 will be 0 (neither I,2,O or V specified), and bit 0 will be 1 (/S specified).
Bits 0,1 and 2 are the only switches used in Microsoft's FORMAT module. These switches are used 1) after INIT has been called to determine if it must load the system; 2) after the last BADSECTOR call to determine if the system should be written, E5 directory conversion should be done, and/or a volume label should be asked for. INIT may force these bits set or reset if desired (for example, some drives may never be used as system disk, such as hard disks). After INIT, the "/S" bit may be turned off (but not on, since the system was never read) if something happens that means the system should not be transferred.
After INIT, a second copy of SWITCHMAP is made internally.It is used to restore SWITCHMAP for each disk to be formatted. FORMAT will turn off the system bit if bad sectors are reported in the system area; DISKFORMAT and BADSECTOR are also allowed to change the map. However, these changes affect only the current disk being formatted, since SWITCHMAP is restored after each disk. (Changes made to SWITCHMAP by INIT affect all disks.) WRITING THE FORMAT MODULE Page 7-9
DRIVE
A byte value containing the drive specified in the command line. 0=A, 1=B, etc.
Once the OEM-supplied module has been prepared, it mustlinked with Microsoft's FORMAT.OBJ module, and theFORMES.OBJ module. In 3.XX, there are additional formatthat must be linked in. If the OEM-supplied module is calledOEMFOR.OBJ, then use the appropriate linker command.
2.XX LINK FORMAT.OBJ+FORMES.OBJ+OEMFOR.OBJ
3.XX LINK FORMAT.OBJ+FORPROC.OBJ+FORMES.OBJ+OEMFOR.OBJ.PRINTF.OBJ
For 3.XX, the command produces an executable file calledFORMAT.EXE. Note that although the PRINTF.OBJ moduleis the last module specified, it does not follow theOEMFOR module in the memory image. The OEMFOR modulecan still make the assumption, as it has in the past,that it is at the "end" of the memory image.
For 2.XX, the command produces a FORMAT.EXE file whichmust be changed to a simple binary. This should be donewith the following command.
EXE2BIN FORMAT.EXE FORMAT.COM
This produces the 2.XX file, FORMAT.COM.
7.2 FORMAT MODULES AND THE ES REGISTER
If an OEM-written FORMAT module makes use of the ESregister, such as DISKFORMAT, the value of ES should beestablished by the OEM's code. The contents of the ESregister cannot be assumed.
WRITING THE FORMAT MODULE PAGE 7-10
7.3 CHANGING THE LOGICAL FORMAT OF DISKS
MS-DOS has an internal table which it builds frominformation returned by the BIOS BUILDBPB routine.There is a table maintained for each drive within thesystem and it is updated to reflect the media typewhenever a new disk is loaded. Before any access tothe disk directory, MS-DOS calls the BIOS MEDIACHECKroutine. If a disk change is reported, MS-DOS callsthe BIOS BUILDBPB routine to get the new mediainformation and updates its internal table. It isimportant to realize that MS-DOS operates with its owntable and not with any table within the BIOS.
FORMAT can be used to physically reformat the disk fromsingle to double-sided use. Therefore, the WRTFATroutine should ensure that the next call to the BIOSMEDIA CHECK/BUILD BPB routines made by the DOS will setthe media type to the type just formatted. This isbecause when the format operation is started, the DPB(Drive Parameter Block) reflects the media that existedbefore the format. This may need to be changed becausethe disk media may have been changed due to the formatprocess. Since this is basically a communicationbetween the OEM part of the FORMAT utility and the OEMBIOS, it is up to the OEM to determine the mostefficient and appropriate way to determine the correctmedia type. As an example, the FORMAT utility can callthe BIOS and cause the BIOS to return "media changed"on the next MEDIA CHECK call made by the DOS. The DOSwill then call the BUILDBPB BIOS routine; it mustreturn the correct BPB for the disk just formatted.
Trying to determine media change externally with theFORMAT utility calling the DOS will not work. Youmust:
o Have the correct BPB in the BIOS, and your FORMAT utility must communicate that information down to your BIOS, or
o Your BIOS must detect that the disk has been changed when the FORMAT utility is used. Then, the BIOS can look on the disk for the BPB and tell the DOS what the new BPB is.
The OEM may decide how this can be structured. TheBIOS can be in control and inform FORMAT what was done,or FORMAT can be in control and inform the BIOS thatthe media has changed.
There is an example of an OEM written FORMAT module on theSample MS-DOS Implementation Diskette.
CONTENTS
CHAPTER 8 TROUBLE-SHOOTING
CHAPTER 8
TROUBLE-SHOOTING
The following section addresses typical problems that youmay encounter when installing MS-DOS.
Problem:
When I type "r" for Retry when a disk error occurs, the system crashes.
Typical Cause:
When an error occurs during I/O, your device driver must report the number of sectors or characters correctly transferred. If you just set the error bit, MS-DOS will assume that it was able to read all of the sectors since the sector count will be the same as that set by MS-DOS.
Recommendation:
Report the actual number of sectors/bytes transferred in addition to reporting the error.
Problem:
I am booting up MS-DOS. I see the MS-DOS copyright message on the screen, but then I get the message "Bad or missing command interpreter."
Typical Cause:
SYSINIT is executing COMMAND.COM. This is the conclusion of MS-DOS initialization and is the first time that the disk must be read successfully. (Failure to find CONFIG.SYS is not an error.) Either COMMAND.COM is not on the disk or an invalid Bios Parameter Block (BPB) has been returned to MS-DOS so it does not correctly understand the format of the disk. TROUBLE-SHOOTING Page 8-2
Recommendation:
Check that the correct BPB is being returned and that COMMAND.COM is on disk. Install debugging code in the device driver to make sure requests to the device driver make sense.
Problem:
I am booting up MS-DOS. I get the MS-DOS copyright message on the screen, but then I get the message "Bad or missing /DEV/CON."
Typical Cause:
SYSINIT has closed all file handles and is now reopening them. The first file it opens is /DEV/CON, which is your console device. The system file table is examined for this device. /DEV/CON should be present. If it is not found, some of your IO.SYS code has destroyed the system file table or MS-DOS itself. This may happen if you have blown the MS-DOS stack, causing MS-DOS to write over the file table.
Recommendation:
Use a local stack in your device drivers.
Problem:
MS-DOS is trying to read some sectors starting at an extremely large or invalid sector number.
Typical Cause:
The BPB that you returned for the drive is bad.
Recommendation:
The INIT and BUILD BPB device driver routines should be checked.
Problem:
After I jump to SYSINIT, control never comes back.
Typical Cause 1:
You may not have loaded MS-DOS correctly with your bootstrap loader. SYSINIT must know exactly where MS-DOS is. MS-DOS must be on a paragraph boundary and CURRENT_DOS_LOCATION and FINAL_DOS_LOCATION must be set up accordingly. TROUBLE-SHOOTING Page 8-3
Recommendation:
Check the location of MSDOS.SYS after bootstrap loading.
Typical Cause 2:
You are incorrectly reporting the amount of memory in the system or the memory scan is failing because of a discontinuity.
Recommendation:
Don't move MS-DOS after bootstrap loading. Don't request a memory scan. Make sure memory is contiguous.
Typical Cause 3:
MS-DOS can't find the beginning of the device list.
Recommendation:
Check the value passed to SYSINIT to make sure that it is the correct value for the beginning of the list.
Typical Cause 4:
The driver attributes are wrong. MS-DOS will not look for the end of list mark if the attributes are wrong.
Recommendation:
Check the device driver attribute words.
Typical Cause 5:
You do not have a driver in the linked list of device drivers with the CLOCK attribute bit set. This is necessary before SYSINIT will start looking for FFFF, FFFF in the last device driver.
Recommendation:
Be sure you have a CLOCK device in your linked list with its attribute word set properly.
Problem:
Everything was working great, but when I tried to install a new device, the system wouldn't boot.
Typical Cause:
You are failing to set the BREAK ADDRESS during the TROUBLE-SHOOTING Page 8-4
device INIT routine. This points to the first byte of free memory after the device code and data.
Recommendation:
Set the break address.
Problem:
Everything works OK until I define a new drive in IO.SYS. Then the system won't come up.
Typical Cause:
You are returning invalid data from the INIT call to the block device driver.
Recommendation:
Examine the INIT call. This is probably not being handled correctly. You should return a DWORD pointer to an array of WORD POINTERS to BPBs. The array must be below the 'break address' returned by INIT. There should be one array element for each drive defined. The number of subunits is also returned by the INIT call.
Problem:
My device driver defines two drives, but when I try to use drive B, I get an "Invalid drive specification" message.
Typical Cause:
You are not handling the INIT call to the device driver properly.
Recommendation:
The INIT call should return the value "2" at offset 13 from the beginning of the static request header.
Problem:
When I have a single-sided disk in drive B and remove it and install a double-sided disk, MS-DOS treats the double-sided disk like a single-sided disk. I am returning the correct BPB for the double-sided disk.
Typical Cause:
The media bytes in the BPBs are not unique.
Recommendation: TROUBLE-SHOOTING Page 8-5
Each BPB has a unique media byte. MS-DOS will not rebuild its internal DPB structure if the media byte doesn't change.
Problem:
I have a one-drive system. When I type B:<Return>, I get an "Invalid drive specification" message, but on some single-drive machines, MS-DOS prompts me for the "disk for drive B:."
Typical Cause:
The INIT call is only defining one disk drive and support for swapping has not been implemented in IO.SYS.
Recommendation:
Support for disk swapping is implemented at the IO.SYS file level rather than at the MS-DOS level. The driver reports two drives and when it sees a request for unit 1 (the second drive), it prints the swap message directly on the screen.
Problem:
Everything is running fine, but when I run Chkdsk I find that I only have 60K bytes free, but I have a 128K machine. I know that DOS and IO.SYS only take up 24K. What is happening to the missing bytes?
Typical Cause:
The Block Device Driver INIT call is returning a bad BPB pointer which reports an absurdly large sector size. This sector size is used to make all of the sector buffers, and consequently wastes thousands of bytes. You could have incorrectly set FINAL_DOS_LOCATION or installed a device driver that returned an 'absurdly large' break address.
Recommendation:
Fix the block device driver INIT call.
Problem:
Every time I try to do an Allocate Memory call (Function 48H) or an EXEC call, I get a return code of 8, "Not enough memory."
Typical Cause:
There is no free memory. TROUBLE-SHOOTING Page 8-6
Recommendation:
Do a Set Block (Function 4AH) call to shrink the size of the currently allocated block, freeing some memory. See the section on arenas in the Glossary.
Problem:
When running a program that opens a number of files via Function Request 3DH, the file open fails even though the file is present on the disk.
Typical Cause:
You have run out of entries in the system file table.
Recommendation:
Increase the "FILES = " entry in CONFIG.SYS and reboot.
Problem:
Control-S, Control-P, and the other control characters seem to be ignored by MS-DOS.
Typical Cause:
The non-destructive console read routine is not implemented properly.
Recommendation:
Check the non-destructive read routine in the console or other character driver where this problem is occurring.
Problem:
Sometimes when I am typing a long file to the screen and press Control-S, the Control-S is ignored and doesn't stop the scrolling of the file. I have the same problem with Control-C.
Typical Cause:
Another character has been typed into the type-ahead buffer first, and the nondestructive read keyboard status check never sees the Control-S or the Control-C.
Recommendation:
Implement Scroll Lock and Break keys which flush the TROUBLE-SHOOTING Page 8-7
input queue and put the Control-S/Control-C at the beginning of the type-ahead buffer.
Problem:
I am trying to use EXE2BIN to convert IO.EXE to IO.SYS. I get the message "File cannot be converted."
Typical Cause:
You have a "SEGMENT AT NNNN" statement and there is code or initialized data in that segment. You may also have a stack segment, which is not permitted.
Recommendation:
Remove the "SEGMENT AT" statement or remove code or initialized data from the segment.
It is possible, if your code contains FAR references, that EXE2BIN may request a 'Fixup' address. If your IO.SYS will always be loaded at the same place in memory, this may be OK. Check your FAR references in any case.
APPENDIX A
CUSTOMIZATION OF MS-DOS AND INTERNATIONALIZATION
A.1 CUSTOMIZING MS-DOS
Many manufacturers find it necessary to customize MS-DOS (asdistinct from IO.SYS) to some degree. The function keytable and OEM serial number are often modified. Thefunction key table is found in the DOSMES.ASM file. Extensivemodification to this table may require modifying the lineinput routines in STRIN.ASM, which is available to sourcelicensees only.
OEM Serial Numbers:
Each OEM is eligible for a unique OEM Serial Number. The Seriesis 0 to FF (255). IBM is 00 and we are currently at about 50Hon list.
These numbers are assigned sequentially by MS-DOS Product Marketingas requested through the OEM's Account Manager.
Once the OEM has this number they can modify the default FFvalue in the file DOSMES.ASM that is part of the adaptation kit. If this is done, when MSDOS.SYS file is built it will the right value.
It can be patched after they MSDOS.SYS is built by followingthe instructions in the README.DOC on the MS-DOS DISTRIBUTIONDISKETTES.
Function Request 30H - Get MS-DOS Version Number willreturn the version of the DOS that is being run, the OEMSerial number and the OEM user number.
To implement OEM user number concept properly each individualdisk shipped should have to have a separate user number patchedin according to the directions in the README.DOC on the MS-DOS DISTRIBUTION DISKETTES.
The OEM serial number can, however, be used without using theOEM User Number.
With these numbers properly installed, an application programcould tell which version of MS-DOS was being run, whichOEM had sold it and which customer had bought it.
Internationalization may also require customizing MS-DOS.The file named DOSMES.ASM contains a case conversion routineand a table used to translate foreign characters into theiruppercase equivalents. This routine defaults to no caseconversion, and a sample for the IBM PC character set isincluded. Note that this table is country-dependent. Youshould not translate a lowercase character available on thekeyboard into a uppercase equivalent that is not on the ___keyboard. For example, in France, translate lowercase ccedilla into uppercase C (not C cedilla); in Germany,translate lowercase "a umlaut" into uppercase A umlaut.
DOSMES.ASM also contains country-dependent tables used bythe international system call (Function 38H). MS-DOSutilities and COMMAND.COM make two system calls to determinetime and date formats and the location of the caseconversion routine. You may supply as many tables as youwish; however, it is not necessary to supply tables for allcountries in all translations. You should include tablesfor all countries into which a language translation isdistributed. For example, French might include tables forFrance, Belgium, and Switzerland. All versions shouldinclude a U.S. table as well. There is a pointer inDOSMES.ASM to the table to which MS-DOS should default ifthe user specifies no "COUNTRY =" parameter in CONFIG.SYS.Country numbers follow the information telephone codes wheretwo-digit numbers are employed.
CUSTOMIZATION OF MS-DOS AND INTERNATIONALIZATION Page A-2
A non-ASCII character text is represented by variablesequated at the beginning of the file. These default to theIBM PC character set. If your character set is different,redefine the equates and reassemble, linking the messagefile with the code files.
The SORTMES.ASM file contains a table for collatingsequences. This defaults to no mapping; all uppercaseASCII is sorted before all lowercase ASCII. A sample tablefor the IBM PC character set is included. Note that thereis no capability for equating a single character to amultiple character string or vice versa. Therefore, Germanimplementations cannot equate an umlaut to "ae", but maychoose to equate it to "a" or have it fall between "a" and"b".
A.2 EXTENDED CHARACTER SET (ECS) CONSIDERATIONS - MS-DOS 2.25
All ECS characters are two-byte quantities which also display as twophysical character positions (double-written) on the screen andprinter. This imposes some constraints on the IO.SYS keyboard andscreen drivers. MS-DOS ensures that 16-bit ECS characters are treatedas a single logical character from the user's standpoint, ratherthan being confused for two characters. CUSTOMIZATION OF MS-DOS AND INTERNATIONALIZATION Page A-3
A.3 INPUT
On input, it is the responsibility of IO.SYS to pass ECScharacters to MS-DOS. IO.SYS must handle allKata-kana-to-ECS conversion or any other method used toenter ECS. IO.SYS always places both bytes of the ECScharacter into its buffer at once; however, they are passedto MS-DOS as if they are two separate single-bytecharacters. Therefore, even non-interrupt-driven keyboardsshould always have the second byte of the ECS characterwaiting by the time the first byte is accepted by MS-DOS.IO.SYS should never pass an invalid ECS sequence toMS-DOS.
A.4 OUTPUT
On output, IO.SYS must identify the first byte of an ECScharacter, set a flag, and wait for the second byte. Oncethe entire ECS character has been received, IO.SYS indexesinto the font table. The font table may be in memory, ondisk, or in a combined memory-disk caching scheme. IO.SYSmay call MS-DOS to read font files stored on the disk inMS-DOS format. These files should be opened in IO.SYS whencontrol is passed back to RE_INIT, after MS-DOS has beeninitialized.
IO.SYS performs error recovery in case the font files are ona disk that has been removed. Door lock detection is mosthelpful here. Files should be reopened whenever thepotential for a changed disk occurs. MS-DOS screen andkeyboard routines are not reentrant, and cannot be calledfrom within IO.SYS to facilitate recovery from this error.A solution to the problem of missing font files is todisplay all ECS characters for which no font is in memoryas double-width reverse video blanks.
IO.SYS also must perform error handling in the data streamwhere an invalid ECS sequence is sent. Although invalidcharacters should never be input from the keyboard, they canbe output by several occurrences:
1. The user can display a garbage file, such as a binary executable file.
2. A program may have executed a file with bad ECS data.
3. The manipulation of fixed length fields may have split a ECS character between its two bytes.
CUSTOMIZATION OF MS-DOS AND INTERNATIONALIZATION Page A-4
If any of these occur, the recommended procedure is todisplay a double-width reverse video blank characterfollowed by the single-byte ASCII value for the characteroutside of the valid second-byte range. This will help toresynchronize the data stream as soon as possible.
MS-DOS recognizes double-byte values, such as blank space,over ECS in its line editing procedures. It also willaccept and display (if appropriate) the second byte where asingle-byte response is anticipated ("Strike any key").
IO.SYS should ensure that a ECS character is never splitacross the last column of one physical line and the firstcolumn of the next line. The entire ECS character muststart on the next line. IO.SYS must keep a flag for eachline to determine whether one or two logical backspaceoperations should be performed. The "Backspace-Space-Backspace" destructive operation issued by MS-DOS will workproperly.
For example, starting with column 1, assume that text runsup to and includes column 79. MS-DOS requests that adouble-byte ECS character be displayed. IO.SYS:
1. Blanks column 80.
2. Sets a flag for that physical line.
3. Moves to the beginning of the next line.
4. Displays both bytes.
MS-DOS requests two backspaces over this ECS character.If a third backspace is issued, IO.SYS must clear the flagand perform an extra backspace, returning to column 79instead of 80. If a space is issued, column 79 will beblanked. Remember that column 80 was originally blank, sothere is no need to reset it.
If the ANSI screen driver is also implemented, the drivershould never allow only one-half of a ECS character to beblock transferred without blanking it in scrolling regions.This rule also applies to both the region being moved andthe area into which it is being moved.
APPENDIX B
HOW TO UPGRADE A 2.XX BIOS TO 3.XX
MS-DOS 3.XX provides very few new services that impact devicedrivers. The basic BIOS mechanisms are identical to thosein MS-DOS 2.XX. The only changes are that a few new devicedriver calls have been added. These calls are not required. ___There are new device attribute bits that indicate thepresence of these new functions. Old device drivers do nothave these bits set, and thus indicate that the functionsare not present.
There are several new CONFIG.SYS commands. The code forthese is contained in the SYSINIT modules, and there are nonew PUBLICs in SYSINIT, or expected EXTERNs in the BIOS.
First, to quickly bring up MS-DOS 3.XX with a 2.XX set ofdevice drivers, all that you need to do is build a new BIOSwith the new 3.XX SYSINIT and SYSIMES modules in the same waythat the 2.XX BIOS was built. This will produce a perfectlyfunctional BIOS, but none of the devices will have any ofthe new 3.XX functions implemented.
Since you have not modified your BIOS, you cannot supportthe following features:
1. The IOCTL is Changeable (Function 4408H) call. This is useful for FORMAT and other programs that want to prompt for a change of media.
2. The character device OPEN and CLOSE device driver calls. These are useful for flushing interrupt-driven I/O.
3. The background print utility spooling to a network printer.
4. Output-until-busy device driver call for PRINT/PSPRINT spool devices.
HOW TO UPGRADE A 2.XX BIOS TO 3.XX Page B-2
1. IOCTL Is Changeable Call
The IOCTL Is Changeable (Function 4408H) call is fairly easy to implement. Set the appropriate bit in the device-attribute word for your block device drivers, and add the necessary code to return the particular value for your floppies and hard disks.
2. OPEN and CLOSE calls
OPEN and CLOSE device driver calls are needed only ____ if you have interrupt-driven I/O. If you omitted this feature, then you have nothing to do. If you support interrupt-driven I/O, set the appropriate bit in the attribute word for your character device driver and add the necessary code to wait until your buffers are empty.
____________________________________________________________| || Note || || The same bit in the attribute word is used to indicate || that Is-Removable and OPEN/CLOSE is present. This || means that you must put in NO-OP stubs for those || functions you will not use (simply return with no error || for OPEN/CLOSE). MS-DOS assumes that all three of || these new functions exist if this attribute bit is set. || ||__________________________________________________________|
3. Background Print Utility
The third feature (background print spooling to a network printer) is difficult to implement. You MAY need to add code to the output loop of the character device driver that tells the network portion of MS-DOS that you sent a character to a particular device. You will also need to modify the code in NETPS (part of the Redirector) to receive this input. The skeleton code in NETPS is for INT 17H (output-to-printer) on the IBM PC. So there is NO SPECIAL CODE in the IBM PC printer device drivers as everything is handled by INT 17H. Your architecture may require a different mechanism. You may wish to use the INT 2FH mechanism to achieve this.
If your architecture doesn't provide for Redirection at the ROM BIOS entry level (INT 17H on the IBM PC), your added code in the device driver will signal the network piece that you have a character destined for a particular device. The network piece will decide whether or not that output should be routed across the network. If so, it will handle the character and return an indication that the character was handled. Otherwise, it will indicate that the device driver should take care of HOW TO UPGRADE A 2.XX BIOS TO 3.XX Page B-3
it. After this call in the device driver, the code should examine the return to see if the device driver should process the character or return. The code required to do this is quite small, typically less than 100 bytes.
There is more information about how this is done in the Redirector Adaptation Guide that is available on the MS-NET distribution diskette.
4. Output-Until-Busy Call
The fourth feature is a new device call that helps the performance of the PRINT and PSPRINT (networking print) utilities. Most printers have RAM buffers which typically hold a line of characters or some fixed amount of characters. These buffers fill up without the printer going busy. This yields a "burst" type of behavior. A line of characters can be very quickly output to the printer, then the printer goes busy for a long time while the characters are being printed. This new device call allows the background spooling programs PRINT and PSPRINT to use this burst behavior efficiently. Rather than take the overhead of a device driver call for each character, or risk getting "stuck" in the device driver outputting a block of characters, this call allows a burst of characters to be output without getting stuck in the device driver waiting for the device to come ready.
APPENDIX C
HOW TO UPGRADE A 3.10 BIOS TO 3.20
The major change in the MS-DOS 3.2 BIOS is in the device drivers.The device drivers provide the support for the new Generic IOCTLrequests. If some of the new MS-DOS 3.2 features are going to be used, then the Generic IOCTL functions have to implemented in the device drivers. For example, the new MS-DOS 3.2 FORMAT utility has been designed to be hardware independent and uses Generic IOCTL's extensively. If the Generic IOCTL's are implemented in the device drivers, then the OEM will not have to modify the FORMAT utility.Refer to the MS-DOS 3.2 Device Drivers Guide and the MS-DOS 3.2Technical Guide for a complete listing of the use of Generic IOCTL's.
NOTE: Old device drivers will still work under MS-DOS 3.2 withoutthe Generic IOCTL's, but will not get the benefit of this feature.
The MS-DOS 3.2 BIOS makes use of a new data structure calledthe Block Data Structure (BDS). The BDS is listed in the fileMSBDS.ASM in the sample BIOS disk. This data structure describes the characteristics of a physical block device. The BDS is filled in at BIOS initialization time. The physical characteristicswithin the BDS can be changed after initialization time by using theDRVPARM option in the CONFIG.SYS file. Any block device drivers thathave the special MS-DOS 3.2 version bit set in the attribute wordmust contain a BDS. The BDS in the device driver will be linked withthe other BDS's of the system at initialization time.The BDS structure must be used if the Generic Device Driver (DRIVER.SYS) is to used in the OEM's system.
The MS-DOS 3.2 BIOS has extended the concept of logical drives.There can now be more than one logical drive associated with each physicaldrive. This logical drive mapping is achieved by using the Generic Device Driver, DRIVER.SYS.The extension of logical drives has prompted the idea of "Present Physical Drive Owner". The Present Physical Drive Owner is the last logical driveto have accessed a physical drive. This is an important concept becausewhen a reference is made to a logical drive that is NOT the PresentPhysical Drive Owner, the BIOS displays the following message:
Insert diskette for drive d: and strike any key when ready
where d: is the logical drive that was referenced. The Present PhysicalDrive Owner is stored in the BDS for the particular physical drive.Two new IOCTL calls have been introduced in connection with logicaldrives. The new calls are GET/SET LOGICAL DRIVE MAP. These two IOCTL'sare important for applications that want to control the printing of themessage to swap disks. The message to swap disks will only be displayedif the Present Physical Drive Owner is not the same as the logical drivebeing referenced. Applications that want to control the printing of thismessage (for example, full screen applications that want to displaythe swap disk message in a dialogue box) would use these calls to get andset the Present Physical Drive Owner.
APPENDIX D
This material was taken from the MS-DOS 3.20 Programmer's ReferenceManual. It is intended be used with the MS-DOS 2.XX/3.XX AdaptationGuide.
CHAPTER 2
MS-DOS DEVICE DRIVERS
2.1 INTRODUCTION
The IO.SYS file is composed of the "resident" devicedrivers, and forms the MS-DOS BIOS. MS-DOS calls upon theseresident drivers to handle I/O requests initiated byapplication programs.
One of the most powerful features of MS-DOS is that it letsyou add new devices such as printers, plotters, or mouseinput devices without rewriting the BIOS. The MS-DOS BIOSis "configurable;" that is, you can add and preempt newdrivers and existing drivers. You can also add non-residentdevice drivers at boot time by using the "DEVICE =" entry inthe CONFIG.SYS file. In this section, these non-residentdrivers are referred to as "installable" to distinguish themfrom drivers which, in the IO.SYS file, are considered asthe resident drivers.
At boot time, a minimum of five resident device drivers mustbe present. These drivers are in a linked list. The"header" of each driver contains a DWORD pointer to thenext. The last driver in the chain has an end-of-listmarker of -1, -1 (all bits on).
Each driver in the chain has two entry points--the strategyentry point and the interrupt entry point. MS-DOS does nottake advantage of the two entry points. Instead, it firstcalls the strategy routine, then immediately calls theinterrupt routine.
The dual entry points are provided for future multitaskingversions of MS-DOS. In multitasking environments, I/O mustbe asynchronous; to accomplish this, the strategy routinewill be called to (internally) queue a request and returnquickly. It is then the responsibility of the interruptroutine to perform the I/O at interrupt time by gettingrequests from the internal queue and processing them. Whena request is completed, the interrupt routine flags it as"done." MS-DOS periodically scans the list of requests,looking for those requests with done flags, and "wakes up" MS-DOS DEVICE DRIVERS Page 2-2
the process that is waiting for the completion of therequest.
When requests are queued in this manner, it is no longersufficient to pass I/O information in registers, since manyrequests may be pending at any one time. Therefore, theMS-DOS device interface uses "packets" to pass requestinformation. These request packets vary in size and formatand are composed of two parts:
1. The static request header section, which has the same format for all requests.
2. A section that has information specific to the type of request.
A driver is called with a pointer to a packet. Inmultitasking versions, this packet will be linked into aglobal chain of all pending I/O requests maintained byMS-DOS.
MS-DOS does not implement a global or local queue. Only onerequest is pending at any one time. The strategy routinemust store the address of the packet at a fixed location,and the interrupt routine, which is called immediately afterthe strategy routine, should process the packet bycompleting the request and returning. MS-DOS assumes thatthe request is complete when the interrupt routine returns.
To make a device driver that SYSINIT can install, you mustcreate a .BIN (core image) or .EXE format file that containsthe device driver header at the beginning of the file. Thelink field should be initialized to -1 (SYSINIT fills itin). Device drivers that are part of the BIOS should havetheir headers point to the next device in the list and thelast header should be initialized to -1,-1. The BIOS mustbe a .BIN (core image) format file.
If you have a non-IBM compatible version of MS-DOS 2.x, youcan use installable device drivers that are in .EXE format.On the IBM PC (or compatible) DOS 2.x versions, the .EXEloader is located in COMMAND.COM, which is not present atthe time that MS-DOS is loading the installable devices.
2.2 FORMAT OF A DEVICE DRIVER
A device driver is a program segment responsible forcommunication between DOS and the system hardware. It has aspecial header at the beginning identifying it as a devicedriver, defining its entry points, and describing itsvarious attributes. MS-DOS DEVICE DRIVERS Page 2-3
------------------------------------------------------------| || Note || || For device drivers, the file must not use the ORG 100H || (like .COM files). Because it does not use the Program || Segment Prefix, the device driver is simply loaded; || therefore, the file must have an origin of zero (ORG 0 || or no ORG statement). || ||__________________________________________________________|
There are two kinds of device drivers:
1. Character device drivers
2. Block device drivers
Character devices perform serial character I/O. Examplesare the console, communications port, and printer. Thesedevices have specific names (i.e., CON, AUX, CLOCK, etc.),and programs may open channels (handles or FCBs) to send I/Oto them.
Block devices are the "disk drives" on the system. They canperform random I/O in structured pieces called blocks(usually the physical sector size). These devices are notnamed as the character devices are, and therefore cannot beopened directly. Instead they have unit numbers and areidentified by drive letters such as A, B, and C.
A single block device driver may be responsible for one ormore logically contiguous disk drives. For example, theblock device driver ALPHA may be responsible for drives A,B, C, and D. This means that it has four units defined(0-3). The position of the driver in the list of alldrivers determines which units correspond to which driveletters. For example, if driver ALPHA is the first blockdriver in the device list, and it defines 4 units (0-3),then they will be A, B, C, and D. If BETA is the secondblock driver and defines three units (0-2), then they willbe E, F, and G, and so on. The theoretical limit is 63, butthe device installation code does not allow the installationof a device if it would result in a drive letter >`Z' (5AH).All block device drivers present in the standard residentBIOS are placed ahead of installable block-device drivers inthe list. MS-DOS DEVICE DRIVERS Page 2-4
------------------------------------------------------------| || Note || || Character devices cannot define multiple units || because they have only one name. || ||__________________________________________________________|
2.3 HOW TO CREATE A DEVICE DRIVER
To create a device driver that MS-DOS can install, you mustcreate a binary file (.COM or .EXE format) with a deviceheader at its beginning. Device driver code should notoriginate at 100H, but at 0. The device header contains alink field (pointer to next device header) which should be-1, unless there is more than one device driver in the file.
You must also correctly set the attribute field and entrypoints. The name field for a character device shouldcontain the name of that device. This name can be any legal8-character filename. But if it is less than eightcharacters, you should pad it out to eight by typing spaces(20H). Note that device names do not include colons (:).The fact that "CON" is the same as "CON:" is a property ofthe default MS-DOS command interpreter (COMMAND.COM) and notof the device driver or MS-DOS interface. All characterdevice names are handled in this way.
MS-DOS always processes installable device drivers beforehandling the default devices, so to install a new CONdevice, simply name the device "CON". Remember to set thestandard input and standard output device bits in theattribute word on a new CON device. The scan of the devicelist stops on the first match, so the installable devicedriver takes precedence.
It is not possible to replace the "resident" disk blockdevice driver with an installable device driver as you wouldreplace other device drivers in the BIOS. Block drivers canbe used only for devices not supported directly by thedefault disk drivers in IO.SYS.
------------------------------------------------------------| || Note || || Because MS-DOS can install the driver anywhere in || memory, you must be careful when making far memory || references. You should not expect that your driver || will always be loaded in the same place every time. || ||__________________________________________________________| MS-DOS DEVICE DRIVERS Page 2-5
2.3.1 Device Strategy Routine
This routine, which MS-DOS calls for each device driverservice request, is primarily responsible for queuing theserequests in the order in which they are to be processed bythe Device Interrupt Routine. Such queuing can be animportant performance feature in a multitasking environment,or where asynchronous I/O is supported. Since MS-DOS doesnot currently support these facilities, only one request(usually a short one) can be serviced at a time. In thecoding examples in Section 2.12, each request is simplystored in a single pointer area.
2.3.2 Device Interrupt Routine
This routine contains the code necessary for processing theservice request. It may interface to the hardware, or itmay use ROM BIOS calls. It usually consists of a series ofprocedures, which handle the specific command codes to besupported, as well as some exit and error-handling routines.See the coding examples in Section 2.12.
2.4 INSTALLATION OF DEVICE DRIVERS
MS-DOS allows new device drivers to be installed dynamicallyat boot time. This is accomplished by IO.SYS initializationcode which reads and processes the CONFIG.SYS file.
MS-DOS calls upon the device drivers to perform theirfunctions in the following manner:
1. MS-DOS makes a far call to strategy entry.
2. MS-DOS passes device driver information in a request header to the strategy routine.
3. MS-DOS then makes a far call to the interrupt entry.
This structure can be easily upgraded to support any futuremultitasking environment. MS-DOS DEVICE DRIVERS Page 2-6
2.5 DEVICE HEADERS
A device header, which is required at the beginning of everydevice driver, looks like this: +--------------------------------------+ | DWORD Pointer to next device | | (Usually set to -1 if this driver | | is the last or only driver in the | | file) | +--------------------------------------+ | WORD Attributes | +--------------------------------------+ | WORD Pointer to device strategy | | entry point | +--------------------------------------+ | WORD Pointer to device interrupt | | entry point | +--------------------------------------+ | 8-BYTE Character device name field | | Character devices set a device name. | | For block devices the first byte is | | the number of units. | +--------------------------------------+ Figure 2.1. Sample Device Header
Note that the device entry points are words. They must beoffsets from the same segment number used to point to thistable. For example, if XXX:YYY points to the start of thistable, then XXX:strategy and XXX:interrupt are the entrypoints.
The device header fields are described in the followingsection.
2.5.1 Pointer to Next Device Field
This pointer is a double word field (offset followed bysegment). MS-DOS sets this field so that it points to thenext driver in the system list at the time the device driveris loaded. Unless there is more than one device driver inthe file, it is important that you set this field to -1prior to loading (when it is on the disk as a file). Ifthere is more than one driver in the file, the first word ofthe double word pointer should be the offset of the nextdriver's device header. MS-DOS DEVICE DRIVERS Page 2-7
------------------------------------------------------------| || Note || || If there is more than one device driver in the || file, the last driver in the file must have the pointer || to the next device header field set to -1. || ||__________________________________________________________|
2.5.2 Attribute Field
The attribute field identifies the type of device thisdriver is responsible for. In addition to distinguishingbetween block and character devices, these bits giveselected character devices special treatment. (Note that ifa bit in the attribute word is defined only for one type ofdevice, a driver for the other type of device must set thatbit to 0.)
For character devices:
Bit Value Meaning 15 1 Character device 14 1 Device supports IOCTL control strings 13 1 Device supports Output Until Busy (OUB) 12 RESERVED 11 1 Device understands OPEN/CLOSE 10-7 RESERVED 6 1 Device supports 3.2 functions 5-4 RESERVED 3 1 Device is CLOCK device 2 1 Device is NUL device 1 1 Device is console output (STO) 0 1 Device is console input (STI)
For Block Devices:
Bit Value Meaning 15 0 Block device 14 1 Device supports IOCTL control strings 13 1 Device determines the media by examining the FATID byte. 12 RESERVED 11 1 Device understands OPEN/CLOSE/Removable Media. MS-DOS DEVICE DRIVERS Page 2-8
10-7 RESERVED 6 1 Device supports 3.2 functions 5-0 RESERVED
For example, assume that you have a new device driver thatyou want to use as the standard input and output. Inaddition to installing the driver, you must tell MS-DOS thatyou want this new driver to override the current standardinput and standard output (the CON device). You do this bysetting bits 0 and 1 to 1 (note that they are separate!).Similarly, you could install a new CLOCK device by settingthe appropriate attribute. (Refer to Section 2.10, "TheCLOCK Device," in this chapter for more information.)Although there is a NUL device attribute, you cannotreassign the NUL device. This attribute exists so thatMS-DOS can determine whether the NUL device is being used.
The IOCTL bit, bit 14, allows IOCTL functions to send andreceive data to character and block devices for their ownuse. This allows them to set baud rate, stop bits, formlength, etc., instead of passing data over the devicechannel as a normal read or write does. The interpretationof the passed information is up to the device, but thedevice must not treat this information as normal I/O. Thisbit tells MS-DOS whether the device can handle controlstrings via the IOCTL system call, Function 44H.
If a driver cannot process control strings, it should setthis bit initially to 0. This tells MS-DOS to return anerror if an attempt is made (via Function 44H) to send orreceive control strings to this device. A device which canprocess control strings should initialize the IOCTL bit to1. For drivers of this type, MS-DOS makes calls to theIOCTL INPUT and OUTPUT device functions to send and receiveIOCTL strings.
For block devices, bit 13 affects the operation of the BUILDBPB (BIOS Parameter Block) device call. If set, it requiresthe first sector of the FAT to reside ALWAYS in the sameplace. Bit 13 has a different meaning on character devices,indicating that the device implements the OUTPUT UNTIL BUSYdevice call.
The OPEN/CLOSE/RM bit, bit 11, signals to MS-DOS 3.x, andlater versions, whether this driver supports additionalMS-DOS 3.0 functionality. But to support these old drivers,it is necessary to detect them. Bit 11 was reserved inMS-DOS 2.x, and is 0. All new devices, however, shouldsupport the OPEN, CLOSE, and REMOVABLE MEDIA calls and setthis bit to 1. Since MS-DOS 2.x never makes these calls,the driver will be backwardly compatible.
The MS-DOS 3.2 bit, bit 6, signals whether the devicesupports logical drive mapping via Function 440EH (GetLogical Drive Map) and Function 440FH (Set Logical Drive MS-DOS DEVICE DRIVERS Page 2-9
Map). This bit also supports generic IOCTL functions viaFunction 440C (Generic IOCTL for Handles) and Function 440D(Generic IOCTL for Block Devices).
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0____________________________________________________________| C | I | O | | O | | | | | 3 | | | C | N | S | S || H | O | Y | | P | | | | | . | | | L | U | T | T || R | C | B | | N | | | | | 2 | | | K | L | O | I ||___|___|___|___|___|___|__|__|__|___|__|__|___|___|___|___|
Figure 2.? Attribute Word for character devices
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0____________________________________________________________| | I | F | | O | | | | | 3 | | | | | | || | O | A | | P | | | | | . | | | | | | || | C | T | | N | | | | | 2 | | | | | | ||___|___|___|___|___|___|__|__|__|___|__|__|___|___|___|___|
Figure 2.? Attribute Word for block devices
2.5.3 Strategy And Interrupt Routines
These two fields are the pointers to the entry points of thestrategy and interrupt routines. They are word values, sothey must be in the same segment as the device header.
2.5.4 Name Field
This is an 8-byte field that contains the name of acharacter device or the number of units of a block device.If it is a block device, the number of units can be put inthe first byte. This is optional, because MS-DOS fills inthis location with the value returned by the driver's INITcode. Refer to Section 2.4, "Installation of DeviceDrivers," for more information.
2.6 REQUEST HEADER
When MS-DOS calls a device driver to perform a function, itpasses a request header in ES:BX to the strategy entrypoint. This is a fixed length header, followed by datapertinent to the function being performed. Note that it isthe device driver's responsibility to preserve the machinestate (for example, save all registers including flags onentry and restore them on exit). There is enough room onthe stack to do about 20 pushes, when MS-DOS calls eitherthe strategy or the interrupt routines. If more stack is MS-DOS DEVICE DRIVERS Page 2-10
needed, the driver should set up its own stack.
The following figure illustrates a request header. REQUEST HEADER -> +-----------------------------+ | BYTE Length of record | | Length in bytes of this | | request header | +-----------------------------+ | BYTE Unit code | | The subunit the operation | | is for (minor device) | | (no meaning on character | | devices) | +-----------------------------+ | BYTE Command code | +-----------------------------+ | WORD Status | +-----------------------------+ | 8 BYTES Reserved | | | |-----------------------------| Figure 2.2. Request Header
The request header fields are described below.
2.6.1 Length of Record
This field contains the length (in bytes) of the requestheader.
2.6.2 Unit Code Field
The unit code field identifies which unit in your devicedriver the request is for. For example, if your devicedriver has 3 units defined, the possible values of the unitcode field would be 0, 1, and 2.
2.6.3 Command Code Field
The command code field in the request header can have thefollowing values:
Command Function Code
0 INIT MS-DOS DEVICE DRIVERS Page 2-11
1 MEDIA CHECK (Block devices only) 2 BUILD BPB (Block devices only) 3 IOCTL INPUT (Only called if device has IOCTL) 4 INPUT (read) 5 NON-DESTRUCTIVE INPUT NO WAIT (Char devs only) 6 INPUT STATUS (Char devs only) 7 INPUT FLUSH (Char devs only) 8 OUTPUT (write) 9 OUTPUT (Write) with verify 10 OUTPUT STATUS (Char devs only) 11 OUTPUT FLUSH (Char devs only) 12 IOCTL OUTPUT (Only called if device has IOCTL) 13 DEVICE OPEN (Only called if OPEN/CLOSE/RM bit set) 14 DEVICE CLOSE (Only called if OPEN/CLOSE/RM bit set) 15 REMOVABLE MEDIA (Only called if OPEN/CLOSE/RM bit set and device is block) 16 OUTPUT UNTIL BUSY (Only called if bit 13 is set on character devices) 19 Generic IOCTL Request (Only called if bit 0 is set for block devices) 23 Get Drive Map (Only called if bit 6 is set on block devices) 24 Set Drive Map (Only called if bit 6 is set on block devices)
Unused command codes are reserved.
2.6.4 Status Field
The following figure illustrates the status field in therequest header.
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 | | S | N | | | | | Y | E | | +---+---+--+--+--+--+---+---+--+--+--+--+--+--+--+--+
The status word is zero on entry and is set by the driverinterrupt routine on return.
Bit 8 is the done bit. When set, it means the operation hascompleted. The driver sets it to 1 when it exits.
Bit 15 is the error bit. If it is set, the low 8 bitsindicate the error. The errors are:
0 Write protect violation 1 Unknown unit 2 Drive not ready MS-DOS DEVICE DRIVERS Page 2-12
3 Unknown command 4 CRC error 5 Bad drive request structure length 6 Seek error 7 Unknown media 8 Sector not found 9 Printer out of paper A Write fault B Read fault C General failure D Reserved E Reserved F Invalid disk change
Bit 9 is the busy bit, which is set only by status calls andthe removable media call.
2.7 DEVICE DRIVER FUNCTIONS
Device drivers may perform all or some of these nine generalfunctions. In some cases, these functions break down intoseveral command codes. Each is described in this section.
1. INIT
2. MEDIA CHECK
3. BUILD BPB
4. READ or WRITE or WRITE TIL BUSY or Write with Verify or Read IOCTL or Write IOCTL
5. NON DESTRUCTIVE READ NO WAIT
6. OPEN or CLOSE (3.x)
7. REMOVABLE MEDIA (3.x)
8. STATUS
9. FLUSH
10. Generic IOCTL
11. Get Logical Device
12. Set Logical Device
All strategy routines are called with ES:BX pointing to theRequest Header. The interrupt routines get the pointers tothe Request Header from the queue in which the strategy MS-DOS DEVICE DRIVERS Page 2-13
routines store them. The command code in the request headertells the driver which function to perform and what datafollows the request header.
------------------------------------------------------------| || Note || || All DWORD pointers are stored offset first, segment || second. || ||__________________________________________________________|
2.7.1 INIT
Command code = 0
INIT - ES:BX -> +------------------------------------+ | 13-BYTE Request header | +------------------------------------+ | BYTE Number of units | +------------------------------------+ | DWORD End Address | +------------------------------------+ | DWORD Pointer to BPB array | | (Not set by character devices) | +------------------------------------+ | BYTE Block device number | +------------------------------------+
One of the functions defined for each device driver is INIT.This routine is called only once when the device isinstalled. The INIT routine must return the END ADDRESS,which is a DWORD pointer to the end of the resident portionof the device driver. To save space you can use thispointer method to delete init code that is needed only once.
The driver sets the number of units, end address, and BPBpointer. For installable block device drivers, the DWORDpointer to BPB array now points to the first character afterthe equal sign (=) on the line in CONFIG.SYS (the line thatcaused this device to be loaded). This line is terminatedby a RETURN or a linefeed. This data is read-only and letsthe device driver scan the CONFIG.SYS line for arguments.
device=\dev\vt52.sys /l ^ |_____BPB address points here
Also, the block device driver defines the first unit andassigns it to the drive number in the block device number MS-DOS DEVICE DRIVERS Page 2-14
field (for example, A=0). This field is also read-only.
Installable character devices must return only the endaddress parameter. This parameter is a pointer to the firstavailable byte of memory above the location of the driverand which the driver may use to throw away initializationcode.
Block devices must return the following information:
1. The number of units. MS-DOS uses this number to determine logical device names. At the time of the install call, if the current maximum logical device letter is F, and the INIT routine returns 4 as the number of units, these units will have logical names G, H, I and J. This mapping is determined by the position of the driver in the device list and by the number of units on the device (stored in the first byte of the device name field).
2. A DWORD pointer to an array of one-word offsets (pointers) to BPBs (BIOS Parameter Blocks). MS-DOS creates an internal structure by using the BPBs passed by the device driver. There must be one entry in this array for each unit defined by the device driver. In this way, if all units are the same, all the pointers can point to the same BPB, saving space. If the device driver defines two units, the DWORD pointer points to the first of two one-word offsets. In turn these offsets point to BPBs. The format of the BPB is described later in this chapter in Section 2.7.3, "BUILD BPB."
Note that this array of one-word offsets must not be above the free pointer set by the return, because the device driver builds an internal DOS structure, starting at the byte pointed to by the free pointer. The defined sector size must be less than or equal to the maximum sector size defined by the resident device drivers (BIOS) during initialization. If it isn't, the installation will fail.
3. The media descriptor byte. This byte, which is the last byte returned by INIT, means nothing to MS-DOS, but is passed to devices so that they know which parameters MS-DOS is currently using for a particular drive unit.
Block devices may be either dumb or smart. A dumb device ____ _____defines a unit (and therefore an internal DOS structure) for MS-DOS DEVICE DRIVERS Page 2-15
each possible media-drive combination. For example, unit 0= drive 0, single sided; unit 1 = drive 0, double sided.For the "dumb device" approach, media descriptor bytes donot mean anything. A smart device allows multiple media perunit. In the case of a smart device, the BPB table returnedupon INIT must define sufficient space to accommodate thelargest possible media. Smart drivers use the mediadescriptor byte to pass information about what media iscurrently in a unit.
For more information on the media descriptor byte, seeSection 2.8, "Media Descriptor Byte."
------------------------------------------------------------| || Note || || If a file contains multiple device drivers, MS-DOS uses || the ending address returned by the last INIT called. || All the device drivers in a single file should return || the same ending address. The code to remain resident || for all the devices in a file should be grouped || together in low memory with the initialization code for || all devices following it. || ||__________________________________________________________|
2.7.2 MEDIA CHECK
Command Code = 1
MEDIA CHECK - ES:BX -> +------------------------------------+ | 13-BYTE Request header | +------------------------------------+ | BYTE Media descriptor from BPB | +------------------------------------+ | BYTE Returned | +------------------------------------+ | Returned DWORD pointer to previous | | Volume ID if bit 11 set and | | Media Changed is returned | +------------------------------------+
The MEDIA CHECK function is used with block devices only.It is called when there is a pending drive access call otherthan a file read or write, such as open, close, delete, orrename. Its purpose is to determine whether the media inthe drive has been changed. If the driver can ensure that MS-DOS DEVICE DRIVERS Page 2-16
the media has not been changed (through a door-lock or otherinterlock mechanism), MS-DOS does not need to reread the FATand invalidate in-memory buffers for each directory access.
When such a disk access call to the DOS occurs (other than afile read or write), the following sequence of events takesplace:
1. The DOS converts the drive letter into the unit number of a particular block device.
2. The device driver is then called to request a media check on that subunit to see if the disk might have been changed. MS-DOS passes the old media descriptor byte. The driver returns:
Media not changed...... (1) Don't know if changed...(0) Media changed...........(-1) Error
If the media has not been changed, MS-DOS proceeds with the disk access.
If the value returned is "Don't know," and if there are any disk sectors that have been modified and not yet written back to the disk for this unit, MS-DOS assumes that the disk has not been changed and proceeds. MS-DOS invalidates any other buffers for the unit and does a BUILD BPB device call (see step 3, below).
If the media has been changed, MS-DOS invalidates all buffers associated with this unit including buffers with modified data that are waiting to be written, and requests a new BIOS Parameter Block via the BUILD BPB call (see step 3, below).
3. Once the BPB has returned, MS-DOS corrects its internal structure for the drive from the new BPB and, after reading the directory and the FAT, proceeds with the access.
Note that the previous media ID byte is passed to the devicedriver. If the old media ID byte is the same as the newone, the disk might have been changed and a new disk may bein the drive. Therefore, all FAT, directory, and datasectors that are buffered in memory for the unit areconsidered invalid.
If the driver has bit 11 of the device attribute word set to1, and the driver returns -1, "Media Changed," it must set MS-DOS DEVICE DRIVERS Page 2-17
the DWORD pointer to the previous Volume ID field. If theDOS determines that "Media Changed" is an error based on thestate of the DOS buffer cache, it generates a 0FH error onbehalf of the device. If the driver does not implementVolume ID support, but has bit 11 set, it should set astatic pointer to the string, "NO NAME",0.
It is not possible for a user to change a disk in less than2 seconds. So when MEDIA CHECK occurs within 2 seconds of adisk access, the driver reports "1," "Media not changed."This action increases performance tremendously.
------------------------------------------------------------| || Note || || For MS-DOS versions before 3.2 if the media ID byte in || the returned BPB is the same as the previous media ID || byte, MS-DOS assumes that the format of the disk is the || same (even though the disk may have been changed) and || skips the step of updating its internal structure. All || BPBs, therefore, must have unique media bytes regardless|| of FAT ID bytes. || ||__________________________________________________________|
2.7.3 BUILD BPB (BIOS Parameter Block)
Command code = 2
BUILD BPB - ES:BX -> +------------------------------------+ | 13-BYTE Request header | +------------------------------------+ | BYTE Media descriptor from BPB | +------------------------------------+ | DWORD Transfer address | | (Points to one sector worth of | | scratch space or first sector | | of FAT depending on the value | | of Bit 13 in the device attribute | | word.) | +------------------------------------+ | DWORD Pointer to BPB | +------------------------------------+
The Build BPB function is used with block devices only. Asdescribed in the MEDIA CHECK function, the BUILD BPBfunction is called any time that a preceding MEDIA CHECKcall indicates that the disk has been, or might have been, MS-DOS DEVICE DRIVERS Page 2-18
changed. The device driver must return a pointer to a BPB.This is different from the INIT call where the device driverreturns a pointer to an array of word offsets to BPBs.
The BUILD BPB call gets a DWORD pointer to a one-sectorbuffer. The contents of this buffer are determined by theNON FAT ID bit (bit 13) in the attribute field. If the bitis zero, the buffer contains the first sector of the firstFAT. The FAT ID byte is the first byte of this buffer, soin this case, the driver must not alter the buffer. Notethat the location of the FAT must be the same as for allpossible media because the DOS must read this FAT sectorbefore the driver returns the BPB that the DOS called. Ifthe NON FAT ID bit is set, the pointer points to one sectorof scratch space (space which may be used for anything).Refer to Section 2.8, "Media Descriptor Byte,"" and Section2.9, "Format of a Media Descriptor Table," for informationon how to construct the BPB.
MS-DOS 3.x includes additional support for devices that havedoor-locks or some other means of telling when a disk hasbeen changed. Error 15, a new error that the device drivercan return, means "the disk has been changed when itshouldn't have been." The user is prompted for the correctdisk using a Volume ID. The driver may generate this errorfor READ or WRITE. The DOS may generate the error for MEDIACHECK if the driver reports media changed, and there arebuffers in the DOS buffer cache that need to be flushed tothe previous disk.
For drivers that support this error, the BUILD BPB functionis a trigger that causes the driver to read a new Volume IDfrom the disk. This action indicates that the disk has beenlegally changed. The FORMAT or LABEL utility places aVolume ID on the disk. This ID is simply an entry in theroot directory of the disk that has the Volume ID attribute.The driver stores the Volume ID as an ASCIZ string.
The requirement that the driver return a Volume ID does notexclude some other Volume identifier scheme as long as thescheme uses ASCIZ strings. A NUL (nonexistent orunsupported) Volume ID is by convention the string:
DB "NO NAME ",0
MS-DOS DEVICE DRIVERS Page 2-192.7.4 READ or WRITE
Command codes = 3,4,8,9, 12, and 16
READ OR WRITE (Including IOCTL) or OUTPUT UNTIL BUSY - ES:BX -> +------------------------------------+ | 13-BYTE Request header | +------------------------------------+ | BYTE Media descriptor from BPB | +------------------------------------+ | DWORD Transfer address | +------------------------------------+ | WORD Byte/sector count | +------------------------------------+ | WORD Starting sector number | | (Ignored on character devices) | +------------------------------------+ | Returned DWORD pointer to requested| | Volume ID if error 0FH | +------------------------------------+
COMMAND CODE REQUEST
3 IOCTL READ 4 READ (block or character) 8 WRITE (block or character) 9 WRITE WITH VERIFY 12 IOCTL WRITE 16 OUTPUT TIL BUSY (char devs only)
The driver must perform the READ or WRITE call depending onwhich command code is set. Block devices read or writesectors; character devices read or write bytes.
When I/O completes, the device driver must set the statusword and report the number of sectors or bytes successfullytransferred, even if an error prevented the transfer frombeing completed. Setting the error bit and error code alone _______ ___ _____ ___ ___ _____ ____ _____is not sufficient.__ ___ __________
In addition to setting the status word, the driver must setthe sector count to the actual number of sectors (or bytes)transferred. No error check is performed on an IOCTL I/Ocall.
If the verify switch is on, the device driver is called withcommand code 9 (WRITE WITH VERIFY). Your device driver isthen responsible for verifying the write.
If the driver returns error code 0FH (Invalid disk change),it must return a DWORD pointer to an ASCIZ string (which isthe correct Volume ID). The return of this error codetriggers the DOS to prompt the user to re-insert the disk.The device driver should have read the Volume ID as a resultof the BUILD BPB function.
Drivers may maintain a reference count of open files on thedisk by monitoring the OPEN and CLOSE functions. Thisallows the driver to determine when to return error 0FH. Ifthere are no open files (reference count = 0), and the disk MS-DOS DEVICE DRIVERS Page 2-20
has been changed, the I/O is okay. If there are open files,however, an 0FH error may exist.
The OUTPUT UNTIL BUSY call is a speed optimization oncharacter devices only for print spoolers. The devicedriver is expected to output all the characters possibleuntil the device returns busy. Under no circumstancesshould the device driver block during this function. Notethat it is not an error if the device driver returns asmaller number of bytes output than bytes requested.
The OUTPUT UNTIL BUSY call allows spooler programs to takeadvantage of the burst behavior of most printers. Manyprinters have on-board RAM buffers which typically hold aline or a fixed amount of characters. These buffers fill upwithout making the printer "busy" between characters for arelatively short time (or at least not for more than teninstructions). The device driver can quickly output a lineof characters to the printer, which is then busy for acomparatively longer time while it prints. This new devicecall allows background spooling programs to use this burstbehavior efficiently. Rather than take the overhead of adevice driver call for each character, or risk getting stuckin the device driver outputting a block of characters, thiscall allows a burst of characters to be output without thedevice driver having to wait until the device is ready.
If the MS-DOS 3.2 bit is set, then MS-DOS can configure thenumber of retries (allowed by the device driver) that theprinter can make before returning "busy."
THE FOLLOWING APPLIES TO BLOCK DEVICE DRIVERS:___ _________ _______ __ _____ ______ _______
Under certain circumstances, the device driver may requestthat the BIOS perform a write operation of 64K bytes, whichseems to be a "wrap around" of the transfer address in theBIOS I/O packet. This request arises due to an optimizationadded to the write code in MS-DOS. It will only manifestitself on user writes within a sector size of 64K bytes tofiles "growing" past the current EOF. The BIOS may ignore ___ ____ ___ ______the balance of the write that "wraps around," if it so___ _______ __ ___ _____ ____ ______ ________ __ __ __chooses. For example, a write of 10000H bytes worth of________sectors with a transfer address of XXX:1 could ignore thelast two bytes. A user program can never request an I/O ofmore than FFFFH bytes and cannot wrap around (even to 0) inthe transfer segment. Therefore, in this case the BIOSignores the last two bytes.
MS-DOS maintains two FATs. If the DOS has problems readingthe first, it automatically tries the second beforereporting the error. The BIOS is responsible for allretries.
Although the COMMAND.COM handler does no automatic retries,there are applications that have their own Interrupt 24H MS-DOS DEVICE DRIVERS Page 2-21
handlers. These handles do automatic retries on certaintypes of Interrupt 24H errors before reporting them.
2.7.5 NON DESTRUCTIVE READ NO WAIT
Command code = 5
NON DESTRUCTIVE READ NO WAIT - ES:BX -> +------------------------------------+ | 13-BYTE Request header | +------------------------------------+ | BYTE read from device | +------------------------------------+
This call lets MS-DOS look ahead one input character. Thedevice sets the done bit in the status word.
If the character device returns busy bit = 0, characters arein the buffer and the next character that would be read isreturned. This character is not removed from the input ___buffer (hence the term "Non Destructive Read"). If thecharacter device returns busy bit = 1, there are nocharacters in the buffer.
2.7.6 OPEN or CLOSE
Command codes = 13 and 14
OPEN or CLOSE - ES:BX -> +------------------------------------+ | 13-BYTE Static request header | +------------------------------------+
These functions are called by MS-DOS 3.x only if the devicedriver sets the OPEN/CLOSE/RM attribute bit in the deviceheader. They are designed to inform the device about itscurrent file activity. On block devices, these functionscan manage local buffering, and the device can keep areference count.
Every OPEN causes the device to increment the count, everyCLOSE to decrement. When the count goes to zero no openfiles are on the device. Also, the device should flush anybuffers that it may have used in case the media has beenchanged.
Block devices can have problems with this mechanism becauseprograms that use FCB calls can open files without closing MS-DOS DEVICE DRIVERS Page 2-22
them. Therefore, when the media has been changed and theBUILD BPB call has been made to the device, you should resetthe count to zero without flushing the buffers.
These calls are more useful on character devices. Forexample, the device could use the OPEN call to send a deviceinitialization string. For example, this string might set aprinter's default characteristics for font and page size.Using IOCTL to set these pre- and post-strings provides aflexible mechanism of serial I/O device stream control. Adriver could also use the reference count mechanism todetect a simultaneous access error. You may not want toallow more than one OPEN on a device at any given time,since, in this case, a second OPEN would result in an error.
Note that since all processes have access to stdin, stdout,stderr, stdaux, and stdprn (handles 0,1,2,3,4), the CON,AUX, and PRN devices are always open. ______
2.7.7 REMOVABLE MEDIA
Command code = 15
REMOVABLE MEDIA - ES:BX -> +------------------------------------+ | 13-BYTE Static request header | +------------------------------------+
This function is called by MS-DOS 3.x only if the devicedriver sets the OPEN/CLOSE/RM attribute bit in the deviceheader. Only a subfunction of the IOCTL system call canissue this call to block devices. Sometimes it is necessaryfor a utility to know whether it is using a non-removablemedia drive (a hard disk), or a removable media drive (afloppy). For example, the FORMAT utility prints differentprompts depending on the media.
The information returns in the busy bit of the status word.If the busy bit is 1, the media is non-removable, and if thebusy bit is 0, the media is removable. Note that the devicedriver does not check the error bit; it just assumes thatthis call always succeeds.
MS-DOS DEVICE DRIVERS Page 2-232.7.8 STATUS
Command codes = 6 and 10
STATUS Calls ES:BX -> +------------------------------------+ | 13-BYTE request header | +------------------------------------+
This call returns information to the DOS to let it know ifdata is waiting for input or output. All the driver must dois set the status word and the busy bit as follows:
For output on character devices: If the driver ___ ______ __ _________ _______ sets bit 9 to 1 on return, it informs the DOS that a write request (if made) would wait for completion of a current request. If bit 9 is 0, there is no current request and a write request (if made) would start immediately.
For input on character devices with a buffer: If ___ _____ __ _________ _______ ____ _ ______ bit 9 equals 1 this implies that the buffer is empty and that a read request (if made) would go to the physical device. If bit 9 is 0 on return, characters are in the device buffer and a read request would start immediately. A return of 0 implies that you have typed something. MS-DOS assumes that all character devices have an input type-ahead buffer; devices that do not should always return busy = 0 so that the DOS does not wait for you to put something into a non-existent buffer.
2.7.9 FLUSH
Command codes = 7 and 11
FLUSH Calls - ES:BX -> +------------------------------------+ | 13-BYTE request header | +------------------------------------+
The FLUSH call tells the driver to flush (terminate) allpending requests. This call is used to flush the inputqueue on character devices. The device driver performs theflush function, sets the status word, and returns.
MS-DOS DEVICE DRIVERS Page 2-242.7.10 Generic IOCTL Request
Command code = 19
ES:BX --> +----------------------------------+ | 13-BYTE Static Request Header | +----------------------------------+ | BYTE Category (Major) Code | +----------------------------------+ | BYTE Function (Minor) Code | +----------------------------------+ | WORD (SI) contents | +----------------------------------+ | WORD (DI) contents | +----------------------------------+ | DWORD pointer to data buffer | +----------------------------------+
This function provides a generic, expandable IOCTL facilitythat replaces and makes the Read IOCTL and Write IOCTLdevice driver functions obsolete. The MS-DOS 2.0 IOCTLfunctions remain to support existing uses of the IOCTLsystem call (subfunctions 2, 3, 4 and 5), but new devicedrivers should use this generic MS-DOS IOCTL facility.
The generic IOCTL function contains both a category andfunction code. The DOS examines the category field in orderto intercept and obey device commands that are actuallyserviced by the DOS code; all other command categories areforwarded to the device driver for servicing.
For more information on these category and function codes,refer to Functions 440CH (Generic IOCTL for handles) andFunction 440DH (Generic IOCTL for block devices) in Chapter1, "System Calls."
2.7.11 Get/Set Logical Drive Map
Command code = 23 (Get) or 24 (Set)
+-------------------------------------------+ | 13-byte Static Request Header | +-------------------------------------------+ | BYTE Input (unit code) | +-------------------------------------------+ | BYTE Output (last device referenced) | +-------------------------------------------+ | BYTE Command code | +-------------------------------------------+ | WORD Status | +-------------------------------------------+ | DWORD Reserved | +-------------------------------------------+
This function is only called by MS-DOS if the device driversets the DOS 3.2 attribute bit in the device header. Thecall is only issued to block devices by a subfunction of theIOCTL system call. The logical drive is passed in the UNITfield of the header to the device driver, which returns the MS-DOS DEVICE DRIVERS Page 2-25
current logical drive that is mapped on the physical drivein the UNIT field of the header.
2.8 MEDIA DESCRIPTOR BYTE
In MS-DOS, the media descriptor byte informs the DOS that adifferent type of media is present. The media descriptorbyte can be any value between 0 and FFH. It does not haveto be the same as the FAT ID byte. The FAT ID byte, whichis the first byte of the FAT, was used in MS-DOS 1.00 todistinguish between different types of disk media. Thisbyte may also be used under 2.x and 3.x disk device drivers.However, FAT ID bytes have significance only for blockdevice drivers where the NON FAT ID bit is not set (0).
Values of the media descriptor byte or the FAT ID byte haveno significance to MS-DOS. They are passed directly to thedevice driver so that programs can determine the media type.
2.9 FORMAT OF A MEDIA DESCRIPTOR TABLE
The MS-DOS file system uses a linked list of pointers (onefor each cluster or allocation unit) called the FileAllocation Table (FAT). Unused clusters are represented byzero and end-of-file by FFF (or FFFF on units with 16-bitFAT entries). No valid entry should ever point to a zeroentry, but if one does, the first FAT entry (which would bepointed to by a zero entry) should be reserved and set toend-of-chain. Eventually, several end-of-chain values canbe defined ([F]FF8-[F]FFF), and used to distinguishdifferent media types.
A preferrable technique is to write a complete mediadescriptor table in the boot sector and use it for mediaidentification. To ensure backward compatibility forsystems whose drivers do not set the NON FAT ID bit(including the IBM PC implementation), it is necessary towrite the FAT ID bytes during the FORMAT process.
In the future to allow more flexibile support for manydifferent disk formats, you should keep the informationrelating to the BPB for a particular media in the bootsector. Figure 2.3 shows the format of such a boot sector. MS-DOS DEVICE DRIVERS Page 2-26
+------------------------------------+ | 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 sectors per FAT | ---+------------------------------------+--- | WORD Sectors per track | +------------------------------------+ | WORD Number of heads | +------------------------------------+ | WORD Number of hidden sectors | +------------------------------------+ | WORD High order number of hidden | | sectors | +------------------------------------+ | DWORD Number of logical sectors | +------------------------------------+
Figure 2.3. Format of Boot Sector
Although MS-DOS does not use the five fields that follow theBPB, they may be used by a device driver to help itunderstand the media.
The "Sectors per track" and "Number of heads" fields areuseful for supporting different media which may have thesame logical layout, but a different physical layout (e.g.,40 track double-sided versus 80 track single-sided)."Sectors per track" tells the device driver how the logicaldisk format is laid out on the physical disk.
The "Number of hidden sectors" and the "High order number ofhidden sectors" fields may be used to suportdrive-partitioning schemes.
The "Number of logical sectors" field is not currently usedbut will tell the device driver how many sectors to reserveif the "Number of sectors in logical image" field is zero. MS-DOS DEVICE DRIVERS Page 2-27
(This is intended for supporting drives that access morethan 32 megabytes.)
NON FAT ID format drivers should use the following procedureto determine media type:
1. Read the boot sector of the drive into the 1-sector scratch space pointed to by the DWORD Transfer address.
2. Determine whether the first byte of the boot sector is either E9H (the first byte of a 3-byte NEAR or 2-byte short jump) or EBH (the first byte of a 2-byte jump followed by a NOP). If it is, return a pointer to a BPB beginning at offset 3.
3. If the boot sector does not have a BPB table, it is probably a disk formatted under a 1.x version of MS-DOS. Therefore, it probably uses a FAT ID byte for determining media.
As an option, the driver may attempt to read the first sector of the FAT into the 1-sector scratch space and then read the first byte to determine the media type. Return a pointer to a hard-coded BPB.
2.10 THE CLOCK DEVICE
MS-DOS assumes that some sort of clock is available in thesystem. This clock may be either a CMOS real-time clock oran interval timer which the user initializes at boot time.The CLOCK device defines and performs functions like anyother character device except that the DOS identifies it bya bit in the attribute word. Consequently this device maytake any name. The IBM version uses "$CLOCK" to avoidconflict with existing files named "CLOCK."
The CLOCK device is unique because MS-DOS reads or writes a6-byte sequence that encodes the date and time. A write tothis device sets the date and time, and a read gets the dateand time.
Figure 2.4 illustrates the binary time format which theCLOCK device uses:
MS-DOS DEVICE DRIVERS Page 2-28
byte 0 byte 1 byte 2 byte 3 byte 4 byte 5+--------+--------+---------+--------+--------+---------+| | | | | | ||days since 1-1-80| minutes | hours | sec/100| seconds ||low byte|hi byte | | | | |+--------+--------+---------+--------+--------+---------+
Figure 2.4. CLOCK Device Format
2.11 ANATOMY OF A DEVICE CALL
The following steps illustrate what happens when MS-DOScalls on a block device driver to perform a WRITE request:
1. MS-DOS writes a request packet in a reserved area of memory.
2. It then calls the block device driver strategy entry point.
3. The device driver saves the ES and BX registers (ES:BX points to the request packet) and does a FAR return.
4. MS-DOS calls the interrupt entry point.
5. The device driver retrieves the pointer to the request packet and reads the command code (offset 2) to determine that this is a write request. The device driver converts the command code for an index into a dispatch table and passes control to the disk write routine.
6. The device driver reads the unit code (offset 1) to determine which disk drive it should write to.
7. Since the command is a disk write, the device driver must get the transfer address (offset 14), the sector count (offset 18), and the start sector (offset 20) in the request packet.
8. The device driver translates the first logical sector number into a track, head, and sector number.
MS-DOS DEVICE DRIVERS Page 2-29
9. The device driver writes the specified number of sectors, starting at the beginning sector on the drive defined by the unit code (the subunit defined by this device driver), and transfers data from the address indicated in the request packet. Note that this may involve multiple write commands to the disk controller.
10. After the transfer is complete, the device driver must report the status of the request to MS-DOS by setting the done bit in the status word (offset 3 in the request packet). It reports the number of sectors actually transferred in the sector count area of the request packet.
11. If an error occurs, the driver sets the done bit and the error bit in the status word and fills in the error code in the lower half of the status word. The number of sectors actually transferred must be written in the request header. It is not sufficient just to set the error bit of the status word.
12. Finally, the device driver does a FAR return to MS-DOS.
The device drivers should preserve the state of MS-DOS,including all registers (and flags). In particular, thedirection flag and interrupt enable bits are critical. Whenthe interrupt entry point in the device driver is called,MS-DOS has room for about 40 to 50 bytes on its internalstack. Your device driver should switch to a local stack ifit uses extensive stack operations. APPENDIX E MSDOS 2.25 Device Driver Interface Extension.
MSDOS 2.25 is designed so as to be able to run with CONSOLE DEVICE DRIVERS FROM PREVIOUS VERSIONS. If this is the case then no interim character processing can be done, and all character composition must be handled directly by the console device driver. The MSDOS 2.25 BIOS interface (IO.SYS) has the following differences from the standard MSDOS 2.11 BIOS. These changes are extensions to the CON (Console) Device driver for hardware which will be utilizing Interim Character support. Consult the MSDOS Adapatation Guide for overall description of device driver design and funtionality 1) On the INPUT and NON-DESTRUCTIVE INPUT calls to the device driver (DD) the DD must check bit 0 of the byte at offset 14 in the request packet. If the bit is 0 then it should return only final characters, if the bit is 1 then the device driver should return interim as well as final characters to the dos. Also on INPUT, if the request is for more than ONE byte then the DD should return ONLY final characters, no matter what the state of bit 0 in the byte at offset 14. 2) On return from INPUT, NON-DESTRUCTIVE INPUT and INPUT STATUS calls, the device driver should return to the dos with bit 10 of the status word SET if the character read, or the character available is an interim character, or the bit RESET if the character is a final character. (Pre 2.25 DD's always return with this bit reset). If more than one character is read on an INPUT call then bit 10 should be RESET as all the characters returned should be final characters (see above). 3) On Console WRITE function the device driver should check bit 0 of the byte at offset 14 in the request packet. If the bit is reset then the character should be output as a regular character by printing the character and advancing the cursor to the next position. If the bit is SET then the character is an interim character and should be treated by the device driver display routine accordingly. In most cases the character should be displayed without advancing the cursor to the next character position. When using interim 16 bit characters that are output a byte at a time, then the routine should handle this correctly, displaying the 16 bit interim and not advancing the cursor to the next character position. Special considerations / requirements. If a console device driver is going to return interim characters then the device driver MUST be able to handle the extension made to character WRITE (described above in 3).
Device drivers should be able to support requests for final / interim characters in any order. Application programs may at any time change the way they want characters, and device drivers should be capable of changing without any other indication than the DD request itself. Device drivers should be capable of handling composition somehow for those applications that do not do it themselves. The keyboard typeahead buffer should be kept at the key level, without further interpretation. All processing of interims in case of an input request for a final character is issued (and there are interims in the buffer that have to be composed to obtain a final character), should be done at the time the request is done to the device driver.
Sample Device Driver for DOS 2.25 Interim Character SupportWARNING!! Not Assembleable. This code must be modified forthe OEM's own hardware and firmware.
PAGE
CODE SEGMENT BYTE
ASSUME CS:CODE,DS:NOTHING,ES:NOTHING;----------------------------------------------------------------;; C O N - CONSOLE DEVICE DRIVER; DW -1,-1 DW 1000000000010011B ; CON IN AND CON OUT + Special bit DW STRATEGY DW ENTRY DB 'CON '
InterH db 0 ; Interim character flagALTAH DB 0 ; Special key handling
;----------------------------------------------------------------;; COMMAND JUMP TABLESCONTBL: DW CON$INIT DW EXIT DW EXIT DW CMDERR DW CON$READ DW CON$RDND DW EXIT DW CON$FLSH DW CON$WRIT DW CON$WRIT DW EXIT DW EXIT
PAGE;----------------------------------------------------------------;; Device entry point;CMDLEN = 0 ;LENGTH OF THIS COMMANDUNIT = 1 ;SUB UNIT SPECIFIERCMD = 2 ;COMMAND CODESTATUS = 3 ;STATUSMEDIA = 13 ;MEDIA DESCRIPTORTRANS = 14 ;TRANSFER ADDRESSCOUNT = 18 ;COUNT OF BLOCKS OR CHARACTERSSTART = 20 ;FIRST BLOCK TO TRANSFER
BRKADR = Oem_Brk ; Break Vector AddressCHROUT = 29H ; fast con int
PAGE;----------------------------------------------------------------;; Entry Procedures;
PTRSAV DD 0
STRATP PROC FAR
STRATEGY: MOV WORD PTR CS:[PTRSAV],BX MOV WORD PTR CS:[PTRSAV+2],ES RET
STRATP ENDP
ENTRY: PUSH SI PUSH AX PUSH CX PUSH DX PUSH DI PUSH BP PUSH DS PUSH ES PUSH BX
LDS BX,CS:[PTRSAV] ; DS:BX points to IO packet
mov cx,word ptr ds:[bx].count ; CX = count mov dl,byte ptr ds:[bx].media ; DL = input type flag mov al,byte ptr ds:[bx].cmd ; AL = command code cbw MOV SI,OFFSET CONTBL ; command table ADD SI,AX ADD SI,AX CMP AL,11 JA CMDERR ; command code out of range
LES DI,DWORD PTR DS:[BX].TRANS ; transfer address PUSH CS POP DS ASSUME DS:CODE
JMP WORD PTR [SI] ; GO DO COMMAND
PAGE;----------------------------------------------------------------;; EXIT - ALL ROUTINES RETURN THROUGH THIS PATH;
CMDERR: MOV AL,3 ; Unknown Command ErrorERR$EXIT: mov ah,10000001b ; Mark Error Return jmp short err1
BUS$EXIT: mov ah,00000011b ; Device Busy Exit jmp short err1
HanExit: mov [InterH],0 ; reset interim flag mov ah,00000101b ; Bit 10 Set for interim chars jmp short err1
EXITP PROC FAR
EXIT: MOV AH,00000001BERR1: LDS BX,CS:[PTRSAV] MOV WORD PTR [BX].STATUS,AX ; Mark Operation Complete
POP BX POP ES POP DS POP BP POP DI POP DX POP CX POP AX POP SI RET ; RESTORE REGS AND RETURNEXITP ENDP
PAGE;----------------------------------------------------------------;; BREAK KEY HANDLING;BREAK: MOV CS:ALTAH,3 ; INDICATE BREAK KEY SET IRET
;----------------------------------------------------------------;; CHROUT - WRITE OUT CHAR IN AL USING CURRENT ATTRIBUTE;; CALLED VIA INT 29H;
OUTCHR: INT OEM_Char_Output RET
PAGE;----------------------------------------------------------------;; INPUT SINGLE CHAR INTO AL;
ChrIn: xor ax,ax xchg al,ALTAH ; Get Character & Zero ALTAH or al,al jnz sj3 mov ah,Request_Interim ; assume interim char input or dl,dl ; Interim chars wanted? jnz sj0 mov ah,Request_Char ; regular whole char inputsj0: int OEM_Kybd_Input ; Get character or ax,ax ; Check for non-key after BREAK jz ChrIn or al,al ; Special Case? jnz ChkInter mov ALTAH,ah ; Save Special Keysj3: mov [InterH],0 ; reset interim flag ret
ChkInter: cmp ah,Hangeul_Interim ; a Hangeul interim? jne sj3 mov [InterH],1 ; yes flag it ret
PAGE;----------------------------------------------------------------;; CONSOLE READ ROUTINE;; Input:; CX = transfer count; DL = input type flag (0 = whole chars, 1 = interim allowed); ES:DI = transfer addess;
CON$READ: JCXZ CON$EXITCON$LOOP: CALL CHRIN ; GET CHAR IN AL STOSB ; STORE CHAR AT ES:DI LOOP CON$LOOPCON$EXIT: cmp [InterH],1 ; An Intermidiate Char? jne ExVec ; no, regulear exit JMP HanExit ; yes, reset flag and exit new way
PAGE;----------------------------------------------------------------;; KEYBOARD FLUSH ROUTINE;
CON$FLSH: MOV [ALTAH],0 ; Clear out holding buffer mov [InterH],0 mov ah,Flush_Buffer int OEM_Kybd_Input JMP EXIT
PAGE;----------------------------------------------------------------;; KEYBOARD NON DESTRUCTIVE READ, NO WAIT; Input:; DL = input type flag (0 = whole chars, 1 = interim allowed);
EXVEC: JMP EXITCONBUS: JMP BUS$EXIT
CON$RDND: MOV AL,[ALTAH] OR AL,AL JNZ sj6 MOV AH,Request_Interim_Status ;Assume interim allowed or dl,dl ; check interim flag jnz sj4 mov ah,Requst_Std_Status ; regular status wantedsj4: INT OEM_Kybd_Input ; Get status JZ CONBUS OR AX,AX JNZ sj6 ; CHECK FOR NULL AFTER BREAK MOV AH,Request_Char INT OEM_Kybd_Input ; READ THE NULL JMP short CON$RDND ; AND GET A REAL STATUSsj6: MOV [InterH],0 ; not interimsj7: LDS BX,[PTRSAV] MOV [BX].MEDIA,AL ; return the char to dos cmp [InterH],0 je EXVEC jmp HanExitsj8: cmp ah,Interim_Char ; a Hangeul interim? jne sj6 mov [InterH],1 jmp short sj7
PAGE;----------------------------------------------------------------;; CONSOLE WRITE ROUTINE;
CON$WRIT: JCXZ EXVEC cmp dl,01h ; write and not ad cursor? je CON$LP2CON$LP: MOV AL,ES:[DI] ; GET CHAR INC DI MOV AH,Output_Char INT CHROUT ; OUTPUT CHAR LOOP CON$LP ; REPEAT UNTIL ALL THROUGH JMP EXIT
CON$LP2: ; write but do not advance cursor MOV AL,ES:[DI] ; GET CHAR INC DI MOV AH,Output_No_Advance INT CHROUT LOOP CON$LP2 ; REPEAT UNTIL ALL THROUGH JMP EXIT
PAGE;----------------------------------------------------------------;; Initialization Code;
CON$INIT: XOR BX,BX MOV DS,BX MOV BX,BRKADR MOV WORD PTR [BX],OFFSET BREAK MOV WORD PTR [BX+2],CS
MOV BX,CHROUT*4 MOV WORD PTR [BX],OFFSET OUTCHR MOV WORD PTR [BX+2],CS
LDS BX,CS:[PTRSAV] MOV WORD PTR [BX].TRANS,OFFSET CON$INIT ; SET BREAK ADDRESS MOV [BX].TRANS+2,CS JMP EXIT
CODE ENDS END
APPENDIX F
MSDOS 2.25 Application Level Interface Extension
1) System call 63H, get_lead_tbl. This call takes an argument in register AL. This argument determines what function will this call execute. Valid values for the function code are 0, 1 and 2. If AL = 0, then the call returns in DS:SI a pointer to a table containing the lead byte ranges for the 16 bit alphabet in question. The table consists of byte pairs that are the boundaries for the lead bytes (both values inclusive). The end of the table is marked by two zero byte entries. Example, for japanese kanji the table would look like db 81H,9FH db 0E0h,0FCh db 0,0 Note that the values should be read as byte values not as word values since otherwise the ranges would be transposed due to the byte ordering in the 8086/88. This table is empty in the regular version of the dos (as there are no 16 bit characters). The table if obtained would point to a pair of zero bytes. If AL = 1 then the call will set (or reset) the interim console flag in the dos depending on the value in DL. If DL = 1, then the interim flag will be SET, and certain console system calls will return interim characters if these are available. If DL = 0 then the interim flag is RESET and only final characters will be returned. The default value of the flag is RESET. All application programs start with the flag RESET. The flag is allways restored to the parents setting when an application terminates. If AL = 2 then the dos will return in DL the current value of the console interim flag (0 if RESET, 1 if SET). If an invalid code is used the call will reurn with carry set and error code 0 (error_invalid_function). IMPORTANT NOTE: This system call unlike all other system calls make NO GUARANTEE to preserve ANY registers other than SS:SP upon return. So care should be taken to save all relevant registers before issuing the call. It is advisable that an application either copy the table to its
private data area or save the pointer to the table at initialization time. This should save considerable execution time as there is no need to reissue the call everytime a check for 16 bit characters is necessary, and consequently there is no need to save any registers before issuing the call. 2) Console i/o system calls. Some console i/o system calls are capable of returning interim character information to application programs. Only those applications that have enabled the feature through the 63H call (function 1) will receive interim characters on these system calls, otherwise the dos will never return interim characters and the system calls will work as in previous versions of 2.00. * Call 01H, Read & Echo. This call never returns interim characters no matter what mode the console is on. Composition if any will take place at the cursor. It will return when the first byte of the final character is obtained. * Call 06H, Direct Console i/o. Always returns final characters, never interims. Only returns character available when a final character is available, not when interims are available. Composition if any is handled as in call 01H. * Call 07H, Direct Console Input. Returns interim characters if one is available and the console mode has been set to interim through the 63H call. Interim characters are returned with the zero flag SET, final characters have the flag RESET. In non interim support (the default) the zero flag value is undefined. * Call 08H, Read Keyboard. Same as system call 07H. * Call 0AH, Buffered Keyboard input. Always returns a string of final characters, composition if any, is handled by the dos. * Call 0BH, Check Keyboard Status. This call supports interim characters if the console has been placed in interim mode through the ioctl call. If a character is available (AL = 0FFH) then the zero flag will
be SET if the character is an interim, or RESET if the character is a final character. The zero flag is undefined if either there is no character available, or the console is not in interim mode. * Call 0CH, Flush Buffer, Read Keyboard. This call will flush the type-ahead buffer and execute the specified console i/o call. The con i/o call will work as described above for each specific case. * Call 3FH, Xenix Read. This call always returns final characters, no matter what the state of the dos. This call when directed to the console it ends up in the buffered console input code, and so it will act as that call (0AH) when used to read from the console.
APPENDIX G
This file is part of what was formerly supplied with MS-DOS 2.11as SPECIAL.DOC. It has information about undocumented COMMAND.COMswitches and the version dependent system call (GET_DPB) whichOEM's may use when writing format.
The remaining portions of this file have been incorporated intoprinted MS-DOS documentation.
COMMAND invocation
COMMAND [[<drive>:]<path>] [<cttydev>] [/D] [/P] [/C <string>] [/E:nnnn]
/P If present COMMAND will be permanent, otherwise this is a transient command.
/D If present COMMAND will not prompt for DATE and TIME when it comes up.
d: Specifies device where command will look for COMMAND.COM current default drive if absent.
<Path> Specifies a directory on device d: root directory if absent.
<cttydev> Name of the CTTY device. \DEV\CON if absent and command is permanent. The \DEV\ may be left off if AVAILDEV is TRUE (see sysinit doc).
/C <string> If present /C must be the last switch. This causes COMMAND to try to execute the string as if the user had typed it at the standard input. COMMAND executes this single command string and then exits. If the /P switch is present it is ignored (can't have a single command, permanent COMMAND). NOTE: ALL of the text on the command line after the /C is just passed on. It is not processed for more arguments, this is why /C must be last.
/E:nnnn Set the environment size to nnnn (specified in decimal bytes). The environment size can be between 128 bytes and 32768 bytes. NOTE: This feature is only available in versions of MS-DOS starting with 3.20.
GET_DPB UNDOCUMENTED SYSTEM CALL. THIS CALL MAY BE USEDTO GET A POINTER TO THE PHYSICAL LOCATION OF THE DISK DEVICEDRIVER. CONSULT THE DBP STRUCTURE DOCUMENTED IN DOSSYM.ASM
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+| C A V E A T P R O G R A M M E R || |
Name: * GET_DPB - get pointer to drive parameter block
Assembler usage: MOV AH,GET_DPB INT 21h ; DS:BX has address of drive parameter block
Description: Return pointer to default drive parameter block.
Error returns: None.
Assembler usage: MOV DL,DrvNUM MOV AH,32H INT 21h ; DS:BX has address of drive parameter block
Description: Return pointer to drive parameter block for drive designated in DL (0=Default, A=1, B=2 ...)
Error returns: AL = FF The drive given in DL is invalid.| || C A V E A T P R O G R A M M E R |+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
APPENDIX H
This material was taken from the MS-DOS 3.10 Programmer's ReferenceManual. It is intended be used with the MS-DOS 2.XX/3.XX AdaptationGuide.
7.1 INTRODUCTION
This chapter describes recommended MS-DOS 3.1 programmingprocedures. By using these programming hints, you canensure compatibility with future versions of MS-DOS.
The hints are organized into the following categories:
Interrupts
System Calls
Device Management
Memory Management
Process Management
File and Directory Management
Miscellaneous
7.2 INTERRUPTS
Never explicitly issue Interrupt 22H (Terminate Process ExitAddress).
This should only be done by the DOS. To change the terminate address, use Function 35H (Get Interrupt Vector) to get the current address and save it, then use Function 25H (Set Interrupt Vector) to change the Interrupt 22H entry in the vector table to point to the new terminate address. PROGRAMMING HINTS Page 7-2
Use Interrupt 24H (Critical Error Handler Address) withcare.
The Interrupt 24H handler must preserve the ES register.
Only system calls 01H-0CH can be made by an Interrupt 24H handler. Making any other calls will destroy the MS-DOS stack and prevent successful use of the Retry or Ignore options.
The registers SS, SP, DS, BX, CX, and DX must be preserved when using the Retry or Ignore options.
When an Interrupt 24H (Critical Error Handler Address) isreceived, always IRET back to MS-DOS with one of thestandard responses.
Programs that do not IRET from Interrupt 24H leave the system in an unpredictable state until a function call other than 01H-0CH is made. The Ignore option may leave data in internal system buffers that is incorrect or invalid.
Avoid trapping Interrupt 23H (Control-C Handler Address) andInterrupt 24H (Critical Error Handler Address). Don't relyon trapping errors via Interrupt 24H as part of a copyprotection scheme.
These might not be included in future releases of the operating system.
Interrupt 23H (Control-C Handler Address) must never beissued by a user program.
Interrupt 23H must be issued only by MS-DOS.
Save any registers your program uses before issuingInterrupt 25H (Absolute Disk Read) or Interrupt 26H(Absolute Disk Write).
These interrupts destroy all registers except for the segment registers.
Avoid writing or reading an interrupt vector directly to or from memory.
Use Functions 25H and 35H (Set Interrupt Vector and GetInterrupt Vector) to set and get values in the interrupttable.
PROGRAMMING HINTS Page 7-3
7.3 SYSTEM CALLS
Use new system calls.
Avoid using system calls that have been superseded by new calls unless a program must maintain backward ____ compatibility with pre-2.0 versions of MS-DOS. See Section 1.8, "Old System Calls," of this manual for a list of these new calls.
Avoid using system calls 01H-0CH and 26H (Create New PSP).
Use the new "tools" approach for reading and writing on standard input and output. Use Function 4B00H (Load and Execute Program) instead of 26H to execute a child process.
Use file-sharing calls if more than one process is ineffect.
See "File Sharing," in Section 1.5.2, "File-Related Function Requests" in Chapter 1 for more information.
Use networking calls where appropriate.
Some forms of IOCTL can only be used with Microsoft Networks. See Section 1.6, "Microsoft Networks," in this manual for a list of these calls.
When selecting a disk with Function 0EH (Select Disk), treatthe value returned in AL with care.
The value in AL specifies the maximum number of logical drives; it does not specify which drives are valid.
7.4 DEVICE MANAGEMENT
Use installable device drivers.
MS-DOS provides a modular device driver structure for the BIOS, allowing you to configure and install device drivers at boot time. Block device drivers transmit a block of data at a time, while character device drivers transmit a byte of data at a time.
Examples of both types of device drivers are given in Chapter 2, "MS-DOS Device Drivers." PROGRAMMING HINTS Page 7-4
Use buffered I/O.
The device drivers can handle streams of data up to 64K. When sending a large amount of output to the screen, you can send it with one system call. This will increase performance.
Programs that use direct console I/O via Function 06H and07H (Direct Console I/O and Direct Console Input) and thatwant to read Control-C as data should ensure that Control-Cchecking is off.
The program should ensure that Control-C checking is off by using Function 33H (Control-C Check).
Be compatible with international support.
To provide support for international character sets, MS-DOS recognizes all possible byte values as significant characters in filenames and data streams. Pre-2.x versions ignored the high bit in the MS-DOS filename.
7.5 MEMORY MANAGEMENT
Use memory management.
MS-DOS keeps track of allocated memory by writing a memory control block at the beginning of each area of memory. Programs should use Functions 48H (Allocate Memory), 49H (Free Allocated Memory), and 4AH (Set Block) to release unneeded memory.
This will allow for future compatibility.
See Section 1.3, "Memory Management," for more information.
Only use allocated memory.
Don't directly access memory that was not provided as a result of a system call. Do not use fixed addressing, use only relative references.
A program that uses memory that has not been allocated to it may destroy other memory control blocks or cause other applications to fail.
PROGRAMMING HINTS Page 7-5
7.6 PROCESS MANAGEMENT
Use the EXEC Function Call to load and execute programs.
The EXEC Function (4B00H) is the preferred way to load programs and program overlays. Using the EXEC call instead of hard-coding information about how to load an .EXE file (or always assuming that your file is a .COM file) will isolate your program from changes in future releases of MS-DOS and .EXE file formats.
Use Function 31H (Keep Process), instead of Interrupt 27H(Terminate But Stay Resident). Function 31H allows programsto terminate and stay resident that are greater than 64K.
Programs should terminate using End Process (4CH).
Programs that terminate by - a long jump to offset 0 in the PSP, - issuing an Interrupt 20H with CS:0 pointing at the PSP, - issuing an Interrupt 21H with AH=0, CS:0 pointing at the PSP, or - a long call to location 50H in the PSP with AH=0
must ensure that the CS register contains the segmentaddress of the PSP.
7.7 FILE AND DIRECTORY MANAGEMENT
Use the MS-DOS file management system.
Using the MS-DOS file system will ensure program compatibility with future MS-DOS versions through compatible disk formats and consistent internal storage. This will ensure compatibility with future MS-DOS versions.
Use file handles instead of FCBs.
A handle is a 16-bit number that is returned by MS-DOS when a file is opened or created using Functions 3CH, 3DH, 5AH, or 5BH (Create Handle, Open Handle, Create Temporary File, or Create New File). The MS-DOS file-related function requests that use handles are listed in Table 1.5 in Chapter 1, "System Calls."
These calls should be used instead of the old file-related functions that use FCBs (file control blocks). This is because a file operation can simply pass its handle rather than having to PROGRAMMING HINTS Page 7-6
maintain FCB information. If FCBs must be used, be sure the program closes them and does not move them around in memory.
Close all files that have changed in length before issuingan Interrupt 20H (Program Terminate), Function 00H(Terminate Program), Function 4CH (End Process), or Function0DH (Reset Disk).
If a changed file is not closed, its length will not be recorded correctly in the directory.
Close all files when they are no longer needed.
Closing unneeded files will optimize performance in a networking environment.
Only change disks if all files on the disk are closed.
Information in internal system buffers may be written incorrectly to a changed disk.
7.7.1 Locking Files
Programs should not rely on being denied access to a lockedregion.
Determine the status of the region by attempting to lock it, and examine the error code.
Programs should not close a file with a locked region orterminate with an open file that contains a locked region.
The result is undefined. Programs that might be terminated by an Interrupt 23H or Interrupt 24H (Control-C Handler Address or Critical Error Handler Address) should trap these interrupts and unlock any locked regions before exiting.
7.8 MISCELLANEOUS
Avoid timing dependencies.
Various machines use CPUs of different speeds. Also, programs that rely upon the speed of the clock for timing will not be dependable in a networking environment. PROGRAMMING HINTS Page 7-7
Use the documented interface to the operating system. Ifeither the hardware or media change, the operating systemwill be able to use the features without modification.
Don't use the OEM (Original Equipment Manufacturer) -provided ROM support.
Don't directly address the video memory.
Don't use undocumented function calls, interrupts, or features. These items may change or not continue to exist in future versions of MS-DOS. Use of these features would make your program highly non-portable.
Use the .EXE format rather than the .COM format.
.EXE files are relocatable and .COM files are direct memory images that load at a specific place and have no room for additional control information to be placed in them. .EXE files have headers that can be expanded for compatibility with future versions of MS-DOS.
Use the environment to pass information to applications.
The environment allows a parent process to pass information to a child process. COMMAND.COM is usually the parent process to every application, so default drive and path information can easily be passed to the application.
GLOSSARY OF MS-DOS TERMS
Allocation Unit
(See Cluster)
Arena
MS-DOS uses a software memory management scheme. Blocks in memory are either owned by processes or are free. An owned block has an ID number, which is the initial paragraph of the Program Segment GLOSSARY OF MS-DOS TERMS
Prefix of a process in memory (your program). Each block has a size as well. When your process is in memory, there is a 16-byte arena block which identifies it and specifies how much memory is allocated.
ASCIZ
Any null (zero byte) terminated ASCII string.
Cluster
The storage unit that MS-DOS uses to allocate space for files on a disk. All files are allocated in multiples of clusters. A cluster must be a power of two sectors (i.e., 1, 2, 4, 8 ... ). This term is synonymous with allocation unit. Block device drivers perform I/O in sectors, not clusters.
Cooked/Raw Mode
Character devices have two modes that have significance when performing I/O via the Read Handle and Write Handle calls (Functions 3FH and 40H). These are "raw" and "cooked" mode. A device driver can be set to raw mode via the IOCTL Function Request 44H.
Cooked mode input is buffered input with echoing to the screen (if console) and Control-C checking. Cooked mode input of a certain number of characters will return when the specified number of characters is returned or a carriage return is typed. Cooked mode output performs Control-C checking between characters.
Raw mode I/O is very fast. When raw mode I/O of "n" characters is requested, MS-DOS passes the request directly to the indicated device driver. The device driver does not return to MS-DOS until the I/O has completed. Characters are written or read directly from the process buffer. No checking of any kind is performed. No characters have any significance, including Control-C.
GLOSSARY OF MS-DOS TERMS
For example, if the requesting program puts a device in raw mode and requests a write of 50,000 characters to the AUX device, the device driver will get a request from MS-DOS to write 50,000 characters from the buffer located at the DWORD transfer address. The driver will not return until the request has completed.
In cooked mode, MS-DOS performs a Control-C check at the console after each single character write. This is an overhead of 50,000 Control-C checks.
Environment
The environment is a maximum of 32K data area which consists of ASCIZ strings of the form: AAAA=BBBBBBB. The end of the environment is marked by two consecutive nulls. The word at 2CH in the Program Segment Prefix points to the segment containing the start of a program's environment. New variables can be added to the environment by using the MS-DOS Set command. Since nulls have significance, the environment cannot be used for storing binary data.
When a parent process (such as COMMAND.COM) executes a child process (any other program), the child is given a copy of the parent's environment. Parameters such as Prompt, which specifies the style of prompt used by COMMAND.COM, are stored in the environment. Application programs can use the environment to find overlays or special files which may not be located in the current directory. COMMAND.COM uses this technique to examine the elements of the Path looking for binaries and batch files. Of course the application program must be specifically coded to find the environment and parse it for variables.
FATID Byte
The FATID byte is the first byte of the File Allocation Table that starts at the sector immediately after the reserved sectors of the disk. The FATID byte was used by OEMs in MS-DOS 1.x for identification of disk media. This byte should be between F8H and FFH. To read MS-DOS 1.x disks, one must read this byte, determine which of the four predefined FATID bytes is present and return a pointer to the appropriate BPB. This method of GLOSSARY OF MS-DOS TERMS
determining media is less general and less desirable than the BPB table method (see MEDIA ID Byte).
File Handle
In versions of MS-DOS that are 2.0 and higher, there is a system file table set up at boot time. By the time COMMAND.COM gets control, all of the character devices have been entered into the system file table. The first five handles are initialized as follows.
HANDLE XENIX NAME DEFAULT SETTING
0 Standard Input CON 1 Standard Output CON 2 Standard Error CON 3 Standard AUX AUX 4 Standard PRN PRN
As new files are opened via XENIX-compatible calls, they are assigned the first available numbers. When COMMAND.COM executes a program, the child process inherits all of the handles that COMMAND.COM has open. Typing
prog < infyle > outfyle
on the command line means that you want PROG to read its input from INFYLE and write its output to OUTFYLE instead of to console out. COMMAND.COM will close handle 0 and open INFYLE; it will DUP handle 0. It will then close handle 1, standard out, and open OUTFYLE (which is assigned to standard out). COMMAND will exec PROG, which inherits this environment. When PROG reads from standard in, or writes to standard out, it reads from and writes to INFYLE and OUTFYLE, respectively.
If a child is executed, it inherits the files of its parent. The converse is not true. When a child process which opens AUX as standard in and PRN as standard out returns, the parent does not ___ inherit the files of its child.
GLOSSARY OF MS-DOS TERMS
MEDIA ID Byte
The MEDIA ID byte is the byte in the Bios Parameter Block (BPB) located at offset 0AH. The MEDIA ID byte may have any value between 0 and 0FFH. It may or may not have the same value as the FATID byte. The major significance of the MEDIA ID byte is that there be a one-to-one relationship between unique MEDIA ID bytes and disk formats. For disk compatibility with other OEMs as well as with future releases of MS-DOS, Microsoft recommends that the BPB table be located at offset 0BH in the first reserved (boot) sector. OEMs may register their media byte/format combinations with OEM Customer Support. The BPB technique of determining disk format is much more general than the limited FATID byte method and is the preferred method.
The significance of the media byte and FATID byte depends on whether you have decided to make your block device driver IBM format-compatible. You must indicate this by setting bit 13 in the device driver header. This will alter the way MS-DOS performs the GET BPB device call. With the NON FATID bit set, you can support various media, including IBM format media. If the device driver is IBM-format compatible, use FATID bytes to determine the media in the drive. The correspondence between FATID bytes and various media is defined in the MS-DOS Programmer's ______ ____________ Reference Manual. _________ ______
If your system is not IBM Format-compatible, you are given a pointer to a one-sector scratch buffer when your block device gets called by MS-DOS to do a BUILD BPB. Follow these steps:
1. Read the boot sector of the disk into that buffer and check the first byte. If it is an E9H, it is the first byte of a 3-byte JMP and there is a BIOS Parameter Block table in the boot sector.
Alternately, EBH may be the first byte. This is also a 3-byte JMP (actually, a 2-byte JMP followed by a NOP). GLOSSARY OF MS-DOS TERMS
2. Return a pointer to the BPB. Set the status word and return. If the first byte of the boot sector is not an E9H, then there is not a BPB table in the boot sector. You can assume that the disk is an IBM format disk and the FAT begins with the second sector of the disk. Read the FAT into the scratch buffer and check the first byte. Determine which one of the four defined FATID bytes it is, and return a pointer to the appropriate BPB.
Refer to the MS-DOS Programmer's Reference ______ ____________ _________ Manual for a list of valid FATID bytes. Any ______ other media should be defined in the boot sector and should use a FATID byte of FFH.
Paragraph
Any location in the memory of the 8086 which has an address that is a multiple of 16 (i.e., 0, 16, 32).
|
