#ident	"@(#)sun4v-pi-fma-enum-1pager.txt	1.12	08/05/02 SMI"
Location: http://sunwebcollab.east.sun.com/gm/folder-1.11.1781395

1. Introduction

   1.1. Project/Component Working Name:

   "Sun4v FMA Platform Independent FMA Topology Enumeration"

   Implement an FMA topology map and enumerator that applies to all sun4v
   platforms, eliminating the need for platform specific topology putbacks.

   This is a sub-project of the umbrella "Sun4v FMA Platform Independence"
   1-pager, located here:
     http://sunwebcollab.east.sun.com/gm/folder-1.11.1781395

   1.2. Name of Document Author/Supplier:

	Scott Davenport

   1.3. Date of This Document:

	January 23 2008

   1.4. Name of Major Document Customer(s)/Consumer(s):

	1.4.1. The PAC or CPT you expect to review your project:

		Solaris PAC

	1.4.2. The ARC(s) you expect to review your project:

		FWARC, PSARC

	1.4.3. The Director/VP who is "Sponsoring" this project:

		Bill.Nesheim@sun.com
		Quresh.Dhoon@sun.com

	1.4.4. The name of your business unit:

		Software

   1.5. Email Aliases:

    	1.5.1. Responsible Manager:	fadi.salem@sun.com, richard.zatorski@sun.com
    	1.5.2. Responsible Engineer:	scott.davenport@sun.com
    	1.5.3. Marketing Manager:	N/A
	1.5.4. Interest List:		sun4v-pi@sun.com

2. Project Summary

   2.1. Project Description:

	This project will deliver a sun4v-generic FMA topology map and
	a corresponding topology enumerator. These deliverables can and
	will be employed by any sun4v platform, current or future, that
	does not supply its own platform specific topology files.

   2.2. Risks and Assumptions:

	This project is heavily dependent on platform-specific firmware
	to achieve its goal. In particular, the Physical Resource Inventory
	(PRI) constructed by firmware is the sole source of input for
	platform independent enumeration. The accuracy and completeness of
	the PRI will directy impact the resulting topology and its usability
	within Solaris FMA.

3. Business Summary

   3.1. Problem Area:

	FMA represents the hardware hierarchy and attributes of a system in a 
	topology, accessed via libtopo. To construct this topology, FMD reads a
	topology map file, which in turn invokes one or more enumerators.  
	FMD's map selection logic first looks for a platform specific map 
	(/usr/platform/`uname -i`), and if one is not found, an architecture 
	specific map (/usr/platform/`uname -m`).

	Since sun4v systems vary is size, stature, and physical layout,
	it is required that each platform provide its own topology map
	to Solaris at a minimum. Some platforms (e.g. Huron, Batoka)
	require new enumeration work as well, which also requires a
	Solaris putback.

	As FMA is a highly desired feature for any platform at RR, the
	RR becomes gated by FMA putbacks to Solaris. Derivative platforms
	are particularly sensitive to such putbacks, and often the FMA
	topology code changes constitutes 50% of the overall Solaris putback.

   3.2. Market/Requester:

	Refer to the umbrella "Sun4v FMA Platform Independence" 1-pager.

   3.3. Business Justification:

	Refer to the umbrella "Sun4v FMA Platform Independence" 1-pager.

   3.4. Competitive Analysis:

	Refer to the umbrella "Sun4v FMA Platform Independence" 1-pager.

   3.5. Opportunity Window/Exposure:

	Refer to the umbrella "Sun4v FMA Platform Independence" 1-pager.

   3.6. How will you know when you are done?:

	This project will be complete when the sun4v generic topology
	map and enumerator are putback into Solaris.

