1 Tuesday, May 06, 1997 Writing OS/2 Warp Device Drivers in C Third Edition 2 Disclaimer This book and software are provided -as is.' The implied warranties of merchantability and fitness for a particular purpose are expressly disclaimed. This book and software may contain programs that are furnished as examples. These examples have not been thoroughly tested under all conditions. Therefore, the reliability, serviceability, or function of any program or program code herein is not guaranteed. The information presented in this book was valid at the time it was written and was conveyed as accurately as possible by the author. However, some information may be incorrect or may have changed prior to publication. The author makes no claims that the material contained in this book is entirely correct, and assumes no liability for use of the material contained herein. 3 Trademarks and Copyrights IBM, AT, OS/2, Personal System/2, PS/2, and Micro Channel are registered trademarks of the International Business Machines Corporation. C/2, XT, and Presentation Manager are trademarks of International Business Machines Corporation. Intel is a registered trademark of the Intel Corporation. Lotus 1-2-3 is a registered trademark of Lotus Development Corporation. MS-DOS, CodeView and Microsoft are registered trademarks of Microsoft Corporation. Microsoft and Microsoft Windows are registered trademarks of Microsoft Corporation. UNIX is a registered trademark of AT&T Bell Laboratories. Copyright 1993 by Van Nostrand Reinhold Library of Congress Catalog Card Number 93-2264 ISBN 0-442-01729-4 All rights reserved. No part of this work covered by the copyright hereon may be reproduced or used in any form or by any means-graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems-without written permission of the publisher. Van Nostrand Reinhold is an International Thomson Publishing company. ITP logo is a trademark under license. Printed in the United States of America Van Nostrand Reinhold International Thomson Publishing GmbH 115 Fifth Avenue KÜnigswinteror Str. 518 New York, NY 10003 5300 Bonn 3 International Thomson Publishing International Thomson Publishing Asia Berkshire House, 168-=173 38 Kim Tian Road, #0105 High Holborn, London WC1V 7AA Kim Tian Plaza England Singapore 0316 Thomas Nelson Australia International Thomson Publishing Japan 102 Dodds Street South Melbourne 3205 2-2-1 Hirakawacho Victoria, Australia Chiyada-Ku, Tokyo 102 Nelson Canada 1120 Birchmount Road Scarborough, Ontario M1K 5G4, Canada 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 Library of Congress Cataloging-in-Publication Data Mastrianni, Steven J., 1951- Writing OS/2 2.x Device Drivers in C / Steven J. Mastrianni. - 3rd ed. p. cm. -- (VNR's OS/2 series) Includes index. ISBN 0-442-01229-4 1. OS/2 device drivers (Computer programs) 2. OS/2 (Computer file) 3. C (Computer program language) I. Title. II. Series. QA76.76.D49M371993 005.4'3--dc20 93-2264 CIP 4 Dedication This book is dedicated to Bernard Engelson, who passed away on June 8, 1994. His knowledge, compassion and understanding were an inspiration to everyone. He will be sorely missed. 5 Acknowledgments I would like to thank 7 Foreword 9 Table of Contents Writing OS/2 Warp Device Drivers in C.......................................................................1 Third Edition................................................................................................................1 Chapter 1 - The Evolution of PC Device Drivers ..........................................................33 Storage Devices................................................................................................34 Interface Adapter Cards....................................................................................35 The First Operating System For Personal Computers ........................................36 The First Bus....................................................................................................38 Chapter 2 - Understanding Device Drivers....................................................................41 Device Drivers Today.......................................................................................44 Device Drivers - A Summary ............................................................................46 Chapter 3 - The PC Hardware Architecture..................................................................49 The System Bus................................................................................................49 The IBM PC - Beginnings.................................................................................50 IBM PC XT......................................................................................................51 IBM PC AT......................................................................................................52 The AT Bus......................................................................................................53 The IBM PS/2 and Micro Channel....................................................................54 Enhanced Industry Standard Architecture (EISA) .............................................56 Bus Wars..........................................................................................................57 Real Mode........................................................................................................57 Protect Mode ...................................................................................................58 Using Addresses and Pointers ...........................................................................61 The Ring Architecture ......................................................................................61 Chapter 4 - An Overview of the OS/2 Operating System ..............................................65 Roots ...............................................................................................................66 Processes and Threads......................................................................................69 OS/2 1.0 - OS/2 Arrives ...................................................................................71 OS/2 1.1 - Presentation Manager Arrives..........................................................71 10 OS/2 1.2 - A Better File System........................................................................71 OS/2 1.3 – IBM’s First Solo Effort...................................................................73 OS/2 2.0- What OS/2 Was Really Meant to Be.................................................73 The OS/2 Application Programming Interface...................................................75 Chapter 5 - The Anatomy of an OS/2 Device Driver.....................................................77 Application-to-Driver Interface.........................................................................77 DOS Device Drivers and OS/2 Device Drivers..................................................78 Designing an OS/2 Device Driver .....................................................................79 Tools Necessary For Driver Development.........................................................79 The Basics of Driver Design .............................................................................80 Request Packets ...............................................................................................81 OS/2 Device Driver Architecture ......................................................................82 Device Driver Modes........................................................................................83 The Device Header...........................................................................................85 Capabilities Bit Strip.........................................................................................87 Providing a Low-Level Interface.......................................................................88 The Strategy Section ........................................................................................94 Initialization......................................................................................................96 A Common Strategy.........................................................................................98 Interrupt Section...............................................................................................99 The Timer Handler ...........................................................................................105 Context Hooks .................................................................................................106 Chapter 6 - Device Driver Strategy Commands ............................................................109 Summary of Device Driver Commands .............................................................112 0h / Init.............................................................................................................115 1H/ Media Check..............................................................................................120 2H / Build BPB ................................................................................................122 4H, 8H, 9H / Read or Write..............................................................................125 5H / Nondestructive Read No Wait...................................................................127 6H, AH / Input or Output Status.......................................................................128 7H,