Date: Mon, 22 Apr 1996 23:50:17 -0700 From: jordan@pongo.West.Sun.COM (Jordan Brown) Subject: Item #343: What does "compatible" mean? P1275 Openboot Working Group Proposal -- Proposal #:343 Ver 0.1 Title: What does "compatible" mean? Author: Jordan Brown Date: 22 April 1996 Ed/Tech: Technical Synopsis: Describes the requirements for device compatibility Doc & Version: New Recommended Practice Problem: In recent internal discussions here at SunSoft, there has been some confusion and concern over whether it is appropriate for a particular device to claim (via the "compatible" property) that it is "compatible" with another. This document attempts to describe what is and is not implied by declaring one device to be "compatible" with another. Proposal: Create the following Recommended Practice: --- Open Firmware Recommended Practice: What does "compatible" mean? Version 0.1 April 22, 1996 6:40 pm Published by the Open Firmware Working Group This document is a voluntary-use recommended practice of the Open Firmware Working Group. The Open Firmware Working Group is an ad hoc committee composed of individuals interested in Open Firmware as defined by IEEE 1275-1994, related standards, and their application to various computer systems. The Open Firmware Working Group is involves both in IEEE sanctioned standards activities, whose final results are published by IEEE, and in informal recommendations such as this, which are published on the Internet at: http://playground.sun.com/1275/ Membership in the Open Firmware Working Group is open to all interested parties. The working group meets at regular intervals at various locations. For more information send email to: p1275-wg@risc.sps.mot.com Revision History 0.1 22 April 1996 Initial version. Jordan Brown, SunSoft. 1. Introduction 1.1 Purpose This document attempts to describe what is, and what is not, implied by including the name of a device in a device node's "compatible" property. 1.2 Scope This document applies to all devices for which a "compatible" property is supplied. 2. References and Definitions 2.1 References [1] IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Practices and Requirements 2.2 Definitions device Normally, a particular hardware implementation of a function. Sometimes, a particular definition of an abstract implementation. emulated device A device, usually an older device, with which the device under question claims compatibility. The newer device claims to emulate the older. emulating device A device, usually a newer device, that claims compatibility with another, usually older, device. 3. What does "compatible" imply? 3.1 Intent Historically, one of the problems with devices that identify themselves is that they have a choice: they can identify themselves accurately, or they can identify a well-known product they claim to emulate. If they identify themselves accurately, then there is a backwards compatibility problem: existing software will not recognize new hardware, even if the new hardware is a pure superset of the old, supported, hardware. If, on the other hand, they identify themselves as an older product that they emulate, the identification is incorrect - it misleads humans and makes it difficult for software to take advantage of added features or work around "imperfections" in the implementation of the emulation. Open Firmware's "compatible" property attempts to address these concerns by allowing both precise identification of the device and explicit identification of other devices with which this device is compatible. The intent is that software does not have explicit support for this particular device but does have support for one of the devices with which it is "compatible", the software will be able to function and correctly operate the device. Because the device may have features in addition to those supported by the "compatible" device, the software may not take full advantage of the hardware. The Generic Names Recommended Practice takes this one step further, by noting that the thing that a particular device is MOST compatible with it is itself, and requiring that the device itself be the first entry in the "compatible" property. The only thing noteworthy about this "identity compatibility" is that if there's a defined specification for a particular device or class of devices, and an implementation uses the name specified therein, the implementation must be compatible with that specification. 3.2 Hardware Programming Interface Ideally, the hardware programming interface of a new device that is "compatible" with an old device will be exactly the same as, or a pure superset of, the interface supported by the old device. This means not only that the device is _capable_ of operating in a compatible fashion, but that the firmware will set it up to operate compatibly. In particular: All defined registers must have their defined semantics. All defined commands (if applicable) must have their defined semantics. There may be additional registers and/or commands which provide additional functionality, but manipulating them must not be required to operate the device in a compatible fashion. Device responses must conform to the defined semantics. There may be additional device responses possible, but they must be disabled so that the software receives only compatible responses. 3.3 Properties As with the hardware interface, properties must be the same as, or a pure superset of, the defined properties of the emulated device. In particular: All properties defined by the emulated device must have their defined semantics. There may be additional properties, but their use must not be required for compatible operation. All defined entries in "reg", "interrupts", and similar properties must have their defined semantics. Such entries must be at the beginning of the property, in the order defined by the emulated device. There may be additional entries in "reg", "interrupts", and similar properties, but their use must not be required for compatible operation. Such entries may be added only at the _end_ of the property, after all entries defined by the emulated device. No property defined by the emulated device may have a value other than those defined by the emulated device. 3.4 Methods Again, the methods supplied must be the same as, or a pure superset of, the defined properties of the emulated device. In particular: All methods defined by the emulated device must have their defined semantics. There may be additional methods, but their use must not be required for compatible operation. All defined arguments to methods, in particular "open" arguments, must have the semantics defined by the emulated device. There may be additional values for arguments to methods, but their use must not be required for compatible operation. Results returned by methods defined by the emulated device must have values as defined by the emulated device. 4. What does "compatible" NOT imply? Anything explicitly specified as "undefined" by the emulated device may differ, and should be expected to differ, in the emulating device. Anything not defined by the emulated device may differ in the emulating device. Registers, portions of registers, commands, methods, properties, and behaviors marked in the emulated device as "reserved", "undefined", "obsolete", "do not use", et cetera may have different semantics in the emulating device. The contents of the "reg", "interrupts", or similar properties after the last entry defined by the emulated device are undefined and may be used in emulating devices. The absolute register addresses, interrupt routing, and so on may differ between the two devices. Software must use the properties supplied to determine these values and must not make assumptions based on the device identification. Electrical interfaces may differ between the two devices. Physical appearance and packaging may differ between the two devices. Labelling, jumpers, switches, installation procedures, and so on may differ between the two devices. 5. In Real Life. Two devices are rarely perfectly compatible. New functionality often requires the sacrifice of old, seldom-used functionality. Subtle undocumented behaviors are often different. While the comments above imply absolute compatibility, in reality placing a device into a "compatible" list is a judgement call. If the newer device is compatible with all but a few never-used interfaces of the old, it may be appropriate to call it "compatible" even though it is not strictly a superset. The vendor must decide whether the customer's best interests lie with the ability to, most likely, use the new hardware with existing software, or with an absolute guarantee of compatibility. No simple set of rules can say how to make this decision; it will depend on the exact device and its market. This gray area is why it is absolutely essential that all devices identify themselves precisely so that, in the event that there is an unexpected incompatibility, the software can take appropriate device-specific corrective action. When in doubt, be precise. You can always supply less-precise identification in "compatible". [ P1275 Item #343 -- Received: Mon Apr 22 23:48:32 PDT 1996 ]