OpenSolaris

FLAG DAY: libtopo changes

Date: Fri, 03 Nov 2006 21:04:23 -0800
From: Cynthia McGuire <cindi at sun dot com>
To: onnv-gate at onnv dot eng dot sun dot com, on-all at eng dot sun dot com
Subject: FLAG DAY: libtopo changes

This is a multi-part message in MIME format.
~--------------000002090600000005060408
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

~--------------000002090600000005060408
Content-Type: text/plain;
 name="flag-day"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="flag-day"

Today's putback for:

	6421101 fmsim doesn't allow simulated topology to be specified with
	6448718 libtopo needs better enum module APIs
	6467144 topo_fmri_str2nvl doesn't handle authority or properties
	6477430 Need ability to load additional libtopo map files
	6477442 libtopo should allow alternate platform topo map files
	6480930 fmtopo should support a -x option

represents a flag day for libtopo enumerator module writers.  You should not
mix and match libtopo modules or .xml files across this flag day.  As usual,
BFU can be used to get you a consistent system.  A number of files have
changed or been removed; to avoid problems with protocmp and makebfu you
should do a clobber build in usr/src/lib/fm/topo before you bringover the
changes from the libtopo putback.  After the libtopo changes have been brought
over, you will need to remove the hc-topology.xml files in
$ROOT/usr/platform/*/lib/fm/topo.  Specific flag day details are described
below.

This project introduces a number of feature enhancements to the project private
libtopo enumerator module API.  These features and the rest of the libtopo
module API will be documented in an upcoming revision to the Fault Management
Daemon Programmer's Reference Manual.

   Enumerator-based .xml file loading
      Additional .xml topology map files may be loaded and parsed at the
      request of an enumerator module.  This feature permits subsystem-specific
      enumeration from a static topology map file and shared across
      platforms.  For example, a common topology for the SCSI susbsystem may be
      loaded from a platform-specific PCI hostbridge enumerator.

   Alternate platform or product specific .xml topology files
      This feature allows platforms to share or separate topology maps
      located in /usr/platform/`uname -i`/lib/fm/topo/maps or
      /usr/platform/`uname -m`/lib/fm/topo/maps.  For example,
      the SUNW,T1000 (Erie) platform may specify a different hc-topology.xml
      topo map from the SUNW,T200 (Ontario) but still share a /usr/platform
      link.

      This feature also permits us to deliver alternate hc-topology.xml files
      based upon product id.  For example, the DIMM topologies for the Sun
      Fire X4200 and the Sun Blade x8400 may be uniquely specified and allow
      fine grained control of slot location.

   Full simulation support under fmsim
      Full simulation of toplogies in a fmsim environment is now supported.
      With this feature, we can test diagnosis and agent software designed for
      one system and but run it on another.  This helps us test large
      configurations on smaller systems (say, a laptop), write customer fault
      management demo tools and perform post-mortem analysis diagnosis software
      based upon customer errlogs and fltlogs.

   New fmtopo display options.
      The internal utility /usr/lib/fm/fmd/fmtopo, supports three new
      command line options and better libtopo module debug facilities.

         -P [property-list]: display FMRIs according to property-list.

   # fmtopo -P io,pci
   TIME                 UUID
   Nov 03 10:56:04 9a747498-f83b-cfe8-8221-8fbeec9ad5af

   hc://:product-id=SUNW,Sun-Fire:server-id=monica-a/centerplane=0/ioboard=8/hostbridge=1/pcibus=1/pcidev=1/pcifn=0/pcibus=1/pcidev=0/pcifn=1
     group: io                           version: 1   stability: Private/Private
       dev               string    /ssm@0,0/pci@1d,700000/pci@1/SUNW,hme@0,1
       devtype           string    network
       driver            string    hme
     group: pci                          version: 1   stability: Private/Private
       device-id         string    1001
       class-code        string    20000
       vendor-id         string    108e

         -p: display FMRIs protocol properties (ASRU, FRU and resource)

   # fmtopo -p
   TIME                 UUID
   Nov 03 10:56:53 d5c302e5-7bc9-4300-829b-e11ab5d857e0

   hc://:product-id=SUNW,Sun-Fire:server-id=monica-a:serial=110807130CB/centerplane=0/cpu=11
           ASRU: cpu:///cpuid=11/serial=110807130CB
           FRU: hc:///component=/N0/SB2
           Label: /N0/SB2

         -x: display a .xml formatted (according to
             /usr/share/lib/xml/dtd/topology.dtd.1) topology for the current
            environment.

   Support for FMRI authority (chassis, server and product identification)
      FMRIs for new platforms will now include authority information as
      demonstrated in the sample output above.

   Support for FMRI FRU identity information (serial, part and revision)
      For the hc-scheme FMRIs that support serial, part or revision
      information, libtopo provides enumerator module interfaces to
      efficiently add and display identity information according to the
      FMRI protocol.  For example:

   hc://:product-id=SUNW,Sun-Fire:server-id=monica-a:serial=110807130E6/centerplane=0/cpu=10

Flag Day information:

   BFU Changes

      I have made minor modifications to BFU itself.  If you have an outdated
      BFU and use it to get to the new archives, you may notice obsolete
      hc-topology.xml files in /usr/platform/`uname -i`/lib/fm/topo and
      /usr/platform/`uname -m`/lib/fm/topo.  This is a benign situation
      and libtopo and its consumers will not be impacted.

   Impact to Platform Developers

      This project changes the namespace of the project private platform or
      machine specific hc-topology.xml files to include the name of platform
      (uname -i), machine (uname -m) or product.  New libtopo .xml files
      should follow this convention.

      This project changes the project private libtopo enumerator module API.
      New platform enumerators should follow the programming guides documented
      in the fmd PRM.

      This project delivers a new option (-p) to fmtopo that is suitable for
      inclusion in section 3 of a platform FMA portfolio.

More Information:

   For more information and updates to the Fault Management Daemon Programmer's
   Reference Manual, see http://fma.eng.  Bugs related to this putback should
   be filed as follows:

   library/fm - libtopo and enumerator plugins
   utility/fm - Solaris utilities fmdump(1M), fmstat(1M), fmadm(1M), fmd(1M) and
                fmtopo

  email aliases for questions and comments

  FMA Technology - fma-interest at sun dot com
  FMA Core Team - fma-core at sun dot om

Cindi

~--------------000002090600000005060408~--