Providing Open Firmware SupportSince the ROM contents is ultimately decided by third-party developers, the first issue to address is what level of Open Firmware support the device will provide. This can be divided into the following categories:
For each level of support, this Note addresses what can and cannot be accomplished by the device for Mac OS or other operating systems the device may target. Defining "Boot" and "Runtime" DriversAt this point, before explaining the different levels of Open Firmware support provided by the device, we need to distinguish between "boot" and "runtime" drivers.
No Support of Open FirmwareThe first type of Open Firmware support is that of no support. This lack of support does not require an expansion ROM at all, although an expansion ROM with no FCode is also contained in this category. However, placing an expansion ROM on a device costs money, and it makes little sense to provide an empty ROM. Problems With This ApproachThere are problems that you should consider with this type of support: 1) not being plug-and-play, 2) having an ambiguous device driver name, 3) wasting memory space, since using base registers only allow memory sizes to be multiples of powers of two, and 4) not being able to define sub-apertures. Sub-apertures are defined using the Configuration Space base registers. A typical example is a display device with a frame buffer, video controller, and RAMDAC. By defining three base registers, one for each function on the device, families can write memory differently than they do registers. This is useful for caching. No Plug-and-PlayWithout an expansion ROM, the device won't be plug and play. Nor will it be available to the user until the file system is initialized because the driver container must be placed on a hard disk and loaded from there. Note that the driver container does not necessarily have to be place on a hard disk: it could, for example, be located on a network. However, the device and driver will be matched and loaded. Ambiguous Device Driver NameAnother issue to consider is that a distinct device "name" property cannot be provided when there is no expansion ROM. This makes unique device/driver matching ambiguous. For example, two manufacturers may supply a similar driver for a particular device, or a chip vendor may rev a PCI interface chip used on your device. Open Firmware during its probing process first looks for a name property in the Expansion ROM. It then looks for the Subsystem ID and Subsystem Vendor ID. And finally, it will choose the Device ID and Vendor ID if the name property is not defined and the Subsystem ID and Subsystem Vendor ID are zero. Runtime drivers may fall into the no-support category but boot drivers cannot exist without an expansion ROM and therefore do not belong in this category. The no-support category is populated mostly by applications controlling a device via a private driver. The device is not available to other applications. Since the name may not be unique, the driver should provide additional software to make sure that the device it has been matched with by the operating system is indeed its device. This could be some sort of a signature diagnostic. For instance, all drivers have a validateHardware interface that is called by the family that instantiates the driver to validate that the match is correct and the device is functional. Minimum Support of Open FirmwareTo achieve minimum support requires an expansion ROM. Minimum support or Run Time Support requires a driver property. It should also include a "name" property. This will eliminate ambiguous driver/devices matching and provide plug-and-play. Full Support of Open FirmwareThe last category -- full support -- includes but is not limited to unambiguous driver/device matching, plug-and-play support, and boot support. The presence of a "name" property in the ROM guarantees matching, the presence of a runtime driver in the ROM guarantees plug-and-play, and the presence of a boot driver guarantees Open Firmware driver support such as display and network devices. Properties Common To All Device TypesGiven that your device has an expansion ROM, there are properties common to all devices as well as device-specific properties. What follows is an introduction to those properties that are defined by the IEEE 1275-1994 Specification, the PCI Binding Specification, and Apple Computer. The "name" PropertyThe "name" property is uniquely used to define the name of your node in the Open Firmware device tree. This is also the name of your device. This is the only required property. If you do not supply this property, the Open Firmware is obliged to construct one on your behalf because it is required. This is the algorithm. The Open Firmware probing process first looks for FCode to define this property in the device tree. If it is not present, it then uses the Subsystem ID and SystemVendor ID that is hard-wired in Configuration Space on your device. If those fields are zero, it then uses the Vendor ID and Device ID also in the Configuration Space. It will construct a "name" property of the form pcixxxx,yyyy. The yyyy field can be the System ID or Device ID while the xxxx field can be a SubsystemVendor ID or Vendor ID. The "reg" PropertyThe "reg" property is used to define your device's PCI memory-mapped areas including I/O space. If a "reg" property is contained in your expansion ROM, it will be used. If not, the Open Firmware probing process constructs one for you. It does so by writing all 1's to the Base Address Registers. (0x10 through 0x24) in Configuration Space. It then reads back the values. These registers are hardwired in powers of two to define your memory needs. Bits returning a zero effectively define the memory requirements. See the PCI Local Bus Specification Revision 2.1 Section 6.2.5 Base Addresses for details. A word about the "assigned-addresses" property. This property is also generated during the probing process from the "reg" property. It is not, however, contained in the expansion ROM but is placed in the device tree. The "device-type" PropertyThe "device-type" property defines the device by function such as display, network, block, and so on. A word of caution is required. All device types except type PCI to PCI bridges use a PCI Configuration Register Map. Bridges use a PCI-to-PCI Bridge Register Map. See Designing PCI Cards and Drivers for Power Macintosh Computers, Chapter 4, "Startup & System Configuration," Figures 4-1 and 4-2 for details. The "interrupts" PropertyUse this property to define whether your device can generate interrupts. Its absence defines no interrupt needs. Since all interrupt pins on the PCI bridge chip are "ORed" together, there can be only one interrupt source on your device. Your device will be required to supply, in the case of multiple sources, a method for the driver to determine which source is the one requiring service. The "model" PropertyThe model number or name of your device. The "address" PropertyUsed to define large virtual address regions. Currently unused by Open Firmware. The "compatible" PropertyUsed to define alternate "name" property values. You would typically use this property to tell the Open Firmware that there are other device choices that can be matched with a driver, given the original "name" property could not be matched. The compatible property allows other drivers to match against your device. For example, consider an XYZ networking card that is register-compatible with an Apple networking card. In this case, the name property would be "XYZ,xxx,yyy" and, correspondingly, the compatible property would be AAPL,xxx,yyy". The "status" PropertyThe status of your device. Use this when you run diagnostics on your device during the Open Firmware boot process and you wish to report the results to Open Firmware. Currently unused by Open Firmware. Standard Device Nodes and Their PropertiesThat concludes our discussion of the properties that are common to all device nodes. Now let's look at some standard device nodes and their properties. The most common five are: "block", "byte", "display", "network", and "serial".
SummaryThis Technote introduces you to the possible expansion ROM contents for all PCI Macintosh computers. The least risky choice between no ROM, minimum ROM, and full ROM is, of course, full support, but the actual decision is constrained by how the board will be used. This Note is intended to make you aware of your ROM-content choices. A closing caveat is that devices of type 'ndrv' or IOKit were not discussed in this Note. These Apple-derived types allow developers to move to PCI before certain families are introduced into the OS. With time, all device types should use families. However, 'ndrv' is a valid type and can be used. Having an expansion ROM on a 'ndrv' or IOKit device can allow the driver writer to at least generate a "name" property with its unambiguous value. This alone will prevent a third-party manufacturer from having to recall its drivers to revise its DriverDescription data structure. ReferencesStarting FORTH; Brody Writing FCode Program for PCI PCI Local Bus Specification Revision 2.1 Technote 1061 - Fundamentals of Open Firmware, Part I: The User Interface, provides an overview of using Forth and the Open Firmware user interface. Technote 1062 - Fundamentals of Open Firmware, Part II: The Device Tree, is intended to get you started with the device tree. Downloadables
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
