TweetFollow Us on Twitter

January 90 - DEBUGGING DECLARATION ROMS

DEBUGGING DECLARATION ROMS

MARK BAUMWELL

Through system software, the Macintosh can read the declaration ROMs in NuBus and pseudo-NuBus slots, like those in the Macintosh SE/30. This article tells you what you must know about NuBus addressing and the structure of correct declaration ROMs to successfully debug the ROM. It walks you through the structure of an example declaration ROM and gives common errors and strategies for debugging declaration ROMs.

The Slot Manager's flexibility in providing a layer between the hardware and higher-level software benefits developers and customers alike. Users can easily expand the Macintosh II family and the Macintosh SE/30 with additional hardware that goes in slots. The Macintosh card architecture lets them plug new cards into the Macintosh without worrying about using the right slot, setting dip switches, or running system configuration software. As a developer, you may need to know more about the architecture that makes this self-configuring environment possible.

THE SLOT MANAGER AND DECLARATION ROMS

Part of the Macintosh operating system, the Slot Manager can find the ROM on each expansion card installed in a system and identify the card's special capabilities. It makes use of predefined data structures called slot Resources (sResources) to initialize and configure a card and report the card's location. Each card installed in a Macintosh expansion slot needs a declaration ROM, also known as a configuration ROM, with information for using the card's hardware. The expansion hardware could be as simple as a memory card that needs to publish its address ranges or as complicated as a video card with initialization code, a driver, and declaration data.

In addition to letting the system determine what hardware is available, the Slot Manager frees applications from being dependent on a particular type of hardware. In other words, the Slot Manager helps insulate an application from the hardware by being able to locate underlying, intermediate driver software that will know about and talk to the specific hardware. The application can be free of the details and need only deal with higher-level functions. The degree of insulation depends on the software and data structures in the declaration ROM.

The Slot Manager:

  • locates and lists the cards with declaration ROMs.
  • defines a uniform structure for information in the declaration ROM and a set of library routines to access the information.
  • includes routines to allow host applications to transparently access information in the ROMs without regard to NuBus or byte lanes.
  • allows ROM initialization code to run on the host CPU during the host's startup sequence.
  • allows cards to have drivers from their declaration ROMs loaded into the host CPU.
  • initializes and manipulates the parameter RAM on the host CPU for the card during startup.

When applications are insulated from particular hardware implementations, they don't have to be revised for each new version of a vendor's board, or even for compatible boards made by competitors. Besides reducing maintenance work for the developer, information hiding of this sort saves wear and tear on customers.

Suppose a customer owns an application and a card and happens to buy another board, from the same or a different vendor, with even slightly different hardware. The difference might be a change in address or meaning of some register or memory location. The customer has to mix and match applications or drivers or INITs to boards. This is not very Macintosh-like, and the board manufacturer is sure to be savaged by the customers and the press. Matching various card-specific versions of software and different revisions of hardware can be a headache for distributors and dealers. Including card-specific software on each card's ROM in a universally accessible structure greatly simplifies installation and maintenance.

USING SRESOURCES

Don't confuse sResources on expansion cards with standard Macintosh resources. The small s indicates a slot resource as opposed to a real Macintosh resource. Although related conceptually, sResources are different and may contain anything from code to data--for example, icons, special fonts, or vendor-defined data. In fact, feel free to substitute "data structure" for "sResource" as you read.

Each card has one special sResource called a board sResource and usually one additional sResource for each function the card can perform, although additional supporting sResources are possible. An sResource affiliated with a function is called a functional sResource and gives information about that particular function, usually to high-level applications interested in accessing the function.

Most cards perform only one function. For example, a modem card might perform only a modem function, a video card might just do video, and so on. These cards would have only one functional sResource, along with the required board sResource. However, it is possible to build a multifunction expansion card--a card with a parallel, serial, and modem port, for example. In this case, the card's declaration ROM would have three functional sResources--one each for the card's functions. In addition to other, optional sResources, it would also have the required board sResource.

A high-level program may need to be able to find and use certain kinds of hardware in the Macintosh slots. For example, QuickDraw works with video cards made by different vendors. QuickDraw finds each video card by looking for the card's functional sResource that says it can do QuickDraw-compatible video.

AN EXAMPLE DECLARATION ROM

As far as the Slot Manager is concerned, at the startup scan of the cards a valid declaration ROM must have proper structures for the format block, sResource directory, and the board sResource. If any of these structures is in error, the Slot Manager marks the slot as empty, and no Slot Manager calls to that slot will work. Though other sResources or data structures may have errors, the Slot Manager doesn't check them at startup. These errors will show up during later calls to the Slot Manager by applications, INITs, drivers, and so forth.

