Date: Tue, 3 Jan 1995 15:35:00 -0800 From: dmk@hsmpk14a-91 (David Kahn) Subject: Item #217: ISA binding *first draft* Jordan Brown, from Sun, graciously agreed to take a first cut at an ISA binding and an X86 binding. We can discuss these at the next meeting. Here's the ISA bindings, x86 binding will be posted separately. Jordan has been added to the p1275-wg alias. -David ----- Begin Included Message ----- From jordan@pongo.West.Sun.COM Tue Jan 3 15:14 PST 1995 Date: Tue, 3 Jan 1995 15:11:00 -0800 From: jordan@pongo.West.Sun.COM (Jordan Brown) To: brianh@ramada.West.Sun.COM, dmk@Eng Subject: Item #217: ISA binding *first draft* (Sorry if this is a dup - my machine crashed immediately after I sent the last one, and I don't know if it went out.) ISA Bus Binding to IEEE 1275-1994 Standard for Boot (Initialization, Configuration) Firmware Revision 0.0 27 December 1994 Prepared by Jordan Brown, SunSoft Inc. Based on text from the PCI Bus Binding. [[ Boilerplate regarding 1275 purposes. Ref PCI binding v1.4 page 1 lines 1-30 -- jb ]] Purpose of this Bus Binding This document specifies the application of Open Firmware to the bus used on the IBM Personal Computer/AT, commonly called the Industry Standard Architecture (ISA) Bus, including requirements and practices for address formats, interrupts, probing, and related properties and methods specific to the ISA Bus. The core requirements and practices specified by Open Firmware must be augmented by system-specific requirements to form a complete specification for the firmware for a particular system. This document establishes such additional requirements pertaining to the ISA Bus. Task Group Members The following individuals were members of the Task Group that produced this document: Jordan Brown, SunSoft Inc. [[ It seems appropriate to credit the PCI group, but I'm not sure exactly what wording to use ]] TRADEMARKS Sun Microsystems is a registered trademark of Sun Microsystems, Inc in the United States and other countries. OpenBoot is a trademark of Sun Microsystems. UNIX is a registered trademark of UNIX System Laboratories, Inc. [[ Or at least it was when the PCI doc was written -- jb ]] SPARC is a registered trademark of SPARC International, Inc. Products bearing the SPARC trademark are based on an architecture developed by Sun Microsystems, Inc. SPARCstation is a trademark of SPARC International, Inc., licensed exclusively to Sun Microsystems, Inc. Personal Computer/AT is [[ I believe -- jb ]] a trademark of IBM. All other products or services mentioned in this document are identified by the trademarks, service marks, or product names as designated by the companies who market those products. Inquiries concerning such trademarks should be made directly to those companies. Revision History Revision 0.0 First version. Overview and References This specification describes the application of Open Firmware to computer systems that use the ISA bus as described in [[ PC/AT hardware tech ref ]] and is to be used in conjunction with that document. Definitions of Terms Bus controller: a hardware device that implements an ISA bus. ISA device: a hardware device that connects to or "plugs in" to an ISA bus: one of a number of logically-independent parts of an ISA device. Many ISA devices have only one function per device; in such cases, the terms "ISA function" and "ISA device" can be used interchangeably. bus node: an Open Firmware device node that represents a bus controller. In cases where a node represents the interface, or "bridge", between one bus and another, the node is both a bus node relative to the bus it controls, and a child node of its parent bus. Note that an Open Firmware device node is not in itself a physical hardware device; rather, it is a software abstraction that describes a hardware device. child node: an Open Firmware device node that represents an ISA function. Such a node can correspond to either a device that is "hardwired" to a planar ISA bus, or to an "add in" expansion card that is plugged into a standard ISA expansion connector. Bus Characteristics Address Spaces ISA has two address spaces (Memory, I/O) with different addressing characteristics. Memory Space Memory Space is the primary address space of the ISA bus; it corresponds to traditional memory and "memory-mapped" I/O. The full ISA bus allows for a 24-bit address space. The "8-bit" or "PC/XT" subset allows for a 20-bit address space. [[ 8-bit devices might decode only 20 bits, appear in each megabyte. ]] I/O Space I/O Space is similar to Memory Space, except that it is intended to be used with the special "I/O access" instructions that some processors have. The full ISA bus allows for a 16-bit address space. The "8-bit" subset allows for a 10-bit address space. Devices are allowed to "alias" I/O addresses by ignoring all but the lower 10 bits of an I/O address. To conserve "reg" property space, a bit (the 't' bit, for ten-bit) is included in the encoding of I/O addresses to indicate that the corresponding "reg" range includes all such aliases. Address Formats and Representations Physical Address Formats Numerical Representation (The Numerical Representation of an address is the format that Open Firmware uses for storing an address within a property value and on the stack, as an argument to a package method.) The numerical address of a ISA address consists of two cells, encoded as follows. For this purpose, the least-significant 32 bits of a cell is used; if the cell size is larger than 32 bits, any additional high-order bits are zero. Bit #0 refers to the least-significant bit. Bit#: 33222222 22221111 11111100 00000000 10987654 32109876 54321098 76543210 phys.hi cell: 00t000ss 00000000 00000000 00000000 phys.lo cell: 00000000 nnnnnnnn nnnnnnnn nnnnnnnn [[ Yes, they could be combined into one cell. Mostly for consistency with other standards, eg PCI, I'd rather keep them separate. This also allows for consistency with the [draft] x86 binding and ISA supersets (EISA?) ]] where: t is 1 if the address is aliased (for I/O) ss is the space code, denoting the address space nn..nn is a 24-bit unsigned number Encoding of type code "ss": 01 denotes I/O space, in which case: t is set if 10-bit aliasing is present. nn..nn must be 65535 or less. 10 denotes Memory Space, in which case: t must be zero nn..nn is the 24-bit Memory Space address Text Representation The text representation of an ISA address is one of the following forms: i[t]NNNN mNNNNNN where NNNN is an ASCII hexadecimal number in the range 0..FFFF NNNNNN is an ASCII hexadecimal number in the range 0..FFFFFF t is the letter 't', whose presence is optional i is the letter 'i' m is the letter 'm' The correspondence between text representations and numerical representations is as follows: i[t]NNNN corresponds to an I/O Space address with the numerical value. If 't' is present, only the low-order 10 bits of an I/O address range is indicated; aliases are assumed for all high-order bits. The numerical value is: ss is 01 nn..nn is the binary encoding of NNNN mNNNNNN corresponds to a Memory Space address. The numerical value is: ss is 10 nn..nnn is the binary encoding of NNNNNN Conversion of hexadecimal numbers from text representation to numeric shall be case-insensitive, and leading zeros shall be permitted but not required. Conversion from numeric representation to text representation shall use the lower case forms of the hexadecimal digits in the range a..f, suppressing leading zeroes. Open Firmware implications: Since some processors cannot generate I/O cycles directly, I/O Space accesses must be done with the register access words (e.g. rb@, rw!). It is recommended that a range of virtual addresses be set aside for use by map-in to I/O Space devices so that the register access words can determine when an I/O cycle needs to be generated. Bus-specific Configuration Variables An Open Firmware-compliant User Interface on a system with a single built-in ISA bus _may_ implement the following ISA-specific Configuration Variable. ISA-probe-list ( -- list-str list-len ) [[ It seems appropriate to supply configuration control over probing, but I do not know what form that control should take. ]] Format of a Probe List [[ perhaps this should consist of a list of device paths to attempt to probe, eg "elx@i300 asy@i3f8 asy@i2f8 ...". Built-in OF drivers would be called to do the probes. Alternatively, supply a list of addresses to check for ROM images. Or both. ]] FCode Evaluation Semantics See the description of probe-ISA for the precise specification of the FCode evaluation semantics. Bus Nodes Note: a bridge is a parent of one bus and a child of another. Consequently, a device node representing a bridge is both a Bus Node and a Child node, with both sets of properties and methods. Properties Open Firmware-defined Properties for Bus Nodes The following standard properties, as defined in Open Firmware, have special meanings or interpretations for the ISA bus. "device_type" S Standard prop-name to specify the implemented interface. prop-encoded-array: a string encoded with encode-string. The meaning of this property is as defined in Open Firmware. A Standard Package conforming to this specification and corresponding to a device that implements an ISA bus shall implement this property with the string value "isa". "#address-cells" S Standard prop-name to define the number of cells necessary to represent a physical address. prop-encoded-array: Integer constant 2, encoded with encode-int. The value of "#address-cells" for ISA Bus Nodes is 2. "#size-cells" S Standard prop-name to define the number of cells necessary to represent the length of a physical address range. prop-encoded-array: Integer constant 1, encoded with encode-int. The value of "#size-cells" for ISA Bus Nodes is 1. Bus-specific Properties for Bus Nodes [[ Any? Bus speed? ]] Methods Open Firmware-defined Methods for Bus Nodes A Standard package implementing the "isa" device type shall implement the following standard methods as defined in Open Firmware, with the physical address representations as specified in section 2.1 of this standard, and with additional ISA-specific semantics: open ( -- okay? ) Prepare this device for subsequent use close ( -- ) Close this previously-open device map-in ( phys.lo phys.hi size -- virt ) Map the specified subregion map-out ( virt size -- ) Destroy mapping from previous map-in dma-alloc ( size -- virt ) Allocate a memory region for later use dma-free ( virt size -- ) Free memory allocated with dma-alloc dma-map-in ( .. virt size cacheable? -- devaddr ) Convert virtual address to device bus DMA address dma-map-out ( virt devaddr size -- ) Free DMA mapping set up with dma-map-in dma-sync ( virt devaddr size -- ) Synchronize (flush) DMA memory caches probe-self ( arg-str arg-len reg-str reg-len fcode-str fcode-len -- ) Interpret FCode, as a child of this node decode-unit ( addr len -- phys.lo phys.hi ) Convert text representation of address to numerical representation encode-unit ( phys.lo phys.hi -- addr len ) Convert numerical representation of address to text representation Note: The ISA bus is little-endian; i.e. a byte address whose least-significant two bits are both zero uses the bus byte lane containing the least-significant portion of a 32-bit quantity. Typically, a bridge from a big-endian bus to an ISA bus will swap the byte lanes so that the order of a sequence of bytes is preserved when that sequence is transferred across the bridge. As a result the hardware changes the position of bytes within a 32-bit quantity that is viewed as a 32-bit unit, rather than as a sequence of individually-addressed bytes. In order to property implement the semantics of Open Firmware register access words (e.g. rl!), the device node for such byte-swapping bridges must substitute versions of those words that "undo" the hardware byte-swapping. Child Nodes Note: A bridge is a parent of one bus and a child of another. Consequently, a device node representing a bridge is both a Bus Node and a Child Node, with both sets of properties and methods as appropriate to the bus types connected. Properties Open Firmware-defined Properties for Child Nodes The following properties, as defined in Open Firmware, have special meanings or interpretations for the ISA bus. "reg" S Standard prop-name, defines device's addressable regions. prop-encoded-array: Arbitrary number of (phys-addr size) pairs. phys-addr is (phys.lo phys.hi), encoded as with encode-phys. size is an integer, encoded as with encode-int. This property is mandatory for ISA child nodes, as defined by Open Firmware. The property value consists of a sequence of (phys-addr, size) pairs. Each (phys-addr, size) pair shall specify the address of an addressable region of Memory Space or I/O Space associated with the function. "interrupts" prop-name, the presence of which indicates that the function represented by this node is connected to an ISA bus interrupt line. prop-encoded-array: Integer, encoded as with encode-int. The integer represents the interrupt line to which this function's interrupt is connected. This is value is in the range 0..15 (decimal). [[ Exclude 2?? ]] [[ DMA channel? ]] Bus-specific Properties for Child Nodes Standard Packages corresponding to devices that are children of a PCI bus shall implement the following properties, if applicable. "fcode-rom-offset" S prop-name, denotes offset of FCode image within the device's Expansion ROM. prop-encode-array: one integer. This property indicates the offset of the Expansion ROM image within the device's Expansion ROM in which the FCode image was found; i.e. the offset of the 0xAA55 signature of that image's Expansion ROM Header. This value shall be generated before the FCode is evaluated. Note thast the absence of this property indicates that no FCode exists for this device node. Methods Bus-specific User Interface Commands An Open Firmware-compliant User Interface on a system with an ISA bus should implement the following ISA-specific user interface commands. probe-ISA [[ Probing is, of course, one of the most awkward parts of driving the ISA bus. It isn't clear to me how OF should handle it. ]] [[ OK, here's some on-the-fly thought on probing... Initialize a list of "claimed" addresses and lengths to the null set. Scan the ROM area for ROM images. On finding any, execute their FCode. (This yields reg properties.) Copy the reg properties into the claimed address list. For each built-in driver For each potential address/len for that driver if the address/len does not conflict with any in the claimed list, create temporary device node with reg property execute driver's probe code on failure, delete device node on success, add reg to claimed address list ]] ROM Image Format for FCode: [[ This needs to be checked against the AT spec ]] Offset from start of ROM Image Data 00h-01h ROM signature field of ROM Header 02h-03h Pointer to FCode program. This is a 16-bit field that is the offset from the start of the ROM image and points to the FCode Program. The field is in little-endian format. 04h-17h Reserved. [[...]] ...h-FFFFh The FCode Program can begin anywhere in this range. The FCode Program is as described in Open Firmware; its size is given by the standard Open Firmware FCode Program header. FCode bytes shall appear at consecutive byte addresses. Encapsulated Drivers This section describes a mechanism which allows the encapsulation of run-time drivers within the standard Open Firmware expansion ROM. The FCode contained with a card's expansion ROM provides for Open Firmware drivers for the device. To enhance the "plug-and-play" of cards in common system platforms, it is desirable to be able to include run-time drivers within this expansion ROM, thus eliminating the extra step of installing drivers onto the OS boot device. The information about run-time drivers is encoded as additional standard properties within the device tree. These properties are created by the FCode probe code of the plug-in card, and are used by the OS to locate and load the appropriate driver. Two new properties are defined; they differ as to how the location of the run-time driver is defined. "driver,..." format This property, encoded as with encode-bytes, contains the run-time driver. This format is used when the run-time driver is contained within the FCode image, itself. The value of the property _is_ the encapsulated driver; the prop-addr,prop-len reported by the various "get-property" FCodes and/or getprop Client interface call represent the location and size of the driver within the device tree's data space. I.e., decode-bytes could be used to copy the driver into the desired run-time location. "driver-reg,..." format This property, encoded as with the "reg" standard property, contains a relative pointer to the run-time driver. This format is used when the driver is not directly contained within the FCode image, but rather, is located in some other portion of the Expansion ROM. The value is encoded in a "reg" format, where the address is relative to the expansion ROM's base address. This format conserves device tree (and, FCode) space, but requires the OS to perform the actions of mapping in the Expansion ROM, using the information supplied by this property and the address of the Expansion ROM, and copying the driver, itself. Note: The "fcode-rom-offset" property facilitates the generation of this property within the context of the FCode's image. The driver can be located relative to the ROM image that contains the FCode (but, does not have to be within the FCode, itself) without regard to the location of that ROM image relative to others within the same expansion ROM. I.e., "self-relocating" images containing encapsulated drivers can be creates that can be concatenated with other images without altering any data within an image (except, of course, for the Indicator to properly indicate the last image). Naming conventions The complete property name for these encapsulated drivers is chosen to allow multiple drivers to co-exist within the expansion ROM. An OS will locate its driver by an exact match of its property name among any such "driver," ("driver-reg,") properties contained within the device tree for this device. The formats of the complete names are: "driver,OS-vendor,OS-type,Instruction-set" "driver-reg,OS-vendor,OS-type,Instruction-set" The OS-vendor component is as defined for device-names; i.e., organizational unique identifier (e.g., stock symbol). The OS-type & Instruction-set components are as defined by the OS-vendor. An example would be: "driver-reg,AAPL,MacOS,PowerPC" ----- End Included Message ----- [ P1275 Item #217 -- Received: Tue Jan 3 15:35:42 PST 1995 ]