Apple II
File Type Notes
_____________________________________________________________________________
                                                  Developer Technical Support


File Type:         $BB (187)
Auxiliary Type:    All

Full Name:     Apple IIGS Device Driver File
Short Name:    Device driver

Written by:    Matt Deatherage                                  November 1989

Files of this type and all auxiliary types contain Apple IIGS device drivers.
_____________________________________________________________________________

An Apple IIGS device driver is defined as code that is necessary to control or 
operate a peripheral in a desired manner.  A driver file's data fork contains 
code (in Object Module Format) that can be loaded by the System Loader or 
ExpressLoad and executed.

The format of a driver file depends largely upon the auxiliary type of the 
driver.  Each driver has a class and an inactive flag in the auxiliary 
type, as Figure 1 indicates.

 _______________________________________________________________
| F | E | D | C | B | A | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|___|___|___|___|___|___|___|___|___|___|___|___|___|___|___|___|
 \_/ \_________________________/ \_____________________________/
  |               |                             |
  |               |                             |
  |               |                             |___ Driver-specific
  |               |                                  classifications
  |               |
  |               |_________________________________ Driver class
  |
  |_________________________________________________ 1 = inactive, 0 = active

                      Figure 1-Auxiliary Type Definition

If bit 15 of the auxiliary type is set, the driver is considered inactive and 
should not be used.  If the bit is clear, the driver is considered active and 
may be used if desired.  Users may inactivate drivers from the Finder and are 
likely to be confused if a driver they marked as inactive continues to appear.

Bits 14 through 8 determine the driver's class.  This mechanism allows many 
types of device drivers to share the same OMF-compatible file type.  Table 1 
lists defined classes of drivers.

                  Class       Definition
                  _________________________________________
                  $00         Print Manager driver
                  $01         GS/OS driver
                  $02         AppleTalk driver
                  $03         MIDI Tools driver
                  $04--$7E    Reserved
                  $7F         Third-party multimedia driver
                  _________________________________________

                         Table 1-Driver Classes

The low byte of the auxiliary type (bits 7 through 0) is referred to as the 
subclass, and it depends upon the driver class for interpretation.  Below are 
the interpretations for the defined driver classes.

Print Manager Drivers

For class $00, the low byte determines the kind of Print Manager driver is 
contained in the file.  A subclass of $00 indicates a printer driver, a 
subclass of $01 indicates a directly-connected port driver, and a subclass of 
$02 indicates a network port driver.  All other values in the subclass for 
Print Manager drivers are reserved.

Printer and Port Drivers are documented in Apple IIGS Technical Note #35, 
Printer Driver Specifications and in Apple IIGS Technical Note #36, Port 
Driver Specifications.

GS/OS Drivers

GS/OS drivers are class $01.  GS/OS groups the subclass into two fields.  Bits 
7 and 6 indicate the GS/OS driver type.  A value of 00 indicates a standard 
GS/OS device driver.  A value of 01 indicates a GS/OS Supervisor driver.  A 
value of 10 indicates a GS/OS "boot driver," a GS/OS driver which is loaded 
before other GS/OS drivers to control the boot device.  For further 
information on boot drivers, contact Developer Technical Support.  A value of 
11 is reserved and must not be used by GS/OS device driver authors.

Bits 5 through 0 are defined by the GS/OS driver type.  For standard device 
drivers, this field indicates the maximum number of devices supported; the 
GS/OS Device Dispatcher will use this field to allocate memory when the driver 
is loaded.  For all other GS/OS driver types, this field is reserved and 
must not be used by GS/OS driver authors.

GS/OS driver definitions are documented in GS/OS Reference, Volume 2.

AppleTalk Drivers

The subclass is used by AppleTalk to determine in which order the drivers 
should be loaded.  Programmers should treat every AppleTalk driver (all 
subclasses) as reserved; do not change the auxiliary type in any way, not 
even to deactivate the drivers.

Class $02 drivers are AppleTalk protocol drivers, including ROM patches for 
AppleTalk firmware.  These drivers are currently loaded and initialized by the 
SCC.Manager supervisor driver.

Note: The SCC.Manager driver must not be deactivated as it 
      arbitrates use of the serial ports.  It is required for AppleTalk 
      to function.  Similarly, the AppleTalk drivers must not be 
      deactivated individually or AppleTalk may not be initialized 
      correctly.  Disable AppleTalk in the Control Panel.  You may then 
      use the Apple IIGS Installer to remove AppleShare if you wish to 
      remove AppleTalk drivers and protocols from a disk.

AppleTalk drivers are loaded only if AppleTalk is enabled in the Control 
Panel.  The drivers are initialized in alphabetical order; therefore, you 
should not change the names of existing AppleTalk drivers.

In the driver subclass, bit 7 indicates whether the flag is a standard 
AppleTalk protocol.  For protocols that you write and ship, this bit must be 
set to 1.  If you feel your driver should have this bit set as a standard 
protocol, contact Developer Technical Support.  Bits 0-3 of the subclass 
indicate the maximum ROM version for which the driver should be loaded.  For 
example, a driver with a value of 1 in this field will not be loaded on a 
machine with a ROM version greater than 1.  A driver with a value of 3 will 
not be loaded on future Apple IIGS machines, but will be loaded on all current 
machines.

AppleTalk drivers are called to initialize themselves in full 16-bit native 
mode.  The A register contains the current AppleTalk channel number (i.e., 
which port is being used for AppleTalk); the X register contains the ROM 
version; the Y register contains the AppleTalk firmware slot number.  Drivers 
should return from initialization with the carry clear and zero in the 
accumulator if initialization was successful or carry set and an error code in 
A if initialization failed.  You may assume that AppleTalk is active during 
AppleTalk driver initialization.  Your driver should perform necessary 
installation tasks (such as opening as socket or adding routines to the 
dispatch table at $E1D600) during initialization.

The remaining bits in the driver subclass are reserved and must not be used 
by AppleTalk driver authors.

MIDI Tools Drivers

The subclass field for MIDI Tools drivers is currently reserved and should 
be set to zero.  MIDI Tools Drivers are documented in Apple IIGS Technical 
Note #54, MIDI Drivers.

Third-Party Multimedia Drivers

The third-party multimedia driver class indicates drivers used by applications 
or other non-system components to control multimedia peripherals such as 
videodisc or video tape players.  The subclass for this class is assigned 
for each driver by Developer Technical Support, as are most file type and 
auxiliary type combinations.  Developers wishing to provide a multimedia 
driver must contact Developer Technical Support for a subclass assignment.

What's Reserved?

Since so many types of drivers are all using the same file type, it is 
essential that you adhere to the auxiliary type conventions specified in 
this Note.  If you are creating a driver whose auxiliary type can not be 
completely defined using the guidelines in this Note, contact Developer 
Technical Support for assistance, or for further assignment.  If you are 
creating a driver which does not fit into an existing driver class, contact 
Developer Technical Support for a new class assignment.

Do not use any field marked as reserved in this Note to store any number 
other than zero.


Further Reference
_____________________________________________________________________________
    o    Apple IIGS Toolbox Reference
    o    GS/OS Reference, Volume 2
    o    Apple IIGS Technical Note #35, Printer Driver Specifications
    o    Apple IIGS Technical Note #36, Port Driver Specifications
    o    Apple IIGS Technical Note #54, MIDI Drivers
