Date: Fri, 11 Apr 1997 12:21:27 -0700 From: tarl@faraway (Tarl Neustaedter) Subject: Item #408: Proposed Bus Binding for IEEE 1394/firewire P1275 Openboot Working Group Proposal -- Proposal #:408 Ver 0.5 Title: Binding for IEEE 1394/Firewire Bus Author: Tarl Neustaedter Date: 11-April-1997 Ed/Tech: Technical Synopsis: A proposed bus binding for IEEE 1394/Firewire is presented Doc & Version: New Document Problem: There is interest in developing a document for the bindings between Open Firmware and the IEEE 1394 serial bus. Proposal: IEEE 1394-1995 Bus Binding to IEEE Std 1275-1994 Version 0.5 1. Overview and References This document specifies the application of Open Firmware to the IEEE 1394 (Firewire) serial bus. 1.1 Revision History Revision 0.0, 97-02-26, Initial Revision Revision 0.1, 97-02-27, Cannot use 5 address cells. Make children of multi-unit devices hierarchical to avoid luid in unit addr. Revision 0.2, 97-03-03, Eliminate hierarchy. Use Unit_Location (required for multi-unit devices) in reg spec & unit address. Revision 0.3, 97-03-05, Remove SBP-2 specifics - they belong in a device-specific binding, not a bus binding. Revision 0.4, 97-03-12, Add isochronous methods. tcp/ip is likely to use the isochronous channels, so tftpboot will need methods. Revision 0.5, 97-03-24, Add node vendor/hw version to list of name generating fields. See figure 53 of IEEE 1212 [4]. 1.2 References [1] IEEE 1275-1994 Standard for Boot (Initialization Configuration) Firmware: Core Requirements and Practices [2] IEEE 1394-1995 Standard for a High-performance Serial Bus [3] 1394 Open Host Controller Interface Specification, Draft 0.9 [4] ISO/IEC 13213 ANSI/IEEE Std 1212 Control and Status Registers (CSR) architecture for microcomputer busses 1.3 Definition of Terms GUID. Globally unique Identifier. A 64-bit extended version of the 48-bit IEEE Global identifiers used as MAC addresses. 2 Bus Characteristics While 1394 is a serial bus, it is also a memory-mapped bus. The address space is 64 bits, which are subdivided into sixteen bits of device number and 48 bits of address space within the devices. These are each further subdivided as described below. The 1394 bus topologies can vary considerably, but we will provide an abstraction of a flat address space. All 1394 device nodes will hang directly off the adapter node, with a unit address based on the GUID and local unit address. 2.1 Physical address formats and representations 2.1.1 Physical address format 2.1.1.1 Numerical Representation The numerical representation of a 1394 address consists of four cells, encoded as follows: Bit# 33222222 22221111 11111100 00000000 10987654 32109876 54321098 76543210 guid.hi cell: gggggggg gggggggg gggggggg gggggggg guid.lo cell: gggggggg gggggggg gggggggg gggggggg phys.hi cell: zzzzzzzz zzzzzzzz mmmmmmmm mmmmmmmm phys.lo cell: mmmmmmmm mmmmmmmm mmmmmmmm mmmmmmmm Where: gg...gg is the 64-bit GUID used to identify a 1394 device. zz...zz must be zero. These are reserved for future expansion. mm...mm is the 48-bit memory space address within the device. 2.1.1.2 Text Representation The text representation of a 1394 address is as follows: GGGGGGGGGGGGGGGG[,AAAAAAAAAAAA] Where GGGGGGGGGGGGGGGG is an ASCII hexadecimal number in the range 0..(2^64)-1, containing the device's GUID. AAAAAAAAAAAA is an ASCII hexadecimal number in the range 0..(2^48)-1, containing a 1394 memory address. This is optional and defined to be zero if not present. Note that the simplest 1394 devices will have unit-addresses with only the GUID visible. Individual units on multi-unit devices will be allocated sub-ranges of the device's 48-bit address space, and thus will show the full GUID,ADDR unit-address. 2.2 Bus-specific configuration variables None. 3 Bus Nodes 3.1 Properties 3.1.1 Open Firmware-defined properties for Bus Nodes The following standard properties, as defined in Open Firmware, have special meanings or interpretations for PCI: "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 a 1394 bus shall implement this property with the value "IEEE-1394". "#address-cells" S Standard prop-name to define the number of cells necessary to represent a physical address. prop-encoded-array: Integer constant 4, encoded as with encode-int. The value of "#address-cells" for 1394 Bus Nodes is 4. "#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 2, encoded as with encode-int. The value of "#size-cells" for 1394 Bus Nodes is 2, reflecting 1394's 48-bit address space. "reg" S Standard prop-name to define the package's unit-address. 3.1.2 Bus-specific properties for Bus Nodes Standard packages corresponding to devices that are 1394 nodes shall implement the following property, if applicable: "interface" S A property name which defines the interface to the 1394 node. Its value is an encoded array, encoded as with encode-string. If the bus node implements an Open HCI interface (see [3]), the value shall be the string "ohci". Other interfaces, as they are implemented, should use a different string. 3.2 Methods 3.2.1 Open Firmware-defined methods for bus nodes A package implementing the "1394" device type shall implement the following standard methods as defined in Open Firmware. open ( -- okay? ) Prepare this device for subsequent use. If necessary, download firmware to the adapter. close ( -- ) Close this previously opened device. decode-unit ( addr len -- guid.hi guid.lo phys.hi phys.lo ) Decodes a unit address. encode-unit ( guid.hi guid.lo phys.hi phys.lo -- addr len ) Encodes a unit address. dma-alloc ( size -- virt ) Allocate a memory region for later use. dma-free ( virt size -- ) Free memory allocated with dma-alloc. map-in ( guid.hi guid.lo phys.hi phys.lo size -- virt ) Map the specified subregion. Note that some 1394 bus controllers (most notably OpenHCI) do not provide this function. map-out ( virt size -- ) Destroy mapping from a previous map-in dma-map-in ( .. virt size cacheable? -- devaddr.hi devaddr.lo ) Convert the virtual address to a 1394 bus address. The 1394 bus address includes our bus#/node#, so becomes obsolete on the next 1394 bus reset. dma-map-out ( virt devaddr.hi devaddr.lo size -- ) Free DMA mapping set up with dma-map-in. 3.2.2 Bus-specific methods for bus nodes A package implementing the "1394" device type shall implement the following standard methods as defined in Open Firmware, with physical address representations as specified in 2.1: phy-read ( reg -- value ) Reads a particular 8-bit phy register. phy-write ( reg value -- ) Writes a particular value to a particular phy register. send-async-req ( pktptr -- okay? ) Allocates dma descriptors, puts the packet on the asynch send context and waits for the indication that the packet has been received by the far end. Does not free packet. send-async-rsp ( pktptr -- okay? ) Allocates dma descriptors, puts packet on the async send_rsp context, and waits for indication that it has been received on the far side. Does not free packet. send-isochronous ( channel pktptr -- okay? ) Allocates dma descriptors, puts packet on the dma engine assigned to the specified channel. Does not wait for transmission to complete. Cleans up any previous packets which have been finished. recv-async-req ( -- pktptr | 0 ) Looks in the recv queue for a packet and gives one to user. If empty, a null pointer is returned. recv-async-rsp ( -- pktptr | 0 ) Looks in the recv response queue and gives one packet to the user. If empty, a null pointer is returned. recv-isochronous ( channel -- pktptr | 0 ) Looks in the receive queue for the dma engine associated with the specified channel and returns a packet or the null pointer. alloc-packet ( size -- pktptr ) Allocate a packet. free-packet ( pktptr -- ) Frees a packet. 4 Child nodes Child nodes are either entire 1394 devices, or in the case of multi-unit devices, each unit within the device is a child-node. 4.1 Properties for Child Nodes 4.1.1 Open Firmware-defined Properties for Child Nodes The following properties, as defined in [1], have special meanings or interpretations for 1394. These properties shall be created for each device discovered when the 1394 bus is probed. "name" S Standard prop-name, whose value is an encoded array, encoded as with encode-string, that defines the name of the node. The name is of the form firewireVVVV,DDDD. VVVV and DDDD are ASCII hexadecimal numbers, lower case, without leading zeroes. VVVV is a vendor ID, and DDDD is a version. These numbers derive from the first of the following pairs to exist: 1) Unit_Spec_Id, Unit_SW_Version 2) Node_Spec_Id, Node_SW_Version, 3) Node_Vendor_Id, Node_Hw_Version 4) Module_Spec_Id, Module_SW_Version 5) Module_Vendor_Id, Module_HW_Version See IEEE 1212 [4] Chapter 8 (ROM Specification) for details on these ROM directory entries. [The above prefix "firewire" will probably be changed when the 1394 naming comittee votes in april '97] "compatible" S Standard prop-name, defines devices with which this device is compatible. Prop-encoded array: The concatenation, as with encode+, of an arbitrary number of text strings, each encoded with encode-string. The default values of this property will include all three possible names defined for the "name" property. Specifically, firewireVVVV,DDDD where VVVV and DDDD consist of: 1) Unit_Spec_Id, Unit_SW_Version 2) Node_Spec_Id, Node_SW_Version, 3) Node_Vendor_Id, Node_Hw_Version 4) Module_Spec_Id, Module_SW_Version 5) Module_Vendor_Id, Module_HW_Version The above list is in order from most-specific (unit_spec) to least specific (module_vendor). "reg" S Standard prop-name to define the package's unit-address. The format for the reg property consists of six cells per register set, four for address and two for size. 1394 devices with minimal ROMs will define a single reg property encompassing their full 48-bit addresses. 1394 devices with multiple units or more specific ROMs (that is, devices with unit directories present in the ROM) will define reg properties for each Unit_Location entry in the unit directory. 4.1.2 Bus-specific properties for child nodes "guid" S Globally unique 64-bit identifier for the child node. This is used to form the unit address for the device node. 4.2 Child node methods 4.2.1 Open Firmware-defined methods for child nodes open ( -- okay? ) Prepare this device for subsequent use. close ( -- ) Close this previously opened device. dma-alloc ( size -- virt ) Allocate a memory region for later use. dma-free ( virt size -- ) Free memory allocated with dma-alloc. 4.2.2 Bus-specific methods for child nodes id ( -- address ) This method returns the current bus#/node# of the 1394 device, as an integer in a single cell. This is a real-time variable quantity so cannot be a property. speed ( -- speed ) This method returns the current speed to the child node. The returned value is in MHz, as an integer. Current supported values are 100, 200, and 400, but we expect higher values soon. This value is also real-time variable quantity, so cannot be a property. ports ( -- neighbors ) This method returns an encoded integer array with the ids of neighbors connected through each port. This method does not distinguish between parents and children. do-transaction ( read|write|xTcode offset addr len -- okay? ) This method performs a read, write or lock transaction and waits for completion. The first argument ( read|write|xTcode ) uses the constants -1 to indicate read and -2 to indicate write. The values 0..(2^16)-1 indicate an xTcode, which in turn indicates that the requested operations is a lock transaction. In the case of read transactions, the returned data is copied into the addr/len buffer, in the case of write transactions, data is copied out of the addr/len buffer. In the case of a lock transaction, the data is copied both before and after the transaction. This method resolves into into a series of send/recv packet/responses at the bus node. [ P1275 Item #408 -- Received: Fri Apr 11 12:21:46 PDT 1997 ]