Date: Wed, 31 Jul 1996 19:11:22 -0700 From: jordan@pongo.West.Sun.COM (Jordan Brown) Subject: Item #381: PC keyboard/mouse controller binding P1275 Openboot Working Group Proposal -- Proposal #381 Ver 0.3 Title: PC keyboard/mouse controller binding Author: Jordan Brown Date: 31 July 1996 Ed/Tech: Technical Synopsis: Revisions from 06/29/96, plus a few minor clarifications. Doc & Version: New document Problem: Apply changes and comments from 06/29/96. Proposal: Change bars indicate changes from version 0.2. --- PC Keyboard/Mouse Controller Device Binding to IEEE 1275-1994 Standard for Boot (Initialization, Configuration) Firmware | Revision 0.3 DRAFT | 31 July 1996 Brian Horn, SunSoft Jordan Brown, SunSoft 1. Purpose of this Device Binding This document specifies the application of Open Firmware to the industry standard PC keyboard/mouse controller, including device-specific requirements and practices for initialization, properties, and methods. 2. Revision History Revision 0.1, 12 December 1995 Initial revision, proposal #301. Brian Horn, SunSoft. Revision 0.2, 22 April 1996 Fit to device binding template. Remove initialization commentary. Add "slot-names". Jordan Brown, SunSoft. | Revision 0.3, 31 July 1996 | Changes per 06/29/96: textual representation, call out | all methods and properties, and change slot-names format. | Some merging with CHRP keyboard controller binding. | 3. References | This Open Firmware Device binding standard shall be used in conjunction | with the followingpublications. When the following standards are | superseded by an approved revision, the revision shall apply. | [1] IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Practices and Requirements [2] Technical Reference, Personal Computer AT IBM part number 6280070 [3] Personal System/2 Model 80 Technical Reference IBM part number 68X2256 | [4] Device Support Extensions to IEEE Std 1275-1994 | http://playground.sun.com/1275/practice/devicex/ | [5] Open Firmware Recommended Practice: Generic Names | http://playground.sun.com/1275/practice/gnames/ 4. Definition of Terms | EISA Extended Industry Standard Architecture | | ISA Industry Standard Architecture | 5. Device Characteristics (Informative) The PC keyboard/mouse controller implements one or two half-duplex clocked serial interfaces to external devices. This is the sole interface used by PC keyboards, and a common interface for mice. The controller is usually implemented as an Intel 8042 microcontroller with appropriate on-chip firmware, and so is often referred to as an "8042", even though the 8042 is a general-purpose microcontroller. Optionally, the keyboard controller will translate incoming data from an AT keyboard into the equivalent data as from an XT keyboard, for backwards compatibility. 5.1 AT Keyboard Controller The AT keyboard controller implements a single interface, universally used to attach a keyboard. 5.2 PS/2 Keyboard Controller The PS/2 keyboard controller implements two interfaces using two interrupts and a shared register strategy. Conventionally, one interface is the "keyboard" interface and the other the "mouse" interface. The two interfaces are electrically equivalent, but the translation mechanism mentioned above is available only on the "keyboard" interface. 6. Device-specific Configuration Variables None. 7. Device Nodes | 7.1. Controller Nodes | This section applies to the node for the controller itself. | 7.1.1. Properties for Controller Nodes | | As defined in IEEE 1275-1994 [1] and the Generic Names Recommended | Practice [5], with the following additions and modifications. | | 7.1.1.1. Open Firmware-defined Properties for Controller Nodes | "name" Standard Open Firmware property. The value shall be "8042". [[ I'm not entirely happy with this, because the 8042 is general-purpose. ]] "compatible" Standard Open Firmware property. The value shall be "8042". [[ I'm not entirely happy with this, because the 8042 is general-purpose. ]] "device_type" Standard Open Firmware property. The value shall be "8042". "#address-cells" Standard Open Firmware property. The value shall be 1. "#size-cells" Standard Open Firmware property. The value shall be 0. | "reg" | Standard Open Firmware property. For the standard ISA | implementation of this controller: | | . the first entry in this property shall specify the | address of the data register. | . the second entry in this property shall specify the | address of the command register. | Note: The data register is conventionally at 0x60 and the command | register is conventionally at 0x64. | | "interrupts" | Standard Open Firmware property. For the standard ISA | implementation of this controller: | | . the first entry in this property shall specify the | interrupt associated with the main port. | . If the device supports an auxiliary port, then the | second entry shall specify the interrupt associated | with the auxiliary port. | | Note: The main port interrupt is conventionally 1, and | the auxiliary port interrupt is conventionally 12. | | 7.1.1.2. Device-specific Properties for Controller Nodes | "slot-names" Specifies the labels on the physical connectors. prop-encoded-array: | The concatenation, with encode+, of one integer, encoded | with encode-int, and one or two text strings, each encoded | with encode-string. | The initial integer contains a bit map specifying which | labels follow. The low-order bit (value "1") in the integer | will be set if a label is supplied for the main connector, | and the next bit (value "2") will be set if a label is supplied | for the auxiliary connector. | The labels then follow: first the label for the main connector, | if any, and then the label for the auxiliary connector, if any. | These values are intended to allow the computer to describe the connectors to the user in a way that will allow the user to identify which connector is which. | 7.1.2. Methods for Controller Nodes | As defined in [1], with the following additions and modifications. | 7.1.2.1. Open Firmware-defined Methods for Controller Nodes | "encode-unit" "decode-unit" As defined in [1]. Numeric representation of unit addresses: Prop encoded int whose value is either 0 (for the main port) or 1 (for the aux port). Text representation of unit addresses: | "0" for the main port. | "1" for the aux port. | 7.1.2.1.1. Device Arguments for "Open" Method for Controller Nodes None. | 7.1.2.2. Device-specific Methods for Controller Nodes None. | 7.2. Child Nodes | | This section applies to the node(s) for the devices attached to the | controller. Consult also [4] and the bindings for the individual | devices. | | 7.2.1. Properties for Child Nodes | | As specified in [1], [4], [5], and the applicable device binding, | with the following additions and modifications: | | 7.2.1.1. Open Firmware-defined Properties for Child Nodes | | "reg" | Standard Open Firmware property. The value shall consist of a | single integer. For the main port, the value shall be 0, and for | the auxiliary port the value shall be 1. | | 7.2.1.2. Device-specific Properties for Child Nodes | | None. | | 7.2.2. Methods | | 7.2.2.1. Open Firmware-defined Methods for Child Nodes | | "open" | "close" | "read" | "write" | As specified in [1] and [4]. | | 7.2.2.1.1. Device Arguments for "Open" Method for Child Nodes | | None. | | 7.2.2.2. Device-specific Methods for Child 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 | The "interrupt enable" bits (0x03) in the Command Byte | shall be zero, disabling interrupts. | If the device on the main port is open (as it will be if it is | selected as Open Firmware's standard input device), then the | "keyboard interface disable" bit (0x10) in the Command Byte | shall be zero, enabling that device. If that device is not | open, the bit shall be one, disabling the device. | | If the device on the auxiliary port is open (as it will be if | it is selected as Open Firmware's standard input device), then | the "auxiliary interface disable" bit (0x20) in the Command | Byte shall be zero, enabling that device. If that device is | not open, the bit shall be one, disabling the device. | | The value of the "keyboard translate mode" bit (0x40) | in the Command Byte is undefined. [[ This is a significant | interoperability issue. Personally, I recommend 0. ]] | | The value of other bits in the Command Byte is undefined. | 9.2. Device State Required When Client Calls Open Firmware | For devices not selected as Open Firmware's "standard input", | there is no requirement. | For devices selected as Open Firmware's "standard input", the | client should not modify the device state. | | Note: If the device is in a different state when the client | calls Open Firmware, unpredictable behavior may result if Open | Firmware accepts input. 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. | 9.3. Device State When Open Firmware Returns Control to Client | Open Firmware must return the device to the client with its | state unmodified. 10. Other Commentary As the two connectors are often mechanically and electrically identical, it would not be surprising for the user to plug the keyboard into the "mouse" port and vice versa. Obviously, ease of use is improved if this situation is handled gracefully. [ P1275 Item #381 -- Received: Wed Jul 31 19:12:59 PDT 1996 ]