/* * Copyright 2008 Sun Microsystems, Inc. All rights reserved. * Use is subject to license terms. */ #ident "@(#)pi_pri.txt 1.11 08/05/22 SMI" 4. Technical Description 4.1 Overview PRI structures are updated with amendments to the component node and phys_io node definitions. These changes are required to support the SUN4V Platform Independent Topology Enumerator (PI enumerator, hereafter). 4.1.1 Component node The component node is specified in FWARC/2006/700, and is extended in FWARC/2007/138 and FWARC/2008/291. These cases list the acceptable names and values for type-specific properties. This case makes the following changes: - The 'id' property as specified in FWARC/2006/700 and FWARC/2008/291 is extended to apply to *all* type nodes in the "components" tree - The 'nac' property as specified in FWARC/2006/700 and extended in FWARC/2007/138 is further extended to be required for any node component designated as a FRU (fru = 0x1) - The 'serial_number', 'part_number', 'rev_number' and 'dash_number' properties as specified in FWARC/2007/138 are extended to be required for any node component designated as a FRU (fru = 0x1) - The 'cfg-handle' property is extended to apply to some node components - Two new properties are added: 'topo-hc-name' and 'topo-skip' Properties: Name Tag Req'd? Description ---------------------------------------------------------------------- id PROP_VAL Yes * This property contains the physical id of the component. The id must be unique within a set of nodes with the same 'topo-hc-name' property (i.e. no two nodes where 'topo-hc-name="dimm"' can have the same id, but a node with 'topo-hc-name="dimm"' and a node with 'topo-hc-name="cpu"' can have the same id). * This property must be present on all component type nodes *except* if a node sets topo-skip to non-zero. In this case, the 'id' property can be omitted. Grandfather clause: Irrespective to topo-skip, 'id' must always be provided for strand, cpu-board, and mem-board type nodes. Name Tag Req'd? Description ---------------------------------------------------------------------- nac PROP_STR Yes * This property contains the NAC for the component, as described in the nomenclature document for the system. * This property is only required on node components that are FRUs (fru = 0x1) Name Tag Req'd? Description ---------------------------------------------------------------------- serial_number PROP_STR Yes * This property contains the component serial number contained in the FRUID. * This property is only required on node components that are FRUs (fru = 0x1) Name Tag Req'd? Description ---------------------------------------------------------------------- part_number PROP_STR Yes * This property contains the component part number contained in the FRUID. * This property is only required on node components that are FRUs (fru = 0x1) Name Tag Req'd? Description ---------------------------------------------------------------------- rev_number PROP_STR Yes * This property contains the component revision number contained in the FRUID. * This property is only required on node components that are FRUs (fru = 0x1) Name Tag Req'd? Description ---------------------------------------------------------------------- dash_number PROP_STR Yes * This property contains the component dash number contained in the FRUID. * This property is only required on node components that are FRUs (fru = 0x1) Name Tag Req'd? Description ---------------------------------------------------------------------- cfg-handle PROP_VAL Yes * This property uniquely identifies a device. * Within the components portion of the PRI, this property is only required on node components with 'topo-hc-name="pciexrc"'. Name Tag Req'd? Description ---------------------------------------------------------------------- topo-hc-name PROP_STR Yes * This property contains the libtopo hc canonical name string for the node. This property must be present on all component type nodes. The value of 'topo-hc-name' must be an approved name in "allowable hardware component names list" per FMA's hc scheme [6] * This property must be present on all component type nodes *except* if a node sets topo-skip to non-zero. In this case, the 'id' property can be omitted. Name Tag Req'd? Description ---------------------------------------------------------------------- topo-skip PROP_VAL No When this property is present and has a non-zero integer value, the PI enumerator will not create a topology entry for this node or any of it's children. This property can be used on any component type node. 4.1.2 I/O device node Name Category Required subordinates Optional subordinates ---- -------- --------------------- --------------------- iodevice optional - iodevice, interrupt-map-entry NOTE: The IO Device node is described in the context of an MD in FWARC/2007/070. All of the information in section 4.1.1 of that case's 1-pager apply to the PRI. This case makes the following changes: - A new property, 'chassis-location-name', is added. - The 'slot-names' and 'slot-present' properties as specified in FWARC/2007/070 are now required. Properties: Name Tag Req'd? Description ---------------------------------------------------------------------- chassis-location-name PROP_STR No This property, when present, contains a NAC name string matching a node in the "components" portion of the PRI graph. This property will exist in the device nodes where a FRU boundary has been crossed in the PCIE fabric. It will exist in the first device node entry pertaining to the FRU. This property is *only* for locations within a chassis. It does not apply for slot adapters or any sub-frus external to the chassis itself. This property is only applicable to device types of teh following values: - pcie-switch-upstream - pcie-switch-downstream Name Tag Req'd? Description ---------------------------------------------------------------------- slot-names PROP_STR Yes The 'slot-names' property as described by the IEEE 1275 PCI device binding. This property is only allowed for device types of the following values: - pcie-switch-downstream - pcie-pcix-bridge - pcix-pcix-bridge Name Tag Req'd? Description ---------------------------------------------------------------------- slot-present PROP_VAL Yes The presence of this property means that a PCI slot is present at this device/function number. This property is only allowed for device types of the following values: - pcie-switch-downstream - pcie-pcix-bridge - pcix-pcix-bridge 4.1.3 Guest MD The 'chassis-location-name' property must also be added to the guest MD. OpenBoot must ensure this property is included in the Solaris device tree. Thus, the FMA PCIBUS enumerator can detect when the PCI Express Fabric has traversed into a chassis-internal FRU. The 'chassis-location-name' property is described above. FWARC/2007/070 already specifies that 'slot-names' and 'slot-present' are part of the MD. This case extends those definitions to be required. The propererties are described above. 4.1.4 'chassis-location-name' device node property "chassis-location-name" Type: Prop-encoded string Contents: Name of a FRU location within a Chassis. This property will exist in the device nodes where a FRU boundary has been crossed in the PCIE fabric. It will exist in the first device node entry pertaining to the FRU. This property is an optional property and applies to locations withing a chassis. It does not apply for slot adapters or any sub-frus outside of the chassis itself. 4.1.5 Components (plural) node and hierarchy The sun4v Platform Independent Topology Enumerator [5] walks the "components" (plural) portion of the PRI to construct the topology used by FMA in the Solaris domain. The hierarchy that is in the PRI is directly translated to the resulting hierarchy in Solaris' FMA topology. While the enumerator does not impose any specific hierarchical arrangements of the "components" tree, there are existing sets of diagnosis rules in Solaris that require a specific, relative hierarchy. Furthermore, additional projects [5] are introducing diagnosis rules that require certain nodes to be present. Musts: - The following IO hierarchy *must* be provided in the "components" tree of the PRI: hostbridge/pciexrc. No intervening nodes are allowed. Failure to comply will break PCIE fabric diagnosis rules in Solaris. Node hierarchy above hostbridge is arbitrary per platform. Other guidelines: - If a platform chooses to employ generic SPARC CPU diagnosis engine as defined in [5], or CPU retirement will be done via the cpumem-retire agent in Solaris, one of the following component nodes *must* be present: 'chip', 'core', or 'strand'. One, some or all can be used. The most logical hierarchy is chip/core/strand. - If a platform chooses to employ the generic SPARC memory diagnosis engine as defined in [5], the following memory hierarchy *must* be provided in the "components" tree: memory-buffer/bank/dimm. No intervening nodes are allowed. Node hierarchy above memory-buffer is arbitrary per platform. 5. Reference Documents: [1] FWARC/2006/700 Physical Resource Inventory (PRI) http://sac.eng/FWARC/2006/700 [2] FWARC/2007/070 Machine Description IO Device Node Definitons http://sac.eng/FWARC/2007/070 [3] FWARC/2007/138 Updates to PRI structures http://sac.eng/FWARC/2007/138 [4] FWARC/2008/291 Power Management Core-disable for n2/vf CPUs http://sac.eng/FWARC/2008/291 [5] sun4v Platform Independence projects http://agares.central/twiki/bin/view/Sun4vpi/Sun4v-pi-fma [6] FMA hc scheme canonical names list /ws/onnv-gate/usr/src/lib/fm/topo/libtopo/common/topo_hc.h