We will look at these key structures in an example declaration ROM and will discuss some common errors developers make. The sample skeleton ROM has the required board sResource and one functional sResource.

The ROM can be divided into four major structures: the sResource directory, functional sResource, board sResource, and format block, as shown in the illustration. Let's look at these structures in more detail.

THE SRESOURCE DIRECTORY
The source code begins with some includes and equates, followed by the sResource directory. A directory is a list of the sResources in the ROM. In the example, we have two sResources, the required board sResource and one functional sResource. The directory looks like this:

_sRsrcDir  OSLstEntry      sRsrcBoard,_sRsrcBoard
                            ;References Board sResource.
            OSLstEntry      sRsrcFun,_sRsrcFun
                            ;References functional sResource.
            DatLstEntry     endOfList,0 
                            ;End of the list.

The OSLstEntry and DatLstEntry items are assembler macros, defined in the MPW ROMEqu.a file. These macros make creating declaration ROMs easier, since most declaration ROM structures fall into two different formats:

  • an ID byte followed by three bytes representing a 24-bit offset or
  • an ID byte followed by a 24-bit data value

A directory contains both of these formats. The first format is used for all sResource entries in a directory. Each sResource entry consists of one byte containing the sResource identification number, and three bytes containing the offset to the sResource itself.

The offset list entry (OSLstEntry) macro is used to conveniently calculate and fill in these types of entries. It takes two arguments: the ID byte and a label designating the destination. The macro puts the first argument as is into the high byte, calculates the 24-bit signed offset value to the destination label, and puts it into the next three bytes. In our example, the first entry of the directory looks like this:

_sRsrcDir   OSLstEntry  sRsrcBoard,_sRsrcBoard  ;References Board 
                                                ;sResource.

The _sRsrcDir label designates the start of the directory. This label is needed because the offset to the directory will be calculated later. The first argument of the macro, sRsrcBoard, is equated to 1 (in the equates near the top of the source code file), and so a $01 will be put into the first byte. The second argument, _sRsrcBoard, is the label designating the start of the board sResource. The macro calculates the offset from the present point in the macro to the label and puts the resultant offset in the next three bytes. The _sRsrcBoard structure is $000C bytes away from the directory entry, so the offset is $000C. Putting them together, the complete directory entry for the board sResource looks like this in hexadecimal:

   $01000C

A similar calculation for the functional sResource is done with the offset from the directory to the _sRsrcFun label.

The second format is used in many places in declaration ROMs. It iscommonly used for the end-of-list entry, which marks the end of the list of directories and sResources. This entry always has an ID byte value of $FF followed by three bytes of zero. It can also be used to hold small pieces of data that fit into three bytes or less.

It is convenient to use the data list entry (DatLstEntry) macro for these types of entries. DatLstEntry is similar to OSLstEntry but simpler. It takes two arguments: the ID byte and the desired data value. It puts the first argument into the high byte and the data value into the next three bytes.

SRESOURCES IN GENERAL
Before looking at our example sResources, let's examine the structure of sResources in general. Every sResource includes an sRsrc_Type entry whose fields identify the sResource. Applications and drivers use the sRsrc_Type entry of each sResource to identify it and the function it performs.

The sRsrc_Type entry is comprised of an ID byte (always a $01), followed by an offset to the sResource type format. For this discussion, we will only look at the Apple defined format for the type format entry, indicated by the leading bit being a zero, since virtually all developers use it.

The sResource type format is a 64-bit value, separated into four fields of 16 bits each. The entry looks like this:

The type format fields have constant, fixed values for the board sResource, so let's look at the values for the more general case of functional sResources. The type format is hierarchical in nature, and the four fields can be considered to be "nested" under each other, with the Category being at the top of the hierarchy. While some of the fields have been predefined, new values can be and often are defined to suit developers' products.

A board can perform broad categories of possible functions, which are represented by the Category field of the type format. Within each Category are subset types that are represented by the cType value. Nested farther in the hierarchy are subset software driver identifiers (the DrvrSW value). Finally, under each DrvrSW entry, there are hardware identifiers (the DrvrHW value). The hierarchical relationship looks like:

Category
    cType
        DrvrSW
            DrvrHW

A given Category can have multiple cType interfaces for it, and each of those cTypes can have its own nested, underlying software interfaces. Many different pieces of hardware can belong to a given software architecture. Equates for many categories have been already defined, such as Display, Network, Communication, and CPU. Further, subtypes for some of these common categories have been defined, as well as software interfaces to go with some subtypes.

