#pragma ident	"@(#)vpciv2dot0.txt	1.3	10/04/09 Oracle"

1. Introduction

 Since the 2nd sun4v set of platforms were released and v1.1 of the IO API
 was implemented, the hv implementation has been operating in a backwards
 compatible mode, compensating for client software that does not use the
 iommu attributes in a manner compliant with any version of this interface.

 The hv implementation has refused to negotiate any version > 1.0 of
 the IO API due to these problems, which creates an issue for new interfaces,
 including some related to PCIe performance.

 In order to correct this, new behavior is proposed by this case:

 a. Document the current behavior of the hypervisor for the sun4v PCI IO API,
    versions 1.0, 1.1 and 1.2.

 b. Document new behavior for new client implementations of IO API version 2.0.


2. References

 [1] - FWARC/2005/112 - sun4v IO API v1.0

 [2] - FWARC/2006/474 - sun4v IO API v1.1 (Adds iotte attributes)

 [3] - FWARC/2009/050 - sun4v IO API v1.2 (Adds dma sync "hints")

 [4] - FWARC/2009/268 - sun4v IO API minor update (clarified "R" bit handling)

 [5] - FWARC/2009/537 - sun4v SDIO HV IO API Update (latest rev of io-api.txt)

 [6] - Bugid 6941582 - http://monaco.sfbay.sun.com/detail.jsf?cr=6941582
       Bugid 6894208 - http://monaco.sfbay.sun.com/detail.jsf?cr=6894208

3. Current HV Implementation Behavior.

 a. Current implementations in the field do not support or negotiate
    io api versions 1.1 and 1.2. Only 1.0 is supported.

 b. As described by [4], iotte attributes always include read permission,
    regardless of the attributes arguments in the APIs.

 c. N2/VF implementations (incorrectly) accept and use v1.1 iotte attributes,
    when v1.0 is negotiated. As noted in the first item in this section,
    v1.0 is currently the only version of the IO APIs that can be negotiated.

4. Future HV Defined Behavior.

 The following table describes the new behavior for the IO API group
 (0x100).

 Client Version			HV Behavior
 ===============		===========

 1.0				"R" (Read attribute) implied in all mappings


 1.1				Not negotiated, use 1.0.


 1.2				Not negotiated, use 1.0.


 2.0				Validate all v1.1 IOTTE attributes including
				R, W, L (RO), PP, BDF fields. Reject any
				incorrect arguments per v1.1 io-api spec.

				Use all attributes implemented on this
				platform.

				Note: "R" (Read) attribute is not implied in
				any mapping and must be specified by the client
				if required by the client program.

				Note: v1.2 dma sync flags are deprecated.


 Notes: In all versions, features that aren't implemented on a given
 platform are ignored as described by the specifications. The client
 still needs to use those interfaces in case that feature is implemented
 and required  on some future hw/platform implementation.

5. Deprecate v1.2 Sun4v PCI IO API Features (dma sync flags).

 As described above, no version of the IO API v1.2 interfaces ever
 shipped on a production platform, therefore, the following interfaces
 originally defined in [3] are deprecated by this project:

 a. IO API Group 0x100, Version 1.2 is deprecated (never shipped)

 b. PCI_DMA_SYNC	Fast trap 0x80 function# 0xb8

	- Strike io_sync_attributes definition in io-api.txt section 4.2

	- Strike v1.2 specific text in pci_dma_sync definition in io-api.txt
	  section 4.3.9. (arg3 reverts to io_sync_direction per v1.0 spec)