Date: Fri, 2 Aug 1996 17:08:00 -0700 From: jordan@pongo.West.Sun.COM (Jordan Brown) Subject: Item #384: PC Serial Port Device Binding P1275 Openboot Working Group Proposal -- Proposal #:384 Ver 0.99 Title: PC Serial Port Device Binding Author: Jordan Brown Date: 02 August 1996 Ed/Tech: Technical Synopsis: Apply changes from 06/29/96. Clarifications and cleanup. Doc & Version: New document Problem: Direction from the minutes was: Amendments: - Add reference to pnpPNP,501 - Clock frequency should be in hertz - Pick up methods from CHRP serial device binding (or move to DSE) Accepted unanimously; Editor directed to produce Approved Version 1.0 with above amendments; AI to suggest "name" convention to recognize superio chips In addition, there were several things that needed cleanup: . missing revision history (oops!) . missing or incomplete references . original PC serial port was 8250, not 8450 (8450 is later, higher performance, still no FIFO) . Some boilerplate missing or needed cleanup . "reg" and "interrupts" needed a little cleanup to limit them to ISA semantics. (If we put this device on PCI, "reg" will be a little different, for instance.) While I think these changes are within the bounds of editorial discretion and the direction from the previous meeting, I'd like people to take one last look to see if I've done anything horribly objectionable before I take this to "1.0 Approved". Proposal: (change bars mark changes) PC Serial Port Device Binding to IEEE 1275-1994 Standard for Boot (Initialization, Configuration) Firmware | Revision 0.99 DRAFT | 02 August 1996 Jordan Brown | Sun Microsystems 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. | Jordan Brown, Sun Microsystems | Revision 0.2, 22 April 1996 | Minor changes per 01/96 meeting. | Jordan Brown, Sun Microsystems | Revision 0.2a, 23 April 1996 | Trivial changes. (Fix hertz/MHz inconsistency, left-over | "no connection" in Note.) | Jordan Brown, Sun Microsystems | Revision 0.99, 02 August 1996 | Changes from 06/29/96 meeting. Minor changes, mostly | editorial. Add mode setting, PnP references. 3. References [1] IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Practices and Requirements | [2] Intel INS8250 Data Sheet | [3] National Semiconductor PC16550D Universal Asynchronous Receiver/ | Transmitter with FIFO's | http://www.national.com/pf/PC/PC16550D.html | [4] Device Support Extensions to IEEE 1275-1994. | http://playground.sun.com/1275/practice/devicex/ | [5] Open Firmware Recommended Practice: Generic Names | http://playground.sun.com/1275/practice/gnames/ | [6] Plug-N-Play Generic Device ID assignments | ftp://ftp.microsoft.com/developr/drg/Plug-and-Play/devids.txt 4. Definition of Terms | ISA Industry Standard Architecture | | UART Universal Asynchronous Receiver/Transmitter | 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 | 8250 [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. | Microsoft [6] has assigned Plug-N-Play identifier PNP0500 to | denote a generic PC serial interface and PNP0501 to denote a | NS16550 compatible PC serial interface. | 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 | Standard property 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. 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 "ns16450" and "ns16550" respectively. For the Intel 8250, | the name shall be "i8250". | To denote compatibility with industry standards, devices | compatible with the NS16550 should include "pnpPNP,501" in | this property. Devices compatible with the Intel 8250 should | include "pnpPNP,500" in this property. | Note: A device compatible with the NS 16550 is also compatible | with the Intel 8250, and so should list both standards. For | example, the National Semiconductor PC87312 is a composite chip | containing, among other things, two NS 16550 compatible serial | interfaces. Its "compatible" property might well start | "nspc87312-serial" and should include "pnpPNP,501" and | "pnpPNP,500" in that order. Additional entries may be supplied, at their appropriate position in the list, to describe devices with which this device is compatible. reg | Standard property to define the package's registers. | prop-encoded-array: | Arbitrary number of (phys-addr size) pairs. | phys-addr is a (phys.lo ... phys.hi) list, encoded | with encode-phys. | size is a list of integers, each encoded with encode-int. | For the standard ISA implementation of this device, this | property shall consist of a single entry describing the | device's register set. | interrupts | Standard property name to define the interrupts used. | prop-encoded-array: | Arbitrary number of interrupt specifiers (bus-specific), | each typically encoded with encode-int. | For the standard ISA implementation of this device, this | property shall consist of a single entry describing the | device's interrupt. | 7.1.2. Device-specific Properties for Device Nodes out1 out2 | Property names to define the wiring attached to the device's | general purpose output pins. | prop-encoded-array: | Text string, encoded with encode-string. | These properties specify what the OUT1 and OUT2 (respectively) pins on the device are attached to. The allowed values are: "enable interrupt" This pin gates the interrupt line. Note: PC-AT compatible implementations use OUT2 for this purpose. "" (null string) This value indicates that the pin is not connected. Note: For historical reasons, it is probably appropriate | to assume "enable interrupt" for "out2" and "" for "out1" | if these properties are absent. clock-frequency | Property name to define the clock frequency supplied to the | device. | prop-encoded-array: | Integer, encoded with encode-int. | This property specifies the clock frequency supplied to the | baud rate generator, in hertz. 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 | Note: These device arguments should probably be added to | the generic definition of a "serial" device in [4]. | As specified in [1] and [4], with the following additions: | | An argument may optionally be specified when opening this | device. The argument string takes the form: | | ,,,, | | Values for the fields are: | | Whatever the hardware will support. Typical | values are 110, 134, 300, 1200, 2400, 4800, | 9600, 19200, and 38400. | | char means | ---- ----- | n none | e even | o odd | m mark | s space | | | char means | ---- ----- | 1 1 stop bit | . 1.5 stop bits | 2 2 stop bits | | | char means | ---- ----- | - none | h hardware (rts/cts) | s software (xon/xoff) | | The default mode is 9600,n,8,1,-. Unspecified fields result in | the corresponding parameters being left at their default | values. | 7.2.2. Device-specific Methods for Device Nodes | Note: These methods should probably be added to the generic | definition of a "serial" device in [4]. | As specified in [1] and [4], with the following additions: | | set-mode ( adr len -- ) | | Sets the device mode according to the string at adr, of length | len, which is interpreted the same as the arguments to the "open" | method, section 7.2.1.1. | | Unspecified fields result in the corresponding parameters being | left unchanged. | | set-modem-control ( bitmask -- ) | | Sets the device's modem control lines according to the following | table: | | Bit value Controls | 0x01 DTR (1=on, 0=off) | 0x02 RTS (1=on, 0=off) | | Other bits are reserved. | 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 "standard input" or "standard output", the initial state is undefined. For devices which are selected as Open Firmware's "standard input" or "standard output", 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 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 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. 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 [ P1275 Item #384 -- Received: Fri Aug 2 17:10:10 PDT 1996 ]