Let's see how this works with a common family of cards: video cards. A category for display functions has been defined (CatDisplay EQU $0001). Under it, a subtype for video displays has been defined (TypVideo EQU $0000). Since Apple has defined a driver and firmware interface for video display cards that are QuickDraw compatible, there is a software driver definition as well (DrSWApple EQU $0001). Now let's say a developer wants to make a QuickDraw-compatible video card -- the Amalgamated VaporWare Widget video board. The developer gets a hardware identifier from .Developer Technical Support;--let's say DTS assigns the developer DrHwWidget EQU $4321--and creates a functional sResource with an sRsrc_Type of

CatDisplay EQU $0001
TypVideo    EQU $0000
DrSwApple   EQU $0001
DrHwWidget  EQU $4321
or in the complete type format:
   0001000000014321

Now QuickDraw will recognize the card, because it looks for type formats that match CatDisplay/TypVideo/DrSwApple. During the search, QuickDraw will only look for a match down to its software architecture level and will mask off the hardware identifier. It does not care about the hardware identifier, because it knows the driver will deal with the underlying hardware. Notice that even though the first three entries in the type format will be the same for all QuickDraw-compatible video cards, the different hardware identifiers will make the entries unique. This is useful for the driver of the Widget card, which very much cares about the underlying hardware. It will want to locate the card and will do so by doing a match of the whole type format, including the hardware identifier.

Developers can take advantage of this if they want to have applications use their software/hardware architecture. By publishing the software interface and type format values, a developer can make a board that others can write applications for.

Besides the sRsrc_Type entry, sResources must also have a name entry (sRsrc_Name), which contains an ID byte (always $02), followed by an offset to a null-terminated string (a C string). In addition to these, the board sResource must have a board ID value (BoardId). All other entries defined for sResources and the board sResource are optional.

Now, let's take a look at the two sResources in detail.

THE BOARD SRESOURCE
Like the directory entries, our board sResource uses the macros we discussed earlier to calculate and fill in the various entries. Labels such as sRsrcType and sRsrcName are defined in the MPW ROMEqu.a file. Others, such as the board ID, are in the declaration ROM source code. The first part of our board sResource looks like this:

;=============================================================
;   The Board sResource
;=============================================================
_sRsrcBoard OSLstEntry  sRsrcType,_BoardType    
        ;References Rsrc_Type entry
    OSLstEntry  sRsrcName,_BoardName    
        ;References Rsrc_Name entry
    DatLstEntry boardId,TheBoardId  
        ;boardId **ASSIGNED BY MACDTS**
    OSLstEntry  primaryInit,_sPInitRec  
        ;Refs Primary init record.
    OSLstEntry  vendorInfo,_VendorInfo  
        ;References Vendor info list.
    DatLstEntry endOfList,0 
        ;End of the list.

The _sRsrcType entry for the board sResource points to the board sResource type format. The type format is always the same for the board sResource-- that's how the board sResource is identified. The type format for the board sResource always has this definition:

_BoardType DC.W    CatBoard    ;ALWAYS $0001 for bd sResource 
            DC.W    TypBoard    ;ALWAYS $0000 for bd sResource
            DC.W    DrSwBoard   ;ALWAYS $0000 for bd sResource
            DC.W    DrHwBoard   ;ALWAYS $0000 for bd sResource

Put together into the full 64 bits, it looks like this:

   $0001000000000000

The _sRsrcName entry points to the name string (a C string), which should be the official product name of the board:

_BoardName DC.L    'OFFICIAL PRODUCT NAME'
;The name of the Board - should be official product name

(At the beginning of the source code, there is a STRING C directive, to automatically generate c strings.)

