Date: Wed, 10 Jan 1996 15:32:26 -0800 From: jordan@pongo74.West.Sun.COM (Jordan Brown) Subject: Item #305: Device binding drafts for a variety ... (v1.1) P1275 Openboot Working Group Proposal -- Proposal #:305 Ver 1.1 Title: Create Device Bindings documents Author: Jordan Brown Date: 08 January 1996 Ed/Tech: Technical Synopsis: Create documents to contain bindings for individual pieces of hardware. Supersedes: "Create Device Bindings documents v1.0", Proposal #304 Doc & Version: New documents Change Summary: v1.1 Add section 7.2.1.1 for Device Arguments to Open v1.0 Original Problem: Effective use of Open Firmware's configuration-reporting features requires that the client know how to associate reported names with actual hardware, and how information about the individual device is reported. For devices that are supported by vendor-supplied Fcode this is relatively straightforward; even if the vendor does not supply appropriate documentation, one can simply observe the device's behavior. For devices supported by motherboard Fcode, however, the picture is not so simple: two firmware vendors might describe the same device differently. For instance, they might choose different names for the same device, might choose to put the entries in the "reg" property in a different order, or might initialize the device into different operating modes. Generally these differences are trivial... but can result in real trouble for "shrink wrap" clients. Generic device bindings, such as those documented in the core 1275 and the Device Support Extensions document, do not fill this need. They document how the generic features of the device (methods, properties) will appear, but do not and should not document the hardware specifics that are needed by client device drivers. Proposal: Create a series of new documents describing individual devices, with contents as shown below. This is a very early draft. Discussion is needed as to the format that this sort of document should take. Because of this, I have presented only one "fully fleshed out" entry as an example of how it might be done; if the Committee thinks it to be an appropriate format then the rest can be fleshed out similarly. I have proposed this as a series of documents, one per device, but it would be equally valid to treat it as a larger document with a section for each device. Note: One problem I have not addressed is the handling of the same device implemented on multiple bus types. Probably what should be done is either to have separate documents for each device/bus type combination, or to describe any bus-specific differences "in line". There are three sections following. The first is a template for device bindings, giving the outline of the information to be supplied. The second is a relatively fully-fleshed-out binding for a standard PC serial device. The third is a bunch of cryptic micro-bindings for standard PC/AT hardware, giving the names for the original PC/AT parts and noting things like suggested "reg" entry ordering. These need to be more fully fleshed out, but I didn't want to spend the time until we had some idea what the form would be. These documents are far from "final form". I fully expect them to go through at least one or two "draft" stages before being adopted, and even then the individual devices are likely to be completed at different times. The intent of this proposal is to get that draft process started. ------------------------------------------------------------- Title: Device Binding Template Note: It is intended that this template be used for all device types, maintaining identical section numbering for all devices. Additional subsections may be added as needed, but sections should not be deleted or renumbered. XXX Device Binding to IEEE 1275-1994 Standard for Boot (Initialization, Configuration) Firmware Revision 0.0 DRAFT 05 October 1995 Jordan Brown SunSoft 1. Purpose of this Device Binding This document specifies the application of Open Firmware to XXX, including device-specific requirements and practices for initialization, properties, and methods. 2. Revision History Revision 0.0, 05 October 1995 Initial revision. 3. References [1] IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Practices and Requirements 4. Definition of Terms 5. Device Characteristics (Informative) 6. Device-specific Configuration Variables 7. Device Nodes 7.1. Properties 7.1.1. Open Firmware-defined Properties for Device Nodes 7.1.2. Device-specific Properties for Device Nodes 7.2. Methods 7.2.1. Open Firmware-defined Methods for Device Nodes 7.2.1.1. Device Arguments for "Open" Method 7.2.2. Device-specific Methods for Device Nodes 8. User Interface Commands 8.1. Open Firmware-defined User Interface Commands 8.2. Device-specific User Interface Commands 9. Device State 9.1. Device State When Client is Started 9.2. Device State Required When Client Calls Open Firmware 9.3. Device State When Open Firmware Returns Control to Client 10. Other Commentary ------------------------------------------------------------- Title: PC Serial Port Device Binding PC Serial Port Device Binding to IEEE 1275-1994 Standard for Boot (Initialization, Configuration) Firmware Revision 0.1 DRAFT 08 January 1996 Jordan Brown SunSoft 1. Purpose of this Device Binding This document specifies the application of Open Firmware to standard PC serial port devices, including device-specific requirements and practices for initialization, properties, and methods. 2. Revision History Revision 0.1, 08 January 1996 Initial revision. 3. References [1] IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Practices and Requirements [2] [3] 4. Definition of Terms 5. Device Characteristics (Informative) The PC serial port is one of the most standardized pieces of hardware in the industry, mostly due to the relative lack of support for it in older operating systems and so the tendency for applications programs to directly manipulate it. The original PC serial ports were implemented using the Intel 8450 [2], a simple UART that supplied only a single byte of buffering in each direction. More modern implementations are based on the National Semiconductor 16550 [3], a superset that supplies a 16-byte FIFO in each direction. 6. Device-specific Configuration Variables None. 7. Device Nodes 7.1. Properties 7.1.1. Open Firmware-defined Properties for Device Nodes name prop-name, specifies the generic name of the device. prop-encoded array: a string encoded with encode-string. The meaning of this property is as defined in Open Firmware, as modified by the Generic Names Recommended Practice. The value for nodes described by this specification shall be "serial". device_type prop-name, specifies the implemented interface. prop-encoded array: a string encoded with encode-string. The meaning of this property is as defined in Open Firmware. The value for nodes described by this specification shall be "serial". compatible prop-name, specifies device names with which this device is compatible. prop-encoded-array: an array of strings, each encoded with encode-string. The meaning of this property is as defined in Open Firmware, as modified by the Generic Names Recommended Practice. As described in those documents, the entries are a list of device names with which this device is compatible, starting with the name of the device itself and progressing through successively less precise and possibly less functional compatible devices. For the National Semiconductor 16450 and 16550, the names shall be "nsc,16450" and "nsc,16550" respectively. For the Intel 8450, the name shall be "intc,8450". Note: A device compatible with the NS 16550 is also compatible with the NS 16450 and the Intel 8450, and so should list all three. Additional entries may be supplied, at their appropriate position in the list, to describe devices with which this device is compatible. reg [boilerplate] A single entry describing the device's register set. interrupts [boilerplate] A single entry describing the device's interrupts. 7.1.2. Device-specific Properties for Device Nodes out1 out2 [boilerplate] These properties specify what the OUT1 and OUT2 (respectively) pins on the device are attached to. The allowed values are: "interrupt enable" This pin gates the interrupt line. Note: PC-AT compatible implementations use OUT2 for this purpose. "no connection" This value indicates that the pin is not connected. Note: For historical reasons, it is probably appropriate to assume "interrupt" enable for "out2" and "no connection" for "out1" if these properties are absent. clock-frequency [boilerplate] This property specifies the clock frequency supplied to the baud rate generator, in megahertz. Note: PC compatible implementations use a clock frequency of 1.8432 MHz, and so on those implementations this value should be 1843200. 7.2. Methods 7.2.1. Open Firmware-defined Methods for Device Nodes As specified in [1], without addition or modification. 7.2.1.1. Device Arguments for "Open" Method As specified in [1], without addition or modification. 7.2.2. Device-specific Methods for Device Nodes None. 8. User Interface Commands 8.1. Open Firmware-defined User Interface Commands None. 8.2. Device-specific User Interface Commands None. 9. Device State 9.1. Device State When Client is Started [ Note: this should be specified in the generic definition of serial devices. ] For devices not selected as Open Firmware's "input-device" or "output-device", the initial state is undefined. For devices which are selected as Open Firmware's "input-device" or "output-device", the device shall be initialized appropriately for the device to which it is attached. 9.2. Device State Required When Client Calls Open Firmware For devices not selected as Open Firmware's "input-device" or "output-device", there is no requirement. For devices selected as Open Firmware's "input-device" or "output-device", the state should be unmodified from the initial state on client startup. Note: If the device is in a different state when the client calls Open Firmware, unpredictable behavior may result if Open Firmware accepts input or generates output. Clients changing the device state should either restore the original state before calling Open Firmware or should avoid using Open Firmware features requiring user interaction. Changing the device state is likely to render Open Firmware unusable for debugging purposes. 10. Other Commentary ------------------------------------------------------------- For the remainder of the devices listed here, I have listed only the "essential" information. As this series of documents is "fleshed out", these descriptions should be expanded similarly to the Serial example above. This listing supplies device names and "reg" definitions, which is an enormous improvement over no definition at all. PC Parallel Port name=parallel device_type=parallel compatible=intc,8255 reg=one entry interrupts=one entry ATA name=ide device_type=ide compatible=??? reg=command,control (1f0,3f0) interrupts=one entry PC Keyboard Controller name=8042 compatible=intc,8042-pckb reg=data, cmd/status (60, 64) interrupts=one entry Note: The 8042 is a programmable microcontroller, and so "compatible" must identify not only the 8042 itself but the interface standard its firmware conforms to. The "-pckb" above refers to the standard PC keyboard interface, with no mouse support. See Also Proposal 301. PC Keyboard Controller with Mouse Port name=8042 compatible=intc,8042-pckbm;intc,8042-pckb reg=data, cmd/status (60, 64) interrupts=main,aux Note: The 8042 is a programmable microcontroller, and so "compatible" must identify not only the 8042 itself but the interface standard its firmware conforms to. The "-pckbm" above refers to the standard PC keyboard/mouse interface. See Also Proposal 301. PC Floppy Controller name=floppy compatible=intc,82077 device_type=floppy (note: new Device Type, needs binding) reg=one interrupts=one entry Note: As this is a nexus node, additional work is needed to document the interface with its children. Floppy Drive name=disk compatible=??? device_type=block reg= Floppy-like Tape name=tape compatible=??? device_type=byte reg= 3COM 3C509B name=ethernet compatible=COMS,3C509B reg=one interrupts=one DMA controller(s) Note: The register specifications for these are incredibly complex, and may argue for treating the PC-AT dual DMA controllers as a single device.. Interupt Controller name=interrupt compatible=intc,8259a reg=one Note: This should document how the interrupt lines are mapped to host interrupts. Again, it might be best if the two 8259s on the AT are treated as a single device. Timer name=timer compatible=intc,8254-2 reg=one interrupts=0,-1,-1 Note: This device supports three timers. Potentially, each of these might be attached to an interrupt line. PC-compatible implementations attach only the first timer to an interrupt line; a notation (-1 above) is needed to document that the others are *not* attached to interrupt lines. PS/2 Watchdog Timer name=timer compatible=? reg=one Game Controller name=game compatible=??? reg=one RTC/CMOS name=rtc compatible=MOT,MC146818 reg=one (note: shared with NMI control) System Control Port B (61) name=misc compatible=ibm,pcat-control-b reg=one(61) System Control Port A (92, PS/2-80) name=misc compatible=ibm,ps2-80-control-a reg=one Floating Point Coprocessor CGA name=display compatible=ibm,cga reg=io,mem MDA (printer separate) name=display compatible=ibm,mda reg=io,mem Note: The original IBM implementation had a printer port on the same card. For Open Firmware definitional reasons, and to support other implementations that do not have a coresident printer port, the printer port is treated as an entirely separate device. EGA name=display compatible=ibm,ega;{ibm,cga|ibm,mda) reg=3b0 I/O,B000 memory (MDA mode) reg=3c0 I/O,B800 memory,A000 memory (CGA mode) Note: This device can be hardware configured to support either monochromatic monitors compatibly with the MDA or color monitors compatibly with the CGA. This presents a problem for "reg" definition. VGA name=display compatible=ibm,vga reg=3b0,3c0,mem Note: This device can be soft-configured to be compatible with the MDA, the CGA, and the EGA. This makes "reg" definition a nightmare if compatibility is to be maintained. Since VGA is today's standard and the others are of only historical interest, I would suggest ignoring compatibility and defining VGA "from scratch". PCI Devices NCR 53C810, 815, 825, ? name=scsi compatible=one of: pci1000,1;pci1000,2;pci1000,3;pci1000,4 reg=config,io,memory interrupts=one S3 928PCI name=display compatible=pci5333,88b0 reg=config,framebuffer,vgamono,vgacolor,vgamem no interrupts? S3 864 name=display compatible=pci5333,88c0;pci5333,88c1;pci5333,88c2;pci5333,88c3 reg=config,framebuffer,rom,vgamono,vgacolor,vgamem no interrupts? Weitek P9100 name=display compatible=pci100e,9100 reg=config,framebuffer/registers no interrupts? Note: This device can be soft-configured for VGA compatibility. I have no idea how to treat this in the property definitions. AMD ethernet (79C970 I believe) name=net compatible=pci1022,2000 reg=config,io,mem(?) interrupts=one AMD SCSI DEC ethernet name=ethernet compatible=pci1011,2 reg=config,io,mem(?) interrupts=one [ P1275 Item #305 -- Received: Wed Jan 10 15:30:23 PST 1996 ]