Native Driver White Paper version 1.0 May 19, 1994 Holly Knight John Fitzgerald Mike Quinn Wayne Meretsky Overview This document proposes required interfaces and packaging for Communications drivers on PCI cards. At the time of this writing there are three different native device driver proposals for the Marconi project. Each proposal covers a separate but overlapping piece of the device driver puzzle for Marconi and future OS releases. The design presented here will cover two broad issues. The first goal is to regularize device driver writing so that PCI and non-PCI device drivers can be written to a single specification. The second equally important goal is to have device drivers written to this specification work for both the Marconi and Maxwell releases, as well as any future releases. Documentation for PCI devices may be found in the following documents: “Device Driver Development Kit” - ApplePC “The Macintosh Expansion Manager” - ApplePC Native Device Driver documents: “Device Manager Changes to Support Native Drivers.” - AppleSoft “Native Drivers for PCI and other Peripherals in Marconi” - AppleSoft “AppleSoft PCI Implementation Plan” - AppleSoft Open Transport/Streams documents: “PCI/DLPI - Open Transport Integration” - Open Transport “Open Transport Ethernet Developer Note” - Open Transport “Streams Modules and Drivers” - Unix Press In addition to providing general native device driver guidelines we use the native DLPI driver for Open Transport to provide implementation specifics. We hope to see this document become part of both a Device Driver Kit for PCI devices and an Open Transport Software Developers Kit. Terminology In this document we use a set of possibly unfamiliar terms. This list is provided to clarify discussions in subsequent sections. Family - This term refers to a collection of devices that provide the same kind of functionality. One example of a family is the set of Open Transport devices with their corresponding Open Transport DLPI drivers. A second example is the family of Display Devices. Scanning - I use the word scanning or scanner to describe code that matches a device with its corresponding driver. The scanning portion of device location is one of the problem areas discussed in this paper. Scanning is probably a sub-function of the family Expert. Expert - Expert is a term coined by Brenden Creane to describe family code that extracts appropriate information from the system (ROM, Slot Manager, Expansion Manager, etc.) and presents the device specific information to each family device in a format agreed upon (documented). A family Expert is the administration function for a family. Experts are important when devices are brought into the system (classically at boot time) but are not part of the primary data paths to a device. Driver Components All native device drivers are CFM-loadable modules that export their API by using CFM’s export-by-name feature. Native drivers are located in either System-ROM, PCI-card RO…

Apple Confidential Information 1 Native Drivers for PCI and other Peripherals in Marconi April 13, 1994 Please direct all comments to: Wayne Meretsky AppleLink: WNM Extension: 4-2955 Apple Confidential Information 2 Scope This document includes the design and implementation plan for allowing entirely native device drivers to be used with Marconi. Summary It is difficult to explain to third party developers of peripheral equipment exactly why the only implementation option available for writing a device driver precludes native code. Combined with the move away from NuBus and towards PCI, the developer story is poor. To entice card developers to create Macintosh devices and to simplify the transition to a Modern Operating System, a native driver model has been designed that will allow native drivers to seamlessly integrate with System Software. Finally, Apple must guarantee that these native drivers will continue to function well with future releases of system software including Maxwell. Approach Marconi will include a new Device Manager that supports a new format for device drivers. Attempts to open a device driver will cause the Device Manager to look for this new driver format in addition to the presently defined 'DRVR' described by Inside Macintosh Volume II, Chapter 6. Device Manager Support The process of locating device drivers during startup does not presently utilize the Device Manager's OPEN service because that service does not provide sufficient control over the exact loading and initialization process that is required by system startup. In fact, it is widely held that the Device Manager's OPEN service is never called to open any driver because the behavior defined by OPEN is always inappropriate. Due to the added complexity of opening native drivers, the entire process of locating a driver, loading it into memory, and initializing the driver's related data structures will be packaged into a new externally defined and supported API extension to the Device Manager. All system software that presently loads and installs drivers into the system must be changed to utilize this new service if they are to be capable of supporting native device drivers. In addition to changes to support native drivers, the Device Manager will provide a new flavor of IODone to greatly simplify the life of many driver writers. This spin of request completion, IORequestDone, allows the driver to specify which request has completed. The parameter block is presumed to be located Apple Confidential Information 3 somewhere on the device control block's list of outstanding requests rooted by the dCtlQHdr but, unlike IODone, it need not be the first request on that queue. The new API is as follows: void IORequestDone (DCtlPtr theDce, ParmBlkPtr thePb, OSErr theResult); Native Device Driver Description Device drivers are best characterized by three general properties: • Container format • API exported from driver to system • API imported by driver from sys…

