Date: Fri, 2 Aug 1996 11:58:56 -0700 From: jordan@pongo.West.Sun.COM (Jordan Brown) Subject: Item #382: PC keyboard device binding v0.3 P1275 Openboot Working Group Proposal -- Proposal #382 Ver 0.3 Title: PC keyboard binding Author: Jordan Brown Date: 02 August 1996 Ed/Tech: Technical Synopsis: Changes from last meeting, plus technical changes to try to allow seamless transitions vis-a-vis indicators. Doc & Version: New document Problem: Miscellaneous editorial changes and clarifications. Indicator/lock state handling revamped again based on previous discussions and additional research. (Now uses methods to get and set the lock state.) Proposal: (Changes marked with change bars) PC Keyboard Device Binding to IEEE 1275-1994 Standard for Boot (Initialization, Configuration) Firmware | Revision 0.3 DRAFT | 01 August 1996 Jordan Brown | Sun Microsystems 1. Purpose of this Device Binding This document specifies the application of Open Firmware to the industry standard PC keyboard, including device-specific requirements and practices for initialization, properties, and methods. 2. Revision History Revision 0.0, 05 October 1995 Initial revision. Revision 0.1, 30 October 1995 First version visible outside Sun. Minor editorial changes. Revision 0.2, 22 April 1996 Indicator handling changed. Editorial changes. | Revision 0.3, 01 August 1996 | Indicator handling changed again. | 3. References [1] IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Practices and Requirements [2] Device Support Extensions to IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware | http://playground.sun.com/1275/practice/devicex/ [3] Technical Reference, IBM Personal Computer | IBM part number ??? [4] Technical Reference, Personal Computer AT IBM part number 6280070 [5] Personal System/2 Model 80 Technical Reference IBM part number 68X2256 4. Definition of Terms AT keyboard A keyboard presenting the interface defined in section 4 of [4], excluding the electrical specifications therein. engravings The glyphs marked on the keys. What the user thinks the keys mean. PS/2 keyboard A keyboard presenting the interface defined in section 6 of [5], excluding the electrical and BIOS specifications therein. scan code A positional code for a particular key, not necessarily related to the engraving on that key. In other words, the leftmost key on the top row of the main alphabetic pad is represented by the same scan code regardless of whether it has a Q printed on it, as on a US keyboard, or an A printed on it, as on a French keyboard. XT keyboard A keyboard presenting the interface defined in section ?? of [3], excluding the electrical specifications therein. 5. Device Characteristics (Informative) 5.1. General Characteristics These devices report scan codes for key presses, separately reporting the press and release of the key. They do not offer any mechanism for programmatically determining the engravings on the keyboard. In other words, there is no programmatic way to determine whether the keyboard has the US layout, with QWERTY on the top row, or the French layout, with AZERTY on the top row. 5.2. XT Keyboard The original, or "XT", keyboard uses a single byte to report a key press and the same byte, but with the high bit set, to report a key release. It has no "output" capability - no indicator LEDs. 5.3. AT Keyboard The AT keyboard uses a single byte to report a key press and two bytes, an F0 followed by the original byte, to report a key release. It adds three indicator lights (Num Lock, Caps Lock, and Scroll Lock) which can be turned on and off under software control. The scan code set used is different from that used by the XT keyboard. 5.3.1 AT-101 Keyboard A later version of the AT keyboard increases the number of keys to 101 or 102. It adds a separate arrow pad, right-side duplicates of "Alt" and "Ctrl", and F11 and F12. Scan codes are made more complex by backwards compatibility considerations - the new keys are represented as an E0 prefix followed by the equivalent older codes. [ At least I think the AT-101 added these "virtual" key presses - I don't have an AT-101 manual. ] 5.4. PS/2 Keyboard The PS/2 keyboard is programmably selectable to emulate an XT keyboard, an AT-101 keyboard, or still another set of scan codes that tries to simplify the confusion caused by efforts to extend the keyboard with additional keys and still maintain backwards compatibility. In all but this latter mode, many keys generate streams of "virtual" key presses to simulate appropriate keystrokes on the older keyboards. On power-on, the keyboard defaults to emulating the AT-101 keyboard. 5.5. Microsoft "Natural" Keyboard The "Natural" keyboard adds three additional keys, but is otherwise compatible with the PS/2 keyboard. [True?] 6. Device-specific Configuration Variables | [[ The keyboard layout probably needs to be stored in a configuration | variable. Arguably this is a private matter for the firmware, but | also arguably the client should be able to set it since the client | is likely to have better UI facilities than the firmware does. | Interface simplicity certainly favors keeping it private to the | firmware. ]] 7. Device Nodes 7.1. Properties 7.1.1. Open Firmware-defined Properties for Device Nodes name prop-name, specifies the vendor and model of the device. prop-encoded array: a string encoded with encode-string. If the Generic Names Recommended Practice is implemented by this package, this property shall have the value "keyboard". If the Generic Names Recommended Practice is not implemented by this package, this property shall contain vendor and device identification as described in [1]. The device identification shall be sufficient to identify the physical layout of the keyboard, including the locations and shapes of all of the keys and indicators, and the engravings thereon. 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 "keyboard". compatible S | Standard property name to define alternate "name" property | values. | prop-encoded-array: The concatenation, with encode+, of an | arbitrary number of text strings, each encoded with | encode-string. | If the Generic Names Recommended Practice is implemented by this package, the first entry in this property shall contain vendor and device identification as described in [1]. The device identification shall be sufficient to identify the physical layout of the keyboard, including the locations and shapes of all of the keys and indicators, the engravings thereon, the scan codes generated by those keys, and the commands required to control those indicators. Later entries may describe other keyboards with similar layouts. The final entry shall be one of: "IBM,ps2-keyboard" "IBM,at-keyboard" "IBM,xt-keyboard" indicating the basic command set to which the keyboard will respond. Note: This property is intended primarily to specify the programmatic interface to the keyboard and secondarily to specify the physical appearance of the keyboard. While it can be used to determine the mapping between scan codes and engravings, the device-specific "layout" property provides that information in a more convenient and generic fashion. 7.1.2. Device-specific Properties for Device Nodes "layout" prop-name, denotes the relationship between the engravings on the keyboard and the scan codes generated. prop-encoded array: a list of strings encoded with encode-string. This property contains an ordered list of layout specifications. It specifies the relationship between the engravings on the keyboard - the meaning the user intended - and the scan code(s) returned by the keyboard. It does not attempt to encode the physical appearance of the keyboard. Each specification is of the form: ,- or, optionally, ,-- where is vendor identification as defined for "name" in [1]. is the ISO 3166 code for the country the keyboard is primarily intended for, in upper case. If the keyboard is not intended for a specific country the definition is vendor-specific. is the ISO 639 code for the language the keyboard is primarily intended for, in lower case. If a keyboard is not intended for a specific language the definition is vendor-specific. is, if there is more than one layout defined by that vendor for that country and language, a vendor-defined identifier for that particular variant. The entries in the list progress from most specific to least specific. Since the vast majority of keyboards use common engraving-to-scan code mappings, it should generally be possible to specify the IBM keyboard that this keyboard emulates: IBM,FR-fr-84 IBM French AT keyboard, per [4]. IBM,DE-de-84 IBM German AT keyboard, per [4]. IBM,IT-it-84 IBM Italian AT keyboard, per [4]. IBM,ES-es-84 IBM Spanish AT keyboard, per [4]. IBM,GB-en-84 IBM UK English AT keyboard, per [4]. IBM,US-en-84 IBM US English AT keyboard, per [4]. IBM,BE-fr-102 IBM Belgian PS/2 keyboard, per [5]. IBM,CA-fr-102 IBM Canadian French PS/2 keyboard, per [5]. IBM,DK-da-102 IBM Danish PS/2 keyboard, per [5]. IBM,NL-nl-102 IBM Dutch PS/2 keyboard, per [5]. IBM,FR-fr-102 IBM French PS/2 keyboard, per [5]. IBM,DE-de-102 IBM German PS/2 keyboard, per [5]. IBM,IT-it-102 IBM Italian PS/2 keyboard, per [5]. IBM,latinamerican-es-102 IBM Latin American PS/2 keyboard, per [5]. IBM,NO-no-102 IBM Norwegian PS/2 keyboard, per [5]. IBM,PT-pt-102 IBM Portugese PS/2 keyboard, per [5]. IBM,ES-es-102 IBM Spanish PS/2 keyboard, per [5]. IBM,SE-sv-102 IBM Swedish PS/2 keyboard, per [5]. IBM,CH-swiss-102 IBM Swiss PS/2 keyboard, per [5]. IBM,GB-en-102 IBM UK English PS/2 keyboard, per [5]. IBM,US-en-101 IBM US English PS/2 keyboard, per [5]. MSFT,US-en-104 Microsoft US English Natural keyboard [[ need to add Asian, MS keyboards ]] If the keyboard encoding is unknown, this property shall be omitted or empty. Note: Unfortunately, the hardware does not provide any way of automatically detecting the keyboard layout. Still, on some platforms it is possible that the keyboard layout can be set in NVRAM at manufacturing time. Regardless, Open Firmware itself | and most if not all clients are likely to need this information, | so the Open Firmware implementation probably needs to provide | a mechanism for the user to supply it. 7.2. Methods 7.2.1. Open Firmware-defined Methods for Device Nodes | "open" | "close" | "read" | "write" | As defined in [1] and [2]. | 7.2.2. Device-specific Methods for Device Nodes | get-lock-state ( -- lock-state ) | Retrieves Open Firmware's current keyboard "lock" state. | This value is a bit map with the following values: | 0x01 Caps Lock | 0x02 Num Lock | 0x04 Scroll Lock | Other bits are reserved and shall be zero. | set-lock-state ( lock-state -- ) | Sets Open Firmware's keyboard "lock" state. The client should | copy reserved bits from the value returned by get-lock-state. | [[ It is not clear to me whether this should cause OF to reset | the LEDs to match. If it's being used to keep the client and | OF in sync, then the client has probably already set the LEDs. | If the client is just randomly tweaking the lock state - maybe | it has a religious objection to lower case - then this should | probably cause OF to reset the LEDs. ]] 8. User Interface Commands 8.1. Open Firmware-defined User Interface Commands None. 8.2. Device-specific User Interface Commands None. 9. Device State | Note: The following device state rules and suggestions are intended to | accomplish two goals: (1) Keep the keyboard usable by maintaining a | consistent scancode set, and (2) provide seamless transitions between | Open Firmware and the client with regard to "lock" state. | 9.1. Device State When Client is Started | The keyboard indicators, if any, shall reflect Open Firmware's | current "lock" state. | Note: This is not a trick question, merely a restatement of the obvious. | 9.1.1. PS/2 Keyboard | The keyboard shall be set to scan code set 2, compatible with an AT keyboard. Note: This mode is chosen because it is the power-on default mode for these keyboards and because it is compatible with AT keyboards, which are the other major grouping in current use. 9.2. Device State When Client Calls Open Firmware | If the client is maintaining a "lock" state independent of Open | Firmware's, then before requesting any Open Firmware service requiring | user interaction: | . The keyboard indicators, if any, should reflect the client's | current "lock" state. (Note: This is not a trick question, | merely a restatement of the obvious.) | | . The client should invoke set-lock-state to inform Open Firmware | of the current "lock" state. | | Note: Before starting user interaction, Open Firmware may want to | explicitly set the keyboard indicators to match its "lock" state. If | the client has been maintaining the indicator state and has informed | Open Firmware of any changes using set-lock-state, this will be | unnecessary. If, on the other hand, the client has not informed Open | Firmware of its "lock" state, this will ensure that the keyboard | indicators will reflect the behavior Open Firmware will implement. | 9.2.1. PS/2 Keyboard The keyboard must be set to scan code set 2, compatible with an AT keyboard. Note: If the keyboard is in a different mode when the client calls Open Firmware, unpredictable behavior may result if Open Firmware accepts keyboard input. Clients changing the keyboard mode should either restore AT compatible mode before calling Open Firmware or should avoid using Open Firmware features requiring user interaction. Changing the keyboard mode is likely to render Open Firmware unusable for debugging purposes. 9.3. Device State When Open Firmware Returns Control to Client | If Open Firmware changes its "lock" state, then the keyboard indicators, | if any, shall reflect Open Firmware's "lock" state. 9.3.1 PS/2 Keyboard | The keyboard scan code selection shall be unchanged. 10. Other Commentary On all keyboards with separate numeric and arrow pads, it is recommended that the Num Lock indicator default to On, with associated appropriate scan code decoding. This is the default mode set by most PC BIOS implementations, and so will match the expectations of the majority of users. It is completely acceptable for an Open Firmware implementation to offer an implementation-specific way of controlling this default. [ P1275 Item #382 -- Received: Fri Aug 2 12:00:38 PDT 1996 ]