Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support


SmartPort
#2:    SmartPort Calls Updated

Revised by:    Llew Roberts                                    September 1989
Written by:    Mike Askins                                           May 1985

This Technical Note documents SmartPort call information which is not found in 
the descriptions of SmartPort in the Apple IIGS Firmware Reference and the 
Apple IIc Technical Reference Manual, Second Edition.  The device-specific
information which had been included in this Note is now found in these
manuals.
Changes since November 1988:  Added diagram and information on vendor ID 
numbers.
_____________________________________________________________________________


STATUS Calls

A STATUS call with unit number = $00 and status code = $00 is a request to 
return the status of the SmartPort host, as opposed to unit numbers greater 
than zero which return the status of individual devices.  The number of 
devices as well as the current interrupt status is returned.  The format of 
the status list returned is illustrated in Figure 1.

           +------------------+
    Byte 0 |   Device Count   |
           +------------------+
    Byte 1 | Interrupt Status |
           +------------------+
    Byte 2 |      Vendor      |   $0000          Vendor unknown
           +                  +---$0001          Apple Computer, Inc.
    Byte 3 |        ID        |   $0002-$FFFF    Third-Party Vendor
           +------------------+
    Byte 4 |    Interface     |   _____|___________________|_____
           +                  +--|F|E|D|C|B|A|9|8|7|6|5|4|3|2|1|0|
    Byte 5 |     Version      |  |_______|_______________|_______|
           +------------------+  |       |               |
    Byte 6 |    Reserved      |  |Major  |    Minor      |$A=Alpha
           +------------------+  |Release|    Release    |$B=Beta
    Byte 7 |    Reserved      |                          |$E=Experimental
           +------------------+                          |$0=Final

               Figure 1-Host General Status Return Information

Stat_list    byte 0       Number of devices
             byte 1       Interrupt Status (If bit 6 is set, then no interrupt)
             bytes 2-3    Driver manufacturer (were Reserved prior to May
                          1988):
                          $0000          Undetermined
                          $0001          Apple
                          $0002-$FFFF    Third-party driver
             bytes 4-5    Interface Version
             bytes 6-7    Reserved (must be $0000)

The Number of devices byte tells the caller the total number of devices hooked 
to this slot or port.

The Interrupt Status byte is used by programs which try to determine if the 
SmartPort was the source of an interrupt.  If bit 6 of this byte is clear, 
there is a device (or devices) in the chain that require interrupt service.  
You cannot use this value to determine which device in the chain is actually 
interrupting.  Your interrupt handler, having determined that a SmartPort 
interrupt has occurred, must poll each device on the chain to find out which 
device requires service.  The UniDisk 3.5 and Memory Expansion Card do not 
generate interrupts, so in these cases, this byte has bit 6 set.

The vendor ID number may be used to determine the manufacturer of a specific 
SmartPort peripheral interface card, a useful piece of information when 
dealing with device-specific calls.  Contact Apple Developer Technical Support 
if you require a specific vendor ID number.  The version word follows the 
SmartPort Interface Version definition described later in this Note.


CONTROL Codes

Before May 1988, control code $04 was defined as device-specific.  It is now 
defined as EJECT, and all SmartPort devices which support removable media must 
support this call.  If a device does not support removable media, it should 
simply return from this call without an error.

Note that the Apple II SCSI card firmware was revised in early 1988 to support 
this change.


INIT

An application should never make an INIT call (SmartPort code $05), since 
doing so is likely to destroy operating system integrity and may cause media 
damage as well.

If you are writing your own operating system (not encouraged) and need to 
reset all SmartPort devices, the INIT call with unit number = $00 will do just 
that.  Note that SmartPort devices cannot be selectively reset, and INIT must 
never be made at all with any unit number other than $00.


SmartPort Interface Version Definition

The SmartPort Interface Version definition uses the most significant nibble of 
the word as the major version number, the next two most significant nibbles as 
the minor version number, and the least significant nibble as a release 
indicator:

    $0 = Final    $A = Alpha    $B = Beta    $E = Experimental

Therefore, the interface version word for an experimental SmartPort interface 
1.15 would be $115E while the interface version word for SmartPort interface 
2.0 would be $2000.  GS/OS driver version numbers also follow this definition.


Further Reference
_____________________________________________________________________________
  o  Apple IIGS Firmware Reference
  o  Apple IIc Technical Reference Manual, Second Edition
  o  Apple IIGS Technical Note #25, Apple IIGS Firmware Reference Updates