Running Emulated Drivers Wayne Meretsky March 9, 1993 Summary This document describes the problems of running emulated device drivers in the V1 software system. Also discussed are proposed solutions to some of those problems and the costs associated with those solutions. Included is a brief description of hardware support that must be included in any native expansion slot card (PSI, PCI, etc). whose purpose is to allow NuBus cards to be plugged into the system. With this provision, a NuKernel based system should be able to remain compatible with all but the most bizzare device drivers and applications. What software cannot be emulated? In a NuKernel based system, software that is invoked as a result of a hardware interrupt, synchronously to the interruption, and at interrupt level, cannot be emulated. For the purpose of this discussion this classification of software is termed interruptlevel software. Note that in System 7, there is a tremendous amount of interrupt-level software. Applications , for example, that make asynchronous I/O requests have their completion routines run synchronously to the hardware interrupt that signifies the completion of the I/O request. These applications, therefore, contain interrupt level software. In the V1 system, however, NuKernel Software Interrupts are used to get the execution of completion routines out of interrupt level. In a V1 system, interrupt-level software includes the following: • ADB device drivers may be interrupt-level software. This depends upon the amount re-work done to the ADB manager. Techniques for removing ADB device drivers from interrupt level have been demonstrated by the NuKernel team. • Certain system software managers such as the VBL Manager, Time Manager, SCSI Manager, etc. These managers all interact with some hardware at interrupt level. However, in a V1 system, these are all ported by the NuKernel team and execute only native instructions. Therefore, unless there is a need to support third party patches to these managers, they represent no problem. Because of changes to the hardware it is doubtful that these patches would work properly even if they were emulated. • Some DRVRs (Serial, Sound, etc.) have hardware interrupt handlers. The TNT team in MSD will be providing native versions of these drivers for V1. Therefore, unless there is a need to support third party M68000 drivers for these devices, they represent no problem. Because of changes to the hardware in TNT it is doubtful that these third-party drivers will work even if they are emulated. • Most NuBus cards have hardware interrupt handlers. These are the most troublesome because the drivers are contained in ROM on the NuBus cards and cannot be easily replaced. This document outlines a strategy that will be capable of supporting most, but not all, NuBus cards. • Applications that have interrupt handlers. This includes certain strange applications that chose to avoid the Device Manager model for dealing with devices. The…

Confidential/Need to Know Release Map Mac OS Releases Mar ‘94 Aug ‘94 (?) Jan ‘95 Jun – Dec ‘95 Capone/7.5 Marconi Maxwell Edison Jamie Cummins Bob Murphy Bob Murphy Jeff Elliott • QuickDraw GX • PowerTalk • Utilities • AppleHelp • Scriptable Finder • 68K & PPC Fall CPU Support • Ruby Light • 603 Emulator • PCI Support • Performance Lite • MASH • OpenDoc • Dos/Win • PPC & 68K • Unicode add’ns • OEM Support (?) • 1st Modern Step • MASH + • OpenDoc + • Industry Netwkg • Int’l’n changes • OEM Support “Create revenue” “Required by HW” “To deliver quantum UE improvements and deliver OpenDoc” “To Enhance & Rebuild the Core OS and provide even more UE improvements” Andy Felong 13 January, 1994