------- io-api.txt -------
1c1
< #pragma ident	"@(#)io-api.txt	1.37	09/07/13 SMI"
---
> #pragma ident	"@(#)io-api.txt	1.39	09/10/06 SMI"
32a33,35
> [6] Sun4v PCI Error Packet Definitions
> 	http://pciexpress.sfbay/fma/docs/sun4v-err.txt
> 
430a434,435
> 	EWOULDBLOCK	io domain not ready for config space access
> 			(See section 6.3.1)
487a493,494
> 	EWOULDBLOCK	io domain not ready for config space access
> 			(See section 6.3.1)
886c893
< 5.3	MSI Services
---
> 5.3	MSI API Definitions
1225a1233,1447
> 
> 6.  SDIO Services.
> 
> 
> 6.1 SDIO Services Function Number and Group Definitions
> 
> 
> 6.1.1. PCI_IOV_SDIO_GROUP (Group number 0x108)
> 
> 	PCI_IOV_ROOT_CONFIGURED		0xf8
> 	PCI_REAL_CONFIG_GET		0xf9
> 	PCI_REAL_CONFIG_PUT		0xfa
> 
> 6.1.2. PCI_ERROR_MODEL (Group number 0x109)
> 
> 	 PCI_ERROR_SEND			0xff
> 
> 6.2.  SDIO Definitions
> 
> 	root domain
> 
> 	    A domain that owns configuration and mangement of a sun4v pci
> 	    virtual root complex.
> 
> 	io domain
> 
> 	    A domain that has access to devices *below* a sun4v pci virtual
> 	    root complex but is not the root domain.
> 
> 6.3.  SDIO API Definitions.
> 
> 6.3.1.	 pci_iov_root_configured
> 
> 	trap#		FAST_TRAP
> 	function#	PCI_IOV_ROOT_CONFIGURED (0xf8)
> 	arg0		devhandle
> 
> 	The root complex identified by devhandle is ready to be shared.  The
> 	root domain guest calls this when it's ready for other io guests to
> 	begin using shared devices under the root complex identified by the
> 	argument devhandle, which must be the devhandle of a root complex
> 	device node owned by this guest.
> 
> 	This call is an indication to the hypervisor that any other guest
> 	sharing the devices under this root complex may now access the
> 	configuration space of those devices.
> 
> 	In any io guest domain, pci_config_get and pci_config_put shall return
> 	EWOULDBLOCK on any attempted access to config space under the root
> 	complex defined by the argument devhandle until this API is called in
> 	the root domain. If the root domain is reset, behavior reverts back to
> 	the initial behavior until this API is called in the root domain.
> 
> 6.3.1.1	Errors
> 
> 	EINVAL		Invalid devhandle
> 	ENOACCESS	No access - not root domain for this RC devhandle
> 
> 
> 6.3.2	pci_real_config_get
> 
> 	trap#		FAST_TRAP
> 	function#	PCI_REAL_CONFIG_GET (0xf9)
> 	arg0		devhandle
> 	arg1		pci_device
> 	arg2		pci_config_offset
> 	arg3		size
> 
> 	ret1		error_flag
> 	ret2		data
> 
> 	Read real PCI configuration space for the pci adaptor defined by
> 	the argument devhandle.
> 
> 	Read size (1, 2 or 4) bytes of data for the PCI device defined
> 	by the argument pci_device, from the offset from the beginning
> 	of the configuration space defined by the argument pci_config_offset.
> 	If there was no error during the read access, set ret1 (error_flag)
> 	to zero and set ret2 to the data read. Insignificant bits in
> 	ret2 are not guaranteed to have any specific value and therefore
> 	must be ignored.
> 
> 	The data returned in ret2 is size based byte swapped.
> 
> 	If an error occurs during the read, ret1 (error_flag) shall be set
> 	to one of the following values:
> 
> 	0x2 indicates that the config space register access did not succeed
> 	due to an error other than Config Request Retry Status(CRS).
> 
> 	0x4 indicates that the config space register access did not succeed
> 	due to CRS.
> 
> 	pci_config_offset must be 'size' aligned.
> 
> 
> 6.3.2.1	Errors
> 
> 	EINVAL		invalid devhandle/pci_device/offset/size
> 	EBADALIGN	pci_config_offset not size aligned
> 	ENOACCESS	Access to this offset is not permitted
> 			or not root domain for this RC devhandle
> 
> 
> 6.3.3	pci_real_config_put
> 
> 	trap#		FAST_TRAP
> 	function#	PCI_REAL_CONFIG_PUT (0xfa)
> 	arg0		devhandle
> 	arg1		pci_device
> 	arg2		pci_config_offset
> 	arg3		size
> 	arg4		data
> 
> 	ret1		error_flag
> 
> 	Write real PCI config space for the pci adaptor defined by the
> 	argument devhandle.
> 
> 	Write 'size' bytes of data in a single operation. The argument
> 	'size' must be 1, 2 or 4. The configuration space address is described
> 	by the arguments pci_device and pci_config_offset. pci_config_offset is
> 	the offset from the beginning of the configuration space given by the
> 	argument pci_device. The argument 'data' contains the data to be
> 	written to configuration space.  Prior to writing the data is
> 	size based byte swapped.
> 
> 	If an error occurs during the read, ret1 (error_flag) shall be set
> 	to one of the following values:
> 
> 	0x2 indicates that the config space register access did not succeed
> 	due to an error other than Config Request Retry Status(CRS).
> 
> 	0x4 indicates that the config space register access did not succeed
> 	due to CRS.
> 
> 	pci_config_offset must be 'size' aligned.
> 
> 	This function is permitted to read from offset zero in
> 	the configuration space described by the argument pci_device
> 	if necessary to ensure that the write access to config space
> 	completes.
> 
> 
> 6.3.3.1	Errors
> 
> 	EINVAL		invalid devhandle/pci_device/offset/size
> 	EBADALIGN	pci_config_offset not size aligned
> 	ENOACCESS	Access to this offset is not permitted
> 			or not root domain for this RC devhandle
> 
> 
> 6.3.4.	pci_error_send
> 
> 	trap#		FAST_TRAP
> 	function#	PCI_ERROR_SEND
> 	arg0		devhandle
> 	arg1		devino
> 	arg2		pci_device
> 
> 	Send an error epkt to any io guest sharing the device identified
> 	by the argument pci_device in the fabric identified by the argument
> 	devhandle.
> 
> 	devhandle must be the devhandle of a PCI root complex, owned by
> 	this guest. devino must be the devino associated with pci error
> 	packets for this root complex.
> 
> 	pci_device is the device reporting the error. If pci_device is
> 	zero, all other guests sharing this pci fabric will receive an
> 	error packet. If pci_device is non-zero, only those guests sharing
> 	the device identified by the pci_device argument will receive the
> 	error packet.
> 
> 	The error packet is delivered to the dev mondo queue of the io guest
> 	sharing this device, if any. The first entry, SYSINO, will be the
> 	correct value for the devhandle, devino in that guest that represents
> 	the shared root complex, identified by the arguments devhandle,
> 	devino for this guest.
> 
> 	Note: The epkt is never delivered to the domain that called this API.
> 
> 	error packet details:
> 
> 	The following document defines the contents of pci error packets:
> 
> 	- http://pciexpress.sfbay/fma/docs/sun4v-err.txt
> 
> 	The packet shall contain the following:
> 
> 	0x00	sysino - devhandle, devino of io guest's root complex
> 	0x08	ehdl# - unique error handle - generated/managed by HV
> 	0x10	stick - the value of the %STICK% register
> 	0x18	DESC (see below), Error Specific - 0
> 	0x20	0
> 	0x28	0
> 	0x30	0
> 	0x38	0
> 
> 
> 	The DESC field shall contain the following values:
> 
> 	31:28 - Block - value 1 - hostbus
> 	27:24 - Op - Value 0
> 	23:20 - Phase - Value 0
> 	19:16 - Cond - Value 0
> 	15:12 - Dir - value 0
> 	11:0 - Flags, bit 11 (STOP) Set, everything else Clear.
> 
> 
> 6.3.4.1. Errors
> 
> 	EINVAL	- Invalid devhandle, devino or pci_device
> 	ENOACCESS - Not owner of devhandle (not root domain)
>