4. Technical Description:

    4.1. Details:

	The tasks of this project are:
		- Create a sun4v-pi.so enumerator
		  This enumerator will live in /usr/platform/sun4v/lib/fm/topo/
		  plugins. It will walk the components tree of the PRI and
		  construct the topology based on the PRI nodes. The entire
		  topology must be enumerated in the hc scheme. 

		- Revamp topo maps
		  A /usr/platform/sun4v/lib/fm/topo/maps/sun4v-hc-topology.xml
		  file exists today, although the enumerators it invokes and
		  the topology hierarchy that results is almost always 
		  wrong for the platform it's running on. This project will
		  change the content of this map to invoke the sun4v-pi
		  enumerator.

		- Update/Amend FWARC 2007/138
		  This FWARC case specifies the content of the component
		  nodes in the PRI. The case must be amended/updated to
		  reflect any new information required for the sun4v-pi.so
		  enumerator as well as explain how the hierarchy of the
		  PRI components tree becomes the FMA topology.

		  For instance, changes will include adding physical ids for 
		  components, a 'topo-hc-name' property, a 'fru-boundary' 
		  property for components in the fabric (switches, bridges), 
		  and inclusion of hostbridges and root complexes in the 
		  components node. This list will grow as the detailed design 
		  progresses.

		- OpenBoot to include 'fru-boundary' property
		  One of the PRI changes will be the inclusion of a 
		  'fru-boundary' property for PCIE switch devices. OpenBoot 
		  must read that property and include it in the device tree 
		  handed to Solaris. This is required to ensure the correct 
		  FRU for fabric devices is reflected in the topology.

		- Enhance the pcibus enumerator to respect 'fru-boundary'
		  The generic enumerator will walk the PRI, building the
		  topology. When a root complex is encountered, the enum will
		  invoke the pre-existing 'pcibus' enumerator in Solaris to
		  walk the PCIE fabric and add the inforamtion to the topology.
		  The fabric can *not* be represented in the PRI (it may extend
		  beyond the chassis).

		  Today, the pcibus enumerator inherits FRU information from
		  it's parent topo node. Not all platforms have the fabric
		  components on the same FRU as the root complex (ex: Batoka).
		  The 'fru-boundary' property (discussed above) is the method to
		  solve this problem. And, the pcibus enumerator must be changed
		  to use the 'fru-boundary' property, if present, for PCIE 
		  fabric nodes.

		- Restructure components tree on Batoka (prototype)
		  To have the platform independent enumerator construct a
		  meaningful topology, the components tree of the PRI must
		  undergo changes. These changes are specific to a given
		  platform. This task represents PRI changes for Batoka as
		  a prototype platform for the project.

		- Augment the hc schemes canonical names list
		  Every node in the hc scheme must use a name defined in the
		  hc scheme's canonical names list. Since this project aims
		  to eliminate future putbacks to Solaris, it will add some
	 	  new names to the list that are logical projections of what
		  future platforms may desire to represent in a topology (e.g.
		  blade, core, microcore, bridge, riser, sensor, power, fan).

		- FMA Portfolio
		  A small portfolio to reflect the hc canonical names changes
		  will be required. The portfolio will also describe the
		  enumerator. It is expected to be a fast track.

		- FW includes 'slot-names' property in PRI
		  The FW must ensure that the 'slot-names' property in the
		  Solaris device tree is populated with the appropriate
		  NAC names. See FWARC 2007/070 for details. Note: Glendale 
		  does this today, although other platforms have been opting
		  not to implement these properties.

	See ARC case material for interface changes.

    4.2. Bug/RFE Number(s):

	6628827 Need platform independent topo enumeration for sun4v platforms
	6616020 hostbridge association for T5440 PRI
	6631326	Prototype PRI changes for FMA platform independence
	6653751 RFE: PRI available outside Control Domain
    
    4.3. In Scope:

	- Create a sun4v-pi.so enumerator
	- Revamp topo maps
	- Update/Amend FWARC 2007/138
	- OpenBoot to include 'fru-boundary' property
	- Enhance the pcibus enumerator to respect 'fru-boundary'
	- Restructure components tree on Batoka (prototype)
	- Augment the hc schemes canonical names list
	- FMA Portfolio
	- FW includes 'slot-names' property in PRI

    4.4. Out of Scope:

	Complete representation of all future hardware entities in the 
	hc scheme canonical names list. This project will future proof
	as best as possible.

	The following tasks have been moved to out of scope:
		- Guest (non-control) domain access to PRI
		  As noted above, the PRI is the sole source of information
		  for generic enumeration. Currently, the PRI is not available
		  outside of the Control Domain. Enumeration in logical guests
		  and IO Service Domains is required to support IO diagnosis.
		  This task involves an LDOMs domain service channel or proxy
		  to allow a non-control domain to obtain a PRI.

		- ds_pri enhancements
		  This task is related to the PRI availability in guest
		  domains. The existing ds_pri kenel driver will abstract from
		  callers where the PRI is obtained from. Logic must be added 
		  to use the newly introduced service/proxy for PRI access 
		  outside the Control Domain.

	Reason: LDOMs team cannot work these until the LDOMs 1.2 time frame
	(June 2008). These tasks to not change the nature of any of the
	other tasks in the project. Making the PRI available outside the
	Control Domain is needed for a full-feature set for a platform (not
	the enumerator). Supernova has been alerted of this gap and are driving
	a resolution.

    4.5. Interfaces:

	This project depends on an interface agreement between the 
	components tree in the PRI and the Solaris-side enumerator.
	See ARC case material for interface classifications.

	This project also introduces new interfaces to libmdesc for
	walking the PRI.

    4.6. Doc Impact:

	No doc impact.

    4.7. Admin/Config Impact:

	No admin/config impact.

    4.8. HA Impact:

	No HA impact.
    
    4.9. I18N/L10N Impact:

	No I18N/L10N impact.
    
    4.10. Packaging & Delivery:

	The SUNWfmd package will be updated to carry the sun4v generic
	topo map and enumerator. At a minimum, this will be:
	 /usr/platform/sun4v/lib/fm/topo/maps/sun4v-hc-topology.xml
	 /usr/platform/sun4v/lib/fm/topo/plugins/sun4v-pi.so

	System Firmware will include the modifications to the PRI necessary
	for the Solaris-side enumerator.
    
    4.11. Security Impact:

	No security impact.
    
    4.12. Dependencies:

	This project depends on the following CR being fixed:

		6518672 pci enumerator shouldn't assume the platform name 
			in "SUNW,xxx" format

	Note: Fixed in ONNV already, planned for s10u5_b4.

	The aforementioned dependency on the PRI content is also a factor,
	although this project intends to treat FW as an integral part of
	the project, not as an outside dependency.

