#pragma ident	"%Z%%M%	%I%	%E% SMI"

ARI Support in Open Firmware.

1. Introduction

ARI, Alternative Routing ID Interpretation, is a PCI Express ECN, approved
in 2007, and incorporated into the PCI Express base specs, and used by the
SR-IOV Specs.

ARI allows a PCI Express device to implement more than 8 Functions.

ARI, an optional feature in root ports and downstream switch ports, when
enabled, allows extended Function numbers to be visible in a PCI Express
device. Support for ARI is present if the ARI Capable bit in the Device
Capabilities 2 Register is Set. Support for ARI is enabled by setting the
ARI Enable bit in the Device Control 2 Register. Both registers are part
of the PCI Express Capability.

The following description is an abbreviated summary of how ARI works.
For a complete description, see [1] section 6.13.

ARI works by using all of the 'd' bits in the RID (Routing ID) as extended
function number bits.

Thus, when ARI is enabled the RID must be interpreted as:

  bbbb.bbbbb.ffff.ffff with an implied device number of 0

rather than:

  bbbb.bbbb.dddd.dfff

when ARI is not enabled.

Note that without ARI support or if ARI support exists but is not enabled,
downstream switch and root ports are required to block any config space
transaction with a non-zero device number (in the ddddd bits of the RID)
on the secondary bus as part of converting a config space transaction from
type 1 to type 0.

The ARI ECN modifies that behavior if the downstream bridge or root port
supports ARI and that support is enabled, it does not block any config
space transactions that would normally be converted to type 0 and passed
to the secondary bus. However, the interpretation of the RID is changed,
as described above so that there are up to 256 Functions, and the device
number is always 0. Note that the default value of the ARI Enable bit is 0,
thus the support, by default, is not enabled.

Existing software and firmware must be modified to support ARI, since the
traditional interpretation of the RID would be incorrect when that support
is enabled.

In general, the firmware doesn't know if the OS it will be booting supports
the alternate RID interpretation when ARI is enabled, so it can't just enable
this support and probe for ARI-enabled devices on existing platforms. The
behavior must be controlled by a platform specific method, the platform team
knows that the minimum supported OS supports ARI.

The remainder of this document defines changes to the PCI Binding
to Open Firmware, as amended for PCI Express and by several cases,
to include ARI support.

2. Probing algorithm changes.

2.1. Add ARI support to the PCI Express probing algorithm:

If ARI support is enabled on this platform {
  If this node is either a root port or a downstream switch port {
    If the PCI Express Capability version is greater than 1 {
      If ARI Forwarding Supported is Set in Device Capabilities 2 {
        Let b = this bridge node;
        Let f = function #0 on the secondary bus# below the bridge;
        if Function f exists and includes the ARI capability {
          Set ARI Forwarding Enable in Device Control 2 in this bridge node b;
          publish the property "ari-enabled" in this bridge node b;
	  Probe devices
        }
      }
    }
  }
}

If any of the checks fails then do normal probing of all the devices.

Notes:

a. Device Capabilities 2 and Device Control 2 are in the PCI Express Capability.

   These registers do not exist in the PCI Express Capability unless the
   PCI Express Capability version (in the PCI Express Capabilities Register)
   is greater than 1.  If the PCI Express Capability version is 1,
   PCIe spec-compliant ARI Forwarding is not supported.

b. ARI Forwarding Supported is applicable only to root ports and downstream
   PCI Express switch ports.

c. The configuration variable pcie-ari-enabled? is defined in section 4.

d. See also [1] sections 6.13 and 7.23.


2.2. Probe PCIe Devices for ARI Functions, when ARI is enabled.

When ARI support is enabled in the immediate parent of a PCI Express
device, the firmware shall probe that child for all possible Functions.

Note: The firmware may optimize this probing. The above sentence does
not imply a blind probe of all 256 Functions. The firmware may use
the multi-function bit in Function 0 and/or the ARI capability linked
list to optimize probing if it chooses to. See also [1] section 7.23.


3. Unit Address for ARI Enabled Functions.

If ARI is enabled in the downstream switch port or root port above
this PCIe Function, the numeric form of the address is interpreted as:

	bbbb.bbbb.ffff.ffff, with an implied device# of 0.

	where bbbb.bbbb is the bus number.
	and ffff.ffff is the Function number.

	as defined in the PCI Binding to Open Firmware.

The unit address format is DD[,F], as defined in the PCI Binding to Open
firmware with the following addition:

  If ARI is enabled in the parent of this Function:

   - DD is 0 and F is an ASCII hexadecimal number in the range 0 .. FF.

   - In the canonical form, leading zeroes are omitted and if the Function
     number is zero, the form is DD, where DD is 0.

When ARI is enabled, the encode-unit and decode-unit methods of
ARI-enabled Functions are modified to interpret and publish the
unit address as defined above.

4. pcie-ari-enabled? Configuration Variable

New optional configuration variable:

  pcie-ari-enabled?	( -- enabled? )			N

  If true, enable ARI in root and downstream switch ports, if that port
  supports ARI and the device immediately "below" that port supports ARI.
  Publish the property "ari-enabled" in that node if ARI is enabled in that
  node. If ARI is enabled, the behavior of encode-unit and decode-unit is
  modified to support ARI extended function numbers.

  The default value is platform specific. On existing platforms, the
  default is false. On new platforms, where the minimum supported OS
  contains ARI support, the default may be true.


5. "ari-enabled" property in pci-pci bridge nodes.

  "ari-enabled"						S

  Standard property name to indicate that ARI is enabled in a
  root or downstream switch port.

  prop-encoded-array: No value. The existence of the property
  indicates that ARI is enabled in this node.

6. "pcie-ari-supported" property in the root node.

   "pcie-ari-supported"					S

   Standard property name to indicate that ARI support exists and is
   enabled by the firmware on this platform.

   prop-encoded-array: No value. The existence of the property
   indicates that ARI is supported for this platform.

   
7. References.

[1] PCI Express Base Spec, v2.1, available at pcisig.com
    Note: See Section 6.13, ARI.

[2] Single Root IO Virtualization, available at pcisig.com

[3] PCI Binding to Open Firmware, available at http://playground.sun.com/1275

[4] PCI Express Binding Update - FWARC/2005/565