After the name comes the required board ID, which, being a 16-bit value, can be filled in using a DatLstEntry macro. Board IDs are assigned by Macintosh DTS. To get board ID, contact Macintosh DTS with the following information:

  • the company name and address (mailing and electronic addresses, if possible)
  • the name of the person in the company responsible for the board (and a phone number, if possible)
  • the functions the board will perform
  • the official product name for the board (or a code name)
  • whether or not the board will have a software driver other than one that has been predefined (like Apple's video driver)
  • whether or not the driver will be in ROM

DTS will assign the board ID and any necessary functional sResource information. This information goes into a database, which is kept strictly confidential. There is a HyperCard® stack on the Developer Services CD and on AppleLink that makes sending in this information easier.

Next, the board sResource contains an entry for the primary initialization code. We have defined one, but it is in a separate file called PrimaryInit.a, which is referenced with an INCLUDE directive:

;-------------------------------------------------------------
;   .i.Primary Init Record; (if needed)
;-------------------------------------------------------------
_sPInitRec  DC.L    _EndsPInitRec-_sPInitRec
        ;physical Block Size
    INCLUDE 'PrimaryInit.a'
        ;Primary Init Code
_EndsPInitRec   EQU *   ;End of block
    STRING  C   ;Restore to 'c' string type.

The following is optional vendor data. It is up to the developer to decide what, if anything, goes in the VendorInfo entries. This example shows the way Apple typically uses the vendor information ;entries.

;-------------------------------------------------------------
;   Vendor Information record
;-------------------------------------------------------------
_VendorInfo OSLstEntry  VendorId,_VendorId  ;References
                                            ;the Vendor
                                            ;Id. 
    OSLstEntry  RevLevel,_RevLevel          ;References
                                            ;the Revision
                                            ;Level.
    OSLstEntry  PartNum,_PartNum            ;References
                                            ;the Part
                                            ;Number.
    DatLstEntry endOfList,0                 ;End of the
                                            ;list.
_VendorId   DC.L    'COMPANY NAME'          ;The Vendor
                                            ;Id.  Most
                                            ;vendors use
                                            ;company name
_RevLevel   DC.L    'Release-1.0'           ;The Revision
                                            ;Level
_PartNum    DC.L    '12-3456'               ;The Part
                                            ;Number

THE FUNCTIONAL SRESOURCE
In our example, our card has only one function, so our ROM has just one functional sResource. For this example, we have defined a nonexistent set of Category, subtype, software, and driver identifiers, which normally would be replaced by the ones assigned by DTS. The functional sResource entry looks like this:

=============================================================
;   The Functional sResource
;=============================================================
_sRsrcFun   OSLstEntry  sRsrcType,_FunType
        ;References sRsrc_Type
    OSLstEntry  sRsrcName,_FunName
        ;References sRsrc_Name
    OSLstEntry  sRsrcDrvrDir,_FunDrvrDir 
        ;References sResource driver dir
    DatLstEntry sRsrcHWDevId,1  
        ;The hardware device Id.
    OSLstEntry  MinorBaseOS,_MinorBase
        ;References Minor Base Offset.
    OSLstEntry  MinorLength,_MinorLength
        ;References Minor Base Length.
    DatLstEntry endOfList,0
        ;End of the list.
The type format for our fictional function looks like this:
_FunType   DC.W    CatExCat    ;<Category>
            DC.W    TypExTyp    ;<Type>
            DC.W    DrSwExSw    ;<DrSw>
            DC.W    DrHwExHw    ;<DrHw>

The sRsrc_Names for functional sResources follow a convention of concatenating the equates for the sRsrc_Type but stripping off the prefixes and separating the type format fields by underscore characters. Since our type is CatExCat/TypExType/DrSwExSw/DrHwExHw, the sRsrc_Name becomes:

_FunName   DC.L    'ExCat_ExType_ExSW_ExHW'

The driver directory identifies the type of driver and the driver itself. In the example, the driver is compatible with the Macintosh OS but contains Motorola 68020 code. The driver itself is in a separate file and is referenced by an INCLUDE directive.

;-------------------------------------------------------------
;   Driver directory; (if there's an on-board driver)
;-------------------------------------------------------------
_FunDrvrDir OSLstEntry  sMacOS68020,_sMacOS68020    
        ;References Macintosh-OS 
        ;68020 driver.
                DatLstEntry endOfList,0
        ;End of the list.
        ;Driver-1 (68020).
_sMacOS68020    DC.L    _End020Drvr-_sMacOS68020    
        ;The physical Block Size
                INCLUDE 'NameofDrvrSrcCodeFile.a'   
        ;The  driver code
_End020Drvr EQU *   
        ;The end of the driver.
    STRING  C

The hardware device ID; field (HWDevID) is optional and defined by the vendor. It can be used to indicate that an sResource is associated with a particular piece of hardware. This would be used in the case of cards that had multiple "hardware areas"--say, multifunction cards--that could be considered to be separate hardware devices. The field could be used to group certain sResources with the various devices. In this case, the functional sResources would have different HWDevID values depending on which hardware device on the card they describe.

For example, you have a card with two serial ports, which you label port 1 and port 2. You have three functional sResources--an asynchronous serial sResource, a MIDI sResource, and a network sResource. Let's say the async serial sResource is assigned to port 1. It is assigned HWDevID=1. Now let's say the network sResource can only be used with port 2. It is assigned HWDevID=2. Similarly, the MIDI sResource can only be used on port 1. It will also be assigned HWDevID=1. Now, by looking at the HWDevID fields, a driver or card software can tell which piece of hardware it is using in case different hardware on the card has different characteristics it must handle. If an sResource does not describe a hardware device, then the HWDevID field may be omitted.

The MajorBaseOS , MinorBaseOS, MajorLength, and MinorLength fields describe where the hardware area starts and how large it is. For example, a video sResource might have the MinorBaseOS be an offset to the starting address of the video frame buffer. The MinorLength field would tell how large it is. Other cards might use the MinorBaseOS to indicate where its hardware control registers are.

Use Major vs. Minor depending whether you want to reference the area using super slot space or NuBus slot space addresses.

In the example, let's say this function has some RAM memory in NuBus slot space that we would like to reference:

_MinorBase     DC.L    defMinorBase    ;RAM Offset
_MinorLength    DC.L    defMinorLength  ;RAM length

THE FORMAT BLOCK
Declaration ROMs are recognized by the presence of the ROM's format block, which occupies the highest address of the ROM's slot address space. This is our example format block:

ORG    ROMSize-FHeaderRec.fhBlockSize
;+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
;   Format Block
;+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    DC.L    (_sRsrcDir-*)**$00FFFFFF    
        ;Offset to sResource directory
    DC.L    ROMSize 
        ;Length of declaration data
    DC.L    0   
        ;CRC-can be patched by MPW crc tool 
    DC.B    romRevision 
        ;Revision level
    DC.B    AppleFormat 
        ;Format
    DC.L    TestPattern 
        ;Test pattern
    DC.B    0
        ;Reserved byte (must be zero)
    DC.B    $E1
        ;ByteLanes: 1110 0001 (bytelane 0)
ENDP
END

The first entry calculates the offset to the beginning of the directory, using the directory label. This must be a signed 24-bit value.

The ROM size;, revision level, format, test pattern, and reserved values are declared in the source and in the included MPW ROMEqu.a file. The CRC value can be generated and patched in by utilities such as MPW tools. Apple supplies two MPW tools on the Developer Services CD and AppleLink called Data and CRC. Data takes the assembled source code file, strips off the CODE 0 resource, and puts the CODE 1 segment (now the actual ROM image) into a data file. This will be convenient for later downloading to a ROM burner. The CRC tool takes the ROM image, calculates the CRC value, and inserts it into the proper place.

The last field in the block is the ByteLanes field, a signature byte that identifies which of the four NuBus byte lanes the ROM image appears on. The Slot Manager attempts to read a valid value in each of the four byte lanes at the end of the slot space. If the Slot Manager is unable to read a valid field, then an error is posted for this slot. If a valid ByteLanes value is read, this information is used to confirm a special test pattern, and perform a ROM validity check. If all verification passes, then the system can utilize the offset to the sResource directory. Note that the Slot Manager attempts to read the format block in both the 1 MB and 16 MB NuBus slot spaces. If any of these verification checks fails, the slot is marked as empty or invalid, and all Slot Manager calls to that slot will return errors.

POTENTIAL PROBLEMS

Now that we've covered the source code to the example ROM, let's look at some common problems developers experience. When trying to assemble the source code, if one or more of the arguments to the OSLstEntry or DatLstEntry macro is incorrectly defined or just left out, you will get an assembler error in the middle of the macro, and the assembler will complain with the error message:
   Invalid arithmetic operation on relocatable id

This message was generated as a result of the assembler's inability to resolve one of the two arguments to the macro. If you get this error, check both arguments and make sure the labels are correctly defined. The first argument must be equated to something in your source or the development system include files, and the second argument must be a label that exists in the source code. Please be aware that some of the predefined equates (in the assembler include files) changed from MPW 2.0 to 3.0. For instance, to improve readability, some IDs had the underscores in the middle removed (Cat_Board became CatBoard in a directory, for example).

Another error can arise from a bug in the macro defined up to and including MPW version 3.0. Most declaration ROM sources are arranged in a sequence like ours: the directory comes first in the source code (and so is lowest in memory), followed by the sResources, and finally the format block, which is at the very end of the source listing.

Structures referenced by sResources are usually defined after the sResources. That is, usually things are referenced in a forward manner and come later in the source code.

Laying out the sResources this way, the macro works fine. However, if you want to have the macro calculate a negative offset to a structure, to reference something that comes earlier in the source code, you may run into trouble. The following macro definition:

       MACRO
        OSLstEntry  &Id,&Offset
        DC.L    (&Id<<24)+&Offset-*
        ENDM

can be fixed by changing it to:

       MACRO
        OSLstEntry  &Id,&Offset
        DC.L    (&Id<<24) ++ ((&Offset-*) ** $00FFFFFF)
        ENDM

This correctly masks off the high byte of the 24-bit offset and thus allows the full range of positive as well as negative offsets to structures.

Often, the source code to the ROM will build, but because of errors in the declaration ROM data structures, the Slot Manager will fail to recognize the ROM, or will generate errors while looking at certain structures. When this happens, looking at the error generated and manually disassembling the ROM will usually find the error. This requires understanding how the ROM appears from a debugger.

DISSEMBLING THE ROM
Declaration ROMs often occupy only one or two of the four NuBus byte lanes, meaning you have to translate your assembly listing by hand. This is because the assembler generates the listing as though the ROM occupies all four byte lanes (that is, as though it would reside in RAM). To translate from the ROM listing to the actual physical addresses the ROM occupies requires knowledge of byte lanes, which are often misunderstood.

The NuBus bus width is 32 bits, or, very importantly, four bytes. Think of each group of four bytes as a chunk. A chunk on the NuBus would look like this:

The four bytes of each chunk are identified by the byte number as shown in the illustration. Byte number 3 on the NuBus side--the most significant--contains NuBus address and data bits 31-24, byte number 2 contains A/D bits 23-16, byte number 1 contains A/D bits 15-8, and byte number 0--the least significant--contains A/D bits 7-0. Bytes whose address modulo 4 equals 0 are carried on byte number 0, those whose address equals 1 are carried on byte number 1, whose address equals 2 are carried on byte number 2, and whose address equals 3 are carried on byte number 3.

This address-to-byte-number mapping is conveniently set up for an Intel-type processor, which carries the most significant bits on a higher numbered address. The Macintosh uses a Motorola type processor, which has the most significant bits on a lower numbered address. In order to preserve consistency of byte addressing, Apple does byte swapping from the NuBus to the Motorola 680x0 CPU.

To see this more clearly, let's expand the byte lanes diagram from the address space chapter of Designing Cards and Drivers for the Macintosh Family.

The diagram looks quite complicated. Fortunately, once you understand the key concepts, it's not. The addressing of bytes within a chunk is in reverse order on the NuBus and 680x0 sides. However, the address range of a chunk is the same when viewed from the NuBus or 680x0 side. The hardware interface between the CPU on the motherboard swaps the bytes of a chunk when going to and from the NuBus.

Now that we understand the byte and address translation between our CPU and the NuBus, let's look at part of our assembled ROM listing. The best place to start is at the format block at the "top" or highest physical address of the ROM, since this is where the Slot Manager starts looking at startup time to find valid declaration ROMs. Assembled, the format block looks like:

00FEC  ;+++++++++++++++++++++++++++++++++++++++++++++++++
00FEC   ;   Format/Header Block
00FEC   ;+++++++++++++++++++++++++++++++++++++++++++++++++
00FEC   00FF F014   DC.L    (_sRsrcDir-*)**$00FFFFFF
        ;Offset to sResource directory
00FF0   0000 1000   DC.L    ROMSize 
        ;Length of declaration data
00FF4   0000 0000   DC.L    0   
        ;CRC-can be patched by MPW crc tool
00FF8   01  DC.B    romRevision 
        ;Revision level
00FF9   01  DC.B    AppleFormat 
        ;Format
00FFA   5A93 2BC7   DC.L    TestPattern ;Test pattern
00FFE   00  DC.B    0   
        ;Reserved byte (must be zero)
00FFF   E1  DC.B    $E1 
        ;ByteLanes: 1110 0001 (byte lane 0)
01000

The Slot Manager will start scanning from the highest address, looking for a ByteLanes value. From there, it will look for confirmation of the ByteLanes value by looking for the reserved values, the test pattern, proper format, and revision values, down to the CRC calculation. If there is a problem with the ByteLanes value or the way the card has been built, this Slot Manager check will fail. At this point, you should load up a debugger and look at the format block. Assuming the board is in slot $B, the above format block (residing on byte lane 3) might look like this in memory (as seen from MacsBug):

00BFFFB0 0000 0000 FF00 0000 F000 0000 1400 0000 ****************
00BFFFC0 0000 0000 0000 0000 1000 0000 0000 0000 ******** *******
00BFFFD0 9D00 0000 8600 0000 3400 0000 FE00 0000 ********4*******
00BFFFE0 0100 0000 0100 0000 5A00 0000 9300 0000 ********Z*******
00BFFFF0 2B00 0000 C700 0000 0000 0000 E100 0000 +***************

The lowest address is at the upper left, and the highest address is at the lower right, with increasing addresses going from left to right. Note that the MacsBug listing shows an example CRC value ($9D8634FE) that was calculated and patched in after the ROM was assembled.

SLOT MANAGER ERRORS
During evaluation at startup or in response to application/driver Slot Manager calls, a number of errors can be returned by the Slot Manager. Often this is due to an incorrect ByteLanes value or bad sResources. The error returned usually helps to narrow down the problem. You can look at the error, then manually track through sResources in the ROM. This requires disassembling and "playing Slot Manager" much as we did above. Drawing a diagram like the one in the front of the article with the addresses and values can often help. However, please note that many Slot Manager calls make other Slot Manager calls, and the error returned may reflect an error returned by one of those calls.

If an error or crash occurs in the ROM before a debugger is loaded (during the primary initialization routine, for example), you can defer the driver or primary initialization until after the boot process has begun and a debugger has been loaded. Do this by first making stubs for the driver and/or primary initialization, or deleting them entirely. Then run them from a high-level application, which can have the primary initialization or drivers in the application or possibly in separate files.

In order to keep the driver from being loaded until after the boot, you might have to temporarily change the functional sResource's type format. This is needed in the case of video boards, for example, since the startup code looks specially for video boards, runs their primary INITs, and opens the drivers. In this case, change the sRsrc_Type to something other than CatDisplay, TypVideo, DrSwApple so that the start code won't identify the video display function. Changing CatDisplay to CatNonsense EQU $0000 would do the trick.

SUMMARY

Declaration ROMs store system-recognizable structures as well as vendor- specific data. Debugging declaration ROMs is complicated by the fact that the declaration ROM sits on the other side of the Nubus, and you have to translate the information you get. But using the techniques discussed in this article should make building, interpreting, and debugging declaration ROMS a little easier.

Mark Baumwell is a low-level O/S sort of guy. He started with Apple in 1981 after a stint with Zilog as a test engineer. After three years in the Lisa division, Mark made the move to Macintosh DTS where he has fulfilled his lifelong dream of being a firefighter. He professes to be "outdoorsy," and getting an airplane pilot's license is hiscurrent passion. He claims that nothing we could say would sully his reputation more than it has already been. We tried, but Apple Legal wouldn't approve it. Would you fly with this guy? *

Download source code for this article.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

iTubeDownloader 6.5.13 - Easily download...
iTubeDownloader is a powerful-yet-simple YouTube downloader for the masses. Because it contains a proprietary browser, you can browse YouTube like you normally would. When you see something you want... Read more
FileZilla 3.47.0 - Fast and reliable FTP...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. Version 3.47.0: Fixed regression loading advanced site... Read more
Transmit 5.6.3 - Excellent FTP/SFTP clie...
Transmit is an excellent FTP (file transfer protocol), SFTP, S3 (Amazon.com file hosting) and iDisk/WebDAV client that allows you to upload, download, and delete files over the internet. With the... Read more
Doomsday 2.2.2 - Play classic Doom on mo...
id Software's Doom pioneered the modern first-person shooter genre. Released in 1993, it was a quantum leap in game engine technology with fluid and - at the time - incredibly realistic 3D graphics.... Read more
Ableton Live 10.1.9 - Record music using...
Ableton Live lets you create and record music on your Mac. Use digital instruments, pre-recorded sounds, and sampled loops to arrange, produce, and perform your music like never before. Ableton Live... Read more
Maintenance 2.6.5 - System maintenance u...
Maintenance is a system maintenance and cleaning utility. It allows you to run miscellaneous tasks of system maintenance: Check the the structure of the disk Repair permissions Run periodic scripts... Read more
Adobe Photoshop 21.1.0 - Professional im...
You can download Photoshop for Mac as a part of Creative Cloud for only $20.99/month (or $9.99/month if you have purchased an earlier software version). Adobe Photoshop remains the gold standard in... Read more
Adobe Lightroom Classic 9.2 - Import, de...
You can download Lightroom for Mac as a part of Creative Cloud for only $9.99/month with Photoshop, included as part of the photography package. The latest version of Lightroom gives you all of the... Read more
Adobe InCopy 15.0.1 - Create streamlined...
InCopy is available as part of Adobe Creative Cloud for $52.99/month (or $4.99/month for InCopy app only). Adobe InCopy, ideal for large team projects involving both written copy and design work,... Read more
Adobe Illustrator 24.0.3 - Professional...
You can download Adobe Illustrator for Mac as a part of Creative Cloud for only $20.99/month (or $9.99/month if you have also purchased an earlier software version). Adobe Illustrator for Mac is the... Read more

Latest Forum Discussions

See All

Mobile Games Starter Kit
Over here at 148Apps, we regularly dive deep into the latest and greatest mobile games hitting the App Store, but that’s not always what people are looking for when searching for a new mobile game. Some folks just want to dip their toes into... | Read more »
Unresolved is a hard-hitting narrative a...
Ghofran Akil's Unresolved in an upcoming text-based adventure game that sees you playing as a mother attempting to find her disappeared husband during the Lebanese Civil War. [Read more] | Read more »
Marvel Strike Force introduces new brawl...
FoxNext's squad-based RPG Marvel Strike Force is set to receive some fresh characters from the X-Men and Iron Man series. They'll arrive as part of the game's latest update, which follows a sizable spending boycott on the title due to complaints... | Read more »
Speed Dating for Ghosts is a narrative a...
Speed Dating for Ghosts originally released on Steam back 2018, since then it has received honourable mentions for narrative during the Independent Games Festival. Now it's made its way over to iOS devices where it's available as a premium title... | Read more »
Fast-paced multiplayer title Tennis Star...
Tennis Stars: Ultimate Clash is the latest free-to-play tennis title to hit iOS and Android. It's said to be a fairly casual experience, offering easy-to-learn controls and fast-paced, mobile-friendly matches. [Read more] | Read more »
Super Mecha Champions' latest updat...
Super Mecha Champions' latest update sees the addition of a brand new character called R.E.D. Alongside that, there's news about the current season and a series of Emojis that have been added to the game. [Read more] | Read more »
Apple Arcade: Ranked - Top 50 [Updated 2...
In case you missed it, I am on a quest to rank every Apple Arcade game there is. [Read more] | Read more »
Apple Arcade: Ranked - 51+ [Updated 2.19...
This is part 2 of our Apple Arcade Ranking list. To see part 1, go here. To skip to part 3, click here. 51. Mini Motorways Description: [Read more] | Read more »
Isle Escape: The House is an upcoming pu...
Isle Escape: The House is an upcoming puzzle game from Simeon Angelov that's intended to serve as an introduction to a saga they're planning on releasing in an episodic fashion. The first chapter is set to release for both iOS and Android on 29th... | Read more »
Company of Heroes, the classic RTS, is n...
Feral Interactive has finally released their highly anticipated iOS version of the strategy classic Company of Heroes. It's available now for iPad as a premium title and has had various tweaks to ensure that it's optimised for touch controls. [... | Read more »

Price Scanner via MacPrices.net

Verizon offers free iPhone 7 to customers ope...
Verizon is offering a free 32GB iPhone 7 for new or existing customers who open a new line of service, no trade-in required. Cost of the phone is credited to your account monthly over 24 months. The... Read more
Sale! 10.5″ 256GB WiFi iPad Air for $549, $10...
Amazon has new 10.5″ 256GB WiFi iPad Airs, in Space Gray, on sale today for $549 shipped. Their price is $100 off Apple’s MSRP for this model, and it’s the cheapest price available from any Apple... Read more
Back on sale! Apple’s new Mac Pro for $5499,...
B&H Photo has the base 2019 Mac Pro (3.5GHz 8-Core Xeon, 32GB RAM, 256GB SSD) in stock today and on sale for $5499 including free overnight delivery to many addresses in the US. Their price is $... Read more
B&H offers $100 discount on base 13″ 1.4G...
B&H Photo has new 2019 13″ 1.4GHz MacBook Pros on sale for $100 off Apple’s MSRP today with prices starting at $1199. Overnight shipping is free to many addresses in the US. These are the same... Read more
Apple continues to offer Certified Refurbishe...
Apple has Certified Refurbished iPhone XS models available for up to $350 off MSRP, with prices starting at $699. Each iPhone is unlocked and comes with Apple’s standard one-year warranty and a new... Read more
Apple AirPods are on sale for $30 off today
Amazon has new 2019 Apple AirPods (non-Pro models) on sale today for $30 off MSRP, starting at $129. Shipping is free: – AirPods with Wireless Charging Case: $169 $30 off MSRP – AirPods with Charging... Read more
27″ 3.7GHz 6-Core 5K iMac on sale for $2099,...
B&H Photo has the 2019 27″ 3.7GHz 6-Core 5K iMac in stock today and on sale for $200 off Apple’s MSRP. Overnight shipping is free to many locations in the US: – 27″ 3.7GHz 6-Core 5K iMac: $2099 $... Read more
Save up to $250 on a 12.9″ iPad Pros with the...
Apple has Certified Refurbished 12.9″ iPad Pros available on their online store for up to $250 off the cost of new models. Prices start at $849. Each iPad comes with a standard Apple one-year... Read more
Save up to $220 on 11″ iPad Pros with these r...
Apple has Certified Refurbished 11″ iPad Pros available on their online store for up to $220 off the cost of new models. Prices start at $679. Each iPad comes with a standard Apple one-year warranty... Read more
8-Core 27″ iMac Pro available for $4249, Cert...
Apple has Certified Refurbished 27″ 3.2GHz 8-Core iMac Pros available for $4249 including free shipping. Their price is $750 off the cost of new models. A standard Apple one-year warranty is included... Read more

Jobs Board

Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
Windows/ *Apple* Technical Support Engineer...
Windows/ Apple Technical Support Engineer McLean , VA , US Apply + Be you + Be Booz Allen + Be empowered + Learn More Job Description Location: McLean, VA, US Job Read more
Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
Geek Squad *Apple* Consultation Professiona...
**762475BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store NUmber or Department:** 001423-San Jose-Store **Job Read more
Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.