5. Reference Documents:

   Refer to PSARC 2007/466 for a description of the overall sun4v
   independence effort which this project is a part of.

   FWARC 2007/070 defines the 'slot-names' property for the PRI/MD.

6. Resources and Schedule:

   6.1. Projected Availability:

	The Solaris components of this project are targeting S10U7.
	The delivery of System Firmware components of this project are
	TBD, pending the prototype effort.

   6.2. Cost of Effort:

	Implementation will take roughly 6.5 staff months total.

	Development cost breakdown is as follows:

	Task						Owner	Effort
	----------------------------------------------	-----	----------
	Create a sun4v-pi.so enumerator			SPSW	 8.0 weeks
	Revamp topo maps				SPSW	 0.5 weeks
	Restructure components on Batoka (prototype)	FW	 4.0 weeks
	Augment the hc schemes canonical names list	SPSW	 0.5 weeks
	Update/Amend FWARC 2007/138			SPSW	 2.0 weeks
	OpenBoot to include 'fru-boundary' property	FW	 2.0 weeks
	Enhance pcibus enumerator to respect 		SPSW	 2.0 weeks
	  'fru-boundary'
	FMA Portfolio					SPSW	 2.0 weeks
	FW includes 'slot-names' property in PRI	FW	 2.0 weeks *
	Testing						SPSW	 3.0 weeks
								----------
								26.0 weeks
	* Needs to be validated.

   6.3. Cost of Capital Resources:

	No capital resources are required for this project. However,
	access to suitable sun4v-class machines will be necessary
	for the duration of the project. It is expected that either
	shared time on existing sun4v systems within SPS can be utilized,
	or existing machines can be reallocated to this project.

   6.4. Product Approval Committee requested information:

   	6.4.1. Consolidation or Component Name:

		ON
		System Firmware

	6.4.3. Type of CPT Review and Approval expected:

		FastTrack

        6.4.4. Project Boundary Conditions:

		TBD

	6.4.5. Is this a necessary project for OEM agreements:

		No.

	6.4.6. Notes:

		None.

	6.4.7. Target RTI Date/Release:

		TBD

	6.4.8. Target Code Design Review Date:

		TBD

	6.4.9. Update approval addition:

		N/A

   6.5. ARC review type:

	FastTrack

7. Prototype Availability:

   7.1. Prototype Availability:

	N/A

   7.2. Prototype Cost:

	N/A