Date: Mon, 8 Jan 96 15:08:53 PST
From: mwi@FirmWorks.COM (Mark Insley)
Subject: Item #303: PCI Bus Binding: Create reserved word in the PCI node


P1275 Openboot Working Group Proposal -- Proposal #:303 Ver 1

Title:          Addition of Reserverd Word to PCI Node

Author:         Mark Insley

Date:           January 8th, 1996

Ed/Tech:        Technical

Synopsis:       Proposal to change an existing word in Apple's OFW to a reserved word
		to allow driver code to modify calls to "map-in" method.

Doc & Version:  PCI Bus Binding   Version 1.5

Problem:        

   There is an incompatible difference in the current implementation of
   the "map-in" method of the PCI node between Sun's, Firmworks' and Apple's
   implementation of OFW.
   
   The syntax for map-in is defined as:
   
   	( phys.lo ... phys.hi size -- virt )
   
   For a machine with a 3 cell address, an example map-in for a PCI device
   might look like:
   
   	0 0 my-space /regs map-in to virt-addr
   
   The incompatibility lies in the specifics of the phys.lo address.
   
   The current Apple OFW implementation always interprets the phys.lo as
   an absolute address. For a map-in call to work on current Apple
   machines, the phys.lo parameter must be set equal to the value of the
   assigned-addresses property.
   
   This should only be done if the "n" bit (bit 31) of the phys.hi
   address is equal to 1. If the "n" bit is 0, then the phys.lo address
   should be an address "offset" relative to the base address of the PCI
   slot.
   
   According to the PCI Bus Binding document (Rev 1.5, pages 6 and 7),
   the phys.lo address is defined as the 32-bit offset from the start of
   the relocatable region of IO space (if the "ss" bits of phys.hi = 00)
   or the 32-bit offset from from the relocatable region of 32-bit
   address Memory Space (if the "ss" bits of phys.hi = 10) or the 64-bit
   offset from the start of the relocatable region of 64-bit address
   Memory Space to the start of the subregion (if the "ss" bits of
   phys.hi = 11).
   
   PCI device drivers developed originally on Apple hardware will not
   work correctly on hardware based on Sun's or Firmworks' OFW. And the
   reverse is true as well, drivers developed on platforms with Sun's and
   Firmworks' OFW will not work correctly on Apple hardware unless the
   driver was written by someone who knows about this problem.
   
   Code must be added to PCI drivers to determine what needs to be done.
   There is no escaping this. If the hardware runs OFW from Sun or
   Firmworks, then the map-in call needs to have phys.lo set to the offset
   address. If the driver is running on Apple hardware with current OFW,
   then the phys.lo address must be determined by extracting the physical
   address from the assigned-addresses property. If the driver is running
   on Apple hardware with a corrected map-in method, then the phys.lo is
   set to the offset value as in the Sun and Firmworks case.
   
   We also want to make this as painless to implement as possible, so we
   want the decision tree to be simple for the driver code. What we are
   recomending is that when Apple releases a new version of their OFW,
   one of the non-mandatory methods of the PCI node be renamed. The
   method we specifically have in mind is "add-range".
   
   Drivers can do a single test by using "find-method", searching the
   parent pci node. If the find-method returns true, then the driver
   knows both that this is an Apple machine and that it must use the
   assigned-addresses property to form the phys.lo parameter for the
   map-in method.
   
   If the find-method fails, then the driver knows to use the offset it
   wants for phys.lo. This because neither Sun nor Firmworks currently
   define the add-range method, and given the proposal, correct versions
   of Apple OFW will not use it either. Another assumption here is that
   for all future versions of anyones implementation of OFW, no one can
   use "add-range" as a method in the PCI node.

Proposal:       

   The specific proposal then is to add a footnote to the PCI Bus
   Bindings document in the Methods section (starting on page 11):
   
   The method "add-range" is reserved and shall not be implemented in
   future releases of OFW. The presence of this method in the PCI node
   indicates to child nodes that the "map-in" method of this bus node
   requires the phys.lo address to be extracted from the
   "assigned-addresses" property. The non-existance of this method
   indicates to child nodes that the phys.lo address is an offset
   relative to the base address.



[ P1275 Item #303 -- Received: Mon Jan  8 15:07:27 PST 1996 ]