Technical Note DV12

Our Checksum Bounced

CONTENTS A Bit of History Drivers That Check In, But Don't Check Out Just When You Thought It Was Safe To Call _SysEnvirons To Sum it Up References Change History Downloadables

This Technical Note discusses a fix to a SCSI Manager bug that concerns all developers working with SCSI and NuBus device drivers. Updated: [October 01 1989]

A Bit of History

The boot code contained in the ROM has a feature used by the Start Manager to perform a checksum on the SCSI driver being loaded. Inside Macintosh, Volume V-573, The SCSI Manager, documents this being performed on the Macintosh SE and later models for volumes using the new partitioning method. The truth, however, is that checksum verification was never performed due to a bug in the ROM, and because of this, all drivers loaded regardless of validity.

That was the case until recently. On new Macintosh computers, the checksum verification works. That's the good news: we've fixed the bug. Now the bad news: this fix causes a number of third-party SCSI drivers to fail to load.

Some SCSI drivers improperly implement the new partitioning scheme. If the partition map entry name begins with the four letters "Maci" (case sensitive) and is of type "Apple_Driver", the driver now has its checksum verified with the entries in the partition map. If this checksum fails, the driver is not loaded. This checksum algorithm is documented in Inside Macintosh, Volume V-580, The SCSI Manager.

DoCksum
        moveq.l     #0,d0       ; initialize sum register
        moveq.l     #0,d7       ; zero extended byte
        bra.s       CkDecr      ; handle 0 bytes
CkLoop
        move.b      (a0)+,d7    ; get a byte
        add.w       d7,d0       ; add to checksum
        rol.w       #1,d0       ; and rotate
CkDecr
        dbra        d1,CkLoop   ; next byte
        tst.w       d0          ; convert a checksum of 0
        bne.s       @1          ; into $FFFF
        subq.w      #1,d0       ;
@1

The following is a C equivalent:

static UInt32 ChecksumDriver(void *start, UInt32 length)
{
    UInt8  *cursor;
    UInt32 result;

    cursor = (UInt8 *) start;
    result = 0;

    while ( length != 0 ) {
        result = result + *cursor;
        result = ((result <<  1) & 0x0FFFE) |
                 ((result >> 15) & 0x00001);
        cursor += 1;
        length -= 1;
    }
    if (result == 0) {
        result = 0x0FFFF;
    }
    return result;
}

Back to top

Drivers That Check In, But Don't Check Out

The checksum routine tests the number of bytes specified in pmBootSize, beginning at the start of the driver boot code. Only drivers contained within the new partition map have this test performed. If you are using the old partition map scheme documented in Inside Macintosh, Volume IV-283, The SCSI Manager, the driver does not have its checksum validated. The following is the startup logic in the new Macintosh ROMs:

IF
  pmSig = $504D
AND
  pmPartName = Maci
AND
  pmPartType = Apple_Driver
AND
  pmBootChecksum = ChecksumDriver(bootCode, pmBootSize)
THEN
  Load the driver
ELSE
  Do not load the driver

Back to top

Just When You Thought It Was Safe To Call _SysEnvirons

The call _SysEnvirons was created for compatibility reasons. It allows an application to make a single call to the system to determine its characteristics. It keeps the application from reading ROM addresses and low memory. This trap is now in the ROM of new machines. But, before you get excited about this addition to ROM, there is something that Inside Macintosh, Volume V-5, Compatibility Guidelines, states that must be understood by those writing SCSI drivers:

"All of the Toolbox Managers must be initialized before calling SysEnvirons." "...SysEnvirons is not intended for use by device drivers, but can be called from desk accessories."

This statement means that neither SCSI nor NuBus device drivers can use _SysEnvirons. The earliest possible moment to call _SysEnvirons is at INIT time. Some SCSI drivers call _SysEnvirons, and this causes the Macintosh to crash at boot time.

Back to top

To Sum Up

Check if your partition map is of the version described in the SCSI Manager chapter of Inside Macintosh, Volume V, and contains the pmPartName and pmPartType as mentioned earlier in this Note. If it does, then verify that the pmBootChecksum is correct. If the checksum is not correct, the new Macintosh computers will not load your driver. The solution to this problem is to have a valid partition map entry in all cases and to expect the Start Manager to perform the checksum verification regardless of the machineType.

_SysEnvirons is not available until the system has been initialized.

Back to top

References

Inside Macintosh, Volume IV-283, The SCSI Manager

Inside Macintosh, Volume V-5, Compatibility Guidelines

Inside Macintosh, Volume V-573, The SCSI Manager

Inside Macintosh: Devices, SCSI Manager

Inside Macintosh: Devices, SCSI Manager 4.3

Technote OV 16, "Gestalt and SysEnvirons: A Never Ending Story"

NuBus is a trademark of Texas Instruments, Inc.

Back to top

Change History

Back to top

Downloadables

Back to top